mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-06-04 07:31:58 +00:00
8b69ec03af
* feat(mcp): Nous-approved MCP catalog with interactive picker
Adds an optional-mcps/ directory mirroring optional-skills/: curated,
Nous-approved MCP servers shipped with the repo but disabled by default.
Presence in optional-mcps/ = approval. No community tier, no trust signals.
Entries are added by merging a PR.
New surface:
hermes mcp Interactive catalog picker (default)
hermes mcp catalog Plain-text list, scriptable
hermes mcp install <name> Install a catalog entry
Picker behavior:
not installed -> install (clone/bootstrap if needed, prompt for creds)
installed/off -> enable
installed/on -> menu (disable / uninstall / reinstall)
Manifest schema (manifest_version: 1) supports:
- transport: stdio (command/args, ${INSTALL_DIR} substitution) or http (url)
- install: optional git clone + bootstrap commands (for repos that need
local venv setup, like the n8n bridge); omit for npx/uvx servers
- auth: api_key (prompts -> ~/.hermes/.env), oauth (provider-mediated
or native MCP), or none
Catalog entries are never auto-updated. Users re-run `hermes mcp install`
to refresh. Credentials always go to ~/.hermes/.env (the .env-is-for-secrets
rule), never to per-server env blocks.
Ships n8n as the reference manifest (https://github.com/CyberSamuraiX/hermes-n8n-mcp).
Tests: 19 catalog tests + E2E install/uninstall round-trip via the shipped
manifest.
* feat(mcp): tool-selection checklist + Linear catalog entry
Adds install-time tool selection so users only enable the MCP tools they
actually want, and ships Linear as a second reference catalog entry to
demonstrate the http+oauth path alongside n8n's stdio+api_key+git-bootstrap.
Tool selection flow:
install (clone/auth/credentials) ->
probe server for available tools ->
curses checklist with pre-checked rows ->
write mcp_servers.<name>.tools.include
Pre-check priority:
1. user's prior tools.include (reinstall preserves selection)
2. manifest's tools.default_enabled (curated subset)
3. all probed tools (default)
Probe-failure fallback (server unreachable, OAuth not yet complete,
backing service offline):
- manifest declared default_enabled -> applied directly
- no default declared -> no filter written (all-on when reachable)
- both cases point user at hermes mcp configure <name>
Manifest schema additions:
tools:
default_enabled: [list, of, tool, names] # optional
Updates:
- optional-mcps/linear/manifest.yaml -- new reference entry (http+oauth)
- optional-mcps/n8n/manifest.yaml -- tools.default_enabled set to the
8 read-mostly tools; mutating tools (activate/deactivate, container_logs)
pruned by default
- docs: new 'Tool selection at install time' section in features/mcp.md
Tests: 7 new tests in TestToolSelection covering probe-success / probe-fail
matrix, manifest-default filtering, reinstall-preserves-selection, and
invalid-default-enabled rejection. 26 catalog tests + 32 existing
mcp_config tests passing.
* feat(mcp): polish — picker unification, include-mode convergence, hardening
Addresses review findings on PR #30870. Lands all improvements that
belong in this PR before merge; defers separate cleanup (consolidating
two probe implementations, change-detector tests) to follow-ups.
Picker UX (mcp_picker.py)
- Unifies catalog + custom (user-added) MCPs in one view with distinct
status badges (available / enabled / installed (disabled) /
custom — enabled / custom — disabled)
- Adds 'Configure tools (probe server + re-pick)' action to both the
catalog-installed and custom-row submenus — the existing
hermes mcp configure flow was previously unreachable from the picker
- Loops until ESC/q so the user can manage several entries in one
session instead of having to re-launch
- Uninstall message now mentions .env credentials are preserved with a
pointer to clean them up manually if no longer needed
- Surfaces a 'requires a newer Hermes' warning per future-manifest
entry instead of silently hiding it
Catalog (mcp_catalog.py)
- catalog_diagnostics() exposes which manifests were skipped and why
(future_manifest vs invalid) so UIs can give actionable feedback
- _do_git_install detects SHA-shaped refs (regex /[0-9a-f]{7,40}/)
and skips the doomed 'git clone --branch <sha>' attempt — clone --branch
only accepts branches/tags, so SHAs always failed noisily before
falling back to the full-clone path
- Probe-success all-tools-enabled message now mentions that new tools
the server adds later will be auto-enabled (no-filter mode)
Convergence (tools_config.py)
- _configure_mcp_tools_interactive now writes tools.include (whitelist)
instead of tools.exclude (blacklist), matching the catalog flow and
hermes mcp configure. The on-disk config shape no longer depends on
which UI the user touched last
- Two existing tests updated to assert the new include-mode contract
Discoverability
- Setup wizard final step now prints 'Browse curated MCPs: hermes mcp'
- Three tip-corpus entries pointing at the new catalog
- Docs updated with: trust model (manifests run code locally, gated by
PR review, but read before installing), runtime ${ENV_VAR} substitution
semantics, and the manifest_version forward-compat behavior
Tests
- 7 new tests covering future-manifest diagnostics, custom MCP picker
rows, SHA-ref git-install path, branch-ref git-install path, and the
tools_config include-mode write contract
- 80 MCP-related tests passing across test_mcp_catalog.py,
test_mcp_config.py, test_mcp_tools_config.py
* fix(mcp): drop setup-wizard catalog hint to satisfy supply-chain scanner
The wizard line 'Browse curated MCPs: hermes mcp' triggered the
CI supply-chain scanner because it pattern-matches on edits to any
file named hermes_cli/setup.py — that filename matches the Python
'install-hook file' heuristic even though this setup.py is the
user-facing 'hermes setup' wizard, not a packaging install hook.
The catalog is already surfaced via three tip-corpus entries in
hermes_cli/tips.py (which the scanner doesn't flag), so dropping the
wizard mention loses no discoverability. Worth revisiting after a
scanner allowlist for this specific file lands.
77 lines
2.6 KiB
YAML
77 lines
2.6 KiB
YAML
# Nous-approved MCP catalog entry.
|
|
# Presence in this directory = approval. Merged via PR review.
|
|
#
|
|
# Schema version 1.
|
|
manifest_version: 1
|
|
|
|
name: n8n
|
|
description: Manage and inspect n8n workflows from Hermes (stdio bridge, no public port).
|
|
source: https://github.com/CyberSamuraiX/hermes-n8n-mcp
|
|
|
|
# How to launch the server once installed. The keys here map 1:1 to the
|
|
# `mcp_servers.<name>` block written into ~/.hermes/config.yaml by the
|
|
# existing `_save_mcp_server()` helper in hermes_cli/mcp_config.py.
|
|
transport:
|
|
type: stdio
|
|
# For git-installed servers, ${INSTALL_DIR} is substituted at install time
|
|
# with the path the catalog cloned the repo into. The catalog never
|
|
# auto-updates: the user re-runs `hermes mcp install official/n8n` to
|
|
# refresh.
|
|
command: "${INSTALL_DIR}/.venv/bin/python"
|
|
args:
|
|
- "${INSTALL_DIR}/server.py"
|
|
|
|
# Optional install step. Omit for npm/uvx servers where transport.command
|
|
# is the install (`npx -y package`). Use for repos that need a local clone
|
|
# + dependency install.
|
|
install:
|
|
type: git
|
|
url: https://github.com/CyberSamuraiX/hermes-n8n-mcp.git
|
|
# Pin to a commit/tag. Required — manifests do not float HEAD.
|
|
ref: main
|
|
# Bootstrap commands run inside the cloned directory after clone.
|
|
bootstrap:
|
|
- "python3 -m venv .venv"
|
|
- ".venv/bin/pip install -r requirements.txt"
|
|
|
|
# Authentication. Three shapes:
|
|
# type: api_key — prompt for env vars, write to ~/.hermes/.env
|
|
# type: oauth — provider-mediated or remote MCP native OAuth (case 1/2)
|
|
# type: none — no credentials needed
|
|
auth:
|
|
type: api_key
|
|
env:
|
|
- name: N8N_BASE_URL
|
|
prompt: "n8n instance URL"
|
|
default: "http://127.0.0.1:5678"
|
|
required: true
|
|
secret: false
|
|
- name: N8N_API_KEY
|
|
prompt: "n8n API key (generate under Settings → API)"
|
|
required: true
|
|
secret: true
|
|
|
|
# Tool selection at install time:
|
|
# n8n's bridge exposes 11 tools. Mutating ones (activate/deactivate, docker
|
|
# container_logs) are pruned from the default so a user who installs casually
|
|
# gets a read-mostly safe surface. Users see the full list in the install-time
|
|
# checklist and can opt into the mutating tools per their threat model.
|
|
tools:
|
|
default_enabled:
|
|
- health
|
|
- list_workflows
|
|
- get_workflow
|
|
- find_workflows
|
|
- list_executions
|
|
- get_execution
|
|
- recent_failures
|
|
- export_workflow
|
|
|
|
post_install: |
|
|
The n8n bridge expects to talk to a running n8n instance over the URL you
|
|
provided. Generate an API key in n8n under Settings → API.
|
|
|
|
Workflow activate/deactivate calls are real mutations against your live n8n.
|
|
Treat them carefully.
|
|
|
|
Start a new Hermes session to load the n8n tools.
|