🚀 Shield MCP 防护中间件

Shield MCP 防护中间件是一款用于增强 Model Context Protocol (MCP) 服务器安全性和监控能力的中间件，无需修改官方 SDK。它提供了一系列工具，可保护和监控 MCP 工具调用，遵循 MCP 文档中的最佳实践，且能在不暴露自身的情况下与 MCP 开发交互。

🚀 快速开始

安装

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

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

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

代码示例

from shieldmcp import ShieldMCP

# 初始化ShieldMCP
shield = ShieldMCP()

# 使用ShieldMCP装饰器保护MCP工具
@shield.protect
def sensitive_tool():
    # 工具逻辑
    pass

# 启动服务
if __name__ == "__main__":
    shield.start()

✨ 主要特性

• 工具访问控制：基于白名单的 MCP 工具访问控制
• 结果净化：对 MCP 工具的结果进行敏感信息处理
• 结构化日志记录：使用结构化方式记录操作日志
• 速率限制：防止高频调用攻击
• 错误处理：统一管理异常和错误
• 与 MCP Inspector 兼容：支持与 MCP 监控工具集成

📦 安装指南

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

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

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

💻 使用示例

基础用法

from shieldmcp import ShieldMCP

# 初始化ShieldMCP
shield = ShieldMCP()

# 使用ShieldMCP装饰器保护MCP工具
@shield.protect
def sensitive_tool():
    # 工具逻辑
    pass

# 启动服务
if __name__ == "__main__":
    shield.start()

高级用法

装饰器

from shieldmcp import ShieldMCP

shield = ShieldMCP(
    allowed_users=["user1", "user2"],
    rate_limit=10  # 每分钟最多10次调用
)

@shield.protect
def my_tool():
    pass

审计日志记录

# 配置审计日志
shield.config_logging(
    log_file="audit.log",
    log_level=logging.INFO
)

访问控制

# 添加允许用户
shield.add_allowed_user("user1")
shield.add_allowed_user("user2")

# 移除不允许用户
shield.remove_allowed_user("user3")

净化器

from shieldmcp.sanitizer import TextSanitizer

sanitizer = TextSanitizer(
    patterns=[r"^\d{11}$"],  # 匹配电话号码
    replacement="PHONE_NUMBER"
)

clean_text = sanitizer.sanitize("你的电话是 12345678901")

速率限制

# 配置速率限制
shield.config_rate_limit(
    rate=10,  # 每分钟最多10次
    burst=2   # 突发允许2次
)

📚 详细文档

要求

系统要求

• 操作系统：Linux/Windows/MacOS
• Python 版本：3.8+

依赖项

• python >= 3.8
• pytest 测试框架
• 其他开发工具（如 IDE、版本控制系统等）

最佳实践

工具访问控制

• 定期审核和更新白名单
• 根据工具敏感程度设置合适的访问权限
• 使用多因素认证增强安全性

结果净化

• 对所有文本输出进行净化处理
• 明确定义需要隐藏的敏感模式
• 设置合理的长度限制

日志记录

• 记录用户和会话 ID
• 监控成功和失败的操作
• 使用结构化日志便于分析

速率限制

• 根据工具复杂度设置合适的限制
• 考虑突发情况设置适当的 burst 值
• 监控限流策略的触发情况

开发

设置开发环境

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

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

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

运行测试

pytest tests/

路线图

计划功能

• 支持 Clerk MCP 和 GitHub MCP
• 扩展文档内容
• 增加 TypeScript 支持

致谢

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

📄 许可证

本项目采用 MIT 许可证。