mcp_catalog.py 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858
  1. """MCP catalog — curated, Nous-approved MCP servers shipped with the repo.
  2. Entries are added only by merging a PR into hermes-agent; presence in ``optional-mcps/`` = Nous
  3. approval (no community tier, no other trust signals). Manifests pin transport details.
  4. """
  5. from __future__ import annotations
  6. import re
  7. import shutil
  8. import subprocess
  9. from contextlib import contextmanager
  10. from dataclasses import dataclass, field
  11. from pathlib import Path
  12. from typing import Any, Dict, Iterator, List, Optional
  13. import hermes_yaml as yaml
  14. from hermes_constants import get_hermes_home, get_optional_mcps_dir
  15. from hermes_cli._subprocess_compat import noninteractive_git_env
  16. from hermes_cli.colors import Colors, color
  17. from hermes_cli.config import load_config, save_config, get_env_value, save_env_value
  18. from hermes_cli.cli_output import prompt as _prompt_input
  19. from utils import rmtree_readonly
  20. _MANIFEST_VERSION = 1
  21. # Substituted at install time inside `transport.command` / `transport.args`.
  22. _INSTALL_DIR_VAR = "${INSTALL_DIR}"
  23. @dataclass
  24. class EnvVarSpec:
  25. name: str
  26. prompt: str
  27. required: bool = True
  28. secret: bool = True
  29. default: str = ""
  30. @dataclass
  31. class AuthSpec:
  32. type: str # "api_key" | "oauth" | "none"
  33. env: list[EnvVarSpec] = field(default_factory=list)
  34. provider: Optional[str] = None # OAuth-specific (third-party provider like Google)
  35. scopes: list[str] = field(default_factory=list)
  36. env_var: Optional[str] = None
  37. # Pre-registered OAuth client block copied verbatim to ``mcp_servers.<name>.oauth`` (vendors
  38. # without Dynamic Client Registration). Secrets stay ``${VAR}`` references declared in ``env``.
  39. oauth: dict[str, Any] = field(default_factory=dict)
  40. # ``auth.oauth`` keys a manifest may pin; everything else is a user-side tuning knob.
  41. _MANIFEST_OAUTH_KEYS = frozenset({"client_id", "client_secret", "redirect_host", "redirect_port", "scope"})
  42. _ENV_REF_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
  43. @dataclass
  44. class TransportSpec:
  45. type: str # "stdio" | "http"
  46. command: Optional[str] = None
  47. args: list[str] = field(default_factory=list)
  48. url: Optional[str] = None
  49. version: Optional[str] = None # informational, pinned
  50. # Static env for the stdio subprocess (telemetry opt-outs, mode flags). NOT for secrets — those
  51. # go through auth.env so they are prompted for and land in ~/.hermes/.env.
  52. env: dict[str, str] = field(default_factory=dict)
  53. @dataclass
  54. class InstallSpec:
  55. """Optional bootstrap step (git clone + dep install)."""
  56. type: str # "git"
  57. url: str
  58. ref: str # commit/tag/branch — pinned, never floats
  59. bootstrap: list[str] = field(default_factory=list)
  60. @dataclass
  61. class ToolsSpec:
  62. """Manifest-side tool-selection hints (see _apply_tool_selection()).
  63. ``default_enabled``: pre-checked in the install checklist / applied directly on probe failure;
  64. None => all pre-checked (no filter written on failure). ``default_excluded``: exclude-mode
  65. counterpart written to ``tools.exclude`` — everything NOT matching stays enabled, including tools
  66. the server adds later (for huge OpenAPI-derived surfaces). Mutually exclusive.
  67. """
  68. default_enabled: Optional[list[str]] = None
  69. default_excluded: Optional[list[str]] = None
  70. @dataclass
  71. class SuggestSpec:
  72. """Composer-suggestion metadata (desktop "brand pill" triggers).
  73. GitHub is intentionally NOT in the catalog and must not be suggested here: its hosted MCP needs a
  74. per-host OAuth app (generic DCR 404s) and the bundled github/* skills are far more capable.
  75. """
  76. keywords: list[str] = field(default_factory=list) # lowercase whole-word/phrase triggers
  77. hosts: list[str] = field(default_factory=list) # hostname suffixes ("atlassian.net")
  78. applications: list[str] = field(default_factory=list) # reviewed local app labels/aliases
  79. examples: list[str] = field(default_factory=list) # capability examples, not executable instructions
  80. requires_app: bool = False # local app prerequisite, unlike cloud services with desktop clients
  81. @dataclass
  82. class CatalogEntry:
  83. name: str
  84. description: str
  85. source: str
  86. transport: TransportSpec
  87. auth: AuthSpec
  88. connector_slug: Optional[str] = None
  89. tools: ToolsSpec = field(default_factory=ToolsSpec)
  90. install: Optional[InstallSpec] = None
  91. post_install: str = ""
  92. suggest: Optional[SuggestSpec] = None
  93. manifest_path: Path = field(default_factory=Path)
  94. class CatalogError(Exception):
  95. """Manifest parse/validation failure or install error.
  96. ``failure_class`` names the raise site for the extension-install metric (a closed name from
  97. ``shared_metrics_contract.EXTENSION_MCP_FAILURE_CLASSES``): manifest problems are
  98. ``config_invalid`` unless the site says otherwise.
  99. """
  100. failure_class = "config_invalid"
  101. def __init__(self, *args, failure_class: Optional[str] = None):
  102. super().__init__(*args)
  103. if failure_class is not None:
  104. self.failure_class = failure_class
  105. def _catalog_root() -> Path:
  106. """The optional-mcps/ dir: env-var override / packaged location, else the source checkout's."""
  107. return get_optional_mcps_dir(Path(__file__).parent.parent / "optional-mcps")
  108. def _parse_env_spec(raw: Any) -> EnvVarSpec:
  109. if not isinstance(raw, dict):
  110. raise CatalogError(f"env entry must be a mapping, got {type(raw).__name__}")
  111. name = raw.get("name") or ""
  112. if not name or not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name):
  113. raise CatalogError(f"invalid env var name: {name!r}")
  114. return EnvVarSpec(
  115. name=name, prompt=raw.get("prompt") or name, required=bool(raw.get("required", True)),
  116. secret=bool(raw.get("secret", True)), default=str(raw.get("default") or ""))
  117. def _require_mapping(path: Path, key: str, raw: Any) -> dict:
  118. if not isinstance(raw, dict):
  119. raise CatalogError(f"{path}: '{key}' must be a mapping")
  120. return raw
  121. def _require_list(path: Path, field: str, raw: Any) -> list:
  122. if not isinstance(raw, list):
  123. raise CatalogError(f"{path}: {field} must be a list")
  124. return raw
  125. def _require_str_list(path: Path, field: str, raw: Any, *, non_empty: bool = False) -> None:
  126. ok = isinstance(raw, list) and all(isinstance(t, str) and (t.strip() if non_empty else True) for t in raw)
  127. if not ok:
  128. kind = "non-empty strings" if non_empty else "strings"
  129. raise CatalogError(f"{path}: {field} must be a list of {kind}")
  130. def _parse_transport(path: Path, raw: Any) -> TransportSpec:
  131. transport_raw = _require_mapping(path, "transport", raw or {})
  132. t_type = transport_raw.get("type")
  133. if t_type not in ("stdio", "http"):
  134. raise CatalogError(f"{path}: transport.type must be 'stdio' or 'http'")
  135. args = _require_list(path, "transport.args", transport_raw.get("args") or [])
  136. env_raw = transport_raw.get("env") or {}
  137. if not isinstance(env_raw, dict) or not all(
  138. isinstance(k, str) and isinstance(v, str) for k, v in env_raw.items()
  139. ):
  140. raise CatalogError(f"{path}: transport.env must be a mapping of string to string")
  141. transport = TransportSpec(
  142. type=t_type, command=transport_raw.get("command"), args=[str(a) for a in args],
  143. url=transport_raw.get("url"), version=transport_raw.get("version"), env=dict(env_raw))
  144. if t_type == "stdio" and not transport.command:
  145. raise CatalogError(f"{path}: stdio transport requires 'command'")
  146. if t_type == "http" and not transport.url:
  147. raise CatalogError(f"{path}: http transport requires 'url'")
  148. return transport
  149. def _parse_auth(path: Path, raw: Any, name: str, http: bool) -> AuthSpec:
  150. auth_raw = _require_mapping(path, "auth", raw or {"type": "none"})
  151. a_type = auth_raw.get("type") or "none"
  152. if a_type not in ("api_key", "oauth", "none"):
  153. raise CatalogError(f"{path}: auth.type must be 'api_key'|'oauth'|'none'")
  154. env_list = [_parse_env_spec(e) for e in _require_list(path, "auth.env", auth_raw.get("env") or [])]
  155. if http and a_type == "api_key":
  156. # _build_server_config emits an Authorization header referencing ${MCP_<NAME>_API_KEY}, but
  157. # install_entry only persists the env vars DECLARED in auth.env. Enforce the naming contract
  158. # here, or a manifest declaring e.g. N8N_API_KEY would send a literal-placeholder header (401).
  159. from hermes_cli.mcp_config import _env_key_for_server
  160. _required_key = _env_key_for_server(name)
  161. if all(spec.name != _required_key for spec in env_list):
  162. raise CatalogError(
  163. f"{path}: http + api_key auth requires auth.env to declare "
  164. f"'{_required_key}' (the key the Authorization header references)"
  165. )
  166. oauth_raw = auth_raw.get("oauth") or {}
  167. if oauth_raw and a_type != "oauth":
  168. raise CatalogError(f"{path}: auth.oauth is only valid with auth.type 'oauth'")
  169. oauth = _require_mapping(path, "auth.oauth", oauth_raw)
  170. unknown = sorted(set(oauth) - _MANIFEST_OAUTH_KEYS)
  171. if unknown or not all(isinstance(v, (str, int)) and not isinstance(v, bool) for v in oauth.values()):
  172. raise CatalogError(
  173. f"{path}: auth.oauth allows string/int values for {sorted(_MANIFEST_OAUTH_KEYS)} only"
  174. + (f" (unknown: {unknown})" if unknown else "")
  175. )
  176. # Same contract as api_key headers: install_entry persists only DECLARED env vars, so an
  177. # undeclared ``${VAR}`` would reach the OAuth flow as a literal placeholder (invalid_client).
  178. declared = {spec.name for spec in env_list}
  179. undeclared = sorted({ref for v in oauth.values() if isinstance(v, str) for ref in _ENV_REF_RE.findall(v)} - declared)
  180. if undeclared:
  181. raise CatalogError(f"{path}: auth.oauth references env vars not declared in auth.env: {undeclared}")
  182. return AuthSpec(
  183. type=a_type, env=env_list, provider=auth_raw.get("provider"),
  184. scopes=list(auth_raw.get("scopes") or []), env_var=auth_raw.get("env_var"), oauth=dict(oauth))
  185. def _parse_tools(path: Path, raw: Any) -> ToolsSpec:
  186. tools_raw = _require_mapping(path, "tools", raw or {})
  187. default_enabled = tools_raw.get("default_enabled")
  188. default_excluded = tools_raw.get("default_excluded")
  189. for key, val in (("default_enabled", default_enabled), ("default_excluded", default_excluded)):
  190. if val is not None:
  191. _require_str_list(path, f"tools.{key}", val)
  192. if default_enabled is not None and default_excluded is not None:
  193. raise CatalogError(f"{path}: tools.default_enabled and tools.default_excluded are mutually exclusive")
  194. return ToolsSpec(default_enabled=default_enabled, default_excluded=default_excluded)
  195. _MAX_APPLICATIONS = 16
  196. _APP_LABEL = re.compile(r"[A-Za-z0-9][A-Za-z0-9 ._+-]{0,79}")
  197. def _validate_applications(labels: object) -> list[str]:
  198. """Accept bounded display labels/aliases, never paths, commands or regexes."""
  199. if not isinstance(labels, list) or len(labels) > _MAX_APPLICATIONS:
  200. raise ValueError("suggest.applications must be a list of at most 16 app labels")
  201. for label in labels:
  202. if (not isinstance(label, str) or not _APP_LABEL.fullmatch(label)
  203. or label != label.strip() or ".." in label or " --" in label):
  204. raise ValueError("suggest.applications must contain safe app labels (1–80 characters)")
  205. return list(labels)
  206. def _parse_suggest(path: Path, suggest_raw: Any) -> Optional[SuggestSpec]:
  207. if suggest_raw is None:
  208. return None
  209. _require_mapping(path, "suggest", suggest_raw)
  210. kw_raw = suggest_raw.get("keywords") or []
  211. hosts_raw = suggest_raw.get("hosts") or []
  212. _require_str_list(path, "suggest.keywords", kw_raw, non_empty=True)
  213. _require_str_list(path, "suggest.hosts", hosts_raw, non_empty=True)
  214. try:
  215. applications = _validate_applications(suggest_raw.get("applications", []))
  216. except ValueError as exc:
  217. raise CatalogError(f"{path}: {exc}") from exc
  218. examples = suggest_raw.get("examples", [])
  219. _require_str_list(path, "suggest.examples", examples, non_empty=True)
  220. if len(examples) > 6 or any(len(e) > 240 or not e.isprintable() for e in examples):
  221. raise CatalogError(f"{path}: suggest.examples allows at most 6 single-line examples of 240 characters")
  222. requires_app = suggest_raw.get("requires_app", False)
  223. if not isinstance(requires_app, bool) or (requires_app and not applications):
  224. raise CatalogError(f"{path}: suggest.requires_app must be a boolean, with applications when true")
  225. if not kw_raw and not hosts_raw and not applications:
  226. raise CatalogError(f"{path}: 'suggest' requires at least one keyword, host or application")
  227. # Matching is case-insensitive whole-word / host-suffix: store lowercase so UIs needn't re-normalize.
  228. return SuggestSpec(
  229. keywords=[k.strip().lower() for k in kw_raw],
  230. hosts=[h.strip().lower().lstrip(".") for h in hosts_raw],
  231. applications=applications, examples=examples, requires_app=requires_app)
  232. def _parse_connector_slug(path: Path, value: Any) -> Optional[str]:
  233. if value is None:
  234. return None
  235. if not isinstance(value, str) or not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", value):
  236. raise CatalogError(f"{path}: connector_slug must be a hosted connector slug")
  237. return value
  238. def _parse_install(path: Path, install_raw: Any) -> Optional[InstallSpec]:
  239. if install_raw is None:
  240. return None
  241. _require_mapping(path, "install", install_raw)
  242. i_type = install_raw.get("type")
  243. if i_type != "git":
  244. raise CatalogError(f"{path}: install.type must be 'git' (got {i_type!r})")
  245. url, ref = install_raw.get("url") or "", install_raw.get("ref") or ""
  246. if not url or not ref:
  247. raise CatalogError(f"{path}: install.url and install.ref are required")
  248. bootstrap = _require_list(path, "install.bootstrap", install_raw.get("bootstrap") or [])
  249. return InstallSpec(type=i_type, url=url, ref=ref, bootstrap=[str(c) for c in bootstrap])
  250. def _parse_manifest(path: Path) -> CatalogEntry:
  251. """Read and validate a manifest.yaml. Raise CatalogError on any problem."""
  252. try:
  253. with open(path, "r", encoding="utf-8-sig") as f:
  254. data = yaml.safe_load(f) or {}
  255. except Exception as exc:
  256. raise CatalogError(f"failed to read {path}: {exc}") from exc
  257. if not isinstance(data, dict):
  258. raise CatalogError(f"{path}: manifest must be a mapping")
  259. mv = data.get("manifest_version")
  260. if mv != _MANIFEST_VERSION:
  261. raise CatalogError(
  262. f"{path}: manifest_version {mv!r} unsupported "
  263. f"(this Hermes understands version {_MANIFEST_VERSION})"
  264. )
  265. name = data.get("name") or ""
  266. if not name or not re.match(r"^[A-Za-z0-9_-]+$", name):
  267. raise CatalogError(f"{path}: invalid or missing 'name'")
  268. description = str(data.get("description") or "").strip()
  269. if not description:
  270. raise CatalogError(f"{path}: 'description' required")
  271. # Validation order (transport, auth, tools, suggest, install) determines which error surfaces.
  272. transport = _parse_transport(path, data.get("transport"))
  273. auth = _parse_auth(path, data.get("auth"), name, transport.type == "http")
  274. tools = _parse_tools(path, data.get("tools"))
  275. suggest = _parse_suggest(path, data.get("suggest"))
  276. connector_slug = _parse_connector_slug(path, data.get("connector_slug"))
  277. install = _parse_install(path, data.get("install"))
  278. return CatalogEntry(
  279. name=name, description=description, source=str(data.get("source") or "").strip(),
  280. transport=transport, auth=auth, connector_slug=connector_slug, tools=tools, install=install,
  281. post_install=str(data.get("post_install") or ""), suggest=suggest, manifest_path=path,
  282. )
  283. # Populated by list_catalog(); inspected by the picker / catalog UIs so the user gets actionable
  284. # feedback instead of a silently-shorter list.
  285. _CATALOG_DIAGNOSTICS: list[tuple] = []
  286. def list_catalog() -> list[CatalogEntry]:
  287. """Return all valid catalog entries, sorted by name.
  288. Invalid manifests are skipped silently (CI catches them); future ``manifest_version`` ones are
  289. skipped too but surfaced via :func:`catalog_diagnostics` so UIs can say "update Hermes".
  290. """
  291. root = _catalog_root()
  292. if not root.exists():
  293. return []
  294. entries: list[CatalogEntry] = []
  295. _CATALOG_DIAGNOSTICS.clear()
  296. for child in sorted(root.iterdir()):
  297. manifest = child / "manifest.yaml"
  298. if not manifest.is_file():
  299. continue
  300. try:
  301. entries.append(_parse_manifest(manifest))
  302. except CatalogError as exc:
  303. msg = str(exc)
  304. future = "manifest_version" in msg and "unsupported" in msg
  305. _CATALOG_DIAGNOSTICS.append((child.name, "future_manifest" if future else "invalid", msg))
  306. return entries
  307. def catalog_diagnostics() -> list[tuple]:
  308. """``(entry_name, kind, message)`` tuples from the most recent :func:`list_catalog` call;
  309. ``kind`` is ``future_manifest`` (newer than this Hermes) or ``invalid`` (malformed)."""
  310. return list(_CATALOG_DIAGNOSTICS)
  311. def get_entry(name: str) -> Optional[CatalogEntry]:
  312. """Look up a single entry by name. ``official/<name>`` prefix accepted."""
  313. name = name.removeprefix("official/")
  314. return next((e for e in list_catalog() if e.name == name), None)
  315. def installed_servers() -> dict[str, dict]:
  316. """Return current ``mcp_servers`` block from config.yaml."""
  317. from hermes_cli.mcp_config import _get_mcp_servers
  318. return _get_mcp_servers()
  319. def is_installed(name: str) -> bool:
  320. return name in installed_servers()
  321. def server_enabled(cfg: dict) -> bool:
  322. """Whether the server block is on: the same reader the MCP client uses."""
  323. from tools.mcp_tool_common import mcp_server_enabled
  324. return mcp_server_enabled(cfg)
  325. def is_enabled(name: str) -> bool:
  326. cfg = installed_servers().get(name)
  327. return bool(cfg) and server_enabled(cfg)
  328. def remove_server(name: str) -> bool:
  329. """Drop ``mcp_servers.<name>`` from config.yaml (pruning an empty block). True if it existed."""
  330. from hermes_cli.mcp_config import _remove_mcp_server
  331. return _remove_mcp_server(name)
  332. def _say(msg: str, colour: str = Colors.GREEN) -> None:
  333. print(color(msg, colour))
  334. def _install_root() -> Path:
  335. """Where git-bootstrapped MCPs are cloned. Per-user, profile-aware."""
  336. root = get_hermes_home() / "mcp-installs"
  337. root.mkdir(parents=True, exist_ok=True)
  338. return root
  339. def _run_bootstrap(cwd: Path, commands: list[str]) -> None:
  340. """Execute bootstrap commands in *cwd*. Raise CatalogError on first failure."""
  341. for cmd in commands:
  342. _say(f" $ {cmd}", Colors.DIM)
  343. rc = subprocess.run(cmd, cwd=str(cwd), shell=True, check=False).returncode
  344. if rc != 0:
  345. raise CatalogError(f"bootstrap step failed (exit {rc}): {cmd}", failure_class="bootstrap_failed")
  346. def _do_git_install(entry: CatalogEntry) -> Path:
  347. """Clone the entry's repo into ``~/.hermes/mcp-installs/<name>`` and run bootstrap. Returns the dir."""
  348. assert entry.install is not None and entry.install.type == "git"
  349. install = entry.install
  350. dest = _install_root() / entry.name
  351. git = shutil.which("git")
  352. if not git:
  353. raise CatalogError("git is required to install this MCP but was not found on PATH", failure_class="git_missing")
  354. if dest.exists():
  355. # Fresh checkout each install — the manifest ref is the source of truth.
  356. _say(f" Removing existing install at {dest}", Colors.DIM)
  357. rmtree_readonly(dest)
  358. _say(f" Cloning {install.url} ({install.ref}) → {dest}", Colors.CYAN)
  359. # `git clone --branch` only accepts branches/tags, NOT commit SHAs; detect SHA-shaped refs
  360. # upfront so the fast path doesn't always fail noisily before the full-clone fallback.
  361. is_sha_ref = bool(re.fullmatch(r"[0-9a-f]{7,40}", install.ref))
  362. # Never hang on a credential prompt: installs run from CLI/dashboard flows nobody can answer.
  363. from hermes_cli.git_credentials import run_git_with_credential_fallback
  364. def _git(*args: str) -> int:
  365. result = run_git_with_credential_fallback(
  366. [git, *args], install.url, env=noninteractive_git_env(),
  367. capture_output=True, text=True, encoding="utf-8", errors="replace")
  368. if result.returncode != 0 and (result.stderr or "").strip():
  369. _say(result.stderr.strip(), Colors.DIM)
  370. return result.returncode
  371. if not is_sha_ref and _git("clone", "--depth", "1", "--branch", install.ref, install.url, str(dest)) != 0:
  372. # Branch/tag form failed (e.g. ref deleted upstream): fall through to full-clone path.
  373. if dest.exists():
  374. rmtree_readonly(dest)
  375. is_sha_ref = True
  376. if is_sha_ref:
  377. if _git("clone", install.url, str(dest)) != 0:
  378. raise CatalogError(f"git clone failed for {install.url}", failure_class="clone_failed")
  379. if _git("-C", str(dest), "checkout", install.ref) != 0:
  380. raise CatalogError(f"git checkout {install.ref} failed", failure_class="clone_failed")
  381. if install.bootstrap:
  382. _run_bootstrap(dest, install.bootstrap)
  383. return dest
  384. def _expand_install_dir(value: str, install_dir: Optional[Path]) -> str:
  385. if _INSTALL_DIR_VAR not in value:
  386. return value
  387. if install_dir is None:
  388. raise CatalogError(f"manifest references {_INSTALL_DIR_VAR} but no install block exists")
  389. return value.replace(_INSTALL_DIR_VAR, str(install_dir))
  390. def _prompt_env_vars(specs: list[EnvVarSpec], preloaded: Optional[dict[str, str]] = None) -> dict[str, str]:
  391. """Prompt for each env spec.
  392. Secrets persist to ~/.hermes/.env. Non-secrets are only collected and
  393. returned — the caller inlines them into the server config (config.yaml),
  394. since .env is secrets-only. Values already supplied by the caller
  395. (``preloaded``, e.g. from a dashboard form) skip the prompt.
  396. """
  397. preloaded = preloaded or {}
  398. collected: dict[str, str] = {}
  399. for spec in specs:
  400. pre = preloaded.get(spec.name)
  401. if pre:
  402. collected[spec.name] = pre
  403. continue
  404. existing = get_env_value(spec.name) if spec.secret else None
  405. if existing:
  406. _say(f" ✓ {spec.name} already set in .env")
  407. collected[spec.name] = existing
  408. continue
  409. value = _prompt_input(spec.prompt, default=spec.default or None, password=spec.secret)
  410. if value:
  411. if spec.secret:
  412. save_env_value(spec.name, value)
  413. collected[spec.name] = value
  414. elif spec.required:
  415. raise CatalogError(f"{spec.name} is required but no value was provided",
  416. failure_class="missing_credentials")
  417. return collected
  418. def _inline_non_secret_value(obj: Any, name: str, value: str) -> Any:
  419. """Recursively replace literal ``${name}`` refs with the collected value.
  420. Only non-secret env vars are inlined this way: secret refs stay as
  421. ``${VAR}`` so config.yaml never carries credentials (resolved from .env
  422. at load time).
  423. """
  424. if isinstance(obj, str):
  425. return obj.replace("${" + name + "}", value)
  426. if isinstance(obj, dict):
  427. return {k: _inline_non_secret_value(v, name, value) for k, v in obj.items()}
  428. if isinstance(obj, list):
  429. return [_inline_non_secret_value(v, name, value) for v in obj]
  430. return obj
  431. def _build_server_config(entry: CatalogEntry, install_dir: Optional[Path]) -> dict:
  432. """Translate a manifest into the ``mcp_servers.<name>`` block format used by hermes_cli/mcp_config.py."""
  433. cfg: dict = {}
  434. t = entry.transport
  435. if t.type == "stdio":
  436. cfg["command"] = _expand_install_dir(t.command or "", install_dir)
  437. if t.args:
  438. cfg["args"] = [_expand_install_dir(a, install_dir) for a in t.args]
  439. if t.env:
  440. cfg["env"] = dict(t.env)
  441. elif t.type == "http":
  442. cfg["url"] = t.url
  443. if entry.auth.type == "oauth":
  444. cfg["auth"] = "oauth"
  445. if entry.auth.oauth:
  446. cfg["oauth"] = dict(entry.auth.oauth)
  447. elif entry.auth.type == "api_key":
  448. from hermes_cli.mcp_config import _bearer_auth_headers
  449. cfg["headers"] = _bearer_auth_headers(entry.name)
  450. return cfg
  451. def _read_prior_tool_list(name: str, key: str) -> Optional[list[str]]:
  452. """The user's prior ``tools.<key>`` (``include``/``exclude``) for *name*, if well-formed.
  453. Read BEFORE a reinstall overwrites the entry: a prior include list pre-checks the checklist and a
  454. user-edited exclude list survives instead of being clobbered by the manifest's ``default_excluded``.
  455. """
  456. tools_cfg = (installed_servers().get(name) or {}).get("tools") or {}
  457. if not isinstance(tools_cfg, dict):
  458. return None
  459. value = tools_cfg.get(key)
  460. ok = isinstance(value, list) and all(isinstance(t, str) for t in value)
  461. return list(value) if ok else None
  462. def _probe_tools(name: str) -> Optional[list[tuple]]:
  463. """Connect to a freshly-configured MCP and list its tools.
  464. ``(tool_name, description)`` tuples on success, ``None`` on any failure (unreachable, OAuth not
  465. yet completed, ...). Failures are swallowed here; :func:`_apply_tool_selection` handles them.
  466. """
  467. server_cfg = installed_servers().get(name)
  468. if not server_cfg:
  469. return None
  470. try:
  471. from hermes_cli.mcp_config import _probe_single_server # lazy: keep this module cheap
  472. tools = _probe_single_server(name, server_cfg)
  473. return list(tools) if tools is not None else []
  474. except Exception as exc:
  475. _say(f" Probe failed: {exc}", Colors.YELLOW)
  476. return None
  477. def _write_tools_filter(name: str, mode: str, values: Optional[list[str]]) -> None:
  478. """Persist ``mcp_servers.<name>.tools.<mode>`` (``include``/``exclude``), clearing the other
  479. mode; ``values=None`` drops the whole tools block (no filter)."""
  480. cfg = load_config()
  481. servers = cfg.setdefault("mcp_servers", {})
  482. server_entry = servers.get(name) or {}
  483. if values is None:
  484. server_entry.pop("tools", None)
  485. else:
  486. tools_block = server_entry.get("tools") or {}
  487. if not isinstance(tools_block, dict):
  488. tools_block = {}
  489. tools_block[mode] = list(values)
  490. tools_block.pop("exclude" if mode == "include" else "include", None)
  491. server_entry["tools"] = tools_block
  492. servers[name] = server_entry
  493. cfg["mcp_servers"] = servers
  494. save_config(cfg)
  495. def _apply_tool_selection(
  496. entry: CatalogEntry,
  497. *,
  498. prior_selection: Optional[list[str]],
  499. prior_exclude: Optional[list[str]] = None) -> None:
  500. """Probe the server and let the user pick which tools to enable.
  501. Probe-success: curses checklist; pre-check priority *prior_selection* (reinstall) > manifest
  502. ``tools.default_enabled`` > all; all-on clears any filter. Probe-fail: keep the prior filter,
  503. else apply ``default_enabled``, else no filter; point the user at ``hermes mcp configure``.
  504. """
  505. print()
  506. name = entry.name
  507. configure_hint = f"`hermes mcp configure {name}`"
  508. # Exclude-mode manifests never probe: the curated exclude list (names or globs) is written as-is
  509. # and everything else stays enabled, including tools the server adds later. A prior include
  510. # selection falls through to the checklist; a prior user-edited exclude list is kept verbatim.
  511. if entry.tools.default_excluded and prior_selection is None:
  512. edit_hint = f"Edit mcp_servers.{name}.tools.exclude in config.yaml or run {configure_hint} to change."
  513. if prior_exclude is not None:
  514. _write_tools_filter(name, "exclude", prior_exclude)
  515. _say(f" Kept your existing exclude list ({len(prior_exclude)} entries). {edit_hint}")
  516. return
  517. _write_tools_filter(name, "exclude", entry.tools.default_excluded)
  518. _say(
  519. f" Applied manifest exclude list ({len(entry.tools.default_excluded)} entries); "
  520. f"everything else stays enabled. {edit_hint}"
  521. )
  522. return
  523. _say(f" Probing '{name}' for available tools...", Colors.CYAN)
  524. probed = _probe_tools(name)
  525. # Probe failure. Order matters: a reinstall must keep the user's previous filter intact (common
  526. # for OAuth entries — the entry rewrite precedes first auth, so the server is unreachable here).
  527. if probed is None:
  528. manifest_default = entry.tools.default_enabled
  529. refine_hint = f"Run {configure_hint} after the server is reachable to refine."
  530. if prior_selection is not None:
  531. mode, values = "include", prior_selection
  532. msg = f"Kept your previous tool selection ({len(prior_selection)} tools). {refine_hint}"
  533. elif prior_exclude is not None:
  534. mode, values = "exclude", prior_exclude
  535. msg = f"Kept your existing exclude list ({len(prior_exclude)} entries)."
  536. elif manifest_default:
  537. mode, values = "include", manifest_default
  538. msg = f"Applied manifest default ({len(manifest_default)} tools). {refine_hint}"
  539. else:
  540. mode, values = "include", None
  541. msg = (
  542. "installed with no tool filter (all tools enabled when "
  543. f"reachable). Run {configure_hint} after first connect to prune."
  544. )
  545. _write_tools_filter(name, mode, values)
  546. sep = ";" if values is None else "."
  547. _say(f" Couldn't probe server{sep} {msg}", Colors.YELLOW)
  548. return
  549. if not probed:
  550. # Keep a prior explicit selection: "no tools today" must not widen ``include: []`` to
  551. # "all tools" the next time the server does advertise some.
  552. _write_tools_filter(name, "include", prior_selection)
  553. _say(" Server reported no tools.", Colors.YELLOW)
  554. return
  555. tool_names = [t[0] for t in probed]
  556. # Non-TTY: skip the checklist; same priority as the interactive pre-check.
  557. import sys as _sys
  558. if not _sys.stdin.isatty():
  559. preferred = prior_selection if prior_selection is not None else (entry.tools.default_enabled or None)
  560. _write_tools_filter(
  561. name, "include", None if preferred is None else [n for n in preferred if n in tool_names]
  562. )
  563. return
  564. # A prior ``include: []`` (user chose zero tools) outranks manifest defaults, like the non-TTY path.
  565. preferred = prior_selection if prior_selection is not None else (entry.tools.default_enabled or tool_names)
  566. pre_set = {n for n in preferred if n in tool_names}
  567. pre_indices = {i for i, n in enumerate(tool_names) if n in pre_set}
  568. _say(f" Found {len(probed)} tool(s). Pre-checked: {len(pre_indices)}.")
  569. from hermes_cli.curses_ui import curses_checklist
  570. labels = [f"{n} — {(d[:60] + '...') if len(d) > 60 else d}" for n, d in probed]
  571. chosen_indices = curses_checklist(
  572. f"Select tools for '{name}' (SPACE toggle, ENTER confirm)", labels, pre_indices)
  573. if not chosen_indices:
  574. # Everything unchecked: write an empty include so the server is installed but contributes
  575. # nothing until reconfigured.
  576. _write_tools_filter(name, "include", [])
  577. _say(f" No tools selected. Run {configure_hint} to change.", Colors.YELLOW)
  578. return
  579. if len(chosen_indices) == len(probed):
  580. # Clear the filter: tools the server adds later are auto-enabled too. To pin the current set,
  581. # re-run `hermes mcp configure <name>` and unselect a tool (switches to include-mode).
  582. _write_tools_filter(name, "include", None)
  583. _say(
  584. f" ✓ All {len(probed)} tools enabled (no filter — new tools "
  585. "the server adds later will be auto-enabled)."
  586. )
  587. return
  588. chosen_names = [tool_names[i] for i in sorted(chosen_indices)]
  589. _write_tools_filter(name, "include", chosen_names)
  590. _say(f" ✓ {len(chosen_names)}/{len(probed)} tools enabled.")
  591. def card_install_config(entry: CatalogEntry) -> dict:
  592. """The ``mcp_servers.<name>`` block a connection card installs, built in memory.
  593. Same block :func:`install_entry` writes, minus everything a terminal owns: no prompts, no
  594. probe, no checklist. The caller saves it only once the server accepted the connection. Tool
  595. filter priority matches :func:`_apply_tool_selection`: a prior user selection survives a
  596. reinstall, else the manifest's curated filter, else none.
  597. """
  598. install_dir = _do_git_install(entry) if entry.install is not None else None
  599. cfg = _build_server_config(entry, install_dir)
  600. cfg["enabled"] = True
  601. prior_include = _read_prior_tool_list(entry.name, "include")
  602. prior_exclude = _read_prior_tool_list(entry.name, "exclude")
  603. if prior_include is not None:
  604. cfg["tools"] = {"include": prior_include}
  605. elif prior_exclude is not None:
  606. cfg["tools"] = {"exclude": prior_exclude}
  607. elif entry.tools.default_excluded:
  608. cfg["tools"] = {"exclude": list(entry.tools.default_excluded)}
  609. elif entry.tools.default_enabled:
  610. cfg["tools"] = {"include": list(entry.tools.default_enabled)}
  611. return cfg
  612. def record_mcp_install(source: str, name: Optional[str], outcome: str, *, failure_class: Optional[str] = None,
  613. error: Optional[BaseException] = None) -> None:
  614. """One shared-metrics extension install for an MCP server (catalog entry name, or None when custom).
  615. A failed one names its ``failure_class`` or passes the raised ``error`` (classified by its type)."""
  616. from hermes_cli.observability.shared_metrics_events import record_extension_install
  617. record_extension_install(kind="mcp_server", source=source, name=name, outcome=outcome,
  618. failure_class=failure_class, error=error)
  619. @contextmanager
  620. def recorded_catalog_install(name: str) -> Iterator[None]:
  621. """Record a first install of catalog entry *name* once: failed when the body raises, else
  622. success. A reinstall over an existing ``mcp_servers`` block is not an install."""
  623. fresh = not is_installed(name)
  624. try:
  625. yield
  626. except Exception as exc:
  627. if fresh:
  628. record_mcp_install("catalog", name, "failed", error=exc)
  629. raise
  630. if fresh:
  631. record_mcp_install("catalog", name, "success")
  632. def install_entry(entry: CatalogEntry, *, enable: bool = True, preloaded_env: Optional[dict[str, str]] = None) -> None:
  633. with recorded_catalog_install(entry.name):
  634. _install_entry(entry, enable=enable, preloaded_env=preloaded_env)
  635. def _install_entry(entry: CatalogEntry, *, enable: bool, preloaded_env: Optional[dict[str, str]]) -> None:
  636. """Install a catalog entry end-to-end.
  637. Order: git clone + bootstrap (if any); credential prompts (``auth.env``) to .env; write
  638. ``mcp_servers.<name>`` (with the ``auth: oauth`` marker and any pre-registered ``oauth`` block); probe + tool checklist (falling back per
  639. :func:`_apply_tool_selection`); print post_install notes.
  640. ``preloaded_env`` carries env values already supplied by the caller (e.g.
  641. the dashboard form); they skip the interactive prompt.
  642. """
  643. print()
  644. _say(f" Installing MCP '{entry.name}'", Colors.CYAN + Colors.BOLD)
  645. if entry.description:
  646. _say(f" {entry.description}", Colors.DIM)
  647. if entry.source:
  648. _say(f" Source: {entry.source}", Colors.DIM)
  649. print()
  650. install_dir = _do_git_install(entry) if entry.install is not None else None
  651. env_values: dict[str, str] = {}
  652. if entry.auth.env:
  653. print()
  654. _say(" Configure credentials:", Colors.CYAN)
  655. env_values = _prompt_env_vars(entry.auth.env, preloaded_env or {})
  656. if entry.auth.type == "oauth" and entry.auth.provider:
  657. # Provider-mediated OAuth relies on the existing `hermes auth <provider>` flow; surface
  658. # guidance rather than auto-running it to keep install decoupled from provider-auth lifecycle.
  659. _say(
  660. f" This MCP uses {entry.auth.provider} OAuth. Run "
  661. f"`hermes auth {entry.auth.provider}` if you have not "
  662. "already authenticated.",
  663. Colors.YELLOW)
  664. elif entry.auth.type == "oauth":
  665. client = "your pre-registered OAuth client" if entry.auth.oauth.get("client_id") else "native OAuth 2.1"
  666. _say(
  667. f" This MCP uses {client}; tokens will be acquired "
  668. "on first connection (browser flow).",
  669. Colors.DIM)
  670. # Read prior user selection BEFORE overwriting the entry so a reinstall preserves it.
  671. prior_selection = _read_prior_tool_list(entry.name, "include")
  672. prior_exclude = _read_prior_tool_list(entry.name, "exclude")
  673. server_cfg = _build_server_config(entry, install_dir)
  674. # Inline non-secret env values into config.yaml; secrets keep their ${VAR}
  675. # refs so the raw file never carries credentials (resolved from .env at load).
  676. for spec in entry.auth.env:
  677. if not spec.secret and spec.name in env_values:
  678. server_cfg = _inline_non_secret_value(server_cfg, spec.name, env_values[spec.name])
  679. server_cfg["enabled"] = enable
  680. from hermes_cli.mcp_config import _save_mcp_server
  681. if not _save_mcp_server(entry.name, server_cfg):
  682. raise CatalogError(f"catalog entry '{entry.name}' rejected: suspicious command/args configuration",
  683. failure_class="config_rejected")
  684. _apply_tool_selection(entry, prior_selection=prior_selection, prior_exclude=prior_exclude)
  685. print()
  686. _say(
  687. f" ✓ Installed '{entry.name}' "
  688. f"({'enabled' if enable else 'disabled'}). "
  689. f"Start a new Hermes session to load its tools."
  690. )
  691. if entry.post_install:
  692. print()
  693. for line in entry.post_install.strip().splitlines():
  694. _say(f" {line}", Colors.DIM)
  695. print()
  696. def uninstall_entry(name: str, *, purge_install_dir: bool = True) -> bool:
  697. """Remove a catalog-installed MCP from config and (optionally) its clone dir. True if anything removed."""
  698. removed = remove_server(name)
  699. if purge_install_dir:
  700. clone = _install_root() / name
  701. if clone.exists():
  702. rmtree_readonly(clone)
  703. removed = True
  704. return removed