{"record":{"id":"fde510daf3dc5e71","repo":"NousResearch/hermes-agent","slug":"hermes-tools-mcp-server-requires-the-mcp-package","errorCode":null,"errorMessage":"hermes-tools MCP server requires the 'mcp' package: {exc}","messagePattern":"hermes-tools MCP server requires the 'mcp' package: (.+?)","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"agent/transports/hermes_tools_mcp_server.py","lineNumber":161,"sourceCode":"    \"kanban_list\",\n    # NOTE: kanban_create / kanban_unblock / kanban_link are orchestrator-\n    # only — the kanban tool gates them on HERMES_KANBAN_TASK being unset.\n    # They're exposed here for orchestrator agents running on the codex\n    # runtime that need to dispatch new tasks.\n    \"kanban_create\",\n    \"kanban_unblock\",\n    \"kanban_link\",\n)\n\n\ndef _build_server() -> Any:\n    \"\"\"Create the FastMCP server with Hermes tools attached. Lazy imports\n    so the module can be imported without the mcp package installed\n    (we degrade to a clear error only when actually run).\"\"\"\n    try:\n        from mcp.server.fastmcp import FastMCP\n    except ImportError as exc:  # pragma: no cover - install hint\n        raise ImportError(\n            f\"hermes-tools MCP server requires the 'mcp' package: {exc}\"\n        ) from exc\n\n    # Discover Hermes tools so dispatch works.\n    from model_tools import (\n        get_tool_definitions,\n        handle_function_call,\n    )\n\n    mcp = FastMCP(\n        \"hermes-tools\",\n        instructions=(\n            \"Hermes Agent's tool surface, exposed for use inside a Codex \"\n            \"session. Use these for capabilities Codex's built-in toolset \"\n            \"doesn't cover: web search/extract, browser automation, \"\n            \"subagent delegation, vision, image generation, persistent \"\n            \"memory, skills, and cross-session search.\"\n        ),","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/transports/hermes_tools_mcp_server.py#L143-L179","documentation":"ImportError from _build_server() in agent/transports/hermes_tools_mcp_server.py:161. The module is deliberately importable without the 'mcp' package (lazy import), but actually building the FastMCP server requires mcp.server.fastmcp.FastMCP; if the package is missing or broken, this clear install-hint error is raised instead of a NameError at import time.","triggerScenarios":"Running the hermes-tools MCP server (the entry point that calls _build_server) in an environment where 'mcp' is not installed, installed under a different interpreter/venv, or corrupted so that `from mcp.server.fastmcp import FastMCP` itself raises ImportError (the original exception is chained and included in the message).","commonSituations":"Using the repo's venv vs the system python mix-up; mcp listed as an optional extra that was never installed; a dependency conflict uninstalling/downgrading mcp; CI image missing the optional dependency.","solutions":["Install the mcp package into the same interpreter that runs hermes: pip install 'mcp>=1,<2' (respecting the repo's upper-bound pinning policy).","Verify with the exact interpreter: `python -c \"from mcp.server.fastmcp import FastMCP\"` — the chained {exc} in the message tells you if it is 'No module named mcp' versus a deeper import failure.","If a deeper failure, fix the conflicting/broken mcp install (pip install --force-reinstall mcp) rather than just adding it."],"exampleFix":"# before\n$ hermes mcp serve hermes-tools   # ImportError: requires the 'mcp' package\n\n# after\n$ pip install 'mcp>=1,<2'\n$ python -c \"from mcp.server.fastmcp import FastMCP; print('ok')\"","handlingStrategy":"validation","validationCode":"def mcp_available() -> bool:\n    try:\n        from mcp.server.fastmcp import FastMCP  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not mcp_available():\n    raise SystemExit(\"install the optional dependency: pip install 'mcp>=1,<2'\")","typeGuard":null,"tryCatchPattern":"try:\n    _build_server()\nexcept ImportError as exc:\n    raise SystemExit(f\"hermes-tools MCP server unavailable: {exc}\") from exc","preventionTips":["Install optional extras into the same venv that runs hermes.","Check importability with the exact interpreter before launching the server.","Keep the dependency pinned with an upper bound per the repo's policy."],"tags":["mcp","dependency","import","optional-extra"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}