递归伴侣MCP

Name: 递归伴侣MCP
Author: democratize-technology

作者：democratize-technology11 星标更新：2025-10-19

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

项目介绍

Recursive Companion MCP

这是一个实现了通过自我批评周期进行迭代细化的MCP（模型上下文协议）服务器。灵感来源于Hank Besser的recursive-companion，此实现增加了增量处理以避免超时并使进度可见。

功能

增量细化：通过将细化分解成离散步骤来避免超时
数学收敛：使用余弦相似度测量细化完成的时间点
领域特定优化：自动检测并优化技术、营销、策略、法律和财务领域
进度可见性：每一步骤立即返回，允许UI更新
并行会话：支持多个并发细化会话
自动会话跟踪：无需手动管理会话ID
AI友好的错误处理：提供可操作的诊断和恢复提示给AI助手

工作原理

细化过程遵循草稿 → 批评 → 修改 → 收敛模式：

草稿：生成初始响应
批评：创建多个并行批评（使用更快的模型）
修改：综合批评生成改进版本
收敛：测量相似度并重复直到达到阈值

详细架构图和系统设计文档，请参见ARCHITECTURE.md。

安装

预备条件

Python 3.10+
uv 包管理器
具有Bedrock访问权限的AWS账户
Claude桌面应用

设置

克隆仓库：

git clone https://github.com/thinkerz-ai/recursive-companion-mcp.git
cd recursive-companion-mcp

安装依赖项：

uv sync

配置AWS凭证作为环境变量或通过AWS CLI
添加到Claude桌面配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

基本配置：

{
  "mcpServers": {
    "recursive-companion": {
      "command": "/path/to/recursive-companion-mcp/run.sh",
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

优化配置（推荐）：

{
  "mcpServers": {
    "recursive-companion": {
      "command": "/path/to/recursive-companion-mcp/run.sh",
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your-access-key", 
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "BEDROCK_MODEL_ID": "anthropic.claude-3-sonnet-20240229-v1:0",
        "CRITIQUE_MODEL_ID": "anthropic.claude-3-haiku-20240307-v1:0",
        "CONVERGENCE_THRESHOLD": "0.95",
        "PARALLEL_CRITIQUES": "2",
        "MAX_ITERATIONS": "5",
        "REQUEST_TIMEOUT": "600"
      }
    }
  }
}

性能提示：

使用Haiku作为CRITIQUE_MODEL_ID以提高50%的速度
将CONVERGENCE_THRESHOLD降低至0.95以加快收敛速度
将PARALLEL_CRITIQUES减少至2以更好地利用资源
参见API_EXAMPLES.md获取更多配置示例

使用方法

该工具提供了几个用于迭代细化的MCP端点：

快速入门示例

简单细化（自动完成）：

quick_refine(prompt="解释安全API设计的关键原则", max_wait=60)

逐步细化（完全控制）：

# 开始会话
start_refinement(prompt="为电子商务设计微服务架构", domain="技术")

# 继续迭代
continue_refinement()  # 草稿阶段
continue_refinement()  # 批评阶段
continue_refinement()  # 修改阶段

# 获取最终结果
get_final_result()

会话管理：

current_session()           # 检查活动会话
list_refinement_sessions()  # 列出所有会话
abort_refinement()          # 停止并获取迄今为止的最佳结果

完整API参考

对于包含实际场景、错误处理模式和集成工作流的全面示例，请参见**API_EXAMPLES.md**。

可用工具

start_refinement - 开始新的细化会话并检测领域
continue_refinement - 推进会话通过草稿→批评→修改周期
get_final_result - 获取已完成的细化
get_refinement_status - 检查进度而不推进
current_session - 获取活动会话信息（无需ID）
list_refinement_sessions - 查看所有活动会话
abort_refinement - 停止细化，返回迄今为止的最佳版本
quick_refine - 自动完成简单的细化（小于60秒）

配置

环境变量	默认值	描述
`BEDROCK_MODEL_ID`	anthropic.claude-3-sonnet-20240229-v1:0	主生成模型
`CRITIQUE_MODEL_ID`	同BEDROCK_MODEL_ID	批评模型（使用Haiku以提高速度）
`CONVERGENCE_THRESHOLD`	0.98	收敛相似度阈值（0.90-0.99）
`PARALLEL_CRITIQUES`	3	每次迭代的并行批评数量
`MAX_ITERATIONS`	10	最大细化迭代次数
`REQUEST_TIMEOUT`	300	超时时间（秒）

🌐 可流式HTTP传输

服务器支持无状态的可流式HTTP传输，适用于需要水平扩展和基于Web集成的企业部署。

启用可流式HTTP传输

# 设置传输类型为streamable_http
export MCP_TRANSPORT=streamable_http
export MCP_HTTP_HOST=127.0.0.1  # 可选，默认为127.0.0.1
export MCP_HTTP_PORT=8080       # 可选，默认为8080

# 运行服务器
uv run python -m recursive_companion_mcp

或者在单个命令中：

MCP_TRANSPORT=streamable_http MCP_HTTP_PORT=8080 uv run python -m recursive_companion_mcp

可流式HTTP特性

✅ 无状态请求处理：每个请求的新服务器实例以实现完全隔离
✅ 会话持久性：通过会话ID跨请求维持会话
✅ 符合JSON-RPC 2.0：通过HTTP支持完整的MCP协议
✅ 企业级扩展性：与负载均衡器一起实现水平扩展
✅ Web集成：适合基于Web的AI助手
✅ 健康检查：内置健康检查端点

示例HTTP请求

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "start_refinement",
      "arguments": {
        "topic": "改进这个算法设计",
        "style": "分析型"
      }
    },
    "id": 1
  }'

