Skip to main content
Glama

rhizome-mcp 是一个本地优先的 MCP 服务器,用于对自主 AI 编码代理进行任务跟踪与协调。它让来自不同产品——Claude Code、Codex、GitHub Copilot、VS Code 以及任何其他兼容 MCP 的客户端——的代理拥有一个共享、持久的项目工作视图:一个静态 Go 二进制文件、每个项目一个 SQLite 数据库,无需账号、无需 Docker、不依赖网络。

为什么

AI 编码代理是并发的、上下文受限的、随时可能被中断的。一份 TODO.md 或单个聊天上下文无法在这种环境中存活。rhizome-mcp 正是围绕这些故障模式构建的:

  • 崩溃安全的认领。 问题通过可续租约以原子操作完成认领。in_progress 永远不是一个被存储的状态——它是从活跃租约推导出来的,因此一个消失的代理无法永远锁住一个问题。当租约过期,这个问题重新变为可认领状态。一个部分唯一索引在数据库层面保证每个问题最多只有一个活跃的认领尝试。

  • 持久的项目记忆。 检查点记录了下一步操作,决策记录可以被新记录取代,事件历史仅追加,还覆盖问题、评论、决策和笔记的 FTS5 全文搜索。新的会话从最近一个检查点恢复,而不是重新推导状态。

  • 契约级的低 token 消耗。 紧凑的列表投影(集成测试强制保证:100 个问题的分页保持在 64 KB 以内)、在 SQL 层剔除自由文本正文的图节点、仅返回摘要的搜索、通过事件 ID 做增量同步,以及大小有界的一次调用即可取回全部上下文的工作包。

  • 规划与依赖图。 经过环检测的 blocks 关系、史诗(epic)、可认领入口点的高亮,以及原子式批量规划(最多 50 个问题、100 个关系、20 个决策处在同一个全有或全无的事务中)。

  • 评审工作流。 评审请求会锁定到精确的问题版本和消息位置;过期的目标会被自动取代,所以不可能批准改变过的代码。

  • 并发约束贯穿始终。 变更使用乐观版本控制,幂等键可重放安全,错误码稳定且可供机器直接处理。

  • 无服务器也有可观测性。 rhizome-mcp board 打印实时租约、阻塞项和评审队列,或输出一个自包含的 HTML 快照;CLI 可以 table、JSON 或 Mermaid 等形式读取所有数据。

**适合这种情况使用:**多个代理会话(或多种代理产品)长期协作在同一个仓库上,需要交接、并行开发以及在崩溃或上下文耗尽后恢复。

不适合这种情况使用: 如果需要的是托管的、多用户的跟踪器,带认证、权限和 Web UI——它在设计上就是一个单开发者的本地工具。

Related MCP server: memory-arbiter-mcp

快速开始

安装与运行

选择适合你工作流的方式:

通过 npm 零安装试用

立即试用 rhizome-mcp,无需单独安装二进制,也不需要本机有 Go 工具链:

npx rhizome-mcp serve

支持任意 MCP 客户端,平台覆盖范围见 packages/npm/README.md。这一方便快捷评估的方式。

VS Code

从 Marketplace 或 Open VSX 安装 Rhizome MCP(odrin.rhizome-mcp)。该扩展自己也平台的二进制,自动注册 MCP 服务器,并在命令面板(Command Palette)添加 Rhizome: Initialize Project。不需要终端,不需要编辑 mcp.json。详见 docs/10-vscode-extension.md。

如果你更倾向于直接使用 mcp.json 一行入口的独立二进制,则先安装下文中的二进制再用这个一键链接:添加到 VS Code。

原生二进制安装程序

下载并安装一个适配当前平台的发布二进制。安装程序会验证校验和,并默认安装到 ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.sh | sh
irm https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.ps1 | iex

官方 MCP Registry

通过官方 MCP Registry 使用 rhizome-mcp:它作为 io.github.Odrin/rhizome-mcp 列在 Model Context Protocol registry 中,供消费该 registry 的客户端使用。

初始化并连接

