mcp.py 39 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846
  1. from __future__ import annotations
  2. import contextlib
  3. import contextvars
  4. import json
  5. import logging
  6. import threading
  7. import time
  8. from dataclasses import dataclass, field
  9. from typing import Any, Callable, Dict, List, Optional, Tuple
  10. from hermes_constants import hermes_home_key
  11. from tools.connectors.contract import Actor, SettleReason, TargetState
  12. from tools.connectors.gateway.config import operation_session_key
  13. from tools.connectors.operation import ConnectionOperation, DetachedOperation, IllegalTransition, Target
  14. from tools.connectors.run import Kind, run_operation
  15. from tools.connectors.targets import hosted_names, misrouted_to_mcp_error
  16. from tools.registry import tool_error
  17. logger = logging.getLogger(__name__)
  18. # One wait for every authorization URL of a call, not one per target: the flows are started
  19. # together, and a provider that is slow to publish its URL must not delay the others.
  20. PREPARE_WAIT_SECONDS = 30.0
  21. NOTE = (
  22. "Settled once; do not re-ask on your own for any target the user skipped or that timed out, but "
  23. "a later request from the USER for that same app is not a re-ask — run it. Connected "
  24. "targets' tools are available now through tool_describe/tool_call and are named under "
  25. "tools_listing. A target with discovery_error is authorized but its tools are unavailable; "
  26. "retry discovery with manage_connections using that target's authorize or install action "
  27. "without asking for consent again."
  28. )
  29. NO_CARD_NOTE = (
  30. "No connection card is drawn for this turn. Show any connect_url to the user so they "
  31. "open it in a browser, then ask them to say when they are done. Connected targets' tools are "
  32. "available now through tool_describe/tool_call and are named under tools_listing. A target with "
  33. "discovery_error is authorized but its tools are unavailable; retry discovery with "
  34. "manage_connections using that target's authorize or install action without asking for consent "
  35. "again. Do not re-ask on your own for skipped or timed-out targets, but a later request from "
  36. "the USER for that same app is not a re-ask — run it."
  37. )
  38. def _catalog_names() -> list[str]:
  39. from hermes_cli.mcp_catalog import list_catalog
  40. return sorted(e.name for e in list_catalog())
  41. def _configured_names() -> list[str]:
  42. from hermes_cli.mcp_catalog import installed_servers
  43. return sorted(installed_servers())
  44. def validate_mcp_names(action: str, names: list[str]) -> Optional[str]:
  45. try:
  46. catalog = _catalog_names()
  47. configured = _configured_names()
  48. except Exception as exc:
  49. return f"could not read the MCP catalog: {exc}"
  50. allowed = set(catalog) if action == "install" else set(configured)
  51. unknown = [n for n in names if n not in allowed]
  52. if not unknown:
  53. return None
  54. foreign = [n for n in unknown if n not in catalog and n not in configured]
  55. if foreign:
  56. hosted = hosted_names() or set()
  57. misrouted = [n for n in foreign if n in hosted]
  58. if misrouted:
  59. return " ".join(misrouted_to_mcp_error(action, name) for name in misrouted)
  60. if action == "install":
  61. return (
  62. f"unknown MCP server(s) for install: {', '.join(unknown)}. Install works for "
  63. f"catalog entries only: {', '.join(catalog) or '(empty catalog)'}."
  64. + (f" Already configured (use enable/authorize): {', '.join(configured)}." if configured else "")
  65. )
  66. return (
  67. f"unknown MCP server(s) for {action}: {', '.join(unknown)}. {action} works for servers "
  68. f"already in mcp_servers: {', '.join(configured) or '(none configured)'}."
  69. + (f" Catalog entries you can install: {', '.join(catalog)}." if catalog else "")
  70. )
  71. # ---------------------------------------------------------------------------
  72. # the backend: the catalog, the installer, the OAuth flow
  73. # ---------------------------------------------------------------------------
  74. def _catalog_entry(name: str):
  75. from hermes_cli.mcp_catalog import get_entry
  76. entry = get_entry(name)
  77. if entry is None:
  78. missing = ValueError(f"no catalog entry '{name}'")
  79. missing.failure_class = "config_invalid" # type: ignore[attr-defined]
  80. raise missing
  81. return entry
  82. class _CatalogBackend:
  83. """The real work behind an MCP target. One object so a caller can pass another one in."""
  84. def required_env(self, name: str) -> list[dict[str, Any]]:
  85. """The credentials the catalog entry declares that have no value yet."""
  86. from hermes_cli.config import get_env_value
  87. return [{"name": spec.name, "prompt": spec.prompt, "required": spec.required,
  88. "secret": spec.secret, "default": "" if spec.secret else spec.default}
  89. for spec in (_catalog_entry(name).auth.env or []) if not get_env_value(spec.name)]
  90. def start_oauth(self, name: str) -> Any:
  91. from tools.connectors import mcp_oauth
  92. # The TUI/Desktop card path supplies its advertised client redirect in a later part.
  93. return mcp_oauth.start(name, client_redirect_uri=None)
  94. def installs_with_oauth(self, name: str) -> bool:
  95. """A catalog entry whose own OAuth the card must run. Provider-mediated OAuth is not one:
  96. its token comes from ``hermes auth <provider>``, so the plain probe covers it."""
  97. auth = _catalog_entry(name).auth
  98. return auth.type == "oauth" and not auth.provider
  99. def start_install_oauth(self, name: str, env: dict[str, str]) -> Any:
  100. """Install an OAuth entry through the card's flow. The configuration is built in memory and
  101. lands, together with the setup values, only when ``initialize`` accepts the token."""
  102. from hermes_cli.mcp_catalog import card_install_config, is_installed, record_mcp_install
  103. from tools.connectors import mcp_oauth
  104. fresh = not is_installed(name)
  105. def commit() -> None:
  106. _save_env(env)
  107. if fresh:
  108. record_mcp_install("catalog", name, "success")
  109. try:
  110. entry = _catalog_entry(name)
  111. _check_declared(name, entry, env)
  112. return mcp_oauth.start(name, cfg=card_install_config(entry), env=env, on_commit=commit)
  113. except Exception as exc:
  114. # An abandoned browser authorization is a cancel, not a failed install: only a flow
  115. # that cannot start is counted here.
  116. if fresh:
  117. record_mcp_install("catalog", name, "failed", error=exc)
  118. raise
  119. def install(self, name: str, env: dict[str, str]) -> list[str]:
  120. """Probe the entry's in-memory configuration with ephemeral credentials; save both only
  121. after the server answered. A failure writes nothing, so a failed reinstall keeps the
  122. previous configuration. A first install is recorded once as an extension install."""
  123. from hermes_cli.mcp_catalog import recorded_catalog_install
  124. with recorded_catalog_install(name):
  125. return self._install(name, env)
  126. def _install(self, name: str, env: dict[str, str]) -> list[str]:
  127. from agent.secret_scope import (
  128. current_secret_scope, current_secret_scope_home, reset_secret_scope, set_secret_scope)
  129. from hermes_cli.mcp_catalog import _inline_non_secret_value, card_install_config
  130. from hermes_cli.mcp_config import _probe_single_server, _save_mcp_server
  131. entry = _catalog_entry(name)
  132. _check_declared(name, entry, env)
  133. cfg = card_install_config(entry)
  134. # `.env` is secrets-only: non-secret values (hostnames, client ids, workspace names) are
  135. # inlined into the server block, the same split `install_entry` makes for the terminal path.
  136. secret_names = {spec.name for spec in (entry.auth.env or []) if spec.secret}
  137. for key, value in env.items():
  138. if key not in secret_names and value:
  139. cfg = _inline_non_secret_value(cfg, key, value)
  140. # The merged scope keeps the bound scope's home stamp: dropping it would
  141. # reopen the env fallthrough under a routed profile with multiplex off.
  142. token = set_secret_scope(
  143. {**dict(current_secret_scope() or {}), **env},
  144. profile_home=current_secret_scope_home())
  145. try:
  146. tools = [str(tool[0]) for tool in (_probe_single_server(name, cfg) or [])]
  147. finally:
  148. reset_secret_scope(token)
  149. if not _save_mcp_server(name, cfg):
  150. rejected = RuntimeError(f"'{name}' was rejected: suspicious command/args configuration")
  151. rejected.failure_class = "config_rejected" # type: ignore[attr-defined]
  152. raise rejected
  153. _save_env({k: v for k, v in env.items() if k in secret_names})
  154. return tools
  155. def enable(self, name: str) -> None:
  156. """Flip ``enabled`` under the scope and lock the dashboard's toggle route uses
  157. (``PUT /api/mcp/servers/{name}/enabled``): the two read-modify-write paths run in one
  158. process, so an unserialised write here drops whichever landed first."""
  159. from hermes_cli.config import load_config, save_config
  160. from hermes_cli.web_routers._common import config_write_scope
  161. with config_write_scope(None):
  162. config = load_config()
  163. servers = config.get("mcp_servers")
  164. if not isinstance(servers, dict) or not isinstance(servers.get(name), dict):
  165. raise ValueError(f"'{name}' is not a configured MCP server")
  166. servers[name]["enabled"] = True
  167. save_config(config)
  168. def _check_declared(name: str, entry: Any, env: dict[str, str]) -> None:
  169. """Configuring one MCP is not a general env-writing primitive: refuse the whole map before the
  170. first write if any key is undeclared or unwritable."""
  171. from hermes_cli.config import validate_env_var_name_for_write
  172. declared = {spec.name for spec in (entry.auth.env or [])}
  173. for key in env:
  174. if key not in declared:
  175. undeclared = ValueError(f"'{name}' does not declare the environment variable {key}")
  176. undeclared.failure_class = "config_invalid" # type: ignore[attr-defined]
  177. raise undeclared
  178. validate_env_var_name_for_write(key)
  179. def _save_env(env: dict[str, str]) -> None:
  180. from hermes_cli.config import save_env_value
  181. for key, value in env.items():
  182. if value:
  183. save_env_value(key, value)
  184. def _default_backend() -> Any:
  185. return _CatalogBackend()
  186. # ---------------------------------------------------------------------------
  187. # the runner: per-operation work, reachable from the RPC thread by op_id
  188. # ---------------------------------------------------------------------------
  189. @dataclass
  190. class _Work:
  191. """One target's work in flight: an OAuth attempt the watcher polls, or a worker's outcome."""
  192. attempt: Any = None
  193. done: threading.Event = field(default_factory=threading.Event)
  194. tools: list[str] = field(default_factory=list)
  195. error: str = ""
  196. class _Runner:
  197. """The backend plus the work for one operation's targets."""
  198. def __init__(self, action: str, backend: Any):
  199. self.action = action
  200. self.backend = backend
  201. self.op_id: Optional[str] = None
  202. self.work: dict[str, _Work] = {}
  203. # The credentials the card approved, per target. Try again carries none (a failed row has
  204. # no fields), so the install that runs again is the one the user approved. Kept here and
  205. # not on the target: the values are secrets, and the runner is the one object whose life
  206. # is exactly the operation's.
  207. self.approved_env: dict[str, dict[str, str]] = {}
  208. def run(self, table: dict[str, Callable], operation: ConnectionOperation, target: Target,
  209. env: Optional[dict[str, str]] = None) -> None:
  210. table[self.action](self, operation, target, env or {})
  211. def spawn(self, operation: ConnectionOperation, target: Target, call: Callable[[], Any]) -> None:
  212. """Run one blocking backend call on a worker thread; ``observe`` reports its outcome."""
  213. if operation.settled: # Continue landed between the state read and here
  214. logger.debug("mcp %s %s: not started, the operation settled first", self.action, target.name)
  215. return
  216. work = _Work()
  217. self.work[target.name] = work
  218. def body() -> None:
  219. tools: list[str] = []
  220. error = ""
  221. try:
  222. tools = [str(name) for name in (call() or [])]
  223. except Exception as exc:
  224. error = _detail(exc, self, target)
  225. if operation.settled:
  226. # The result froze while the work ran; there is no row left to report into.
  227. logger.debug("mcp %s %s: outcome dropped, the operation settled first",
  228. self.action, target.name)
  229. return
  230. work.tools, work.error = tools, error
  231. work.done.set()
  232. operation.wake.set()
  233. # The worker runs in a copy of the calling thread's context: a named-profile turn binds its
  234. # home through a contextvar, and the install must write the credentials into that home.
  235. threading.Thread(target=contextvars.copy_context().run, args=(body,), daemon=True,
  236. name=f"mcp-{self.action}-{target.name}").start()
  237. def prepare(self, operation: ConnectionOperation) -> None:
  238. _RUNNERS[operation.op_id] = self
  239. self.op_id = operation.op_id
  240. self.operation = operation
  241. if self.action == "authorize" and len(operation.targets) > 1:
  242. self._prepare_together(operation)
  243. return
  244. for target in operation.targets:
  245. self.run(_PREPARE, operation, target)
  246. def _prepare_together(self, operation: ConnectionOperation) -> None:
  247. """Start every OAuth flow at once and wait for the URLs once. Each flow blocks until its
  248. provider publishes an authorization URL, so a sequential prepare would keep the card empty
  249. for one wait per target.
  250. The wait bounds how long prepare blocks, not how long a provider may take: a row still
  251. pending afterwards is left to its own thread, which is the only writer of that row and
  252. ends with the URL or the flow's own failure. Failing it here as well would make two
  253. writers of one row, and a URL that arrives a moment later would have no row to land on.
  254. Each thread runs in its own copy of the calling thread's context: a named-profile turn
  255. binds its home through a contextvar, and the flow resolves ``mcp_servers`` and stores the
  256. token by that home."""
  257. threads = [threading.Thread(target=contextvars.copy_context().run,
  258. args=(self.run, _PREPARE, operation, target), daemon=True,
  259. name=f"mcp-prepare-{target.name}") for target in operation.targets]
  260. for thread in threads:
  261. thread.start()
  262. deadline = time.time() + PREPARE_WAIT_SECONDS
  263. for thread in threads:
  264. thread.join(max(0.0, deadline - time.time()))
  265. def observe(self, operation: ConnectionOperation) -> None:
  266. for target in operation.targets:
  267. # Only a live target can be advanced by a read; a failed one waits for Try again.
  268. if operation.settled or target.state not in (TargetState.pending, TargetState.initiated):
  269. continue
  270. _OBSERVE[self.action](self, operation, target)
  271. def close(self) -> None:
  272. """The operation is over. An attempt still waiting on the browser is stopped when the user
  273. ended the turn, and otherwise left to finish: the card closed, not the authorization. What
  274. it commits is picked up before the session's next turn (``adopt_late_connections``)."""
  275. if self.op_id is not None:
  276. _RUNNERS.pop(self.op_id, None)
  277. operation = getattr(self, "operation", None)
  278. for name, work in list(self.work.items()):
  279. if work.attempt is None or operation is None:
  280. continue
  281. if operation.settled_by == SettleReason.interrupt:
  282. from tools.connectors.mcp_oauth import cancel_attempt
  283. cancel_attempt(work.attempt.flow)
  284. else:
  285. _LATE_ATTEMPTS.setdefault(_late_key(operation), {})[name] = work.attempt
  286. self.work.clear()
  287. def _late_key(operation: ConnectionOperation) -> tuple[str, str]:
  288. """The ``(profile, session)`` pairing ``live.open`` keys an operation by. ``profile_key``
  289. is stamped there; the detached no-card path never opens, so fall back to the calling
  290. thread's home — ``close`` runs on the tool thread under the turn's profile scope."""
  291. return (operation.profile_key or hermes_home_key(), operation.session_key)
  292. # (profile key, session key) -> {server: attempt} for OAuth attempts that outlived their card.
  293. # The profile is part of the key for the same reason live.py keys _open by it: two multiplexed
  294. # profiles can carry the same session key, and an attempt must only ever be adopted by the
  295. # profile whose card authorized it.
  296. _LATE_ATTEMPTS: dict[tuple[str, str], dict[str, Any]] = {}
  297. def adopt_late_connections(agent: Any) -> list[str]:
  298. """Register the servers whose authorization committed after their card had closed, and add
  299. them to the agent's toolset selection. Runs between turns, so the result that said "not
  300. connected" is followed by a turn in which the tools are there."""
  301. session_key = operation_session_key(getattr(agent, "session_id", None))
  302. key = (hermes_home_key(), session_key)
  303. attempts = _LATE_ATTEMPTS.get(key)
  304. if not attempts:
  305. return []
  306. adopted: list[str] = []
  307. for name, attempt in list(attempts.items()):
  308. snapshot = attempt.poll()
  309. if snapshot["status"] == "pending":
  310. continue
  311. attempts.pop(name, None)
  312. if snapshot["status"] != "approved" or snapshot.get("discovery_error"):
  313. continue
  314. try:
  315. from tools.mcp_tool_config import _load_mcp_config
  316. from tools.mcp_tool_discovery import register_mcp_servers
  317. config = _load_mcp_config().get(name)
  318. if isinstance(config, dict):
  319. register_mcp_servers({name: config})
  320. adopted.append(name)
  321. except Exception:
  322. logger.debug("late MCP connection %s was not adopted", name, exc_info=True)
  323. if not attempts:
  324. _LATE_ATTEMPTS.pop(key, None)
  325. enabled = getattr(agent, "enabled_toolsets", None)
  326. if adopted and enabled is not None and "no_mcp" not in enabled:
  327. agent.enabled_toolsets = [*enabled, *(n for n in adopted if n not in enabled)]
  328. return adopted
  329. # op_id -> the runner driving it, so the card's answer and Try again (RPC thread) find the work.
  330. _RUNNERS: dict[str, _Runner] = {}
  331. def open_runner(action: str, backend: Any = None) -> _Runner:
  332. """The runner for one MCP operation. ``prepare`` binds it to the operation, so the card's
  333. answer and its Try again — both of which arrive on another thread — find the same work."""
  334. return _Runner(action, backend or _default_backend())
  335. # Errors that carry no message reach the user as their class name; say what happened instead.
  336. _BARE_ERRORS = {
  337. "CancelledError": "tool discovery was interrupted; run the same action again to list the tools",
  338. "TimeoutError": "the server did not answer in time",
  339. }
  340. def _detail(exc: Any, runner: _Runner, target: Target) -> str:
  341. """The user-facing text of a failure. Every value the card submitted for this target is
  342. replaced by exact match before the pattern redactor runs: an opaque credential has no
  343. recognizable shape, so only the runner knows what to remove."""
  344. from agent.redact import redact_sensitive_text
  345. text = str(exc) or (_BARE_ERRORS.get(exc.__class__.__name__, exc.__class__.__name__)
  346. if isinstance(exc, BaseException) else "error")
  347. text = _BARE_ERRORS.get(text, text) # a worker hands over the class name of a message-less error
  348. for value in runner.approved_env.get(target.name, {}).values():
  349. if value:
  350. text = text.replace(value, "[REDACTED]")
  351. return redact_sensitive_text(text, force=True) or "error"
  352. def _catalog_instructions(name: str) -> str:
  353. """The manifest's ``post_install`` text for a catalog name; a custom configured server has none."""
  354. from hermes_cli.mcp_catalog import get_entry
  355. entry = get_entry(name)
  356. return str(entry.post_install or "") if entry is not None else ""
  357. def _move(operation: ConnectionOperation, target: Target, to: TargetState, actor: Actor, **fields: Any) -> bool:
  358. """Move one target from the prepare, worker-outcome or observe path.
  359. Continue on the RPC thread can settle the operation between any read of the target's state and
  360. this call. A settled operation has a frozen result, so the lost move is dropped rather than
  361. raised into the tool result; anything else is a real contract violation."""
  362. try:
  363. operation.transition(target.name, to, actor, **fields)
  364. return True
  365. except IllegalTransition:
  366. if not operation.settled:
  367. raise
  368. logger.debug("mcp target %s: %s dropped, the operation settled first", target.name, to.value)
  369. return False
  370. def _fail(operation: ConnectionOperation, target: Target, detail: str) -> None:
  371. """Report a failure, whatever the row was doing: a repeated failure has no state change to
  372. emit, only newer text."""
  373. if operation.settled:
  374. logger.debug("mcp target %s: failure dropped, the operation settled first", target.name)
  375. return
  376. if target.state == TargetState.failed:
  377. operation.refresh(target.name, connect_url=None, detail=detail, actor=Actor.backend_watcher)
  378. return
  379. target.connect_url = None # whatever link the row was offering is dead
  380. _move(operation, target, TargetState.failed, Actor.backend_watcher, detail=detail)
  381. def _register_connected(runner: _Runner, target: Target, name: str) -> tuple[list[str], str]:
  382. """Register one committed server in the current profile scope and report its callable names."""
  383. try:
  384. from tools.mcp_tool_config import _load_mcp_config
  385. from tools.mcp_tool_discovery import register_mcp_servers
  386. config = _load_mcp_config().get(name)
  387. if not isinstance(config, dict):
  388. raise RuntimeError(f"no committed MCP configuration for '{name}'")
  389. register_mcp_servers({name: config})
  390. return _registered_tool_names(name), ""
  391. except Exception as exc:
  392. return [], _detail(exc, runner, target)
  393. def _registered_tool_names(name: str, wait_seconds: float = 30.0) -> list[str]:
  394. """The server's callable names, read from the registry once its registration has finished.
  395. Registration is a no-op for a server the process already holds, and that includes one another
  396. task is still connecting: saving the configuration wakes the config watcher, which starts its
  397. own connect, so a large server (hundreds of tools) was reported with no tools three seconds
  398. before they were registered. A server that failed discovery earlier is parked with no tools
  399. and is woken once. A server that finished registering with no tools is a valid empty list."""
  400. from tools import mcp_tool as _core
  401. from tools.mcp_tool_loop import reconnect_mcp_server
  402. from tools.mcp_tool_scope import _resolve_server_key
  403. from tools.registry import registry
  404. key = _resolve_server_key(name)
  405. deadline = time.time() + wait_seconds
  406. woken = False
  407. while True:
  408. names = registry.get_tool_names_for_toolset(f"mcp-{name}")
  409. if names or time.time() >= deadline:
  410. return names
  411. if key not in _core._server_connecting:
  412. server = _core._servers.get(key)
  413. finished = server is not None and getattr(server, "session", None) is not None \
  414. and hasattr(server, "_registered_tool_names")
  415. if finished:
  416. return names
  417. if woken or server is None or not reconnect_mcp_server(name):
  418. return names
  419. woken = True
  420. time.sleep(0.25)
  421. def _connect(operation: ConnectionOperation, target: Target, tools: list[str], discovery_error: str = "") -> None:
  422. extra: dict[str, Any] = {"tools": tools}
  423. if discovery_error:
  424. extra["discovery_error"] = discovery_error
  425. _move(operation, target, TargetState.connected, Actor.backend_watcher, **extra)
  426. def _actor(target: Target) -> Actor:
  427. """Try again is the user's move; a first attempt is the backend's."""
  428. return Actor.user if target.state == TargetState.failed else Actor.backend_watcher
  429. def _start_oauth(runner: _Runner, operation: ConnectionOperation, target: Target, env: dict[str, str]) -> None:
  430. actor = _actor(target)
  431. target.instructions = _catalog_instructions(target.name)
  432. try:
  433. attempt = runner.backend.start_oauth(target.name)
  434. except Exception as exc:
  435. _fail(operation, target, _detail(exc, runner, target))
  436. return
  437. runner.work[target.name] = _Work(attempt=attempt)
  438. _move(operation, target, TargetState.initiated, actor, connect_url=attempt.auth_url,
  439. detail=getattr(attempt, "detail", ""))
  440. def _declare_env(runner: _Runner, operation: ConnectionOperation, target: Target, env: dict[str, str]) -> None:
  441. """The install row waits pending; the card draws a field per credential it still needs."""
  442. target.instructions = _catalog_instructions(target.name)
  443. try:
  444. required = runner.backend.required_env(target.name)
  445. except Exception as exc:
  446. _fail(operation, target, _detail(exc, runner, target))
  447. return
  448. target.required_env = required
  449. def _missing_required(runner: _Runner, target: Target, env: dict[str, str]) -> list[dict[str, Any]]:
  450. """The declared credentials that still have no value. The install runs on a worker thread,
  451. where ``install_entry``'s prompt for a missing credential would block on stdin forever."""
  452. declared = runner.backend.required_env(target.name)
  453. return [spec for spec in declared
  454. if spec.get("required", True) and not env.get(str(spec.get("name") or ""))]
  455. def _start_install(runner: _Runner, operation: ConnectionOperation, target: Target, env: dict[str, str]) -> None:
  456. approved = {**runner.approved_env.get(target.name, {}), **env}
  457. try:
  458. missing = _missing_required(runner, target, approved)
  459. except Exception as exc:
  460. _fail(operation, target, _detail(exc, runner, target))
  461. return
  462. if missing:
  463. # The row stays pending and the card draws a field per credential it still needs; the
  464. # refresh is what tells the renderer to ask again.
  465. target.required_env = missing
  466. operation.refresh(target.name, connect_url=target.connect_url, actor=Actor.backend_watcher,
  467. detail=f"waiting for {', '.join(str(spec['name']) for spec in missing)}")
  468. return
  469. runner.approved_env[target.name] = approved
  470. actor = _actor(target)
  471. target.required_env = [] # the credentials are written by the install; the row stops asking
  472. if not _move(operation, target, TargetState.initiated, actor, detail=""):
  473. return
  474. if _installs_with_oauth(runner, target):
  475. _start_install_oauth(runner, operation, target, approved)
  476. return
  477. runner.spawn(operation, target, lambda: runner.backend.install(target.name, approved))
  478. def _installs_with_oauth(runner: _Runner, target: Target) -> bool:
  479. try:
  480. return bool(runner.backend.installs_with_oauth(target.name))
  481. except Exception:
  482. return False # the install itself reports a bad entry
  483. def _start_install_oauth(runner: _Runner, operation: ConnectionOperation, target: Target,
  484. env: dict[str, str]) -> None:
  485. """The row is already ``initiated``; publish the authorization link onto it. The same
  486. ``initiated`` + ``connect_url`` pair is what every card reads as its URL step."""
  487. try:
  488. attempt = runner.backend.start_install_oauth(target.name, env)
  489. except Exception as exc:
  490. _fail_install(runner, operation, target, exc)
  491. return
  492. runner.work[target.name] = _Work(attempt=attempt)
  493. if operation.settled:
  494. return
  495. operation.refresh(target.name, connect_url=attempt.auth_url, actor=Actor.backend_watcher,
  496. detail=getattr(attempt, "detail", ""))
  497. def _fail_install(runner: _Runner, operation: ConnectionOperation, target: Target, error: Any) -> None:
  498. """A failed install asks for its fields again, so the card can reopen the form over the draft
  499. it kept. Nothing was saved, so every declared field is still missing."""
  500. with contextlib.suppress(Exception):
  501. target.required_env = runner.backend.required_env(target.name)
  502. _fail(operation, target, _detail(error, runner, target))
  503. def _do_enable(runner: _Runner, operation: ConnectionOperation, target: Target, env: dict[str, str]) -> None:
  504. actor = _actor(target)
  505. if not _move(operation, target, TargetState.initiated, actor, detail=""):
  506. return
  507. try:
  508. runner.backend.enable(target.name)
  509. except Exception as exc:
  510. _fail(operation, target, _detail(exc, runner, target))
  511. return
  512. tools, discovery_error = _register_connected(runner, target, target.name)
  513. _connect(operation, target, tools, discovery_error)
  514. def _install_now(runner: _Runner, operation: ConnectionOperation, target: Target, env: dict[str, str]) -> None:
  515. """Off the desktop nobody can fill a credential in, so a missing one is the answer."""
  516. try:
  517. missing = [spec["name"] for spec in runner.backend.required_env(target.name) if spec.get("required", True)]
  518. except Exception as exc:
  519. _fail(operation, target, _detail(exc, runner, target))
  520. return
  521. if missing:
  522. from hermes_constants import display_hermes_home
  523. _fail(operation, target, f"set {', '.join(missing)} in the environment or "
  524. f"{display_hermes_home()}/.env, then install again")
  525. return
  526. actor = _actor(target)
  527. if _installs_with_oauth(runner, target):
  528. # No card here, so the result carries the link; the flow's own worker commits the install.
  529. try:
  530. attempt = runner.backend.start_install_oauth(target.name, {})
  531. except Exception as exc:
  532. _fail(operation, target, _detail(exc, runner, target))
  533. return
  534. runner.work[target.name] = _Work(attempt=attempt)
  535. _move(operation, target, TargetState.initiated, actor, connect_url=attempt.auth_url,
  536. detail=getattr(attempt, "detail", ""))
  537. return
  538. _move(operation, target, TargetState.initiated, actor)
  539. try:
  540. runner.backend.install(target.name, {})
  541. except Exception as exc:
  542. _fail(operation, target, _detail(exc, runner, target))
  543. return
  544. tools, discovery_error = _register_connected(runner, target, target.name)
  545. _connect(operation, target, tools, discovery_error)
  546. def _observe_oauth(runner: _Runner, operation: ConnectionOperation, target: Target) -> None:
  547. work = runner.work.get(target.name)
  548. if work is None or work.attempt is None:
  549. return
  550. snapshot = work.attempt.poll()
  551. status = snapshot.get("status")
  552. if status not in ("approved", "error"):
  553. return
  554. runner.work.pop(target.name, None)
  555. if status == "approved":
  556. discovery_error = snapshot.get("discovery_error") or ""
  557. if discovery_error:
  558. _connect(operation, target, [], _detail(discovery_error, runner, target))
  559. else:
  560. tools, registration_error = _register_connected(runner, target, target.name)
  561. _connect(operation, target, tools, registration_error)
  562. return
  563. error = snapshot.get("error") or "the authorization flow failed"
  564. if runner.action == "install":
  565. _fail_install(runner, operation, target, error)
  566. return
  567. _fail(operation, target, _detail(error, runner, target))
  568. def _observe_install(runner: _Runner, operation: ConnectionOperation, target: Target) -> None:
  569. """An install is an OAuth attempt for an OAuth entry and a worker for every other one."""
  570. work = runner.work.get(target.name)
  571. observe = _observe_oauth if work is not None and work.attempt is not None else _observe_worker
  572. observe(runner, operation, target)
  573. def _observe_worker(runner: _Runner, operation: ConnectionOperation, target: Target) -> None:
  574. work = runner.work.get(target.name)
  575. if work is None or not work.done.is_set():
  576. return
  577. runner.work.pop(target.name, None)
  578. if work.error:
  579. if runner.action == "install":
  580. _fail_install(runner, operation, target, work.error)
  581. return
  582. _fail(operation, target, _detail(work.error, runner, target))
  583. return
  584. tools, discovery_error = _register_connected(runner, target, target.name)
  585. _connect(operation, target, tools, discovery_error)
  586. def _nothing(runner: _Runner, operation: ConnectionOperation, target: Target, env: dict[str, str]) -> None:
  587. """Authorize needs no approval: the row's verb opens the link the flow already minted."""
  588. _PREPARE = {"authorize": _start_oauth, "install": _declare_env, "enable": _nothing}
  589. _APPROVE = {"authorize": _nothing, "install": _start_install, "enable": _do_enable}
  590. _RETRY = {"authorize": _start_oauth, "install": _start_install, "enable": _do_enable}
  591. _OBSERVE = {"authorize": _observe_oauth, "install": _observe_install, "enable": _observe_worker}
  592. _NO_CARD = {"authorize": _start_oauth, "install": _install_now, "enable": _do_enable}
  593. # ---------------------------------------------------------------------------
  594. # the card's answer and its Try again
  595. # ---------------------------------------------------------------------------
  596. def _answer_env(entry: dict[str, Any]) -> dict[str, str]:
  597. raw = entry.get("env")
  598. return {str(k): str(v) for k, v in raw.items()} if isinstance(raw, dict) else {}
  599. def apply_answer(operation: ConnectionOperation, raw: str) -> None:
  600. """Fold the card's ``connection.respond`` payload into the operation: a skip, an approval that
  601. starts the backend's work, and Continue. The card never reports an outcome, so any other claim
  602. moves nothing."""
  603. try:
  604. answer = json.loads(raw)
  605. except (TypeError, ValueError):
  606. answer = {}
  607. if not isinstance(answer, dict):
  608. answer = {}
  609. runner = _RUNNERS.get(operation.op_id)
  610. for entry in answer.get("targets") or ():
  611. if not isinstance(entry, dict):
  612. continue
  613. target = operation.target(str(entry.get("name") or "").strip().lower())
  614. if target is None:
  615. continue
  616. status = str(entry.get("status") or "").lower()
  617. if status == "skipped":
  618. # A row the backend resolved before this move landed has nothing to move; the rest of
  619. # the answer still applies. A settled operation is frozen. The check and the move are
  620. # not one step, so the refusal itself is the witness, not a read taken before it.
  621. kept = _cancel_attempt(runner, target)
  622. try:
  623. operation.transition(target.name, TargetState.skipped, Actor.user,
  624. **({"detail": kept} if kept else {}))
  625. except IllegalTransition:
  626. if not target.resolved and not operation.settled:
  627. raise
  628. elif status == "approved" and runner is not None:
  629. if target.state == TargetState.pending:
  630. runner.run(_APPROVE, operation, target, _answer_env(entry))
  631. elif target.state in (TargetState.failed, TargetState.expired):
  632. # Connect on the form a failed row reopened: the same attempt, with the new values.
  633. runner.run(_RETRY, operation, target, _answer_env(entry))
  634. if answer.get("settled_by") == SettleReason.continue_.value and not operation.all_resolved:
  635. operation.settle(SettleReason.continue_)
  636. AUTHORIZATION_KEPT = ("the authorization had already completed when this was canceled, so it was "
  637. "kept; run the same action again to list the tools")
  638. def _cancel_attempt(runner: Optional[_Runner], target: Target) -> str:
  639. """Stop the target's OAuth attempt so a late reply cannot be adopted. Returns the note for a
  640. cancel that lost the race: the attempt had committed, and a completed authorization stays."""
  641. work = runner.work.pop(target.name, None) if runner is not None else None
  642. flow = getattr(getattr(work, "attempt", None), "flow", None)
  643. if flow is None:
  644. return ""
  645. from tools.connectors.mcp_oauth import cancel_attempt
  646. return AUTHORIZATION_KEPT if cancel_attempt(flow) else ""
  647. def retry(operation: ConnectionOperation, names: list[str]) -> Optional[str]:
  648. """Re-run the named MCP targets on the open operation (the card's Try again): a fresh OAuth
  649. flow, a fresh install, a fresh enable. Returns an error message when the operation is not one
  650. this module is running."""
  651. runner = _RUNNERS.get(operation.op_id)
  652. if runner is None:
  653. return "this operation has no MCP work to re-run"
  654. if operation.settled:
  655. return "this operation has settled; its result is frozen"
  656. for name in names:
  657. target = operation.target(name)
  658. if target is not None:
  659. runner.run(_RETRY, operation, target)
  660. return None
  661. # ---------------------------------------------------------------------------
  662. # the tool entry point
  663. # ---------------------------------------------------------------------------
  664. def _no_card_result(runner: _Runner, names: list[str], action: str, session_key: str) -> str:
  665. operation = DetachedOperation([Target(n, "mcp", action) for n in names], session_key=session_key)
  666. for target in operation.targets:
  667. runner.run(_NO_CARD, operation, target)
  668. payload = operation.result(with_urls=True)
  669. payload["status"] = "initiated" if any(t.state == TargetState.initiated for t in operation.targets) else "settled"
  670. payload["note"] = NO_CARD_NOTE
  671. return json.dumps(payload, ensure_ascii=False)
  672. def run_mcp_operation(
  673. names: list[str],
  674. action: str,
  675. *,
  676. connection_callback: Optional[Callable[[dict[str, Any]], Optional[str]]],
  677. session_id: Optional[str],
  678. tool_call_id: Optional[str] = None,
  679. backend: Any = None,
  680. ) -> str:
  681. error = validate_mcp_names(action, names)
  682. if error:
  683. return tool_error(error)
  684. runner = open_runner(action, backend)
  685. session_key = operation_session_key(session_id)
  686. # Every interactive surface that renders the card attaches this callback. Registry dispatch and
  687. # messaging sessions attach none, so they receive the link instead of opening an unanswerable op.
  688. if connection_callback is None:
  689. return _no_card_result(runner, names, action, session_key)
  690. try:
  691. from tools.connectors.mcp_launch import launch_for
  692. return run_operation(
  693. [Target(n, "mcp", action, launch=launch_for(action, n)) for n in names],
  694. Kind(prepare=runner.prepare, observe=runner.observe, note=NOTE),
  695. session_key=session_key, tool_call_id=tool_call_id,
  696. connection_callback=connection_callback, with_urls_in_result=False,
  697. )
  698. finally:
  699. runner.close()