shield-mcp-0pe

🚀 Shield MCP 防护中间件

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

🚀 快速开始

Shield MCP 是用于增强 MCP 服务器安全性和监控能力的中间件。以下是一个简单示例，展示如何使用它来保护 MCP 工具：

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()

高级用法

装饰器

用于保护 MCP 工具的方法或函数，支持配置访问控制和速率限制。

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
)

访问控制

管理 MCP 工具的访问权限，支持基于用户、IP 和时间等多种策略。

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

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

净化器

净化 MCP 工具输出的结果，防止敏感信息泄露。

from shieldmcp.sanitizer import TextSanitizer

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

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

速率限制

防止高频调用攻击，保护 MCP 服务。

# 配置速率限制
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 许可证。

| 属性 | 详情 | |------|------| | 模型类型 | 用于增强 Model Context Protocol (MCP) 服务器安全性和监控能力的中间件 | | 训练数据 | 无 |

⚠️ 重要提示

请确保你的 Python 版本为 3.8 或更高，以保证本中间件的正常运行。

💡 使用建议

在使用工具访问控制时，定期审核和更新白名单，以确保系统的安全性。同时，对所有文本输出进行净化处理，明确定义需要隐藏的敏感模式。