在你的仓库里面初始化跟踪:

rhizome-mcp init

然后向你的 MCP 客户端注册服务器。各客户端的自动化安装:

rhizome-mcp connect claude    # Claude Code
rhizome-mcp connect codex     # Codex
rhizome-mcp connect vscode    # VS Code (if using standalone binary instead of extension)
rhizome-mcp connect json      # Template for any other client

使用 --print 可先预览(试运行)。connect 会找到你的项目的实际根目录(从当前目录向上逐级查找,和 serve 的行为相同),并用 --project-root 定住它,这样无论 MCP 客户端后续从哪个子目录启动服务器,写出的配置都有效。四个目标(claude、codex、vscode、json)在这个问题上行为一致。

对于任意 MCP 客户端,手动配置与 connect 输出的服务器键等价:

{
  "mcpServers": {
    "rhizome-mcp": {
      "command": "/absolute/path/to/rhizome-mcp",
      "args": ["serve", "--project-root", "/absolute/path/to/your/repository"]
    }
  }
}

或,通过 npx 而完全不需要安装二进制:

{
  "mcpServers": {
    "rhizome-mcp": {
      "command": "npx",
      "args": ["-y", "rhizome-mcp", "serve", "--project-root", "/absolute/path/to/your/repository"]
    }
  }
}

connect 能检测到自己正处于 npx rhizome-mcp 包装器中运行,并自动输出这种 npx 形式,而不是尝试假设 npx 解析出的二进制绝对路径——那个路径存在于 npx 缓存中,一旦载体被淘汰(eviction)或者 yerm升级就会变得过期。使用解析出来的绝对路径写出的配置(默认就是这种形式)是为单台机器量身定做的,不适合提交入库或跨机器共享;如果你就是要生成一份共享的、portable 的配置,请传 connect TARGET --command 改为一个裸的 rhizome-mcp 命令名,完全依赖 PATH 查找,但使用该配置的目标机器必须都在 PATH 中具备 rhizome-mcp。

Stdio 是默认传输;协议数据输出到 stdout,日志写到 stderr。

这样就可以了——已连接的 agent 使用绝对仓库路径调用 open_project 开启会话,持有返回的 project_ref,并在后续的项目级调用中传递该引用。完整的工作流,见 agent workflow guide。返回的元数据会链接到 rhizome://guides/agent-workflow、rhizome://guides/issue-lifecycle 和 rhizome://guides/multi-agent-handoff 这些资源;仓库里的 agents 还能从 .github/skills/ 中加载 rhizome-task-workflow技能。

安装 agent 工作流技能

针对支持开放 Agent Skills 格式的 agent,可以通过 npm 分发的 skills CLI 安装 rhizome-task-workflow:

npx skills add Odrin/rhizome-mcp --skill rhizome-task-workflow

在项目运行此命令可以安装到当前项目;添加 --global 则让技能对所有项目生效。该技能会教兼容的 agent 如何选择、认领、做检查点、交接和完成 Rhizome 相关的工作任务。它与 MCP 服务器互补:它不安装 rhizome-mcp 二进制,也不会配置 MCP 连接。

监控你的项目

rhizome-mcp board                        # status counts, active leases, blockers, review queue
rhizome-mcp board --serve                # interactive local board UI at a loopback URL
rhizome-mcp board --output board.html    # self-contained HTML snapshot with the planning graph
rhizome-mcp issue list --status ready
rhizome-mcp graph ISSUE-42 --format mermaid
rhizome-mcp doctor --full

状态看板显示当前的租约数量、被阻塞的问题及其原因,未解决的评审请求以及项目全局的规划图。这个规划图会把已完成的工作(done、cancelled)从节点数量预算中排除,因此入口点的计数始终代表当前可认领的工作量。当图因为 100 节点的预算而被截断,board 会将其标记为 truncated,并用表格和 JSON 两种格式报告保留的节点数。

可选:本地 HTTP 传输

rhizome-mcp serve --http-address 127.0.0.1:0

