Shieldmcp

🚀 MCP Security Shield

An MCP middleware that enhances security and monitoring capabilities without modifying the official SDK, adhering to best practices.

🚀 Quick Start

To use the Shield MCP, you first need to install the library:

pip install shieldmcp

Then, follow these steps to configure and use it:

1. Initialize the ShieldMCP instance:

   from shieldmcp import ShieldMCP
   
   shield = ShieldMCP()
   

2. Configure access control:

   shield.set_allowed_tools(["tool1", "tool2"])
   

3. Enable the result cleaning function:

   shield.enable_output_cleaning(patterns=[r"\bCredit Card Number\b"], max_length=500)
   

4. Use ShieldMCP to process requests:

   response = shield.process_request(request_data)
   

✨ Features

• Tool Access Control: Whitelist-based access control for MCP tools.
• Result Cleaning: Configurable output cleaning for results.
• Structured Logging: Comprehensive audit logging using structlog.
• Rate Limiting: Rate limiting implemented with the token bucket algorithm.
• Error Handling: Standardized error handling and formatting.
• MCP Inspector Compatibility: Seamless collaboration with the MCP Inspector tool.

📦 Installation

from shieldmcp import ShieldMCP

💻 Usage Examples

Basic Usage

from shieldmcp import ShieldMCP

shield = ShieldMCP()
shield.set_allowed_tools(["tool1", "tool2"])
shield.enable_output_cleaning(patterns=[r"\bCredit Card Number\b"], max_length=500)
response = shield.process_request(request_data)

📚 Documentation

Components

Decorators (decorators.py)

Provides decorators for protecting MCP endpoints:

from shieldmcp.decorators import shield_mcp_endpoint

@shield_mcp_endpoint
def protected_endpoint(data):
    # Process the request
    return response

Logging (logging.py)

Integrates structured logging into your application:

from shieldmcp.logging import setup_logging

setup_logging("info")
logger.info("Processing started")

Best Practices

Tool Access Control

• Always define a whitelist of allowed tools.
• Regularly review and update the whitelist.

Result Cleaning

• Clean all text outputs.
• Define sensitive data patterns.
• Set reasonable length limits.

Logging

• Include user and session IDs when available.
• Log both successful and failed operations.
• Use structured logging for better analysis.

Rate Limiting

• Set appropriate limits based on tool complexity.
• Consider burst sizes to enhance the user experience.
• Monitor rate limit triggers.

Development

Set up the development environment

# Clone the repository
git clone https://github.com/shieldmcp/shieldmcp.git
cd shieldmcp

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
pip install -r requirements.txt

Run tests

pytest tests/

Roadmap

Planned Features

• Support for Clerk MCP and Github MCP.
• Extended documentation.
• TypeScript support.

Acknowledgments

• Model Context Protocol for providing the protocol specification.
• structlog for structured logging.

Requirements

System Requirements

• Python 3.8 or higher
• pip (Python package installer)
• virtualenv (recommended for development)

License

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