CoralSwarm Connect

CoralSwarm Connect

连接 CoralSwarm MCP，即可在会话中自动将工作记录到你的 ocean——在会话进行期间的自然检查点记录，而不只是会话结束时。支持 Claude Code、Cursor 和 Codex。请在一个管理器中启用此插件；同时启用两份会导致 SessionStart 触发两次（内核会忽略重复触发）。

安装

公开目录提交材料和独立的 OpenAI ZIP 构建器见目录发布。OpenAI 目录包支持按需搜索和选择性保存，但不包含捕获钩子；下方的编码插件则保留现有的捕获行为。

安装分为两个层级。插件提供 MCP 工具、捕获钩子和捆绑的技能；原始 MCP URL仅提供工具，可用于任何 MCP 客户端。

客户端	安装
Claude Code（插件）	/plugin marketplace add CoralSwarm/coralswarm-connect 然后运行 /plugin install coralswarm-connect@coralswarm-connect
Cursor（插件）	将此仓库添加为插件源，安装 coralswarm-connect，然后完成 MCP 登录
Codex（插件）	使用同一仓库和同一插件名称；Codex 可能会在首次使用时要求你信任钩子
任何 MCP 客户端——Cursor、ChatGPT、VS Code 或你自己的客户端——（仅工具）	添加类型为 streamable HTTP 的 MCP 服务，地址为 https://api.coralswarm.com/mcp

coralswarm-connect@coralswarm-connect 并非笔误：前半部分是插件，后半部分是此仓库发布到的市场（两者都名为 coralswarm-connect——参见 .claude-plugin/marketplace.json）。在 shell 中运行 claude plugin marketplace add … / claude plugin install … 也能执行相同的两个命令。

完成上述任一安装后，请进行身份验证：在 Claude Code 中运行 /mcp，并在 coralswarm 服务上选择 Authenticate；在 Cursor 中使用 /mcp login 或 mcp_auth 提示词。身份验证采用 OAuth（Clerk）和动态客户端注册——无需粘贴 API 密钥，也无需将任何内容写入配置文件。

MCP URL 必须是这个确切字符串。Cursor 会拒绝与服务受保护资源元数据不匹配的 fly.dev 资源。

CoralSwarm Connect 尚未列入任何客户端内置的插件或连接器目录。上述安装方式是目前可用的方式。此仓库还提供了 server.json，用于将其以 com.coralswarm/coralswarm 的名称提交到官方 MCP Registry；该条目会通过发布标签发布（参见发布），因此只有在发布标签后，才应视为已在目录中列出。

启用插件时，不要运行 scripts/install.mjs，否则会在 settings.json 中重复注册相同事件。

公开插件仓库。 此仓库是市场源。产品后端仍位于 CoralSwarm/coralswarm。运行 /plugin marketplace update coralswarm-connect 以刷新。

一次性信任和 OAuth。 插件提供的 MCP 服务仍要求你首次使用时批准该服务（信任提示），并通过 /mcp 完成 OAuth——插件会声明服务，但无法预先授权你的账户。

插件的设置内容

1. MCP 连接（.mcp.json）——声明 CoralSwarm MCP 服务 （HTTP 传输），以便在完成身份验证后使用其工具（list_oceans、recent_activity、ask_ocean、 search_atoms、get_reef、add_context、list_sessions，等等）。

   插件 .mcp.json 中使用的是字面量 URL https://api.coralswarm.com/mcp（主机不会展开 ${VAR:-default}，并且 Cursor 要求与服务端受保护资源元数据逐字节完全一致）。没有单独的组织地址；同一个 URL 同时服务于你的 个人 ocean 和你所属的所有组织。暂存环境或本地后端应通过用户级 MCP 覆盖项（~/.cursor/mcp.json / claude mcp add）配置，而不是修改插件。

   个人与组织通过带内方式选择，而不是通过 URL：如果你至少属于 1 个组织，连接启动时会限制为工作区工具 list_tenants 和 select_tenant。调用 list_tenants，然后调用 select_tenant 并指定你想使用的组织（或者不传 org_id 以使用个人 ocean）。这样会解锁其余工具，并将范围限定为你选择的空间。随时再次调用 select_tenant 即可切换，无需新会话， 不同于旧的按 URL 配置方式。

   想同时使用两者？用它自己的服务名称再次注册这个相同的 URL（见下文的手动安装），然后分别在每个注册项上调用 select_tenant——每个注册项都有自己的 OAuth 连接 和独立记忆的选择。这样，你便可在同一个会话中使用两组工具， 并通过服务名称区分。

