MCP Circuit Breaker

mcp断路器

可编程安全层 模型上下文协议（MCP）。它检测并打破代理的无限循环，防止“令牌燃烧”，并保护下游SaaS API（Salesforce、Zendesk、Stripe）免受重复的自主故障。

🚀 特性

• 传递代理：无缝封装任何现有的MCP服务器（stdio）。
• 阈值监控：跟踪连续故障并使断路器跳闸，以阻止代理无限期重试。
• 语义干预：向LLM返回“SYSTEM OVERRIDE”消息以强制其停止。
• 自动重置（半开）：自动测试电路在冷却期后是否可以关闭。
• 可配置的：调整故障阈值、窗口大小和超时。
• MIT许可证：开源，适合企业使用。

📦 安装

# Using pip
pip install mcp-circuit-breaker

# Using poetry
poetry add mcp-circuit-breaker

*注意：此包当前是本地包。您可以从源代码安装它。*

🛠 用法

“Sidecar”模式（企业最佳实践）

该项目允许您实施 侧车图案。您可以单独包装每个关键工具，而不是一个可能是单点故障的单一“通用网关”。这提供了：

1. 孤立：如果 filesystem 断路器跳闸，你的 salesforce 工具继续工作。
2. 精细安全：申请 STRICT 模式到敏感工具和 COOL-OFF 模式给别人。

快速启动（直观覆盖）

要使断路器“直观”（代理不可见），您可以将其配置为 替换 您的标准工具条目 claude_desktop_config.json.

示例：更换文件系统服务器

复制以下内容 manual_test_config.json （用自己的路径替换路径）：

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/mcp-circuit-breaker/.venv/bin/python",
      "args": ["-m", "mcp_circuit_breaker"],
      "env": {
        "DOWNSTREAM_COMMAND": "npx",
        "DOWNSTREAM_ARGS": "[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/username/Desktop\"]",
        "CB_FAILURE_THRESHOLD": "3",
        "CB_RESET_TIMEOUT": "30"
      }
    }
  }
}

现在，每当克劳德试图使用 read_file 或 list_directory，它透明地穿过断路器。

配置（环境变量）

🏗 建筑

断路器位于客户端（Claude/Cursor）和服务器（SaaS工具）之间。

graph LR
    Client[Claude Desktop] -->|MCP| CB[Circuit Breaker]
    CB -->|MCP| SaaS[SaaS MCP Server]

    subgraph "Safety Logic"
    CB -- Monitor --> Store[State Store]
    Store -- Trip --> Intervention[Stop Signal]
    end

🎯 人学技能整合

断路器也可作为 独立人类学技能 它独立于MCP基础设施工作。

什么是人类学技能？

人类技能是Claude可以在所有环境（Claude.ai、ClaudeCode、API）中使用的结构化功能。断路器技能提供相同的保护模式，而不需要MCP设置。

使用技能

技能位于 src/skills/circuit-breaker/ 包括：

• 技能.md：使用YAML frontmatter的主要技能文档
• 脚本/：独立的验证和执行工具
• 参考文献：详细的策略模式和错误目录
• 资产/：即用型配置模板

快速入门（技能）

1. 验证：测试配置

   cd src/skills/circuit-breaker
   python scripts/validate_config.py assets/config_template.json

1. 执行：测试工具是否会被堵塞

   python scripts/apply_strategy.py \
     --config assets/config_template.json \
     write_file \
     --arguments '{"path": "/etc/passwd"}'

何时使用MCP与技能

看 src/技能/断路器/README.md 获取详细的技能文档。

🤝 贡献

1. 克隆仓库。
2. 安装依赖项： poetry install.
3. 运行测试： poetry run pytest.

📄 许可证

麻省理工学院