mcpd-plugins: Python SDK for Building mcpd Plugins

A Python SDK for building plugins for the mcpd plugin system. This SDK provides a simple, async-first API for creating gRPC-based plugins that can intercept and transform HTTP requests and responses.

Features

• Simple API: Extend BasePlugin and override only the methods you need
• Async/Await: Full async support using Python's asyncio
• Type Hints: Complete type annotations for better IDE support
• gRPC-based: Built on grpcio with protocol buffers
• Minimal Dependencies: Only requires grpcio and protobuf
• Comprehensive Examples: Five example plugins demonstrating common patterns

Installation

# Using uv (recommended)
uv add mcpd-plugins

# Using pip
pip install mcpd-plugins

Quick Start

Here's a minimal plugin that adds a custom header to HTTP requests:

import asyncio
import sys
from mcpd_plugins import BasePlugin, serve
from mcpd_plugins.v1.plugins.plugin_pb2 import (
    FLOW_REQUEST,
    Capabilities,
    HTTPRequest,
    HTTPResponse,
    Metadata,
)
from google.protobuf.empty_pb2 import Empty


class MyPlugin(BasePlugin):
    async def GetMetadata(self, request: Empty, context) -> Metadata:
        return Metadata(
            name="my-plugin",
            version="1.0.0",
            description="Adds a custom header to requests"
        )

    async def GetCapabilities(self, request: Empty, context) -> Capabilities:
        return Capabilities(flows=[FLOW_REQUEST])

    async def HandleRequest(self, request: HTTPRequest, context) -> HTTPResponse:
        response = HTTPResponse(**{"continue": True})
        response.modified_request.CopyFrom(request)
        response.modified_request.headers["X-My-Plugin"] = "processed"
        return response


if __name__ == "__main__":
    # Pass sys.argv for mcpd compatibility (handles --address and --network flags)
    asyncio.run(serve(MyPlugin(), sys.argv))

Run your plugin:

# For mcpd (with --address and --network arguments)
python my_plugin.py --address /tmp/my-plugin.sock --network unix

# For standalone testing (defaults to TCP port 50051)
python my_plugin.py

When running under mcpd, the --address and --network flags are required and automatically passed by mcpd. For standalone testing without arguments, the plugin defaults to TCP on port 50051.

Core Concepts

BasePlugin

The BasePlugin class provides default implementations for all plugin methods:

• Configure() - Initialize plugin with configuration
• Stop() - Clean up resources on shutdown
• GetMetadata() - Return plugin name, version, and description
• GetCapabilities() - Declare which flows the plugin supports
• CheckHealth() - Health check endpoint
• CheckReady() - Readiness check endpoint
• HandleRequest() - Process incoming HTTP requests
• HandleResponse() - Process outgoing HTTP responses

Override only the methods your plugin needs.

Flows

Plugins can process two types of flows:

• FLOW_REQUEST: Intercept and modify incoming HTTP requests
• FLOW_RESPONSE: Intercept and modify outgoing HTTP responses

Declare your supported flows in GetCapabilities().

Request/Response Handling

When handling requests or responses, you can:

1. Pass through unchanged: Return HTTPResponse(**{"continue": True})
2. Modify and continue: Set **{"continue": True} and modify fields
3. Reject: Set **{"continue": False} with a status code and body

Examples

The SDK includes five example plugins demonstrating common patterns:

1. Simple Plugin

Adds a custom header to all requests.

cd examples/simple_plugin
uv run python main.py

2. Auth Plugin

Validates Bearer token authentication and rejects unauthorized requests.

export AUTH_TOKEN="your-secret-token"
cd examples/auth_plugin
uv run python main.py

3. Logging Plugin

Logs HTTP request and response details for observability.

cd examples/logging_plugin
uv run python main.py

4. Rate Limit Plugin

Implements token bucket rate limiting per client IP.

cd examples/rate_limit_plugin
uv run python main.py

5. Transform Plugin

Transforms JSON request bodies by adding metadata fields.

cd examples/transform_plugin
uv run python main.py

Development

Setup

# Clone the repository
git clone https://github.com/mozilla-ai/mcpd-plugins-sdk-python.git
cd mcpd-plugins-sdk-python

# Setup development environment
make setup

Running Tests

# Run all tests
make test

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/unit/test_base_plugin.py

Linting

# Run all pre-commit hooks
make lint

# Run ruff directly
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Generating Protocol Buffers

The proto files are automatically generated from the mcpd-proto repository and committed to this repo. To regenerate:

make generate-protos

API Reference

BasePlugin

class BasePlugin(PluginServicer):
    async def Configure(self, request: PluginConfig, context) -> Empty
    async def Stop(self, request: Empty, context) -> Empty
    async def GetMetadata(self, request: Empty, context) -> Metadata
    async def GetCapabilities(self, request: Empty, context) -> Capabilities
    async def CheckHealth(self, request: Empty, context) -> Empty
    async def CheckReady(self, request: Empty, context) -> Empty
    async def HandleRequest(self, request: HTTPRequest, context) -> HTTPResponse
    async def HandleResponse(self, response: HTTPResponse, context) -> HTTPResponse

serve()

async def serve(
    plugin: BasePlugin,
    args: Optional[list[str]] = None,  # Command-line arguments (typically sys.argv)
    grace_period: float = 5.0,
) -> None

Parameters:

• plugin: The plugin instance to serve
• args: Command-line arguments. When provided (e.g., sys.argv), enables mcpd compatibility by parsing --address and --network flags. When None, runs in standalone mode on TCP port 50051.
• grace_period: Seconds to wait during graceful shutdown

Command-line flags (when args is provided):

• --address: gRPC address (socket path for unix, host:port for tcp) - required
• --network: Network type (unix or tcp) - defaults to unix

Exceptions

• PluginError - Base exception for all plugin errors
• ConfigurationError - Configuration-related errors
• ServerError - Server startup/shutdown errors

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

For security issues, please see SECURITY.md.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Related Projects

• mcpd - The mcpd daemon
• mcpd-proto - Protocol buffer definitions
• mcpd-plugins-sdk-go - Go SDK for plugins
• mcpd-plugins-sdk-dotnet - .NET SDK for plugins
• mcpd-sdk-python - Python SDK for mcpd clients