Metadata-Version: 2.4
Name: cerberus-mcp
Version: 0.1.0
Summary: MCP server instrumentation for Cerberus API monitoring
Project-URL: Homepage, https://github.com/gpotrock/cerberus
Project-URL: Documentation, https://github.com/gpotrock/cerberus#mcp-server-monitoring
Project-URL: Repository, https://github.com/gpotrock/cerberus.git
Project-URL: Issues, https://github.com/gpotrock/cerberus/issues
Author: Griffin Potrock
License-Expression: MIT
License-File: LICENSE
Keywords: ai,analytics,async,instrumentation,llm,mcp,model-context-protocol,monitoring,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# cerberus-mcp

MCP (Model Context Protocol) server instrumentation for [Cerberus](https://github.com/gpotrock/cerberus) API monitoring.

Drop-in replacement for `FastMCP` that captures tool, resource, and prompt call metrics and streams them to the Cerberus analytics pipeline.

## Installation

```bash
pip install cerberus-mcp
```

## Quick Start

Replace `FastMCP` with `CerberusMCP` — a single-line change:

```python
from cerberus_mcp import CerberusMCP

mcp = CerberusMCP(
    "my-server",
    cerberus_config={
        "token": "your-api-key",
        "client_id": "your-client-id",
        "ws_url": "ws://your-cerberus-backend:8765",
    }
)

@mcp.tool()
def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"Sunny in {location}"

@mcp.resource("config://settings")
def get_settings() -> str:
    """Return server settings."""
    return '{"theme": "dark"}'

@mcp.prompt()
def summarize(text: str) -> str:
    """Summarize text."""
    return f"Please summarize: {text}"
```

All tool calls, resource reads, and prompt invocations are automatically captured with:
- Execution timing (duration_ms)
- Sanitized arguments (sensitive values redacted)
- Error tracking
- Result summaries
- MCP client identity (name, version) and session correlation

Events are sent asynchronously via WebSocket to the Cerberus event_ingest backend using the same pipeline as `cerberus-django`.

## Configuration

| Key | Required | Description |
|-----|----------|-------------|
| `token` | Yes | API key for Cerberus authentication |
| `client_id` | Yes | Client identifier for your MCP server |
| `ws_url` | Yes | WebSocket URL of your Cerberus event_ingest server |
| `server_name` | No | Override server name in events (defaults to MCP server name) |

Set `CERBERUS_DEBUG=true` to enable verbose logging.

## How It Works

`CerberusMCP` subclasses `FastMCP` from the MCP Python SDK and wraps the `tool()`, `resource()`, and `prompt()` decorators. Each handler call is intercepted to capture timing, arguments, results, and errors. Events are queued into a thread-safe queue and sent via a background WebSocket connection — zero impact on your MCP server's response times.

## Requirements

- Python >= 3.10
- `mcp` >= 1.0 (MCP Python SDK)
- `websockets` >= 12.0
- A running Cerberus backend ([cerberus-int](https://github.com/gpotrock/cerberus))

## License

MIT