监听绑定到的端点会记入 stderr;Streamable HTTP 端点为 http://127.0.0.1:<port>/mcp。该传输只允许回环地址、不执行认证,并强制校验严格的 Host/Origin,同时限制最大 1 MiB 的外层请求体。现代 MCP 2026-07-28 客户端会先调用 server/discover 然后再携带元数据直接发送请求;旧的 2025-11-25 客户端仍可以使用 initialize 和 notifications/initialized,无需依赖持久化的 transport 会话。若要进行持久的审计归属,可以用 create_agent_session 创建 agent_session_handle,把它传给相关变更工具,之后用 end_agent_session 为它结束;transport 连接关闭并不会隐式结束这个映射。

工作原理

init 在仓库里写且只写一个文件:

{
  "version": 1,
  "project_id": "01J..."
}

存储为 .agent-tracker.json。SQLite 数据库位于仓库外部,在操作系统的应用数据目录中,所述路径由 project_id 解析:

<application-data>/rhizome-mcp/projects/<project-id>/tasks.db

要用 --data-rootas 显式指定任意命令的数据根目录。除此之外不会触碰仓库中的其他任何内容,数据库本身也永远不会被提交到 Git 仓库。

**设计原则:**一个问题不能永远卡在 in_progress 中。有效状态是由存储状态和是否存在活跃租约共同计算得到的;如果 agent 消失且租约过期,该尝试变成 expired,目标将恢复可读取

命令

用途

init

创建 .agent-tracker.json 和项目数据库

serve [--http-address ADDR] [--profile full|agent|read-only|migration] [--project-root PATH]

运行 MCP 服务器(stdio;--http-address 用于本地 HTTP;--profile 用于收窄公布的工具目录;--project-root 用于服务工作目录之外的项目)

connect TARGET [--print] [--command]

向 MCP 客户端(claude、codex、vscode、json)注册服务器

board [--output PATH] [--serve [--http-address ADDR]]

状态看板:计数、租约、阻塞项、审查队列;可选的 HTML 快照;--serve 运行一个临时 HTTP 服务器

issue list / issue show ISSUE-ID

使用过滤器查看 issue

search QUERY

跨 issue、评论、决策和笔记进行全文搜索

graph ISSUE-ID

以表格、JSON 或 Mermaid 的形式呈现依赖图

project info / project export / project import

项目元数据;逻辑 JSON 输出;逻辑 JSON 导入(`--input PATH

-with--dry-runor--apply`)

backup --output PATH

WAL 安全的在线备份

doctor [--full]

完整性、架构和不变量检查

maintenance release-attempt / rebuild-search-index

管理恢复

不带参数运行 rhizome-mcp 可查看完整用法,运行 rhizome-mcp version 可查看构建信息。

MCP 接口

服务器提供 42 个工具,覆盖完整生命周期:项目发现;带标签和关系的 issue CRUD;规划与依赖图;批量计划校验/应用;评论与决策;带可选原子资源预留的 claim/renew/checkpoint/finish 工作尝试;工作上下文组装;审查请求;全文搜索;增量变更;逻辑项目导出/导入;以及带门禁证据和诊断的工作流策略管理。完整的契约,包括 MCP 工具注解矩阵以及 full/agent/read-only/migration 暴露配置矩阵,见 docs/03-mcp-tools.md。

默认情况下,serve 公布完整的 full 目录。传入 --profile agent|read-only|migration(或设置 RHIZOME_TOOL_PROFILE)以收窄目录——例如,对于不应看到任何修改器的客户端,可传入 serve --profile read-only。配置文件是对暴露范围和提示大小的控制,而不是授权边界:无论客户端在 tools/list 中能看到什么,每个工具仍会执行自己的服务端校验。完整的环境变量集合及其优先级,包括已弃用的不带前缀的回退名称,见 docs/04-storage-runtime.md §17.1。

文档

