AGENT SKILL

mcp-server-patterns

Add or troubleshoot MCP servers in Hermes Agent.

License 许可
MIT
最近更新
2026-11-03
Stars
★ 1
Forks
0

01 前言 Front Matter

name
mcp-server-patterns
author
OraMesLita
license
MIT
version
1.0.0
metadata
{ "hermes": { "triggers": [ "add mcp server", "mcp configuration", "filesystem mcp", "mcp not working", "mcp tools missing", "add searxng", "add brave search", "mcp server setup" ], "related_skills": [ "hermes-agent" ] } }
description
Add or troubleshoot MCP servers in Hermes Agent.

02 资源文件 1

03 SKILL.md 正文

MCP Server Configuration Patterns

Practical patterns for configuring MCP servers in Hermes Agent. Covers common setups, pitfalls, and optimization techniques.

Quick Reference

Filesystem MCP — Parent Directory Access

Key insight: Specifying a parent directory grants access to ALL subdirectories automatically. No wildcards needed.

# ❌ Verbose — listing every subdirectory
filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - F:\projects\app1
    - F:\projects\app2
    - F:\projects\app3

# ✅ Clean — parent directory covers all subdirs
filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - F:\projects          # ALL subdirs automatically accessible
    - F:\obsidian_note     # ALL Obsidian vaults

Why this works: The server treats specified directories as allowed roots. Any path under them is automatically accessible, including future subdirectories.

MCP SDK Installation

Prerequisite: The mcp Python package must be installed for MCP support.

# Install MCP SDK
pip install mcp

# Verify installation
python -c "import mcp; print('MCP SDK installed')"

Pitfall: If you see "MCP SDK not available -- skipping MCP tool discovery", the package is missing. MCP support is silently disabled without it.

MCP Roots Protocol

For dynamic directory updates without server restart, use MCP Roots:

filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    # No directories specified — client provides via Roots protocol

When to use: When you need runtime directory updates via roots/list_changed notifications. Most users should stick with explicit directory args.

Common MCP Server Configurations

SearXNG — Privacy-respecting Web Search

searxng:
  command: npx
  args:
    - -y
    - mcp-searxng
  env:
    SEARXNG_URL: "http://your-searxng-instance:8080"
  timeout: 30

Why: Replaces ddgs (often broken), private, no API key needed.

Brave Search — High-quality Web Search

brave-search:
  command: npx
  args:
    - -y
    - "@brave/brave-search-mcp-server"
  env:
    BRAVE_API_KEY: "your-brave-api-key"  # Free at brave.com/search/api
  timeout: 30

everyfile — Instant Local File Search via Everything

everyfile does NOT ship a built-in MCP server module. You must write a bridge script that wraps the everyfile Python API using the MCP SDK (MCPServer in MCP 2.x, FastMCP in 1.x).

Prerequisites: Windows, Python ≥ 3.11, VoidTools Everything installed and running. Install: pip install everyfile[mcp] (or pipx install everyfile[mcp]).

Bridge script (save as everyfile_mcp_server.py):

from everyfile import Everything, EverythingError
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("everyfile")

@mcp.tool()
def search_files(query: str, max_results: int = 50, sort: str = "name",
                 descending: bool = False, match_case: bool = False,
                 match_path: bool = False, regex: bool = False) -> str:
    ev = Everything()
    cursor = ev.search(query, sort=sort, descending=descending,
                       limit=max_results, match_case=match_case,
                       match_path=match_path, regex=regex)
    results = [row.to_dict() for row in cursor]
    return json.dumps({"results": results, "count": len(results),
                       "total": cursor.total}, default=str, ensure_ascii=False)

if __name__ == "__main__":
    mcp.run()

Config (Hermes + Claude Code):

# Hermes config.yaml
everyfile:
  command: "C:/Users/<user>/AppData/Local/pipx/pipx/venvs/everyfile/Scripts/python.exe"
  args:
    - "C:/Users/<user>/AppData/Local/hermes/everyfile_mcp_server.py"
# Claude Code
claude mcp add -s user everyfile -- \
  "C:/Users/<user>/AppData/Local/pipx/pipx/venvs/everyfile/Scripts/python.exe" \
  "C:/Users/<user>/AppData/Local/hermes/everyfile_mcp_server.py"

Why: Sub-millisecond filename/path/metadata search across all NTFS drives (reads the MFT directly). Complements ripgrep — Everything for filenames, rg for content. Also works as a standalone CLI (ev command) and Python API.

