Metadata-Version: 2.5
Name: mcp-monitor-local-sdk
Version: 0.1.2
Summary: Self-host monitoring SDK for Python MCP servers
Project-URL: Homepage, https://pypi.org/project/mcp-monitor-local-sdk/
Project-URL: Repository, https://pypi.org/project/mcp/
Author: MCP Monitor
License: MIT
Keywords: mcp,metrics,model-context-protocol,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2,>=1.2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-monitor-local-sdk

Self-host monitoring SDK for Python MCP servers. [User guide](#user-guide) · [Developer guide](#developer-guide)

Repo copies: [USER.md](USER.md) · [DEV.md](DEV.md)

## User guide

Point this SDK at your self-host API (`metrics_server_url` + `instance_secret`). It wraps tool handlers and sends tool-call metrics (name, duration, success/error) — not application logs — to `POST /v1/metrics`. Open the local UI or desktop app to see them. This package does not talk to the hosted dashboard.

```bash
pip install mcp-monitor-local-sdk
```

```python
from mcp_monitor_sdk import MonitoredFastMCP

server = MonitoredFastMCP(
    "todo-mcp",
    server_name="todo-mcp",
    instance_secret="change-me-to-a-long-random-secret",
    metrics_server_url="http://localhost:8000/v1/metrics",
)

@server.tool()
def todos_list() -> str:
    """List all todos."""
    return "No todos."

if __name__ == "__main__":
    server.run()
```

`instance_secret` must match `INSTANCE_SECRET` on the API.

## Developer guide

Same ingest contract as the JS SDK. Built to sit next to the official [`mcp`](https://pypi.org/project/mcp/) package.

### Options

| Option | Required | Default | Notes |
|---|---|---|---|
| `server_name` | yes | | Trimmed and lowercased |
| `instance_secret` | yes | | Min 16 characters; sent as `X-Instance-Secret` |
| `metrics_server_url` | yes | | Full ingest URL, usually `http://localhost:8000/v1/metrics` |
| `batch_size` | no | 10 | Max 100 |
| `retry_attempts` | no | 2 | `0` still tries once |
| `timeout_ms` | no | 5000 | |
| `flush_interval_ms` | no | 5000 | |
| `log_level` | no | `info` | `debug` \| `info` \| `warn` \| `error` \| `silent` |

Events flush when the batch is full or every `flush_interval_ms`. Failed flushes are restored. Shutdown drains remaining events.

Local checkout:

```bash
pip install -e ./local/sdk/py
```

Publish:

```bash
cd local/sdk/py
python -m build
twine upload dist/*
```
