Metadata-Version: 2.4
Name: pymcp-kit
Version: 0.2.0
Summary: A capability-first MCP server toolkit for FastAPI with Streamable HTTP and stdio transport
Author-email: Prince Roshan <princekrroshan01@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Agent-Hellboy/py-mcp
Project-URL: Documentation, https://agent-hellboy.github.io/py-mcp/
Project-URL: Repository, https://github.com/Agent-Hellboy/py-mcp
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: jsonschema
Requires-Dist: pydantic<3,>=2.7.0
Requires-Dist: typing-extensions>=4.0
Requires-Dist: uvicorn
Requires-Dist: requests
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8; extra == "docs"
Requires-Dist: pymdown-extensions>=10.14; extra == "docs"

# PyMCP Kit

[![Python CI](https://github.com/Agent-Hellboy/py-mcp/actions/workflows/python-ci.yml/badge.svg)](https://github.com/Agent-Hellboy/py-mcp/actions/workflows/python-ci.yml)
[![codecov](https://codecov.io/gh/Agent-Hellboy/py-mcp/graph/badge.svg)](https://codecov.io/gh/Agent-Hellboy/py-mcp)
[![MCP Conformance-v2025-11-25](https://github.com/Agent-Hellboy/py-mcp/actions/workflows/conformance.yml/badge.svg)](https://modelcontextprotocol.io/specification/2025-11-25)
[![PyPI - Version](https://img.shields.io/pypi/v/pymcp-kit.svg)](https://pypi.org/project/pymcp-kit/)
[![PyPI Downloads](https://static.pepy.tech/badge/pymcp-kit)](https://pepy.tech/projects/pymcp-kit)
[![Docs](https://img.shields.io/badge/docs-github%20pages-0f766e.svg)](https://agent-hellboy.github.io/py-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

[Documentation](https://agent-hellboy.github.io/py-mcp/) | [Quick Start](https://agent-hellboy.github.io/py-mcp/getting-started/) | [Tasks](https://agent-hellboy.github.io/py-mcp/tasks/) | [Security](https://agent-hellboy.github.io/py-mcp/security/) | [Middleware](https://agent-hellboy.github.io/py-mcp/middleware/)

`PyMCP Kit` is a capability-first MCP server toolkit for FastAPI. It keeps the built-in transport surface small, supports Streamable HTTP and stdio, and ships app-scoped registries, roots, tasks, and optional auth hooks without pulling in a larger framework.

## Quick Start

Install from PyPI:

```bash
pip install pymcp-kit
```

For local development from this repo:

```bash
pip install -e .
```

Register tools, prompts, and resources, then build an app:

```python
from pymcp import (
    CapabilitySettings,
    ServerSettings,
    create_app,
    prompt_registry,
    resource_registry,
    tool_registry,
)


@tool_registry.register
def add(a: float, b: float) -> str:
    return str(a + b)


@prompt_registry.register(description="Create a release summary prompt.")
def summarize_release(topic: str) -> str:
    return f"Summarize the release impact for {topic}."


@resource_registry.register(
    uri="memo://release-plan",
    name="release_plan",
    description="Latest release checklist",
    mime_type="text/markdown",
)
def release_plan() -> str:
    return "# Release Plan\n- freeze API\n- tag build\n"


@resource_registry.register_template(
    uri_template="note://{topic}",
    name="topic_note",
    description="Parameterized note resource keyed by topic.",
)
def topic_note(topic: str) -> str:
    return f"Notes for topic: {topic}"


app = create_app(
    server_settings=ServerSettings(
        name="demo-server",
        version="0.1.0",
        capabilities=CapabilitySettings(
            advertise_empty_prompts=False,
            advertise_empty_resources=False,
        ),
    )
)
```

The HTTP transport is mounted at `/mcp`. For local-process integrations, use `run_stdio_server(app)`.

Hosted documentation is built from `docs/` with MkDocs Material and published to GitHub Pages.

## Features

- Streamable HTTP transport for networked MCP servers
- Stdio transport for local-process MCP hosts
- Tool, prompt, and resource registries, including parameterized resource templates
- Roots, resource subscriptions, and app-scoped session lifecycle
- Task-aware tool execution with progress, cancellation, and result polling
- Optional authentication and authorization hooks
- Capability advertising through `CapabilitySettings`
- FastAPI middleware integration through `MiddlewareConfig`
- Small surface area focused on practical MCP server builds

## Supported MCP Methods

Server-side JSON-RPC methods and notifications implemented by `pymcp-kit`:

### Lifecycle

- `initialize`
- `ping`
- `notifications/initialized`
- `notifications/cancelled`

### Tools

- `tools/list` (cursor pagination)
- `tools/call`

### Prompts

- `prompts/list` (cursor pagination)
- `prompts/get`

### Resources

- `resources/list` (cursor pagination)
- `resources/templates/list` (cursor pagination)
- `resources/read`
- `resources/subscribe`
- `resources/unsubscribe`
- `notifications/resources/updated` (server → client)
- `notifications/resources/list_changed` (server → client, when enabled)

### Completions

- `completion/complete` (when `completions_enabled` is set)

### Tasks

- `tasks/list` (cursor pagination)
- `tasks/get`
- `tasks/cancel`
- `tasks/result`
- `notifications/tasks/status` (server → client)
- `notifications/progress` (server → client)

### Client capabilities (server-initiated helpers)

These are not inbound server handlers; the toolkit sends requests or notifications to the client when the client advertises the capability:

- `roots/list` via `request_roots_list()`
- `notifications/roots/list_changed` (client → server notification)
- `elicitation/create` via `request_elicitation()`
- `sampling/createMessage` via `request_sampling()`
- `notifications/message` via `send_log_message()`

List operations support optional `cursor` / `nextCursor` pagination. Page size is controlled by `CapabilitySettings.list_page_size` (default `50`).

See [Runtime Surface](https://agent-hellboy.github.io/py-mcp/runtime-surface/) for protocol versions, HTTP endpoints, and capability settings.

## Example Server

Run the bundled example server:

```bash
python example/run_server.py
```

That starts a FastAPI app on `http://127.0.0.1:8088` with the MCP endpoint mounted at `http://127.0.0.1:8088/mcp`.

## Stdio Transport

```python
from pymcp import create_app, run_stdio_server


app = create_app()
run_stdio_server(app)
```

## Middleware

Middleware stays separate from capability registration. Use `MiddlewareConfig` to control CORS, compression, logging, auth hooks, and custom ASGI middleware, then pass it into `create_app()`. See the hosted [Middleware guide](https://agent-hellboy.github.io/py-mcp/middleware/) for examples.

## Scope

- Prompts and resources are advertised only when registered by default
- Registries are copied into an app-scoped manager when `create_app()` runs
- Streamable HTTP and stdio are the only built-in transports
- Extra transports such as SSE and HTTP NDJSON are intentionally not shipped in `pymcp-kit`