Pitfall — MCP 2.x API rename: FastMCP was renamed to MCPServer in MCP 2.x. If you see ModuleNotFoundError: No module named 'mcp.server.fastmcp', you're on MCP 2.x — import from mcp.server.mcpserver instead. The migration guide is at https://py.sdk.modelcontextprotocol.io/v2/migration/.

Pitfall — async functions in MCP 2.x: Any @mcp.tool() that uses await (e.g. await ctx.info(...)) MUST be declared async def. A plain def with await inside produces SyntaxError: 'await' outside async function. If the tool doesn't need await, a plain def is fine.

Obsidian MCP — Direct Vault Manipulation

obsidian:
  command: npx
  args:
    - -y
    - "@fazer-ai/mcp-obsidian"
  env:
    OBSIDIAN_API_KEY: "your-obsidian-api-key"  # Enable in Obsidian settings
    OBSIDIAN_HOST: "localhost"
    OBSIDIAN_PORT: "27123"
  timeout: 30

PostgreSQL — Database Access

postgres:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-postgres'
    - postgresql://user:pass@localhost:5432/dbname

GitHub — Repository Management

github:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-github'
  env:
    GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"

Transport Types

Stdio Transport (command-based)

server_name:
  command: "npx"             # Executable to run
  args: ["-y", "pkg-name"]   # Command arguments
  env:                       # Environment variables for subprocess
    SOME_API_KEY: "value"
  timeout: 120               # Per-tool-call timeout (seconds)
  connect_timeout: 60        # Initial connection timeout (seconds)

HTTP Transport (url-based)

server_name:
  url: "https://mcp.example.com/mcp"
  headers:
    Authorization: "Bearer sk-..."
  timeout: 180
  connect_timeout: 60

Note: A server config must have either command (stdio) or url (HTTP), not both.

Security Considerations

Environment Variable Filtering

For stdio servers, Hermes only passes safe baseline variables:

  • PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
  • Any XDG_* variables

All other environment variables are excluded unless explicitly added via env. This prevents accidental credential leakage.

github:
  command: "npx"
  args: ["-y", "@modelcontextprotocol/server-github"]
  env:
    # Only this token is passed to the subprocess
    GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

Credential Stripping in Error Messages

Failed MCP tool calls automatically redact credential patterns:

  • GitHub PATs (ghp_...)
  • OpenAI-style keys (sk-...)
  • Bearer tokens
  • Generic token=, key=, API_KEY=, password=, secret= patterns

Troubleshooting

"MCP SDK not available -- skipping MCP tool discovery"

pip install mcp

"No MCP servers configured"

Check ~/.hermes/config.yaml has mcp_servers key with at least one entry.

"Failed to connect to MCP server 'X'"

Common causes:

  • Command not found: Ensure npx, uvx, or the command is on PATH
  • Package not found: For npx servers, add -y to auto-install
  • Timeout: Increase connect_timeout
  • Port conflict: For HTTP servers, verify URL is reachable

Tools not appearing

  • Check server is under mcp_servers (not mcp or servers)
  • Verify YAML indentation
  • Tool names are prefixed: mcp_{server}_{tool}
  • Look at startup logs for connection messages

Connection keeps dropping

Client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If fundamentally unreachable, gives up after 5 attempts.

Pitfalls

  • Don't list every subdirectory. Specify parent directories instead — the server grants access to all subdirs automatically.
  • Don't forget -y for npx servers. Without it, npx may prompt for installation, which hangs in automated environments.
  • Don't put secrets in args. Use env for API keys and tokens. Args are visible in process listings.
  • Don't use both command and url. A server config must have one or the other, not both.
  • Don't assume MCP tools are available. Check hermes mcp list to verify server status and tool discovery.
  • Don't skip the MCP SDK. Without pip install mcp, MCP support is silently disabled.

Verification

After adding MCP servers:

# Check server status
hermes mcp list

# Verify tools are discovered
hermes tools | grep mcp_

# Test a specific tool
hermes chat -q "List files in F:\projects using the filesystem MCP"

Notes

  • MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
  • Server connections are persistent and shared across all conversations in the same agent process
  • Adding or removing servers requires restarting the agent (no hot-reload currently)
  • The native MCP client is independent of mcporter — you can use both simultaneously

04 同仓库更多 Skills