Shield MCP 0pe

🚀 Shield MCP Protection Middleware

A middleware for enhancing the security and monitoring capabilities of Model Context Protocol (MCP) servers without modifying the official SDK. This package provides tools to protect and monitor MCP tool calls, adhering to the best practices mentioned in the MCP documentation. It interacts with MCP development without revealing itself.

🚀 Quick Start

Prerequisites

• System Requirements:
  • Operating System: Linux/Windows/MacOS
  • Python Version: 3.8+
• Dependencies:
  • python >= 3.8
  • pytest testing framework
  • Other development tools (e.g., IDE, version control system, etc.)

Installation

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

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

# Install dependencies
pip install -r requirements.txt

Basic Usage

from shieldmcp import ShieldMCP

# Initialize ShieldMCP
shield = ShieldMCP()

# Protect MCP tools using the ShieldMCP decorator
@shield.protect
def sensitive_tool():
    # Tool logic
    pass

# Start the service
if __name__ == "__main__":
    shield.start()

✨ Features

• Tool Access Control: Whitelist-based access control for MCP tools.
• Result Sanitization: Handle sensitive information in MCP tool results.
• Structured Logging: Log operation logs in a structured manner.
• Rate Limiting: Prevent high-frequency call attacks.
• Error Handling: Manage exceptions and errors uniformly.
• Compatibility with MCP Inspector: Support integration with MCP monitoring tools.

📦 Installation

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

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

# Install dependencies
pip install -r requirements.txt

💻 Usage Examples

Basic Usage

from shieldmcp import ShieldMCP

# Initialize ShieldMCP
shield = ShieldMCP()

# Protect MCP tools using the ShieldMCP decorator
@shield.protect
def sensitive_tool():
    # Tool logic
    pass

# Start the service
if __name__ == "__main__":
    shield.start()

Advanced Usage

Decorator

from shieldmcp import ShieldMCP

shield = ShieldMCP(
    allowed_users=["user1", "user2"],
    rate_limit=10  # Maximum 10 calls per minute
)

@shield.protect
def my_tool():
    pass

Audit Logging

# Configure audit logging
shield.config_logging(
    log_file="audit.log",
    log_level=logging.INFO
)

Access Control

# Add allowed users
shield.add_allowed_user("user1")
shield.add_allowed_user("user2")

# Remove disallowed users
shield.remove_allowed_user("user3")

Sanitizer

from shieldmcp.sanitizer import TextSanitizer

sanitizer = TextSanitizer(
    patterns=[r"^\d{11}$"],  # Match phone numbers
    replacement="PHONE_NUMBER"
)

clean_text = sanitizer.sanitize("Your phone number is 12345678901")

Rate Limiting

# Configure rate limiting
shield.config_rate_limit(
    rate=10,  # Maximum 10 calls per minute
    burst=2   # Allow 2 bursts
)

📚 Documentation

Best Practices

Tool Access Control

• Regularly audit and update the whitelist.
• Set appropriate access permissions based on tool sensitivity.
• Use multi-factor authentication to enhance security.

Result Sanitization

• Sanitize all text outputs.
• Clearly define sensitive patterns to be hidden.
• Set reasonable length limits.

Logging

• Log user and session IDs.
• Monitor successful and failed operations.
• Use structured logs for easy analysis.

Rate Limiting

• Set appropriate limits based on tool complexity.
• Consider burst situations and set appropriate burst values.
• Monitor the triggering of rate-limiting policies.

Development

Set up the development environment

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

# Create and activate 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/

🔧 Technical Details

Roadmap

Planned Features

• Support for Clerk MCP and GitHub MCP.
• Expand documentation content.
• Add TypeScript support.

📄 License

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

Acknowledgments

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