docs/ 下的模块化文件是权威规范;SPEC.md 是索引。智能体只需加载与当前任务相关的章节(AGENT_BRIEF.md 说明了方式)。

  1. 产品目标与范围

  2. 领域模型

  3. MCP 工具

  4. 存储与运行时

  5. 实现要求

  6. 延后功能和非目标

  7. 逻辑交换格式

  8. 本地 HTTP 传输契约

  9. 审查工作流契约

  10. VS Code 扩展

  11. 项目路由契约

  12. 资源预留

  13. 状态看板

面向人类读者的指南(快速入门、工作流、CLI)位于 site/,并通过 GitHub Pages 发布。发布历史见 CHANGELOG。

开发

构建与测试(不需要 CGO,不依赖外部服务):

CGO_ENABLED=0 go build -o rhizome-mcp .
go test ./...
go test -tags=integration ./...

集成测试运行真实进程的 MCP 冒烟测试和工作流测试:它们为每个测试构建临时服务器二进制文件、初始化一个全新的仓库和 SQLite 数据根,然后通过 stdio 或 HTTP 与 serve 通信。除单进程冒烟覆盖外,该测试套件还在一个共享的数据根目录上的 SQLite 测试在跨进程场景中——并发 claim 和 update-version 竞争、进程非正常终止和重启、以及服务器写入期间进行备份——以捕获单进程测试在结构上无法看到的缺陷。这些测试大多位于专用的 integration 包中;需要访问未导出的包 main 内部构造的测试仍留在仓库根目录。

CI 在每次为了 main 的 push 和 pull request 在 Ubuntu、macOS 和 Windows 上运行 go vet、单元测试和集成测试。版本发布(.github/workflows/release.yml)发布符合 CGO 限制的二进制文件,并附 SHA-256 校验和,适用于 linux/amd64、linux/arm64、darwin/amd64、darwin/arm64 和 windows/amd64;发布二进制文件内置了版本号、提交和构建时间戳(本地构建显示 git VCS 信息或 dev,且 VERSION 环境变量覆盖两者)。

版本验证包括:

  • 在二进制上传之前运行完整的 go test ./... 测试套件

  • 构建出的二进制会进行冒烟测试(例如,./rhizome-mcp --version 验证版本字符串与标签一致)

  • npm 启动器测试套件在 npm 发布之前运行(捕获 Node.js 启动器包装器中的回归问题)

  • 在 workflow_dispatch 重新发布时,VS Code 扩展二进制从标记的源码(不是 main)取回,确保版本保持一致

  • 聚合的发布状态作业会在任何发布步骤(npm、MCP Registry、Marketplace、Open VSX)失败时使 workflow 失败,使部分失败可见

本仓库通过 rhizome-mcp 跟踪自己的积压:工作通过 MCP 服务器选择、认领并完成,持久的选择会记录为决策。Markdown 只保存规范,不保存任务状态。参见 AGENTS.md 和 CONTRIBUTING.md。

许可证

Apache-2.0。安全策略:SECURITY.md。

Available Tools

35 tools
add_commentA

Append collaboration context to an issue without rewriting history.

Inputs: content (required), issue_id (required), project_ref, idempotency_key, +1 more. Returns: comment

apply_importA
DestructiveIdempotent

Apply a validated logical project import document into an empty destination.

Inputs: document, source_uri, project_ref, agent_session_handle. Returns: counts, conflicts, latest_event_id

apply_issue_planB
DestructiveIdempotent

Atomically create issues, relations, and decisions from a valid plan.

Inputs: issues (required), decisions (required), relations (required), idempotency_key (required), +2 more. Returns: next_actions, created_issues, latest_event_id, created_decisions, +1 more

archive_issueA
DestructiveIdempotent

Archive one issue using its current version; history remains available.

Inputs: issue_id (required), expected_version (required), view, project_ref, +2 more. Returns: object

cancel_review_requestA
DestructiveIdempotent

Cancel an open or claimed review request using its current version.

Inputs: expected_version (required), review_request_id (required), project_ref, agent_session_handle. Returns: id, status, version, issue_id, +8 more

claim_issueA
Idempotent

Atomically acquire exclusive ready/review work for a 60-3600s renewable lease; already claimed work fails; keyed retries replay.

Inputs: issue_id (required), view, project_ref, lease_seconds, +2 more. Returns: object

