Shield MCP 0pe

🚀 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 許可證。