+
Skip to content

Add plugins like observability, timeout, timing, ratelimiting, guardrails, human-in-the-loop to your MCPs

License

Notifications You must be signed in to change notification settings

zhjch05/mcp-plugins

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

99 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MCP Plugins

🚧 Experimental - Not Recommended for Production Use
This package is currently in experimental mode and may contain bugs, breaking changes, or incomplete features. Use at your own risk in development and testing environments only.

A collection of MCP middleware plugins based on FastMCP to add features like observability, error handling, guardrails, allowlists, and human-in-the-loop etc. for your MCP. Can be called from python code or through a cli proxy on top of MCP.

Quick Start

pip install mcp-plugins

Usage with python (FastMCP)

from fastmcp import FastMCP

from mcp_plugins import ToolLoggingMiddleware

MCP_CONFIG = {
    "hackernews": {
      "command": "uvx",
      "args": ["mcp-hn"],
      "transport": "stdio"
    },
    "every": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "transport": "stdio"
    }
}

server = FastMCP.as_proxy(MCP_CONFIG, name="MCP-HN with Tool Logging")

server.add_middleware(
    ToolLoggingMiddleware(
        log_tool_metadata=True,
        log_arguments=True,
        log_results=True,
        include_timestamps=True,
        max_log_length=1000,
    )
)

server.run(transport="streamable-http", host="0.0.0.0", port=9000)

Usage with config.json via cli proxy

mcp-plugins run config.json --transport streamable-http --host 0.0.0.0 --port 9000

config.json

{
  "mcpServers": {
    "hackernews": {
      "command": "uvx",
      "args": ["mcp-hn"],
      "transport": "stdio"
    },
    "every": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "transport": "stdio"
    }
  },
  "plugins": [
    {
      "type": "tool_logging",
      "config": {
        "enabled": true,
        "log_tool_metadata": true,
        "log_arguments": true,
        "log_results": true,
        "include_timestamps": true,
        "max_log_length": 1000,
        "log_format": "human"
      }
    }
  ]
}

Available Middleware

This package provides both custom middleware plugins and integrates with FastMCP's built-in middleware system. Each middleware has its own detailed documentation:

⚠️ Important Caveat: When multiple MCP servers are joined together, the tool names to be allowed or denied would be in the format "<server_name>_<tool_name>". For example, if you have a server named "weather" with a tool "get_forecast", you would reference it as "weather_get_forecast" in your allowlist or denylist configuration. You may use MCP inspector to check the exact tool names.

Custom Middleware Plugins

Logging

Human-in-the-Loop

Debugging

  • DebugMiddleware - Raw JSON-RPC context inspection for protocol-level debugging

Access Control

Guardrails

Tool Call Timeout

FastMCP Built-in Middleware

Timing & Performance

Rate Limiting

Logging

Error Handling

Project Structure

The project is organized into several key directories:

  • mcp_plugins/: Core middleware plugins and CLI implementation
  • python_examples/: Python code examples demonstrating middleware usage
  • json_examples/: JSON configuration examples for direct CLI usage
  • docs/: Comprehensive documentation for each middleware type
  • tests/: Test suite for all middleware implementations

Using the CLI

The easiest way to get started is using the built-in CLI:

# Create a sample configuration
mcp-plugins create-config config.json

# Run in stdio mode (default)
mcp-plugins run config.json

# Run with custom transport
mcp-plugins run config.json --transport streamable-http

# Run with custom host/port
mcp-plugins run config.json --transport streamable-http --host 127.0.0.1 --port 9001

# Run with custom log level
mcp-plugins run config.json --log-level DEBUG

# Run with all servers in configuration
mcp-plugins run config.json

Transport Types:

  • stdio: For local command execution (requires command and args)
  • http: For HTTP endpoints (requires url)
  • sse: For Server-Sent Events (requires url)
  • streamable-http: For streamable HTTP (requires url)

Note: The CLI always runs as an output server. Use --transport stdio for local development or specify network transports (http, sse, streamable-http) with --host and --port for remote access.

Examples

The project includes comprehensive examples demonstrating all available middleware plugins. You can run examples using the unified runner:

List Available Examples

# Using uv (recommended)
uv run python run_examples.py --list

# Or directly from the python_examples directory
uv run python python_examples/run_examples.py --list

Run Examples

# Run a simple logging example
uv run python run_examples.py simple-logging

# Run a specific variant
uv run python run_examples.py tool-logging basic

# Run advanced examples
uv run python run_examples.py multiple-middleware custom
uv run python run_examples.py timing detailed
uv run python run_examples.py rate-limiting token-bucket
uv run python run_examples.py error-handling with-logging
uv run python run_examples.py structured-logging custom-methods

Available Example Categories

  • simple-logging: Basic operation tracking
  • tool-logging: Detailed tool execution logging
  • tool-access-control: Tool allowlist/denylist access control
  • multiple-middleware: Combining multiple plugins
  • timing: Performance timing middleware
  • rate-limiting: Request rate limiting
  • error-handling: Error handling middleware
  • structured-logging: Structured logging

Each category includes multiple variants demonstrating different configurations and use cases.

Example Formats

  • python_examples/: Python implementation of all examples with runnable code
  • json_examples/: JSON configuration examples that follow the same schema as sample-config.json and can be used directly with the MCP Plugins CLI

JSON Examples

The JSON examples provide ready-to-use configuration files that can be run directly with the CLI:

# List all available JSON examples
uv run python json_examples/run_json_examples.py list

# Show detailed information about a specific example
uv run python json_examples/run_json_examples.py show simple_logging_example.json

# Validate all JSON examples
uv run python json_examples/run_json_examples.py validate

# Run any JSON example directly with the CLI
mcp-plugins run json_examples/simple_logging_example.json
mcp-plugins run json_examples/tool_logging_example.json
mcp-plugins run json_examples/multiple_middleware_example.json

Development and Code Quality

The project includes comprehensive tooling for development and code quality:

Code Quality Tools

# Format all code
make format

# Check code formatting
make format-check

# Lint all code
make lint

# Auto-fix linting issues
make lint-fix

# Run all checks (format, lint, test)
make check

# Run all checks with auto-fix
make check-fix

Validation

All JSON examples are validated using the same validation logic as the CLI:

  • Schema Validation: Ensures examples follow the correct configuration structure
  • MCP Server Validation: Validates server configurations and transport types
  • Plugin Validation: Validates plugin configurations against defined schemas
  • Type Checking: Ensures proper data types for all configuration values

Testing

# Run tests
make test

# Run tests with coverage
make test-coverage

# Run tests in watch mode
make test-watch

License

Apache 2.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

Add plugins like observability, timeout, timing, ratelimiting, guardrails, human-in-the-loop to your MCPs

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published
点击 这是indexloc提供的php浏览器服务,不要输入任何密码和下载