Shieldmcp

Shield MCP

一款适用于模型上下文协议（MCP）服务的安全中间件，无需修改官方 SDK，即可增强安全性和监控能力。此软件包提供用于保护和监控 MCP 工具调用的工具，并遵循 MCP 文档中列出的最佳实践。在 MCP 开发过程中为你抽象处理这些事务。

目录

• 功能
• 要求
• 安装
• 快速开始
• 组件
• 最佳实践
• 开发
• 路线图
• 致谢

功能

• 工具访问控制：基于白名单控制 MCP 工具的访问
• 结果清理：可配置的工具输出清理功能
• 结构化日志：使用 structlog 进行全面的审计日志记录
• 速率限制：使用令牌桶算法进行速率限制
• 错误处理：标准化的错误处理和格式化
• 兼容 MCP Inspector：可与 MCP Inspector 工具无缝配合使用

要求

系统要求

• Python 3.8 或更高版本
• pip（Python 软件包安装程序）
• virtualenv（开发时推荐使用）

快速开始

from shieldmcp import secure_tool
from shieldmcp.sanitizers import ToolSanitizer
from shieldmcp.rate_limit import RateLimitConfig

# Define allowed tools
ALLOWED_TOOLS = {"search", "read_file", "write_file"}

# Create a text sanitizer
text_sanitizer = ToolSanitizer.createTextSanitizer(
    max_length=1000,
    sensitive_patterns=[
        r"\b\d{16}\b",  # Credit card numbers
        r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"  # Email addresses
    ]
)

# Configure rate limiting
rate_limit = RateLimitConfig(
    requests_per_minute=60,  # 1 request per second
    burst_size=10  # Allow bursts of up to 10 requests
)

# Apply the decorator to your MCP tools
@secure_tool(
    allowed_tools=ALLOWED_TOOLS,
    sanitize_fn=text_sanitizer,
    user_id="user123",
    session_id="session456",
    rate_limit=rate_limit
)
def search(query: str):
    # Your tool implementation
    return results

组件

装饰器（decorators.py）

主要的 @secure_tool 装饰器，用于协调所有安全功能：

@secure_tool(
    allowed_tools={"tool1", "tool2"},  # Set of allowed tool names
    sanitize_fn=your_sanitizer,        # Optional result sanitization function
    user_id="user123",                 # Optional user identifier
    session_id="session456",           # Optional session identifier
    rate_limit=RateLimitConfig(        # Optional rate limit configuration
        requests_per_minute=60,
        burst_size=10
    )
)
def your_tool():
    pass

审计日志（audit.py）

使用 structlog 进行结构化日志记录：

from shieldmcp import ToolAudit

audit = ToolAudit()
audit.logToolCallStart(
    tool_name="search",
    args={"query": "test"},
    user_id="user123"
)

访问控制（access.py）

工具访问验证：

from shieldmcp import ToolAccess

access = ToolAccess(allowed_tools={"tool1", "tool2"})
access.validateToolAccess("tool1")  # Raises ValueError if not allowed

清理器（sanitizers.py）

结果清理实用工具：

from shieldmcp import ToolSanitizer

# Create a custom sanitizer
sanitizer = ToolSanitizer.createTextSanitizer(
    max_length=1000,
    sensitive_patterns=[r"\b\d{16}\b"]
)

# Use it directly
clean_text = sanitizer("Your text with sensitive data")

速率限制（rate_limit.py）

令牌桶速率限制：

from shieldmcp import RateLimitConfig

# Configure rate limits
config = RateLimitConfig(
    requests_per_minute=60,
    burst_size=10
)

最佳实践

工具访问控制

• 始终定义允许使用的工具白名单
• 尽可能采用限制最严格的工具集合
• 定期检查并更新白名单

结果清理

• 清理所有文本输出
• 为敏感数据定义匹配模式
• 设置合理的长度限制

日志记录

• 在可用时包含用户 ID 和会话 ID
• 记录成功和失败的操作
• 使用结构化日志以便更好地分析

速率限制

• 根据工具的复杂程度设置合适的限制
• 考虑突发请求数量，以改善用户体验
• 在日志中监控触发速率限制的情况

开发

设置开发环境

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

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

# Install development dependencies
pip install -r requirements.txt

运行测试

pytest tests/

路线图

计划中的功能

• 支持 Clerk MCP 和 Github MCP
• 扩展文档
• 支持 TypeScript

致谢

• 模型上下文协议 提供协议规范
• structlog 提供结构化日志功能

---

欢迎随时咨询。