`gjtZUdZddlmZddlZddlZddlZddlmZmZddl m Z ddl m Z m Z mZmZddlZddlmZmZddlmZmZdd lmZmZmZmZdd lmZd Zd Z eGd dZ!eGddZ"eGddZ#eGddZ$eGddZ%eGddZ&Gdde'Z(d5dZ)d6dZ*d7dZ+d8dZ,gZ-de.d <d9d!Z/d:d"Z0d;d#Z1dd(Z6d?d)Z7d@d*Z8 dAd+Z9dBd,Z:dCd-Z;dDd.Z< dEd/Z=d0d1dFd2Z>d0d3dGd4Z?y)HugMCP catalog — curated, Nous-approved MCP servers shipped with the repo. Mirrors the optional-skills/ pattern: each catalog entry lives under ``optional-mcps//manifest.yaml`` and ships disabled. Users discover entries via ``hermes mcp catalog`` or the interactive ``hermes mcp picker``, and install them with ``hermes mcp install `` (or by toggling in the picker, which flows them through any required env/OAuth setup). Catalog policy: - Entries are added only by merging a PR into hermes-agent. Presence in the ``optional-mcps/`` directory = Nous approval. No community tier, no trust signals beyond "it's in the catalog". - Manifests pin transport details (commands, args, refs). Pins follow the same supply-chain rules as pyproject dependencies: exact versions for package launchers (``uvx pkg==X``, ``npx pkg@X``), full commit SHAs for git installs, and the pinned release should be at least 2 weeks old at pin time. MCPs are never auto-updated; users explicitly re-run ``hermes mcp install `` to pull a new manifest version after a repo update. - Secrets prompted at install time go to ``~/.hermes/.env`` (the .env-is-for-secrets rule). Non-secret env vars also go to .env to keep one credential store. See website/docs/user-guide/mcp-catalog.md for user docs. See references/mcp-catalog.md (this repo's skill) for the manifest schema. ) annotationsN) dataclassfield)Path)AnyDictListOptional)get_hermes_homeget_optional_mcps_dir)Colorscolor) load_config save_config get_env_valuesave_env_value)promptz${INSTALL_DIR}cLeZdZUded<ded<dZded<dZded<dZded <y ) EnvVarSpecstrnamerTboolrequiredsecretdefaultN)__name__ __module__ __qualname____annotations__rrrI/root/.hermes/venv/lib/python3.12/site-packages/hermes_cli/mcp_catalog.pyrr:s* I KHdFDGSr#rcleZdZUded<eeZded<dZded<eeZd ed <dZ ded <y) AuthSpecrtypedefault_factoryList[EnvVarSpec]envN Optional[str]provider List[str]scopesenv_var) rrr r!rlistr+r-r/r0r"r#r$r&r&Cs: I!$7C 7"Hm"d3FI3!G]!r#r&czeZdZUded<dZded<eeZded<dZded <dZ ded <ee Z d ed <y) TransportSpecrr'Nr,commandr(r.argsurlversionDict[str, str]r+) rrr r!r4rr1r5r6r7dictr+r"r#r$r3r3MsE I!G]!D1D)1C!G]! 5C5r#r3cLeZdZUdZded<ded<ded<eeZded<y ) InstallSpeczmOptional bootstrap step (git clone + dep install). Omit for one-shot launchable servers (npx, uvx). rr'r6refr(r. bootstrapN)rrr __doc__r!rr1r=r"r#r$r;r;Zs' I H H 6Iy6r#r;c eZdZUdZdZded<y) ToolsSpeczManifest-side tool-selection hints. Drives the pre-checked state of the install-time tool checklist, and acts as the fallback selection when probe fails. See install_entry() flow. NOptional[List[str]]default_enabled)rrr r>rBr!r"r#r$r@r@fs,0O(/r#r@ceZdZUded<ded<ded<ded<ded<ee Zd ed <d Zd ed<dZded<ee Z ded<y ) CatalogEntryrr descriptionsourcer3 transportr&authr(r@toolsNzOptional[InstallSpec]installr post_installr manifest_path) rrr r!rr@rIrJrKrrLr"r#r$rDrDtsP I K NY7E97%)G ")L#5M45r#rDceZdZdZy) CatalogErrorz3Manifest parse/validation failure or install error.N)rrr r>r"r#r$rNrNs=r#rNc`tttjjdz S)zEReturn the optional-mcps/ directory shipped with this Hermes install.z optional-mcps)r r__file__parentr"r#r$ _catalog_rootrRs$ !h!6!6!=!=!O PPr#c t|ts!tdt|j|j dxsd}|rt jd|std|t||j dxs|t|j ddt|j d dt|j d xsd S) Nz!env entry must be a mapping, got rrz^[A-Za-z_][A-Za-z0-9_]*$zinvalid env var name: rrTrr)rrrrr) isinstancer9rNr'rgetrematchrrr)rawrs r$_parse_env_specrYs c4 >tCy?Q?Q>RSTT 776? bD rxx ;TB3D8<==  wwx (Dcggj$/0CGGHd+,CGGI&,"-  r#c t|dd5}tj|xsi}dddt t st |d|jd}|tk7rt |d |d td |jd xsd }|rtjd|st |dt|jdxsd j}|st |dt|jdxsd j}|jdxsi}t |t st |d|jd} | dvrt |d|jdxsg} t | tst |d|jdxsi} t | t r td| jDst |dt!| |jd| D cgc] } t| c} |jd|jdt |  } | d!k(r| j"st |d"| d#k(r| j$st |d$|jd%xsdd&i}t |t st |d'|jdxsd&}|d(vrt |d)|jdxsg}t |tst |d*|Dcgc] }t'|}}t)|||jd+t|jd,xsg|jd-.}|jd/xsi}t |t st |d0|jd1}|0t |trtd2|Dst |d3t+|4}d}|jd5}|t |t st |d6|jd}|d7k7rt |d8|d |jdxsd }|jd9xsd }|r|st |d:|jd;xsg}t |tst |d<t-||||Dcgc] }t|c}=}t/|||| |||t|jd>xsd |? S#1swYxYw#t$r}t d|d||d}~wwxYwcc} wcc}wcc}w)@zERead and validate a manifest.yaml. Raise CatalogError on any problem.rzutf-8)encodingNzfailed to read z: z: manifest must be a mappingmanifest_versionz: manifest_version z. unsupported (this Hermes understands version )rrz^[A-Za-z0-9_-]+$z: invalid or missing 'name'rEz: 'description' requiredrFrGz: 'transport' must be a mappingr')stdiohttpz*: transport.type must be 'stdio' or 'http'r5z: transport.args must be a listr+c3fK|])\}}t|txrt|t+ywNrTr).0kvs r$ z"_parse_manifest..s/06:a 1c1z!S110s/1z5: transport.env must be a mapping of string to stringr4r6r7)r'r4r5r6r7r+r_z$: stdio transport requires 'command'r`z: http transport requires 'url'rHnonez: 'auth' must be a mapping)api_keyoauthrhz,: auth.type must be 'api_key'|'oauth'|'none'z: auth.env must be a listr-r/r0)r'r+r-r/r0rIz: 'tools' must be a mappingrBc3<K|]}t|tywrbrcrdts r$rgz"_parse_manifest..s< #$Jq# < z1: tools.default_enabled must be a list of strings)rBrJz: 'install' must be a mappinggitz": install.type must be 'git' (got r<z*: install.url and install.ref are requiredr=z": install.bootstrap must be a list)r'r6r<r=rK) rrErFrGrHrIrJrKrL)openyaml safe_load ExceptionrNrTr9rU_MANIFEST_VERSIONrVrWrstripr1allitemsr3r4r6rYr&r@r;rD)pathfdataexcmvrrErF transport_rawt_typer5env_rawarGauth_rawa_type env_list_raweenv_listrH tools_rawrB tools_specrJ install_rawi_typer6r<r=cs r$_parse_manifestrsE $g . +!>>!$*D + dD !dV#?@AA $ %B f'v.00A/B! E  88F  !rD rxx 3T:dV#>?@@dhh}-34::Emmo0-fI J   !!)," #c!f #   e $!!), M I!2!2dV#GHII  dV#BCDDxx3FF#3H h %dV#=>?? \\& ! +VF 11dV#OPQQ<<&,"L lD )dV#<=>>,89q"9H9   j)HLL*0b1 Y'  D!'RI i &dV#>?@@mm$56O"/40< (7< 9 &IJ ?;J%)G((9%K+t,$'DEF F( U?$'I&STUV Vooe$*ooe$*#$'QRS SOOK06B )T*$'IJK K'01!s1v1     .17R8  W + + E_TF"SE:;DET$&:R2s?T<T/T<U 0U$%U)/T94T<< UUUct}|jsgSg}tjt |j D]3}|dz }|j s |jt|5|S#t$rb}t|}d|vr'd|vr#tj|jd|fn"tj|jd|fYd}~d}~wwxYw)aSReturn all valid catalog entries, sorted by name. Invalid manifests are skipped silently (CI tests catch them at PR time). Manifests with a future ``manifest_version`` are also skipped, but the skip is surfaced via :func:`catalog_diagnostics` so the picker / catalog UIs can tell the user their Hermes is out of date. z manifest.yamlr] unsupportedfuture_manifestinvalidN) rRexists_CATALOG_DIAGNOSTICSclearsortediterdiris_fileappendrrNrr)rootentrieschildmanifestr{msgs r$ list_catalogrs ?D ;;= "$G  '?*!   NN?84 5  N c(C"S(]c-A$++UZZ9JC,PQ$++UZZC,HI  s&B C/ AC**C/ List[tuple]rc ttS)uDiagnostics from the most recent :func:`list_catalog` call. Returns a list of ``(entry_name, kind, message)`` tuples where ``kind`` is one of: - ``future_manifest`` — manifest_version is newer than this Hermes understands. Update Hermes to install this entry. - ``invalid`` — manifest is malformed in some other way (caught by CI for shipped manifests; user-modified manifests can hit this). )r1rr"r#r$catalog_diagnosticsr=s $ %%r#c|jdr|tdd}tD]}|j|k(s|cSy)zDLook up a single entry by name. ``official/`` prefix accepted.z official/N) startswithlenrr)rentrys r$ get_entryrJsG {#C $%& :: L r#cht}|jdxsi}t|tr|SiS)z6Return current ``mcp_servers`` block from config.yaml. mcp_servers)rrUrTr9)cfgserverss r$installed_serversrWs0 -Cggm$*G $/77R7r#c|tvSrb)r)rs r$ is_installedr^s $& &&r#ct}|j|}|sy|jdd}t|tr|j dvSt |S)NFenabledT>1yestrue)rrUrTrlowerr)rrrrs r$ is_enabledrbsT!G ++d C ggi&G'3}}"666 =r#cFtdz }|jdd|S)z@Where git-bootstrapped MCPs are cloned. Per-user, profile-aware.z mcp-installsT)parentsexist_ok)r mkdir)rs r$ _install_rootrps$  ~ -DJJtdJ+ Kr#c|D]s}ttd|tjt j |t |d}|jdk7sZtd|jd|y)zExecute bootstrap commands in *cwd*. Raise CatalogError on first failure. Each command runs through the shell (so `&&` etc. work). The output is streamed to the user's terminal for visibility. z $ T)cwdshellrzbootstrap step failed (exit z): N) printrr DIM subprocessrunr returncoderN)rcommandscmdprocs r$_run_bootstraprwsp  ed3%L&**-.~~cs3xt< ??a .t.?s3%H  r#c |j|jjdk(sJ|j}t|jz }t j d}|s t d|jr;ttd|tjt j|ttd|jd|jd|tjt!t#j$d|j}|sqt'j(|dd d d |j|jt+|g}|j,d k(rn'|jrt j|d }|rt'j(|d|jt+|g}|j,d k7rt d|jt'j(|dt+|d|jg}|j,d k7rt d|jd|j.rt1||j.|S)z|Clone the entry's repo into ``~/.hermes/mcp-installs/`` and run bootstrap commands. Returns the install directory.roz=git is required to install this MCP but was not found on PATHz Removing existing install at z Cloning z (u) → z[0-9a-f]{7,40}clonez--depthrz--branchrTzgit clone failed for z-Ccheckoutz git checkout z failed)rJr'rrshutilwhichrNrrrr rrmtreer6r<CYANrrV fullmatchrrrrr=r)rrJdestro is_sha_refrs r$_do_git_installrs == $););u)DD DmmG ?UZZ 'D ,,u C Z[[ {{} e5dV`` block format used by hermes_cli/mcp_config.py.r_rr4r5r+r`r6rjrH) rGr'rr4r5r+r9r6rH)rrrrmrs r$_build_server_configrs C Avv,QYY_"kJI 66HIO1.q+>OCK 55aeeCJ J 6 UUE ::??g %!CK JPsCc t}|j|xsi}|jdxsi}t|tsy|jd}t|trt d|Dr t |Sy)aReturn the user's prior `tools.include` for *name*, if any. Used during reinstalls so the install-time checklist starts pre-checked with whatever the user already had. Tools no longer on the server are silently dropped at checklist-display time. rINincludec3<K|]}t|tywrbrcrls r$rgz-_read_prior_tool_selection..s(MAs);(Mrn)rrUrTr9r1rv)rrr tools_cfgrs r$_read_prior_tool_selectionrsq !G ++d  !rC &BI i &mmI&G'4 S(MW(M%MG} r#ct}|j|}|sy ddlm}|||}| t |SgS#t $r0}t td|tjYd}~yd}~wwxYw)ugConnect to a freshly-configured MCP and list its tools. Returns a list of ``(tool_name, description)`` tuples on success, or ``None`` on any failure (server unreachable, OAuth not yet completed, backing service offline, etc.). Failures are intentionally swallowed here — the fallback path in :func:`_apply_tool_selection` handles them. Nr)_probe_single_serverz Probe failed: ) rrUhermes_cli.mcp_configrr1rsrrr YELLOW)rr server_cfgrrIr{s r$ _probe_toolsrsv !GT"J  >$T:6#/tE{7R7  e&se,fmm<=s>> A7&A22A7cRt}|jdi}|j|xsi}||jddnL|jdxsi}t |t si}t ||d<|jdd||d<|||<||d<t|y)z6Persist or clear ``mcp_servers..tools.include``.rNrIrexclude)r setdefaultrUpoprTr9r1r)rrrr server_entry tools_blocks r$_write_tools_includers -Cnn]B/G;;t$*L$'"&&w/52 +t,K!%g I 4( + W GDM C r#c tttd|jdtjt |j}||j j}|rTt|j|ttdt|d|jdtjyt|jdttd|jdtjy|s:t|jdttd tjy|Dcgc]}|d  }}|r|Dchc] }||vs| }}nJ|j jr)|j jDchc] }||vs| }}n t|}t|Dchc] \}}||vs |} }}d dl } | jjs|+|Dcgc] }||vs| } }t|j| y|j jr?|j jDcgc] }||vs| } }t|j| yt|jdyttd t|d t| d tj d dlm} |D cgc]"\}} |dt| dkDr| dddzn| $}}} | d|jd|| }|sHt|jgttd|jdtjyt|t|k(rGt|jdttdt|dtj yt'|Dcgc]}|| }}t|j|ttdt|dt|dtj ycc}wcc}wcc}wcc}}wcc}wcc}wcc} }wcc}w)uProbe the server and let the user pick which tools to enable. Probe-success path: - Curses checklist of all probed tools. - Pre-check uses (in priority order): 1. *prior_selection* (reinstall: preserve what the user had) 2. manifest's ``tools.default_enabled`` 3. all tools (default) - All-on selection clears any filter (no ``tools.include`` written). - Sub-selection writes ``tools.include``. Probe-fail path: - If manifest declares ``tools.default_enabled`` → apply directly. - Otherwise → leave config with no filter (all on when reachable). - Either way, point the user at ``hermes mcp configure ``. z Probing 'z' for available tools...Nz3 Couldn't probe server. Applied manifest default (z# tools). Run `hermes mcp configure z*` after the server is reachable to refine.zu Couldn't probe server; installed with no tool filter (all tools enabled when reachable). Run `hermes mcp configure z` after first connect to prune.z Server reported no tools.rz Found z tool(s). Pre-checked: .)curses_checklistu — <z...zSelect tools for 'z' (SPACE toggle, ENTER confirm)z/ No tools selected. Run `hermes mcp configure z ` to change.u ✓ All uT tools enabled (no filter — new tools the server adds later will be auto-enabled).r/z tools enabled.)rrrr rrrIrBrrrset enumeratesysstdinisattyrhermes_cli.curses_uirr)rprior_selectionprobedmanifest_defaultrm tool_namesnpre_seti pre_indices_sysrrdlabelschosen_indices chosen_namess r$_apply_tool_selectionr .s& G %+ejj\)ABFKK PQ %** %F~ ;;66  -= > %()*+--2ZZL9**    !T 2 %--2ZZL9$$    UZZ. e16==AB &'1!A$'J'-Aj1AA  $ $#kk99MQ*_1MMj/!*:!6GA!w,1GKG ::     &"1EQQ*_qEGE W 5  [[ ( ("'++"="=QQjqQGQ W 5  !T 2 % 3v;- K() ,   6 Aq #WQ"afun!<=F& UZZL(GHN  UZZ, e=ejj\J  MM   >c&k) UZZ. eV &; ; LL  +1.+ABaJqMBLB\2 % \"#1S[MA  O(BMHFRFCsN P. P3%P3 P8$P8 P=P=< QQ QQ'Q  QT)enablec tttd|jdtjtj z|j r0ttd|j tj|jr0ttd|jtjtd}|j t|}|jjdk(rMtttdtjt|jjn|jjdk(r|jjrSttd |jjd |jjd tj n#ttd tjt#|j}t%||}||d <ddlm}||j|st+d|jdt-||tttd|jd|rd nddtj.|j0r]t|j0j3j5D](}ttd|tj*ty)aInstall a catalog entry end-to-end. Steps: 1. If ``install.type == git``, clone + run bootstrap commands. 2. If ``auth.type == api_key``, prompt for env vars, save to .env. 3. If ``auth.type == oauth`` (remote MCP / case 1), write the ``auth: oauth`` marker (MCP client handles browser on first connect in the non-pre-authenticated case). 4. Translate the manifest into an ``mcp_servers.`` block and save into config.yaml. 5. Probe the server, present a curses checklist for tool selection, write ``tools.include`` (or no filter, depending on choice). If probe fails, fall back to the manifest's ``tools.default_enabled`` or all-on. 6. Print post_install notes. z Installing MCP ''z z Source: Nriz Configure credentials:rjz This MCP uses z OAuth. Run `hermes auth z(` if you have not already authenticated.z] This MCP uses native OAuth 2.1; tokens will be acquired on first connection (browser flow).rr)_save_mcp_serverzcatalog entry 'z1' rejected: suspicious command/args configuration)ru ✓ Installed 'z' (disabledz0). Start a new Hermes session to load its tools.)rrrr rBOLDrErrFrJrrHr'rr+r-rrrrrrNr rrKru splitlines)rr rrrrlines r$ install_entryrsY" G %$UZZL2FKK&++4M NO  eb**+,fjj9: || ej/<= G"&K }} %e,  zz)#  e. <=( G # ::   %"5::#6#6"78 % 3 345))   %6  1 MM% G Nr#)returnr)rXrrr)rxrrrD)rzList[CatalogEntry])rr)rrrzOptional[CatalogEntry])rzDict[str, dict])rrrr)rrrr.rNone)rrDrr)rrrOptional[Path]rr)rr*rr8)rrDrrrr9)rrrrA)rrrzOptional[List[tuple]])rrrrArr)rrDrrArr)rrDr rrr)rrrrrr)@r> __future__rrVrr dataclassesrrpathlibrtypingrrr r rqhermes_constantsr r hermes_cli.colorsr rhermes_cli.configrrrrhermes_cli.cli_outputrrrtrrr&r3r;r@rDrsrNrRrYrrrr!rrrrrrrrrrrrrrr rrr"r#r$r$s6# (,, C+ :$    "" "  6 6  6 77 7  0 0  0  6 6  6>9>Q xvB%'k& &8' 1h=0 &4 ($0(~ ~-@~ ~B:>U p=Ar#