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

# 定义允许的工具
ALLOWED_TOOLS = {"search", "read_file", "write_file"}

# 创建一个文本清理器
text_sanitizer = ToolSanitizer.createTextSanitizer(
    max_length=1000,
    sensitive_patterns=[
        r"\b\d{16}\b",  # 信用卡号码
        r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"  # 电子邮件地址
    ]
)

# 配置速率限制
rate_limit = RateLimitConfig(
    requests_per_minute=60,  # 每秒 1 个请求
    burst_size=10  # 允许最多 10 个请求的突发
)

# 将装饰器应用于您的 MCP 工具
@secure_tool(
    allowed_tools=ALLOWED_TOOLS,
    sanitize_fn=text_sanitizer,
    user_id="user123",
    session_id="session456",
    rate_limit=rate_limit
)
def search(query: str):
    # 您的工具实现
    return results

组件

装饰器 (decorators.py)

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

@secure_tool(
    allowed_tools={"tool1", "tool2"},  # 允许的工具名称集合
    sanitize_fn=your_sanitizer,        # 可选的结果清理函数
    user_id="user123",                 # 可选的用户标识符
    session_id="session456",           # 可选的会话标识符
    rate_limit=RateLimitConfig(        # 可选的速率限制配置
        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")  # 如果不允许，则引发 ValueError

清理器 (sanitizers.py)

结果清理实用程序：

from shieldmcp import ToolSanitizer

# 创建一个自定义清理器
sanitizer = ToolSanitizer.createTextSanitizer(
    max_length=1000,
    sensitive_patterns=[r"\b\d{16}\b"]
)

# 直接使用它
clean_text = sanitizer("包含敏感数据的文本")

速率限制 (rate_limit.py)

令牌桶速率限制：

from shieldmcp import RateLimitConfig

# 配置速率限制
config = RateLimitConfig(
    requests_per_minute=60,
    burst_size=10
)

最佳实践

工具访问控制

• 始终定义允许的工具的白名单
• 使用尽可能严格的工具集
• 定期审查和更新白名单

结果清理

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

日志记录

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

速率限制

• 根据工具的复杂性设置适当的限制
• 考虑突发大小以获得更好的用户体验
• 监控日志中的速率限制命中

开发

设置开发环境

# 克隆存储库
git clone https://github.com/shieldmcp/shieldmcp.git
cd shieldmcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 或 Windows 上的 `venv\Scripts\activate`

# 安装开发依赖项
pip install -r requirements.txt

运行测试

pytest tests/

路线图

计划的功能

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

致谢

• 模型上下文协议 用于协议规范
• structlog 用于结构化日志记录

---

如有任何疑问，请随时提出。