create_agent_sessionA

Create a durable attribution session and one unrecoverable handle; writes a new session on every call (non-idempotent).

Inputs: client_name (required), model, agent_label, project_ref, +2 more. Returns: session, agent_session_handle

create_issueA

Create one epic, task, or bug with optional hierarchy and labels.

Inputs: type (required), title (required), view, labels, +10 more. Returns: object

create_review_requestA

Create a review request for an exact issue version, event position, and artifact set. Deprecated: prefer replace_review_request.

Inputs: issue_id (required), target_event_id (required), target_issue_version (required), project_ref, +3 more. Returns: id, status, version, issue_id, +8 more

end_agent_sessionB
Idempotent

End one explicitly created durable agent session handle.

Inputs: agent_session_handle (required), project_ref. Returns: session

export_projectB
Read-onlyIdempotent

Export the selected project as the version 1 logical interchange document.

Inputs: delivery, project_ref, agent_session_handle. Returns: object

finish_attemptB
DestructiveIdempotent

End a leased attempt with outcome, verification, artifacts, and status.

Inputs: outcome (required), attempt_id (required), lease_token (required), result_summary (required), +14 more. Returns: object

get_changesA
Read-onlyIdempotent

Get ordered issue events after an event ID for incremental synchronization.

Inputs: since_event_id (required), limit, issue_id, event_types, +2 more. Returns: events, has_more, next_event_id, latest_event_id

get_issueA
Read-onlyIdempotent

Get the current issue record by ULID or ISSUE-N display ID.

Inputs: issue_id (required), view, project_ref, agent_session_handle. Returns: id, type, title, labels, +13 more

get_issue_activityA
Read-onlyIdempotent

Get a unified newest-first timeline of issue work and artifacts.

Inputs: issue_id (required), limit, order, types, +3 more. Returns: items, has_more, next_cursor

get_issue_graphA
Read-onlyIdempotent

Get a bounded relation and hierarchy graph around one issue.

Inputs: root_issue_id (required), view, depth, direction, +6 more. Returns: edges, nodes, summary, warnings, +6 more

get_planning_graphA
Read-onlyIdempotent

Get dependency-aware entry points and blocking nodes for work selection.

Inputs: depth, max_nodes, project_ref, root_issue_id, +3 more. Returns: edges, nodes, summary, warnings, +6 more

get_projectA
Read-onlyIdempotent

Get metadata, limits, supported values, event position, and guide links for a project_ref or configured default.

Inputs: project_ref, agent_session_handle, include_instructions. Returns: guides, limits, project, session, +11 more

get_review_requestA
Read-onlyIdempotent

Get one review request by identifier.

Inputs: review_request_id (required), project_ref, agent_session_handle. Returns: id, status, version, issue_id, +8 more

get_work_contextB
Read-onlyIdempotent

Get bounded task, blocker, decision, checkpoint, and recovery context.

Inputs: issue_id (required), limits, include, project_ref, +1 more. Returns: issue, reviews, blockers, warnings, +15 more

list_decisionsA
Read-onlyIdempotent

List project-wide or issue-scoped decisions with cursor pagination.

Inputs: limit, cursor, issue_id, project_ref, +1 more. Returns: items, has_more, next_cursor

list_issuesA
Read-onlyIdempotent

List and filter issues, including effective status, blockers, and claimability.

Inputs: view, limit, types, cursor, +10 more. Returns: items, has_more, next_cursor, next_actions

list_labelsA
Read-onlyIdempotent

List reusable labels with optional name search and cursor pagination.

Inputs: limit, query, cursor, project_ref, +1 more. Returns: items, has_more, next_cursor

list_review_requestsA
Read-onlyIdempotent

List review requests with optional status and claimability filters.

Inputs: limit, cursor, status, claimable, +2 more. Returns: items, has_more, next_cursor

manage_issue_relationB
DestructiveIdempotent

Add or remove one blocks, related_to, or duplicates relation.

Inputs: action (required), relation_type (required), source_issue_id (required), target_issue_id (required), +3 more. Returns: changed, relation, affected_issues

