{"repo":"NousResearch/hermes-agent","public_id":"30904","display_label":"MCP SDK missing causes unclear NameError at runtime","summary":"Multiple issues and fixes address a problem where missing MCP or related SDK packages produce confusing NameError exceptions instead of clear ImportError messages. The fixes aim to provide actionable error messages when the MCP SDK is not installed.","subsystem":"hermes_cli","counts":{"members":8,"open_issues":1,"open_issues_distinct":1,"open_prs":2,"closed_issues":2,"merged_prs":1,"attempt_prs":4},"landed_fix":{"status":"merged_to_main","basis":"structural","pr":31450},"resolution":{"state":"partially_resolved","by":"pr-31450"},"freshness":{"state":"verified","last_verified_at":"2026-05-24T11:44:59+00:00","is_stale":false},"grouping":{"backbone":"STRUCTURAL_PARTIAL","link_density":0.20428571428571426},"fix_edges":[{"issue_number":30904,"pr_number":31450,"tier":"verified","basis":"closing_ref","confidence":0.95,"recoverable_from_timeline":true}],"members":[{"kind":"issue","number":30904,"title":"MCP stdio client raises NameError: name 'StdioServerParameters' is not defined (v0.14.0)","url":null,"state":"closed"},{"kind":"issue","number":31005,"title":"Homebrew bottle 2026.5.16 missing 'mcp' and 'websockets' packages — MCP and browser tools fail at runtime","url":null,"state":"open"},{"kind":"issue","number":34220,"title":"mcp add / mcp test raise NameError when mcp package not installed","url":null,"state":"closed"},{"kind":"pr","number":30907,"title":"fix(mcp): raise clear ImportError in _run_stdio when SDK unavailable","url":null,"state":"closed","close_reason":{"refs":[{"kind":"commit","value":"5acaeba2b","number":0},{"kind":"pr","value":"#31450","number":31450},{"kind":"pr","value":"#30904","number":30904}],"category":"superseded_by_pr","implication":"superseded"},"merged":false},{"kind":"pr","number":31450,"title":"fix(mcp): raise ImportError instead of NameError when stdio SDK missing","url":null,"state":"merged","close_reason":{"category":"merged","implication":"superseded"},"merged":true,"is_fix_pr":true,"fix_tier":"verified","files_changed":["tests/tools/test_mcp_tool.py","tools/mcp_tool.py"],"fix_hunks":[{"file":"tests/tools/test_mcp_tool.py","hunks":["@@ -1462,6 +1462,27 @@ async def _test():\n \n         asyncio.run(_test())\n \n+    def test_stdio_unavailable_raises_importerror_not_nameerror(self):\n+        \"\"\"Regression test for #30904.\n+\n+        When the mcp SDK isn't installed, ``_run_stdio`` previously leaked a\n+        bare ``NameError: name 'StdioServerParameters' is not defined``. The\n+        gate now raises a clear ``ImportError`` with install instructions,\n+        mirroring ``_run_http``'s behaviour when the HTTP transport is\n+        unavailable.\n+        \"\"\"\n+        from tools.mcp_tool import MCPServerTask\n+\n+        server = MCPServerTask(\"local\")\n+        config = {\"command\": \"python3\", \"args\": [\"/tmp/echo.py\"]}\n+\n+        async def _test():\n+            with patch(\"tools.mcp_tool._MCP_AVAILABLE\", False):\n+                with pytest.raises(ImportError, match=r\"mcp.*SDK\"):\n+                    await server._run_stdio(config)\n+\n+        asyncio.run(_test())\n+\n     def test_http_seeds_initial_protocol_header(self):\n         from tools.mcp_tool import LATEST_PROTOCOL_VERSION, MCPServerTask\n "]},{"file":"tools/mcp_tool.py","hunks":["@@ -1255,6 +1255,15 @@ async def _wait_for_lifecycle_event(self) -> str:\n \n     async def _run_stdio(self, config: dict):\n         \"\"\"Run the server using stdio transport.\"\"\"\n+        if not _MCP_AVAILABLE:\n+            raise ImportError(\n+                f\"MCP server '{self.name}' requires the 'mcp' Python SDK, but \"\n+                \"it is not installed. Install with:\\n\"\n+                \"  pip install 'hermes-agent[mcp]'\\n\"\n+                \"or (full install):\\n\"\n+                \"  pip install 'hermes-agent[all]'\"\n+            )\n+\n         command = config.get(\"command\")\n         args = config.get(\"args\", [])\n         user_env = config.get(\"env\")\n"]}]},{"kind":"pr","number":34223,"title":"fix(mcp): fail fast when sdk is missing","url":null,"state":"open","close_reason":{"category":"uncategorized","implication":"needs_llm"},"merged":false},{"kind":"pr","number":34245,"title":"fix(mcp): fail fast with actionable error when mcp SDK missing (#34220)","url":null,"state":"closed","close_reason":{"refs":[{"kind":"pr","value":"#105586","number":105586}],"category":"superseded_by_pr","implication":"superseded"},"merged":false},{"kind":"pr","number":105586,"title":"fix(mcp): fail fast with actionable error when mcp SDK missing (salvage of #34245)","url":null,"state":"open","close_reason":{"refs":[{"kind":"pr","value":"#34223","number":34223},{"kind":"pr","value":"#34245","number":34245}],"category":"duplicate_of","implication":"duplicate"},"merged":false}],"trust":{"default_tier":"verified","includes_suggested":false}}