{"record":{"id":"e737ee2c607e4a88","repo":"JuliusBrussee/caveman","slug":"install-caveman-middleware-mcp-for-the-native-mcp-adapter","errorCode":null,"errorMessage":"Install caveman-middleware[mcp] for the native MCP adapter","messagePattern":"Install caveman-middleware\\[mcp\\] for the native MCP adapter","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"packages/middleware/python/caveman_middleware/mcp.py","lineNumber":19,"sourceCode":"\"\"\"Native MCP result views and local host recovery registration.\n\nThe caller keeps its Client/ClientSession, transports and original results.\nThis adapter adds no MCP server or protocol implementation. All compression and\nscoped recovery use the shared Engine-backed Caveman runtime.\n\"\"\"\nfrom __future__ import annotations\n\nfrom collections.abc import Awaitable, Callable, Mapping, Sequence\nfrom dataclasses import dataclass\nfrom importlib.metadata import version\nimport json\nimport uuid\nfrom typing import Any\n\ntry:\n    from mcp.types import CallToolResult, TextContent, Tool\nexcept ModuleNotFoundError as error:\n    raise ImportError(\"Install caveman-middleware[mcp] for the native MCP adapter\") from error\n\nfrom caveman_cloud.middleware import Adapter, AsyncMiddlewareRuntime, Candidate, MiddlewareError, Scope, sha256\nfrom ._native import owner\nfrom ._versions import matches_framework\n\n\n@dataclass(frozen=True)\nclass MCPToolBinding:\n    \"\"\"The native MCP definition and the callable registered in the host loop.\"\"\"\n    tool: Tool\n    execute: Callable[..., Awaitable[CallToolResult]]\n\n\ndef bind_mcp_tool(client, tool: Tool) -> MCPToolBinding:\n    \"\"\"Use an existing native client; it keeps auth, IDs, validation and options.\"\"\"\n    async def execute(arguments=None, **native_options):\n        return await client.call_tool(tool.name, arguments, **native_options)\n    return MCPToolBinding(tool, execute)","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/middleware/python/caveman_middleware/mcp.py#L1-L37","documentation":"ImportError guard in the MCP adapter module: the mcp package is not installed, but the native MCP result views / recovery registration need it. Install the packaged mcp extra (pip install 'caveman-middleware[mcp]') to use this adapter; it adds no MCP server of its own.","triggerScenarios":"Importing caveman_middleware.mcp (or code paths that import it) without the mcp distribution installed in the active Python environment.","commonSituations":"Installing caveman-middleware bare instead of caveman-middleware[mcp], using a different venv than the one where extras were installed, or deployment images missing optional dependencies.","solutions":["pip install \"caveman-middleware[mcp]\" in the active environment","Or install the mcp package directly: pip install mcp","Verify with python -c \"import mcp.types\" in the same interpreter/venv your app uses"],"exampleFix":"// before\npip install caveman-middleware\n// after\npip install \"caveman-middleware[mcp]\"","handlingStrategy":"try-catch","validationCode":"try:\n    import mcp.types  # noqa: F401\nexcept ModuleNotFoundError:\n    raise SystemExit(\"install with: pip install 'caveman-middleware[mcp]'\")","typeGuard":null,"tryCatchPattern":"try:\n    import caveman_middleware.mcp as mcp_adapter\nexcept ImportError as e:\n    if \"caveman-middleware[mcp]\" in str(e):\n        raise SystemExit(\"install with: pip install 'caveman-middleware[mcp]'\")\n    raise","preventionTips":["Install the [mcp] extra wherever the MCP adapter is used","Verify optional deps in the deployment image's venv, not the dev shell","Add an import-time smoke test for optional adapters in CI"],"tags":["python","import-error","mcp","optional-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}