2. 捕获钩子（hooks/hooks.json），全部在会话期间触发：

   • SessionStart → 提示 Agent 加载相关 ocean 上下文，并在每个里程碑发生时保存， 同时输出经过清理的会话元数据（项目键、Git 分支、去除凭据的远程地址、仓库路径、主机名、 harness 版本），供 Agent 添加到每次保存的数据中。混合式 事件清单会列出已注册的捕获事件与本次会话中观察到的事件；从未触发某个事件的主机将保持静默（公开降级），而不会阻塞当前轮次。
   • UserPromptSubmit → 防抖提醒（每约 15 分钟活跃工作时间触发一次）以保存近期进度，并在会话中 Git 分支变更时显示一行提示。这是会话期间定期进行的捕获。
   • PreCompact → 在对话压缩前，将未保存的工作写入 ocean，避免内容丢失。
   • Stop → 最后的兜底保存（约 10 分钟防抖）。
   • PostToolUse（匹配器 add_context）→ 每次运行 add_context 保存时都会写入本地活动 日志（Claude mcp__…add_context、Cursor MCP: …/add_context / CallDynamicTool），以支持崩溃会话的确定性恢复（见下文）。每个事件都会通过 hooks/run.mjs 调度。

3. coralswarm-connect 技能——说出 “onboard coralswarm”，随附的 技能就会以对话方式引导你完成相同的设置（适用于通过其他方式安装了 MCP，或想验证往返流程的情况）。

插件安装始终包含 Stop 兜底钩子。 手动安装程序 （scripts/install.mjs）提供 --no-stop 标志，可省略此钩子；但插件的 hooks.json 是静态的——无法接收安装时标志——因此这里始终包含 Stop 钩子。该钩子经过防抖（每个会话约 10 分钟），因此不会频繁触发；主要由 PreCompact 和会话期间的提醒完成大部分工作。

钩子引用 ${CLAUDE_PLUGIN_ROOT}，Claude Code、Cursor 和 Codex 会将其展开为此插件的安装目录。每个事件的命令都是 node "${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs"（Cursor 会忽略单独的 args 数组）。钩子脚本会将每个会话的防抖、分支和 primer 状态写入 ~/.coralswarm/state/（与手动安装路径共享）。primer 每个 session_id 只运行一次，因此同时安装 Claude 和 Cursor 时不会重复注入。

会话元数据与凭据剥离保证（阶段 2）

SessionStart 预备钩子会读取钩子 stdin 载荷并收集尽力而为的会话元数据——无法获取的字段会被省略；如果缺少 git/env，钩子仍会继续运行。保存会话检查点仍需要 session_id；可省略可选的来源信息。git 远程地址会经过 hooks/project-key.mjs 处理；它是后端 v1 规范化器（backend/src/project_key.rs）的逐字节一致移植版，会无条件剥离嵌入的凭据，确保该值在注入提示词之前就已完成剥离——像 https://x:[email protected]/a/b.git 这样包含令牌的远程地址只会输出为 github.com/a/b。这些值是尽力而为的来源信息；服务器会重新规范化并验证所有内容。

Agent 会话——后台运行、机器人及其子 Agent

机器人或后台工作进程可通过向 add_context 传入稳定的 session_id 和 session_kind="agent"，并提供 agent_name 和实际的客户端 platform，来保存 Agent 会话。不同主题之间应沿用相同的会话 ID，并为每个里程碑使用新的检查点 ID。仅设置 session_kind 会使保存内容仍被视为备注。

