Metadata-Version: 2.5
Name: mcpulse-sdk
Version: 0.1.0
Summary: Analytics for MCP servers. One import, one wrap — see which of your tools actually work for the models calling them.
Project-URL: Homepage, https://github.com/getmcpulse/mcpulse-python
Project-URL: Repository, https://github.com/getmcpulse/mcpulse-python
Project-URL: Issues, https://github.com/getmcpulse/mcpulse-python/issues
Author: MCPulse
License: MIT License
        
        Copyright (c) 2026 MCPulse
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: analytics,llm,mcp,model-context-protocol,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mcp>=2.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# mcpulse

Analytics for MCP servers, for the [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk).

One import, one wrap — see which of your tools actually work for the models
calling them.

```python
from mcp.server.mcpserver import MCPServer
from mcpulse import watch

mcp = MCPServer("my-server")
watch(mcp, key="mp_live_…")
```

That is the whole integration. The server is instrumented in place and handed
straight back, so the call drops in around an existing server without moving
anything else.

## Install

```bash
pip install mcpulse-sdk
```

The distribution is `mcpulse-sdk`; the import stays `mcpulse`. They differ
because `mcpulse` on PyPI belongs to an unrelated project, and PyPI has no
scoping to fall back on the way npm does — so this package mirrors the npm name
(`@mcpulse/sdk`) instead.

No runtime dependencies. `mcp` is your dependency, not ours.

## Options

| Option | Default | Meaning |
|---|---|---|
| `key` | — | Ingest key, `mp_live_…`, minted per MCP in the dashboard |
| `endpoint` | `https://api.getmcpulse.com` | Point at a local API while developing |
| `enabled` | `True` | `False` makes `watch()` a no-op — useful in tests and CI |
| `debug` | `False` | Log what is sent, and why a send failed, to **stderr** |

An empty key turns it off, so a server started without its key configured is
silent rather than a source of 401s on every flush.

## What leaves your process

Sizes and hashes. Arguments and results do not, and no option turns that on.

Every tool call reports its name, how long it took, how it ended, how many
bytes came back, whether the result was empty, and a 12-character one-way hash
of the arguments — enough to tell a retry from a fresh call, and not enough to
learn anything about either.

## The three rules

1. **Never throw.** Every entry point swallows. If MCPulse fails inside your
   tool call, your tool fails and you blame us.
2. **Never block.** Record, buffer, return. Nothing awaits the network on the
   path a model is waiting on — sending happens on a background thread, never
   on your event loop.
3. **Never store customer data.** See above.

## Supported

- `mcp >= 2.0` — attaches through the supported `Server.middleware` chain.
- `mcp 1.x` — falls back to patching the dispatcher's handler map.

Both then wrap your own tool callbacks, which is what lets MCPulse tell a tool
that crashed from one whose arguments never validated — the MCP server converts
both to `isError` before anything outside can see the difference.

## Cross-language consistency

`args_hash` is the first 12 hex characters of the SHA-256 of the
[RFC 8785](https://www.rfc-editor.org/rfc/rfc8785) canonical form of the
arguments. `tests/fixtures/canonical.json` is the shared conformance suite that
every MCPulse SDK runs, so a call hashed here and a call hashed by the
TypeScript SDK land in the same bucket.

## Licence

MIT
