# mcp-shared (Python)

Python parallel of the `mcp-shared` TypeScript library. Used by
`ringcentral-admin` and `docstrange-mcp` (Phase B).

## Install

```
pip install -r requirements.txt
```

or

```
pip install -e .
```

## Usage

```python
from mcp.server import Server
from mcp_shared import serve_mcp_over_http

server = Server("docstrange")
# ... register tools ...

serve_mcp_over_http(
    server,
    port=18815,
    token=os.environ["MCP_BEARER_TOKEN"],
)
```

For the legacy SSE compatibility shim (claude.ai cloud agents):

```python
serve_mcp_over_http(
    server,
    port=18815,
    token=os.environ["MCP_BEARER_TOKEN"],
    legacy_sse=True,
)
```

## Routes

| Path        | Method | Auth     | Purpose                            |
| ----------- | ------ | -------- | ---------------------------------- |
| /health     | GET    | none     | liveness                           |
| /mcp        | ANY    | bearer   | Streamable HTTP MCP transport      |
| /sse        | GET    | bearer   | legacy SSE stream (opt-in)         |
| /messages   | POST   | bearer   | legacy SSE POST (opt-in)           |

## Auth

`require_bearer(headers, expected_token)` returns either `None`
(pass-through) or a Starlette `JSONResponse(401)`. Uses
`secrets.compare_digest` for constant-time comparison. The token value
is never logged.

## Tests

```
pip install -e .[test]
pytest test_auth.py test_transport.py
```