Rootr

Rootr CLI + MCP 服务

将团队不断积累的知识库连接到 Claude、ChatGPT 和任意 AI Agent。

Rootr 是一个团队知识与文档工作区。此软件包是让 AI Agent 直接访问团队共享文档、结构化数据和机构知识，并遵循权限控制 的官方方式，这样助手就能直接了解团队掌握的信息，无需你在每次对话中复制粘贴上下文。

有两种连接方式。

1. 远程连接器——无需安装（推荐）

Rootr 通过 Streamable HTTP 托管远程 MCP 端点。在 Claude Desktop、claude.ai 或 ChatGPT 中，只需添加连接器并使用 OAuth 登录：

https://rootr.io/mcp

无需 JSON、CLI，也无需粘贴令牌。登录并选择工作区后，助手即可根据你现有的权限访问团队文档。请参阅 文档。

2. 本地 CLI / stdio MCP 服务（rootr-cli）

适用于 Shell，或使用本地 stdio MCP 服务进行通信的 Agent（例如 Claude Code）：

npm install -g rootr-cli
rootr config --api-key rootr_xxxx --workspace ws_xxx
rootr mcp          # start the stdio MCP server

rootr 命令也可独立使用：ls、read、write、append、edit、 search、ask、ws、config。

纯 Node.js ESM，无需构建。需要 Node 18+（使用内置的 fetch）。

• 主页： https://rootr.io
• 文档： https://rootr.io/en/docs
• npm： https://www.npmjs.com/package/rootr-cli

---

安装

直接从克隆的仓库运行，或全局安装。

npm install -g rootr-cli
rootr --help

# or from source
cd cli && npm install
node bin/rootr.js --help

配置

优先级：环境变量 > ~/.rootr/config.json

环境变量	配置键	说明
ROOTR_API_KEY	apiKey	rootr_... API 密钥。每次请求都会通过 x-api-key 标头发送。
ROOTR_WORKSPACE	workspace	工作区 ID
ROOTR_BASE_URL	baseUrl	默认为 https://rootr.io/api/v1

保存到配置文件（创建时会执行 chmod 600）：

rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123
# optional on-prem / dev base URL
rootr config --api-key rootr_xxx --workspace ws_123 --base-url https://dev.rootr.io/api/v1

rootr config          # show current config (api key shown masked)

两种密钥

Rootr API 密钥分为两种，部分工具要求使用特定类型：

• 工作区密钥——仅限单个工作区 （docs:read / docs:write / graph:read / ask / webhooks:manage）。足以用于大多数 文档、LOG、问题、Webhook 和提问工具。
• 账户密钥（PAT）——可在整个账户范围内使用。启用 workspaces:create 权限后，可创建新的工作区（rootr_create_workspace）。使用工作区密钥执行 账户级操作会返回 403，并提示需要账户密钥。

CLI 用法

路径规则：以 / 开头的参数视为路径（通过按路径查询的 API 解析为节点 ID；需要设置工作区）。 否则视为节点 ID。

rootr ls                                   # whole tree  (TYPE<TAB>path)
rootr ls /notes                            # subtree

rootr read /notes/todo.md                  # markdown to stdout
rootr read /notes/todo.md --json           # full JSON incl. metadata

echo "# Title" | rootr write /notes/new.md # full replace (creates if missing)
rootr write /notes/new.md --file ./local.md

rootr append /notes/log.md "Deployed today"          # safe, conflict-free
rootr append /notes/log.md "- one more" --heading "## Todo"

rootr edit /notes/todo.md --find "- [ ] ship" --replace "- [x] ship"

rootr search "deploy runbook"              # path — snippet
rootr ws                                   # list workspaces (id<TAB>name)
rootr ask "why did latency go up after last week's deploy?"

append 不会重写整个文档，因此可以安全地并发运行。write 支持 --if-match "\"etag\""，用于乐观并发控制（412 表示文档已在你操作期间发生更改——重新读取并重试）。如果 --find 缺失或 不唯一，edit 会返回 409；传入 --all 可替换所有匹配项。ask 会查询工作区知识图谱 （GraphRAG），并打印答案及引用（文档路径：引文）。

用作 MCP 服务

