JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[mcp] for the native MCP adapter

Error message

Install caveman-middleware[mcp] for the native MCP adapter

What it means

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.

Solutions

  1. pip install "caveman-middleware[mcp]" in the active environment
  2. Or install the mcp package directly: pip install mcp
  3. Verify with python -c "import mcp.types" in the same interpreter/venv your app uses

Example fix

// before
pip install caveman-middleware
// after
pip install "caveman-middleware[mcp]"
Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import mcp.types  # noqa: F401
except ModuleNotFoundError:
    raise SystemExit("install with: pip install 'caveman-middleware[mcp]'")

Try / catch

try:
    import caveman_middleware.mcp as mcp_adapter
except ImportError as e:
    if "caveman-middleware[mcp]" in str(e):
        raise SystemExit("install with: pip install 'caveman-middleware[mcp]'")
    raise

Prevention

When it happens

Trigger: Importing caveman_middleware.mcp (or code paths that import it) without the mcp distribution installed in the active Python environment.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/e737ee2c607e4a88. Report an issue: GitHub.

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/mcp.py:19

"""Native MCP result views and local host recovery registration.

The caller keeps its Client/ClientSession, transports and original results.
This adapter adds no MCP server or protocol implementation. All compression and
scoped recovery use the shared Engine-backed Caveman runtime.
"""
from __future__ import annotations

from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass
from importlib.metadata import version
import json
import uuid
from typing import Any

try:
    from mcp.types import CallToolResult, TextContent, Tool
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[mcp] for the native MCP adapter") from error

from caveman_cloud.middleware import Adapter, AsyncMiddlewareRuntime, Candidate, MiddlewareError, Scope, sha256
from ._native import owner
from ._versions import matches_framework


@dataclass(frozen=True)
class MCPToolBinding:
    """The native MCP definition and the callable registered in the host loop."""
    tool: Tool
    execute: Callable[..., Awaitable[CallToolResult]]


def bind_mcp_tool(client, tool: Tool) -> MCPToolBinding:
    """Use an existing native client; it keeps auth, IDs, validation and options."""
    async def execute(arguments=None, **native_options):
        return await client.call_tool(tool.name, arguments, **native_options)
    return MCPToolBinding(tool, execute)

View on GitHub (pinned to 3ee70a1026)