在受支持的运行环境中，只需命名 Agent 即可：在启动前设置 CORALSWARM_AGENT_NAME（或使用 Claude Agent SDK 运行；它会通过 CLAUDE_AGENT_SDK_CLIENT_APP 自动命名），预备钩子便会将 agent_name 与运行环境的会话 ID 一并输出——服务器会根据该名称的存在推断 session_kind=agent。只有在服务器无法通过其他方式识别运行环境时，才显式设置 CORALSWARM_SESSION_KIND=agent（以及 CORALSWARM_PLATFORM、CORALSWARM_TASK）。自定义机器人直接调用 MCP，并在运行状态中保留会话 ID 和检查点 ID。有关独立备注、编码对话、机器人检查点、重试以及确认保存内容的说明，请参阅保存约定和示例。有关环境变量以及如何将每个子 Agent 自己的会话关联到父会话的信息，请参阅 Agent 设置。

确定性对账——崩溃/被终止的会话如何恢复

上面的提示是由模型驱动的：只有 Agent 采取行动时才有帮助。 仍有三种情况会导致工作遗漏：

• 强制终止——SIGKILL、笔记本电脑关机、OOM——不会触发任何退出钩子， 因此进程退出时无法刷新数据；
• Agent 忽略会话中途的提示；
• 很长的单轮交互会在防抖提醒之间完成大量工作。

由于已终止的会话无法在终止时写入“你有未保存的工作”标记， 插件会在正常运行期间持续写入心跳，并在下一次会话开始时进行对账。它会为每个会话 保留一条精简记录——仅包含路径和时间戳，绝不包含对话记录内容——存放在 ~/.coralswarm/state/sessions/{session_id}.json：

• SessionStart、UserPromptSubmit 和 Stop/PreCompact 会更新 last_activity_at（并记录对话记录路径、cwd 和项目键）；
• 每当运行 add_context，PostToolUse 钩子就会写入 last_save_at。 当一次恢复保存操作在工具输入中传入原始会话的 session_id 时，时间戳会写入 该会话的记录——因此后续会话中的保存操作可以确定性地清除较早会话的待处理 标记。

在下一次新的 SessionStart 时，primer 会扫描记录，找出 last_activity_at 晚于 last_save_at 的记录（即从未保存的工作），限定为同一项目、最近 7 天内的记录，排除当前会话，且最多取最近的 3 条。对于每条记录，它都会注入一条有界指令，要求只读取该会话本地对话记录的末尾（这些文件可能有数百 MB，绝不能读取整个文件），整理出简明摘要，并通过 add_context 保存，同时传入原始 session_id。该保存操作会清除标记。每个会话最多提示两次，之后会标记为已放弃，以保持列表整洁；超过 30 天的记录会被清理。

此流程完全在本地进行：无需更改后端、无需长期令牌，也不会上传原始对话记录。模型仍会准确整理要保存的内容，记录账本只负责让提醒变得确定。注入安全：记录账本中的值都是数据，因此只有当候选记录的 session_id 符合 UUID 格式，且其对话记录路径指向实际存在并位于主目录之下的文件时，才会提供该记录；ID 和路径会剥除控制字符并进行 JSON 转义，primer 绝不会读取任何对话记录内容。

可通过环境变量调整（与间隔变量一样，会限制为有限正数）： CORALSWARM_RECONCILE_WINDOW_DAYS（7）、CORALSWARM_RECONCILE_PRUNE_DAYS（30）、 CORALSWARM_RECONCILE_MAX_OFFERS（2）、CORALSWARM_RECONCILE_MAX_CANDIDATES（3）。

测试（无依赖项）

node tests/run.mjs

使用与 Rust 单元测试相同的用例矩阵运行规范化器；在带有含令牌远程地址的临时 git 仓库中端到端运行 session-primer（断言输出中绝不出现机密）；测试在仓库外的优雅降级、崩溃对账、通过 run.mjs 传入符合 Cursor 格式的 stdin（双重发送、仅运行一次 primer、MCP: / CallDynamicTool 保存时间戳）、确定性对账记录账本，以及对每个 .mjs 运行 node --check。有意省略自动恢复（[CoralSwarm resume]）。