open_projectA
Read-onlyIdempotent

Open a project by absolute root and return its project_ref, metadata, limits, supported values, event position, and guide links.

Inputs: project_root (required). Returns: guides, limits, project, session, +11 more

record_decisionA
Destructive

Append a durable project or issue decision, optionally superseding one.

Inputs: title (required), content (required), summary (required), status, +4 more. Returns: decision, superseded_decision_id

renew_attemptA

Extend an active work or review lease before it expires.

Inputs: attempt_id (required), lease_token (required), project_ref, lease_seconds, +1 more. Returns: server_time, next_actions, lease_expires_at

replace_review_requestB
DestructiveIdempotent

Atomically supersede a predecessor review request and create its open successor in one transaction.

Inputs: idempotency_key (required), target_event_id (required), target_issue_version (required), predecessor_request_id (required… Returns: successor, predecessor, latest_event_id

save_attempt_noteB

Append a restartable checkpoint, finding, warning, or progress note.

Inputs: kind (required), content (required), attempt_id (required), lease_token (required), +6 more. Returns: artifacts, attempt_note, next_actions

supersede_review_requestA
DestructiveIdempotent

Supersede an open or claimed review request using its current version. Deprecated: prefer replace_review_request.

Inputs: expected_version (required), review_request_id (required), project_ref, agent_session_handle. Returns: id, status, version, issue_id, +8 more

update_issueA
DestructiveIdempotent

Patch one issue using its current version for optimistic concurrency.

Inputs: changes (required), issue_id (required), expected_version (required), view, +4 more. Returns: object

validate_importA
Read-onlyIdempotent

Validate a logical project import document without writing anything.

Inputs: document, source_uri, project_ref, agent_session_handle. Returns: counts, writes, conflicts

validate_issue_planA
Read-onlyIdempotent

Normalize and validate a bounded multi-issue plan without writing it.

Inputs: issues (required), decisions (required), relations (required), project_ref, +2 more. Returns: valid, errors, summary, warnings, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 35 tools

    Disambiguation2/5

    Several tools have overlapping purposes: create_review_request, replace_review_request, and supersede_review_request all handle review request creation/supersedure, with two marked deprecated. Also, get_planning_graph and get_work_context both provide context-heavy views, and the abundance of similar verbs (create/list/get/manage) creates boundary confusion despite useful descriptions.

    Naming Consistency4/5

    Tool names overwhelmingly use a consistent snake_case verb_noun pattern (e.g., list_issues, renew_attempt, archive_issue). The only notable deviation is the single-word 'search' and a few unconventional verb choices like 'open_project' and 'manage_issue_relation', which are minor and do not obscure the overall pattern.

    Tool Count2/5

    With 35 tools, the server is well above the 'too many (25+)' threshold. The count is inflated by deprecated tools (create_review_request, supersede_review_request) that could be removed, and the sheer number makes the tool surface unnecessarily heavy for agents to navigate.

    Completeness4/5

    The server covers a comprehensive domain: issue lifecycle, review requests, attempts/leases, decisions, relations, sessions, import/export, and planning graphs. Minor gaps like lacking a direct 'list_relations' tool are mitigated by get_issue_graph, but the presence of deprecated tools and some redundancies suggest the surface is not fully polished.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      A lightweight, fully local MCP server that provides AI coding tools with a shared SQLite memory store and built-in conflict arbitration, enabling structured memory sharing across tools like ZCode, Codex, Cursor, and Claude Code without external dependencies.
      4
      10
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Local MCP server giving AI coding agents (Claude Code, Cursor, VS Code/JetBrains Copilot) a shared, persistent memory of your projects and every bug/issue faced during development. Stateless, plain-file storage (AGENTS.md + issues.jsonl) — no database.
      16
      78 npm
      1
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A fully local, privacy-first MCP server that gives AI coding assistants deep repository intelligence with file-and-line-cited answers, persistent semantic memory, and agentic abilities like task planning and code review—all without any cloud API calls.
      23
      -