rootr mcp 会通过 stdio 启动 Model Context Protocol 服务。它提供覆盖整个 Rootr 功能的 80+ 个工具， 让 Agent 能够创建和查询每种节点类型：

分组	工具（示例）
文档	rootr_list、rootr_read、rootr_append （推荐，无冲突）、rootr_edit、rootr_write、rootr_search、rootr_document_versions、rootr_delete_node、rootr_duplicate_node
发布与评论	rootr_publish_document、rootr_set_document_public、rootr_document_public_status、rootr_comment_document、rootr_list_document_comments
工作区与脚手架	rootr_workspaces、rootr_scaffold_plan、rootr_create_workspace、rootr_scaffold_apply
数据库（类型化列 + 看板 / 表格视图）	rootr_read_database、rootr_add_row、rootr_update_row、rootr_delete_row、rootr_list_rows
电子表格（公式）	rootr_create_spreadsheet、rootr_read_spreadsheet、rootr_update_spreadsheet、rootr_create_sheet、rootr_update_sheet、rootr_delete_sheet、rootr_patch_spreadsheet_cells
白板	rootr_create_whiteboard、rootr_read_whiteboard、rootr_update_whiteboard
表单	rootr_create_form、rootr_read_form、rootr_update_form、rootr_list_form_responses、rootr_submit_form_response、rootr_create_form_share_link、rootr_list_form_share_links
CRM	rootr_crm_* — 公司、联系人、交易（看板）、活动、任务、CSV 导入
演示文稿	rootr_create_presentation、rootr_read_presentation、rootr_update_presentation、rootr_update_presentation_slide、rootr_append_presentation_slides、rootr_reorder_presentation_slides
LOG 数据存储	rootr_create_log_store、rootr_update_log_fields、rootr_add_log_entries、rootr_query_log_entries、rootr_log_stats
问题	rootr_create_issue_tracker、rootr_list_issues、rootr_create_issue、rootr_get_issue、rootr_update_issue、rootr_comment_issue
Webhook	rootr_list_webhooks、rootr_create_webhook、rootr_delete_webhook
GraphRAG 问答	rootr_ask — 使用自然语言对知识图谱进行根因问答，并提供引用
图片	rootr_generate_image、rootr_remove_image_background

工具说明会引导 Agent 优先使用 rootr_append / rootr_edit，而不是具有破坏性的 rootr_write。如果未提供 workspace 参数，接受该参数的工具会回退到 ROOTR_WORKSPACE（或配置默认值）。所有工具的架构均为英文；返回 JSON 的工具会以美化格式的 JSON 文本作答。

在 Claude Code / Claude Desktop 中注册

将以下内容添加到 ~/.claude.json（Claude Code）或 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "rootr": {
      "command": "rootr",
      "args": ["mcp"],
      "env": {
        "ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",
        "ROOTR_WORKSPACE": "ws_123"
      }
    }
  }
}

（如果未进行全局安装，请使用 "command": "node" 和 "args": ["/path/to/rootr-cli/bin/rootr.js", "mcp"]。）

错误处理

收到非 2xx 响应时，CLI 会将 API 的 message（如果存在）打印到 stderr，并以状态码 1 退出：

• 401 / 403 — 检查 API 密钥 / 工作区范围
• 412 — 文档在读取后发生了变化（If-Match 不匹配）：重新读取并重试
• 409 — 服务器返回的原因会原样显示（例如，edit 未找到匹配项 / 匹配项不唯一）

目录结构

• bin/rootr.js — 入口点、命令分发
• lib/config.js — 配置加载 / 保存
• lib/client.js — Rootr REST API 客户端
• lib/resolve.js — 共享路径 / ID 目标解析
• lib/mcp.js — MCP stdio 服务，组装所有工具分组
• lib/mcp-tools/* — 每个工具分组对应一个模块（documents、workspaces、databases、 spreadsheets、whiteboards、forms、crm、presentations、logs、issues、webhooks、ask、misc）

依赖项：@modelcontextprotocol/sdk（MCP 服务）和 zod（工具输入架构）。CLI 核心没有外部依赖项。无需构建步骤 — 纯 ESM JavaScript。

---

由 Inspirio 制作 · rootr.io · [email protected]