由已连接的 Agent 调用 add_context MCP 工具来完成捕获，因此使用你现有的 OAuth——不会存储凭据，也无需更改后端。

手动安装／卸载（备用方案，不使用插件系统）

如果无法使用插件方式（例如使用较旧版本的 Claude Code，或希望将钩子安装到特定的 settings.json 作用域），原有安装程序仍可使用。它会将钩子脚本复制到 ~/.coralswarm/hooks/，并以幂等方式将钩子条目合并到 Claude Code 的 settings.json 中——绝不会覆盖现有钩子，并且只会处理命令路径指向 CoralSwarm 钩子目录的钩子。

node scripts/install.mjs --scope project     # this repo only (default)
node scripts/install.mjs --scope user        # every session
node scripts/install.mjs --scope project --no-stop     # omit the Stop backstop
node scripts/install.mjs --scope project --uninstall

手动安装方式和插件方式在功能上等效（使用相同的四个事件和命令）。不要在同一作用域同时运行两种方式，否则钩子会重复。如果安装了插件，就不需要运行手动安装程序。

自动化范围与确定性升级

这是由模型驱动的：是否捕获取决于 Agent 是否按照钩子提示词执行。对于有意义的里程碑，这种方式很可靠，但无法保证逐字节完全一致。完全确定的路径——使用 shell 钩子将原始会话记录 POST 到 CoralSwarm，不受 Agent 行为影响——需要在引导过程中签发长期有效的 CLI 令牌，并提供摄取认证端点。这是已记录的后续事项，尚未实现。

其他宿主

新的 MCP 宿主意味着新增一个清单文件，而不是重写内核。Claude Code 使用 .claude-plugin/plugin.json；Cursor 使用 .cursor-plugin/plugin.json；Codex 使用 .codex-plugin/plugin.json。这三个清单都指向同一个 .mcp.json、skills/ 和 hooks/hooks.json。对于没有插件管理器的机器，scripts/install.mjs 仍可作为 Claude settings.json 的备用方案（执行形式：command: "node"，args: [absolute run.mjs]）。

发布

一个版本号，四个清单文件：.claude-plugin/plugin.json、.cursor-plugin/plugin.json、.codex-plugin/plugin.json 和 server.json。如果这些文件的版本号不一致，scripts/check-version.sh 会报错，PR CI 也会运行该脚本。

# 1. bump all four to the new version, in a PR
bash scripts/check-version.sh          # must pass before you push

# 2. after it merges, tag the merge commit on main
git tag v1.2.3 && git push origin v1.2.3

创建标签后会启动 .github/workflows/release.yml，该工作流会再次检查标签是否与清单文件中的版本号一致（--expect），运行测试，验证 server.json，通过 coralswarm.com 上的 DNS 证明向注册表进行身份验证，然后发布。不会从分支或 PR 发布任何内容。

版本号严格遵循 SemVer 2.0.0——不能有前导零，也不能有空标识符——因为注册表不接受范围，并且非 SemVer 版本在发布后无法可靠排序。该工作流运行的 mcp-publisher 二进制文件固定为确切版本，并在执行前进行校验和验证，因为这是唯一持有签名密钥的步骤。

采用 DNS 证明而非 GitHub OIDC，是因为注册表根据身份验证方式推导命名空间：GitHub 身份验证仅授予 io.github.<owner>/*，而 com.coralswarm/* 这样的反向 DNS 命名空间需要进行域名验证。coralswarm.com 上的顶级域 TXT 记录和 MCP_REGISTRY_DNS_PRIVATE_KEY 密钥已记录在工作流头部。

支持

• Bug 和功能请求：GitHub Issues
• 其他问题：[email protected]
• 安全问题：请参阅 SECURITY.md

贡献

仅接受 PR——main 已锁定。请参阅 CONTRIBUTING.md 和 SECURITY.md。提交 PR 前，请运行 node tests/run.mjs 和 bash scripts/check-version.sh。