#!/usr/bin/env python3 """Connection lifecycle tool for managed gateway accounts and local MCP servers. Disconnecting accounts remains a portal-only user decision. """ from typing import Any, Callable, Dict, Optional from tools.connectors.catalog_tool import MANAGE_CATALOG_SCHEMA, manage_catalog from tools.connectors.gateway import config as gateway_config from tools.connectors.managed import run_managed_action from tools.connectors.mcp import run_mcp_operation from tools.connectors.targets import ALIAS_PATTERN, ALL_ACTIONS, MCP_ACTIONS, normalize_targets, validate_action from tools.registry import registry, tool_error def manage_connections( args: dict[str, Any], *, client_factory: Optional[Callable[[], Any]] = None, mcp_backend: Optional[Any] = None, session_id: Optional[str] = None, tool_call_id: Optional[str] = None, turn_id: Optional[str] = None, connection_callback: Optional[Callable[[dict[str, Any]], Optional[str]]] = None, connectors_available: Optional[Callable[[], bool]] = None, card_surface: bool = False, ) -> str: action = str(args.get("action") or "status").strip().lower() managed, mcp_targets, target_error = normalize_targets(args.get("connectors")) if target_error: return tool_error(target_error) action_error = validate_action(action, managed, mcp_targets) if action_error: return tool_error(action_error) if action in MCP_ACTIONS: return run_mcp_operation( mcp_targets, action, backend=mcp_backend, connection_callback=connection_callback, session_id=session_id, tool_call_id=tool_call_id, ) return run_managed_action( action, managed, args, client_factory=client_factory, session_id=session_id, tool_call_id=tool_call_id, turn_id=turn_id, connection_callback=connection_callback, connectors_available=connectors_available, card_surface=card_surface, ) MANAGE_CONNECTIONS_SCHEMA = { "name": "manage_connections", "description": ( "Connect the user to apps. Two kinds: a hosted connector account (Gmail, Notion, ...) " "served through the tool gateway, and a local MCP server from the bundled catalog. " "Targets go in 'connectors': a bare slug or {\"name\": \"gmail\"} is a hosted connector " "account; {\"name\": \"linear\", \"mcp\": true} is a local MCP server. Many names exist on " "both sides, so the user's own words decide. Pass \"mcp\": true only when the user asks " "for an MCP server, a local server or an install, or when the name exists only as a " "catalog entry; otherwise the target is hosted. 'connect' and 'reconnect' are hosted " "actions; 'install', 'enable' and 'authorize' are MCP actions. A target the other side " "owns is refused with the call that does work. " "Hosted actions: 'display' (desktop only; elsewhere returns status) shows every connector and " "waits for Continue (300 s); put slugs to suggest in 'connectors'. Returns connected/newly_connected " "(+timed_out); the user saw the list, so do not repeat it. 'connect' is for an app the user names. " "'status' lists connectors and whether each is connected; 'connect' " "starts an authorization for the given connectors; 'reconnect' checks each one and " "repairs only what is not connected ('force': true restarts even a working one, for an " "account switch). A second account of one app is 'connect' with a new 'alias': pick a short " "lowercase name from the user's words (e.g. 'work'), and ask the user if unsure. 'status' lists " "each connector's accounts; 'rename' names or renames one. Pass SEVERAL slugs in one call. In the desktop app, the terminal UI and " "the interactive CLI the call shows the user a card and blocks until every app is " "connected, skipped, or the deadline passes; the result lists each target as connected / " "skipped / not_connected and never carries a link. Where no card exists (a one-shot run, " "a scheduled job, a messaging platform) the result carries a connect_url per app for the " "USER to open in a browser (never open it yourself); ask them to say when they are done, " "then use 'status'. " "When a hosted connector tool call returns CONNECTION_REQUIRED, use 'connect'. " "MCP actions (every target must carry \"mcp\": true): 'install' adds a catalog entry, " "'enable' re-enables a disabled configured server, 'authorize' runs its OAuth. " "They show the user an approval card and block until it settles. Never hand-edit " "mcp_servers config — always use this tool. After a skip or a timeout, do not re-ask on " "your own: continue without the app or ask in chat. A later request from the USER for that " "same app is not a re-ask — run it. A connected server's tools are named in the result and are " "callable at once through tool_describe/tool_call. Where no card exists an MCP target runs at once and the result says what " "happened, with a link for the user to open when one is needed. This tool can NOT " "disconnect, delete, or revoke an account — that is deliberately user-only. When asked, say so and direct the user to the " "Nous Portal (their org's Connectors page) or the desktop app." ), "parameters": { "type": "object", "properties": { "action": { "type": "string", "enum": list(ALL_ACTIONS), "description": ( "Defaults to status. connect, reconnect and rename take hosted connector slugs only. " "install, enable and authorize take mcp:true targets only." ), }, "connectors": { "type": "array", "items": { "anyOf": [ {"type": "string"}, { "type": "object", "properties": { "name": {"type": "string"}, "mcp": { "type": "boolean", "description": ( "true = a local MCP server from the catalog; absent or " "false = a hosted connector account." ), }, "alias": { "type": "string", "description": ( "Hosted only: the account's name. connect: a new name adds another " "account; reconnect: repairs that account; rename: its current name " "(or its label when unnamed). One aliased target per call." ), }, "to": { "type": "string", "pattern": ALIAS_PATTERN, "description": "rename only: the new name.", }, }, "required": ["name"], "additionalProperties": False, }, ] }, "description": ( "Targets. REQUIRED for every action but status and display " "(e.g. [\"gmail\", {\"name\": \"linear\", \"mcp\": true}]); optional filter for " "status. A bare slug is a hosted connector, so an MCP server needs the object " "form with \"mcp\": true." ), }, "force": { "type": "boolean", "description": "reconnect only: restart the authorization even if the app is connected (account switch).", }, }, "required": [], }, } registry.register( name="manage_connections", toolset="connections", schema=MANAGE_CONNECTIONS_SCHEMA, # The portal gate decides schema presence: an account the portal has not enabled for # connectors never sees the tool, so the model cannot call it and read the gateway's # 404 back to them. The handler runs the same gate so the RPC path (methods_connectors) and # a cached schema agree. Read as a module attribute so tests patch # ``gateway.config.connectors_available`` at one seam. handler=lambda args, **kw: manage_connections( args, session_id=kw.get("session_id"), tool_call_id=kw.get("tool_call_id"), connectors_available=gateway_config.connectors_available, ), check_fn=lambda: gateway_config.connectors_available(), emoji="🔗", ) # Registry dispatch has no card callback, so it answers with the CLI pointer. registry.register( name="manage_catalog", toolset="catalog", schema=MANAGE_CATALOG_SCHEMA, handler=lambda args, **kw: manage_catalog(args, session_id=kw.get("session_id")), emoji="🧩", )