raccoon_mcp

# 浣熊 MCP [](/LICENSE) [](https://buymeacoffee.com/dangunn) 浣熊 MCP 是一个本地 MCP 服务器，用于协调多个 AI 代理在不同仓库中协同完成一个功能。 它在 SQLite 中持久化共享协调状态，并为仓库注册、工作规划、工人运行跟踪、持久跨仓库问题、消息和工件、事件等待和有界审计/补救循环提供 MCP 工具。 ## 目录 - [思维模型](#思维模型) - [快速入门](#快速入门) - [连接 MCP 客户端](#连接-mcp-客户端) - [使用服务器](#使用服务器) - [架构和协议文档](#架构和协议文档) - [服务器配置](#服务器配置) - [请求跟踪](#请求跟踪) - [限制和安全](#限制和安全) - [故障排除](#故障排除) - [推荐的 Codex 技能](#推荐的codex-技能) ## 思维模型 ```text 项目 ├── 仓库：后端 │ ├── 调度器实例 │ ├── 执行器 / 巴特勒 / 审计器运行 │ └── 收件箱交付 ├── 仓库：前端 │ ├── 调度器实例 │ ├── 执行器 / 巴特勒 / 审计器运行 │ └── 收件箱交付 ├── 功能 │ └── 具有所有者、依赖项、声明和修订的工作项 ├── 持久仓库请求 └── 消息、工件和仓库事件 ``` | 实体 | 目的 | | --- | --- | | `项目` | 协作边界。具有相同 `project_key` 的仓库加入同一个项目。 | | `仓库` | 后端、前端、移动、基础设施或其他代码库的稳定身份。 | | `调度器实例` | 仓库中活跃的顶级代理。一个项目或仓库可以有多个。 | | `功能` | 高级共享功能卡。 | | `工作项` | 功能中具有所有者仓库、依赖项、修订、声明和审计策略的具体部分。 | | `工人运行` | 在 `执行器`、`巴特勒` 或 `审计器` 角色中租用的子代理运行。工人不是仓库。 | | `请求` | 指向一个仓库的持久问题。可以被声明、回答、释放或失败。 | | `消息` | 交付给一个或多个仓库收件箱的不可变、紧凑的信封。 | | `工件` | 附加到消息的全文：实现报告、API 合同、答案、审计报告或注释。 | | `事件` | 指向已更改对象的轻量级通知。通过其专用工具读取对象。 | 调度器通过 `instance_id` 作用；工人通过 `worker_run_id` 作用。作用域工具需要其中一个 ID。 ## 快速入门 需求： - 稳定的 Rust 工具链； - 支持 Streamable HTTP 的 MCP 客户端； - 服务器端口的本地访问。 从项目根目录运行服务器： ```powershell cargo run --release -- --database .raccoon-mcp/hub.sqlite3 ``` 默认端点是： ```text http://127.0.0.1:8765/mcp ``` 数据库目录会自动创建。使用单独的数据库和端口进行隔离测试运行： ```powershell cargo run --release -- ` --port 8877 ` --database C:\temp\raccoon-mcp\hub.sqlite3 ` --log-level DEBUG ``` 检查 HTTP 进程和 SQLite 写路径： ```powershell Invoke-RestMethod http://127.0.0.1:8765/healthz Invoke-RestMethod http://127.0.0.1:8765/readyz ``` `/healthz` 仅检查 HTTP 进程。`/readyz` 打开一个 SQLite 事务，执行一个无害的写入，然后回滚。`/metrics` 在服务器启动时不可用 `--enable-metrics`。 `Ctrl+C` 执行正常关闭：主动等待被取消，维护停止，本地租期过期。 ## 连接 MCP 客户端 ### Codex 将服务器添加到 `%USERPROFILE%\.codex\config.toml` 在 Windows 上，或 `~/.codex/config.toml` 在类 Unix 系统上： ```toml [mcp_servers.raccoon_mcp] url = "http://127.0.0.1:8765/mcp" enabled = true tool_timeout_sec = 90 ``` 在更改 MCP 客户端配置后重启它。 保持 `tool_timeout_sec` 高于服务器的 `--max-wait-seconds` 值。事件等待在两侧都是有限的：服务器默认为 60 秒上限，MCP 客户端可以提前取消。 MCP 客户端处理 `initialize`、`Mcp-Session-Id`、协议版本标头和会话删除。正常使用不需要手写的 JSON-RPC 或 HTTP 请求。 ## 使用服务器 配置服务器、MCP 客户端、仓库路由块和协作技能后，请要求一个仓库中的代理通过 Raccoon MCP 协调任务。例如： > 使用 `$raccoon-mcp-collaboration` 来协调此功能与后端、Android 和 web 仓库。担任主要调度器，创建共享计划，委托仓库拥有的工作，保持功能开启，直到所需的独立审计通过。 在每个应参与的仓库中启动或打开一个代理会话。代理注册他们的仓库，发现共享工作，生成跟踪的子代理，交换持久报告，并通过 MCP 工具等待相关事件。你仍然负责功能请求、产品决策和审查生成的代码。 在高级别上，一个协调的任务遵循此生命周期： ```text 功能 -> 仓库拥有的工作项 -> 新的执行器运行和实现报告 -> 独立的审计器运行 -> 可选的补救和重新审计 -> 完成或取消的功能 ``` 仓库是持久的身份。调度器实例和子工人运行是租用的执行会话。如果一个调度器消失，同一个仓库中的另一个实例可以在所有权租期过期后恢复持久工作；它不需要重用以前的 `instance_id`。 ## 架构和协议文档 人类安装、配置和故障排除保留在此 README 中。详细的实体规则、JSON 示例、工具工作流程、模式、事件语义、租期和恢复行为在 [架构和协议参考](/docs/ARCHITECTURE.md) 中。 代理通常应遵循下面的协作技能，以及实时的 MCP 工具模式和 `hub://guide`。架构文档主要供维护者、技能作者、调试和协议审查使用；用户不需要手动重现其调用。 ## 服务器配置 显示权威 CLI 帮助： ```powershell cargo run -- --help ``` | 标志 | 默认值 | 目的 | | --- | ---: | --- | | `--host` | `127.0.0.1` | 绑定接口。 | | `--port` | `8765` | TCP 端口。 | | `--database` | `.raccoon-mcp/hub.sqlite3` | SQLite 路径。 | | `--max-db-connections` | `4` | 连接池大小，从 1 到 32。 | | `--lease-seconds` | `1800` | 调度器租期，60–65535 秒。 | | `--worker-lease-seconds` | `3600` | 工人租期，60–65535 秒。 | | `--request-claim-lease-seconds` | `600` | 请求声明租期，60–65535 秒。 | | `--work-item-claim-lease-seconds` | `3600` | 工作项声明租期，60–65535 秒。 | | `--max-summary-bytes` | `1024` | UTF-8 标题和摘要字段的限制，128–65535。 | | `--max-artifact-bytes` | `524288` | UTF-8 工件正文的限制，1024–1048576。 | | `--max-wait-seconds` | `60` | 事件等待的硬上限，1–65535 秒。 | | `--maintenance-interval-seconds` | `30` | 租期和会话清理间隔，1–3600 秒。 | | `--retention-interval-seconds` | `0` | 保留间隔；`0` 禁用保留。 | | `--retention-seconds` | `604800` | 启用保留时的事件/幂等性保留年龄。 | | `--enable-metrics` | 关闭 | 暴露 `GET /metrics`。 | | `--session-idle-timeout-seconds` | `3600` | MCP 会话空闲超时，60–65535 秒。 | | `--max-sessions` | `128` | 内存 MCP 会话限制，1–4096。 | | `--log-level` | `INFO` | 应用程序级别：`DEBUG`、`INFO`、`WARNING` 或 `ERROR`。依赖项保持在 `WARN`（选择时为 `ERROR`），因此 `DEBUG` 不会打印 SQL 语句。 | | `--allow-host` | — | 其他来源主机名；可以重复。 | 实际本地配置文件通常很简单： ```powershell cargo run --release -- ` --database .raccoon-mcp/hub.sqlite3 ` --max-summary-bytes 4096 ` --log-level INFO ``` ## 请求跟踪 每个解析的 JSON-RPC 调用都会在 `mcp_request` 跟踪范围中生成一个 `MCP 请求完成` 事件。在默认的 `INFO` 级别下，这个可搜索的故事包括： - `session_id`、`JSON-RPC` `rpc_request_id`、方法、工具名称； - 客户端提供的原始演员和链接实体 ID； - `coordination_request_id`，与 JSON-RPC 请求 ID 分开； - 标量所有权、血统、线程/回复、取消、资源和页面光标链接； - 依赖项、审计范围和收件人数组的计数，而不是转储这些数组； - 解析后的 `project_id` 和 `repository_id` 在演员授权后； - 总 `duration_ms`、结果和调用失败时的稳定错误代码。 `wait_for_events` 还记录了请求的/有效的超时、解析的起始和结束光标、事件计数、经过的时间以及 `events`、`deadline`、`cancelled` 或 `error` 作为其退出原因。演员解析详细信息在 `DEBUG` 级别仍然可用，而不会产生第二个误导性的 INFO 请求行。 无更改的租期维护通过也仅在 `DEBUG` 级别记录。`INFO` 维护条目意味着实际清除了会话或演员，放弃了工人，或重新排队了请求。 ## 限制和安全 | 值 | 限制 | | --- | ---: | | `context_refs` | 50 个对象 | | 一个审计器运行中的工作项 | 50 | | 一个工作项的依赖项 | 100 | | 一个消息的收件人 | 100 | | `list_work_items` 页面 | 100 | | `list_inbox` 页面 | 100 | | `wait_for_events` 页面 | 50 | | 历史/发现列表页面 | 50 | | 每个项目的审计深度 | 1–10 | | 显式 `wait_for_events.timeout_seconds` | 0–配置的 `--max-wait-seconds` 在发布的模式中 | | `idempotency_key` | 1–128 字节 | | `correlation_id` | 最多 128 字节 | | `consumer_key` | 1–64 字节；ASCII 字母、数字、`.`、`_` 和 `-` | `context_refs` 是任意 JSON 对象的数组。服务器验证对象形状和计数，但不强制执行自定义模式。保持引用紧凑，而不是复制大量上下文到每个调用中。 不支持 JSON-RPC 批处理。一次发送一个 MCP 请求。 此服务器用于受信任的本地环境： - 没有用户身份验证； - 来源验证不是身份验证； - 工件可能包含本地源代码上下文并在 SQLite 中持久化； - 不要将端口暴露给不受信任的网络，或在没有外部保护的情况下使用 `--host 0.0.0.0`。 ## 故障排除 ### 代理无法看到工具 1. 检查 `GET /healthz`。 2. 检查配置的 URL：`http://127.0.0.1:8765/mcp`。 3. 在更改配置后重启 MCP 客户端。 4. 检查另一个进程是否占用该端口。 5. 使用 `--log-level DEBUG` 启动服务器。 ### `wait_for_events` 意外结束 `outcome: "deadline"` 响应是正常的：这意味着在此有限调用期间没有匹配的事件到达。使用不变的 `next_cursor` 仅在功能仍然激活时重复。 如果 MCP 客户端在预期之前取消，请将其 `tool_timeout_sec` 保持在 `--max-wait-seconds` 以上。省略使用服务器上限；它永远不会创建无限等待。 ### `revision_conflict` 另一个突变首先更改了工作项。调用 `get_work_item`，将预期的更改应用于当前状态，然后使用新的 `expected_revision` 重试。 ### `claim_conflict` 另一个实时演员拥有该资源。尊重返回的 `retry_at` 或 `retry_after_seconds`，然后在重试之前读取当前状态。 ### 工作人员无法完成 使用 `get_worker_run`。过期的工作人员变为 `abandoned` 且无法复活；创建一个新的工作人员运行。工作项执行器还需要其自己的 `implementation_report`；审计器需要一个 `audit_report`。 ### 工作项无法完成 检查： 1. 项目是 `in_progress`，或在已经完成的工作报告恢复后 `claimed`； 2. 其声明当前由调用的调度器拥有； 3. 链接的执行器已完成； 4. `expected_revision` 是当前的； 5. `implementation_artifact_id` 属于仓库和项目最新的已完成执行器。执行器的原始父实例不必保持在线：在声明过期后，同一仓库中的另一个调度器可以接管并接受持久报告。 ## 推荐的 Codex 技能 保持仓库级 `AGENTS.md` 路由规则小，并将操作工作流程移到可重用的 Codex 技能中。这样可以将工作流程从每个会话中分离出来，除非明确请求 MCP 协调。 在 Windows 上将技能安装为 `%USERPROFILE%\.codex\skills\raccoon-mcp-collaboration\SKILL.md`，或在配置 `CODEX_HOME` 时安装在 `$CODEX_HOME/skills/raccoon-mcp-collaboration/SKILL.md`。 ### 仓库 `AGENTS.md` 块 为每个参与的仓库替换占位符。使用相同的项目密钥和不同的稳定仓库密钥。 ```xml <mcp_collaboration_mode> 在使用 `$raccoon-mcp-collaboration` 进行 MCP 协调、跨仓库协作、跟踪的执行器/巴特勒/审计器委托或现有协调任务的继续之前，请使用 `raccoon-mcp`。否则，请仅在该仓库内工作。 当请求协调时，使用 `$raccoon-mcp-collaboration`，并使用： - 项目密钥：`<PROJECT_KEY>`; - 仓库密钥：`<REPOSITORY_KEY>`; - 仓库显示名称：`<REPOSITORY_DISPLAY_NAME>`; - 仓库路径：当前工作树的规范绝对路径； - 仓库范围：`<REPOSITORY_SCOPE>`; - 已知对等方：`<OPTIONAL_PEER_KEYS_AND_SCOPES>`。 用户的最新明确指令覆盖此配置。 </mcp_collaboration_mode> ``` ### `SKILL.md` 使用以下内容创建 `raccoon-mcp-collaboration/SKILL.md`： ```markdown --- name: raccoon-mcp-collaboration description: 通过 raccoon-mcp 服务器协调持久的多仓库开发。只有在用户明确请求 MCP 协调、跨仓库协作、跟踪的执行器/巴特勒/审计器委托或现有协调任务的继续时才使用它。涵盖调度器注册、功能和工作项状态、工人运行、仓库请求、消息、事件等待、租期和有界审计/补救。 --- # 浣熊 MCP 协作 从活跃仓库的 `AGENTS.md` 中读取仓库特定的项目、仓库、路径、范围和对等方配置。遵循用户的最新明确覆盖。 ``` ## 工作流程 1. 在进行协同工作之前建立仓库身份。 - 首先，使用配置的项目和仓库密钥、当前绝对仓库路径以及有用的功能元数据调用 `connect_orchestrator`。 - 对于全新流程，省略 `instance_id`。仅在故意重新连接同一协调器实例时，重用先前返回的实例 ID。 - 保留服务器返回的 `project_id`、`repository_id`、`instance_id`、对等仓库 ID、`snapshot_event_cursor` 和引导计数器。 - 连接后读取 `hub://guide`，尤其是在服务器合约可能自上次编写此文件以来发生变化时。 2. 在创建新的协调对象之前恢复持久状态。 - 使用 `list_features` 和有界的 `list_work_items` 页面查找现有工作。 - 使用 `list_worker_runs`、`list_requests`、`list_deliveries`、`list_messages` 和仅限元数据的 `list_artifacts` 页面，在不记住实体 ID 的情况下重建执行和通信状态。 - 不要仅仅因为这是新的聊天会话而重复现有的功能、工作项、工人运行、请求或报告。 - 为可重试的创建调用使用稳定的 actor-scoped `idempotency_key` 值。 - 使用 `list_inbox` 检查待处理 inbox 头部；当确认历史很重要时，使用 `list_deliveries`。仅在需要内容时调用 `read_message` 和 `read_artifact`，然后使用 `ack_message` 确认已处理的投递。 - 跨项目恢复接受的实现/审计报告和显式功能/工作项链接的非请求工件。保持未链接的仓库内容私有，并将请求问题/答案工件视为参与者私有。 - 读取恢复页面后，严格在连接的 `snapshot_event_cursor` 之后开始事件消费，以便协调恢复期间提交的变更。 - 对于持久进度，选择协调器特定的 `consumer_key`，使用 `get_event_checkpoint` 读取它，并在处理后使用 `commit_event_cursor` 推进。 3. 将服务器工作卡视为共享执行 backlog。 - 使用 `create_feature` 表示整体用户可见目标，使用 `create_work_item` 表示可执行单元，并使用显式所有者仓库和依赖 ID。 - 工作项是正常的 ownership 和执行单位；除非用户明确指定本地计划，否则不要在服务器外部发明第二个隐藏队列。 - 尊重依赖顺序。`planned` 项在服务器将其移至 `ready` 之前不可执行。 - 在每次 `update_work_item` 或认领变更之前，获取当前卡并传递其当前 `expected_revision`。在 `revision_conflict` 时，重新读取、重新应用预期变更到当前状态，并在仅当变更仍然有效时重试。 4. 使用跟踪的工人运行进行委托的子代理工作。 - 每个运行的作用域限定一次：执行器/审计员仅使用 `work_item_id`；管家仅使用 `request_id`。永远不要提交两个链接或都不提交。 - 在生成子代理之前，当运行实现特定项时认领所有者工作项，然后使用角色 `executor` 和该 `work_item_id` 调用 `create_worker_run`。 - 为每个独立实现工作项生成一个新鲜的执行器子上下文。永远不要为无关的工作项重用该子上下文。 - `create_worker_run` 记录运行但不生成进程。仅在服务器返回 `worker_run_id` 后，通过可用的代理运行时生成子进程。 - 将 `worker_run_id`、任务、验收标准、相关功能和工作项 ID 以及紧凑的 `context_refs` 传递给子进程。 5. 使用持久请求进行跨仓库问题。 - 当进度依赖于另一个仓库的信息时，调用 `ask_repository` 以使问题具有明确的目标、状态、所有者和答案。 - 包括简洁的问题摘要、完整正文（如果有必要）和 `context_refs` 以便接收者识别相关功能和工作项。 - 仅当目标可以从协调状态、所有权、范围或已经掌握的现有报告中回答时，设置 `handler_requirement: orchestrator_allowed`。在答案需要当前代码检查、精确合约验证、多文件跟踪、命令或测试时，始终设置 `butler_required`。 6. 使用消息和工件进行持久报告，而不是作为隐含任务队列。 - 使用 `publish_message` 进行报告、公告、命令、API 合约、笔记和回复，这些应该被发送到仓库 inbox。 - 优先使用类型化的 `feature_id`、`work_item_id` 和 `request_id` 链接。在需要多消息对话时，使用 `thread_id`、`in_reply_to` 和 `correlation_id`。 7. 消费仓库事件。 - 使用 actor ID、相关过滤器、限定页面限制和显式上一个 `next_cursor` 或 `consumer_key` 调用 `wait_for_events`。显式光标优先。 - 当只需要一个功能或所有者时，使用 `feature_id` 和 `owner_repository_id` 过滤器。在加载完整实体之前检查紧凑状态、修订版和链接 ID。 8. 对每个完成的实现应用限定审计/补救。 - 创建一个仓库拥有的 `audit` 工作项，其 `audit_scope_work_item_ids` 仅包含来自同一仓库的已完成实现卡片。 将跨仓库审查分成一个卡片/所有者。 - 所有者仓库认领审计卡片并生成一个新鲜的角色 `auditor` 子进程，无执行器/补救对话历史，通过 `work_item_id` 链接。仅提供规范、验收标准、ID、工件引用和当前仓库状态。要求在完成工作者和审计卡片之前，恰好有一个带有结构化 `audit_outcomes` 判决的 `audit_report`。 9. 继续合格的仓库拥有的工作。 - 在完成当前项后，检查功能 backlog。如果另一个准备就绪、范围内的工作项由该仓库明确拥有，并且仍然是用户请求目标的一部分，请调用 `claim_work_item` 并执行它，除非用户限制了范围。 10. 从持久状态完成协调。 - 仅当其相关工作项处于预期终端状态、链接了必需的实现报告、每个发布的实现报告都已 `verified`、完成了必需的审计/补救，并且完成所需的请求未解决时，才认为请求的共享任务已完成。 ## 操作规则 - 不要直接读取或写入 SQLite 数据库；使用 MCP 工具。 - 不要生成 ID、重用另一个 actor 的 ID 或将 `instance_id` 和 `worker_run_id` 一起传递给 actor-scoped 工具。 - 不要将只读调用视为心跳。为协调器使用 `heartbeat`，为工作者使用 `heartbeat_worker_run`，或在长时间工作期间使用主动租约续期操作。 ## AI 用例 第一个试点版本的服务器很久以前就创建了，当时它只支持两个预定义仓库之间的协调。使用 Codex 和 GPT-5.6，我完全重新设计了该原型，将其变成了一个全新的开发者工具：Raccoon MCP 现在可以在一个项目中连接多个仓库，提供结构化和持久的协调工作流，并支持专门的协调器、执行器、管家和审计员角色。 在 OpenAI Build Week 前几天，主要的重新设计工作才刚刚开始，但在活动期间完成了大部分实施。我使用 Codex 来探索和规划服务器架构，在 Rust 中实现重新设计，调查和修复错误，并独立审计已完成的变更。在初始实施后，我运行了一个大型多仓库现场测试，带有真实的协调器会话。Codex 帮助我分析生成的报告和持久的服务器状态，将发现结果转化为具体的协议更新计划，实现该计划，并通过进一步的测试和审计验证更新的协调工作流。