防护mcp

Name: 防护mcp
Author: shieldmcp

作者：shieldmcp3 星标更新：2025-04-05

安装使用来源：spider==github.com

项目介绍

Shield MCP

这是一个用于 Model Context Protocol (MCP) 服务器的安全中间件，它增强了安全性和监控能力，而无需修改官方SDK。此包提供了工具以保护和监控 MCP 工具调用，并遵循 MCP 文档中概述的最佳实践。在 MCP 开发过程中抽象自己。

功能

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

需求

系统需求

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,  # 每分钟请求次数
    burst_size=110  # 允许突发的最大请求数量
)

# 将装饰器应用于您的 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("Your text with sensitive data")

速率限制 (`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 支持

致谢

Model Context Protocol 提供协议规范
structlog 提供结构化日志记录

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