传输模式比较

特性	Stdio传输	HTTP传输	可流式HTTP传输
使用场景	Claude桌面	网络访问	企业扩展性
状态管理	内存中	内存中	每个请求无状态
会话持久性	无	无	是（通过会话ID）
负载均衡	无	无	是
Web集成	无	有限	完全支持

性能

在优化设置下：

每次迭代：60-90秒
典型收敛：2-3次迭代
总时间：2-4分钟（分布在多次调用中）

使用Haiku进行批评可以减少迭代时间约50%。

AI友好功能

此工具包括专为使用它的AI助手提供的特殊功能：

自动会话跟踪：current_session_id自动维护
智能错误消息：错误包含带有可操作诊断的_ai_前缀字段
性能提示：响应包含优化建议和预测
进度预测：收敛跟踪包括剩余迭代估计

示例AI帮助错误响应：

{
  "success": false,
  "error": "未提供session_id且没有当前会话",
  "_ai_context": {
    "current_session_id": null,
    "active_session_count": 2,
    "recent_sessions": [...]
  },
  "_ai_suggestion": "使用start_refinement创建新会话",
  "_human_action": "首先启动一个新的细化会话"
}

架构

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Claude    │────▶│  MCP Server  │────▶│   Bedrock   │
│  Desktop    │◀────│              │◀────│   Claude    │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   Session    │
                    │   Manager    │
                    └──────────────┘

开发

运行测试

uv run pytest tests/

本地测试

uv run python test_incremental.py

自动化基础设施

该项目包括全面的自动化以准备开源：

🤖 Dependabot：具有智能分组的自动化依赖项更新
🚀 Semantic Release：基于常规提交的自动化版本和发布
🔒 安全监控：多工具安全扫描（Safety、Bandit、CodeQL、Trivy）
✅ 质量门：自动化测试、覆盖率、代码检查和类型检查
📦 依赖项管理：高级依赖项健康监控和更新

自动化命令

# 验证自动化设置
uv run python scripts/setup_check.py

# 验证工作流程配置
uv run python scripts/validate_workflows.py

# 手动发布（如有必要）
uv run semantic-release version --noop  # 干运行
uv run semantic-release version --minor  # 实际发布

开发工作流程

功能开发：在功能分支上工作
拉取请求：质量门自动运行
代码审查：自动的安全性和质量反馈
合并到develop：自动创建Beta版本
合并到main：自动创建生产版本

参见AUTOMATION.md获取完整的自动化文档。

致谢

本项目受到Hank Besser的recursive-companion的启发。原始实现提供了概念性的草稿 → 批评 → 修改 → 收敛模式。此MCP版本添加了：

基于会话的增量处理以避免超时
AWS Bedrock集成用于Claude和Titan嵌入
领域自动检测和专门提示
数学收敛测量
批评与生成不同模型的支持

贡献

欢迎贡献！请阅读我们的贡献指南以获取详情。

许可证

MIT许可证 - 详情请参见LICENSE文件。

感谢

原始概念：Hank Besser的recursive-companion
为模型上下文协议构建
使用AWS Bedrock访问LLM
受AI推理中的迭代细化模式启发