Dg Team MCP

⚠️ 概念验证 -这是一个原型实现，用于探索如何通过模型上下文协议（MCP）将话语图与人工智能助手集成。它仅用于原型制作和实验目的。

话语图MCP服务器

通往漫游研究图的人工智能桥梁。通过与Claude的自然对话，询问有关话语图的问题，探索研究节点之间的关系，分析试点用户反馈，读/写页面和块，包括用于漫游侧目标可见性的缓冲附加建议。

我该怎么办？

• “给我看看支持这一说法的所有证据”
• “这个星期球队做了什么？”
• “搜索与CRISPR相关的任何内容”
• “哪些飞行员提到了Canvas？”（实时搜索，立即生效）
• “根据我们的飞行员，我们接下来应该建造什么？”（需要 知识索引 先建）
• 对漫游页面和块的完全读/写访问权限
• 具有Roam本地批准的多批写入提案——虚拟块在目标父级内联呈现(propose_write / propose_write_batch)
• 原始数据日志查询、类型化话语关系、查询构建器执行、K-hop图遍历

无需代码。你和克劳德谈谈；克劳德对着你的图表说话。

______________________________________________________________________

设置

先决条件

• 漫游桌面 在启用本地API的情况下运行
• Node.js 18+

1.连接到您的漫游图（一次性）

npx @roam-research/roam-mcp connect

按照提示进行身份验证。您的令牌已保存到 ~/.roam-tools.json.

2.克隆并安装

git clone 
cd discourse-graph-mcp
npm install

3.添加MCP服务器

克劳德代码：

claude mcp add -s user discourse-graph -- /path/to/discourse-graph-mcp/node_modules/.bin/tsx /path/to/discourse-graph-mcp/src/index.ts

为什么是绝对路径？ 使用 npx tsx 对cwd敏感——当在没有cwd的项目中打开Claude Code时，它会失败 tsx 本地安装。

克劳德桌面版 --添加到您的MCP配置中：

Config file locations

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

Codex CLI：

使用内置版本进行最可靠的设置：

npm run build
codex mcp add discourse-graph -- node /path/to/discourse-graph-mcp/dist/index.js

如果您正在积极开发服务器，也可以直接从源代码运行它：

codex mcp add discourse-graph -- /path/to/discourse-graph-mcp/node_modules/.bin/tsx /path/to/discourse-graph-mcp/src/index.ts

更新现有安装

如果您已经从本地签出配置了MCP服务器：

git pull
npm install
npm run build

然后重新启动使用 discourse-graph MCP服务器。如果 过时的MCP进程仍在占用漫游写可见性网桥端口，停止 MCP子进程，并让新的会话重新启动它：

ss -ltnp 'sport = :3597'
kill 

当前网桥报告所有者/客户端诊断：

curl -s http://127.0.0.1:3597/write-visibility/health

{
  "ok": true,
  "role": "owner",
  "service": "dg-team-mcp-write-visibility",
  "pid": 12345,
  "cwd": "/path/to/project",
  "pendingCount": 0,
  "port": 3597
}

验证是否已添加：

codex mcp list

{
  "mcpServers": {
    "discourse-graph": {
      "command": "npx",
      "args": ["tsx", "/path/to/discourse-graph-mcp/src/index.ts"]
    }
  }
}

4.设置权限（克劳德代码）

服务器在深度搜索和索引等操作期间进行许多API调用。为了避免逐一审批，请提前允许MCP工具。

在您的克劳德代码设置中(~/.claude/settings.json)，添加：

{
  "permissions": {
    "allow": [
      "mcp__discourse-graph__*"
    ]
  }
}

这允许所有话语图工具在没有每次调用批准的情况下运行。为了获得更多控制，只允许读取操作：

{
  "permissions": {
    "allow": [
      "mcp__discourse-graph__search_*",
      "mcp__discourse-graph__get_*",
      "mcp__discourse-graph__query_*",
      "mcp__discourse-graph__deep_*",
      "mcp__discourse-graph__check_*",
      "mcp__discourse-graph__index_*",
      "mcp__discourse-graph__catch_*",
      "mcp__discourse-graph__run_*",
      "mcp__discourse-graph__save_*"
    ]
  }
}

这仍然会提示写入(create_*, update_*, delete_*).

5.验证其是否正常工作

打开一个新的Claude会话并尝试：

"What discourse node types are in my graph?"

注： 此服务器包括所有标准的Roam MCP工具。你做 不 需要 @roam-research/roam-mcp 单独安装——如果有的话，请将其删除，以避免重复使用工具。

______________________________________________________________________

工作流

理解你的图形

探索联系

研究活动

阅读与写作

对于在创建任何内容之前希望在漫游中查看和批准目标的写入，请使用 propose_write_batch （或 propose_write 对于单个分支）。这 写可见性插件 使用批准/拒绝控件在每个父级渲染虚拟块。直接的 create_block 保持可用并立即执行。

试点用户——实时搜索

立即工作，无需设置。实时扫描试点页面。

试点用户——带知识指数

需要先构建索引（请参见 下一节).一旦建立，查询就是即时的。

______________________________________________________________________

飞行员知识指数

知识索引是试点用户页面的结构化摘要，包括反馈、功能请求、痛点、工作流程等。一旦构建完成，对它的查询就是即时的。

它住在哪里

~/.discourse-graph-mcp/pilot-index.json --本地到您的机器。 从未承诺回购，从未分享。 它包含图形的数据。如果你失去了它，重建它。

运作原理

MCP服务器从导频页面中提取原始数据。Claude阅读内容，将其分类为主题，并保存结果。不需要单独的API密钥。

"Index all pilot pages"
        |
   index_pilot_pages --> extracts batch of 5 pilots
        |
   Claude reads and classifies into topics
        |
   save_pilot_index --> writes to disk
        |
   index_pilot_pages (next batch) --> repeats
        |
   ... until all pilots are done ...
        |
   Claude generates cross-pilot rollups
        |
   save_pilot_index --> writes rollups
        |
   Done. Future queries are instant.

构建指数

说：

“索引我的所有试点页面”

Claude处理其余部分——发现所有飞行员，分批处理，将每个飞行员的内容分类为特征请求、疼痛点、工作流程、反馈、挑战等主题。类别不是固定的——克劳德会根据发现的内容进行调整。

在处理完所有飞行员后，Claude会生成跨飞行员汇总：排名功能请求、常见痛点以及下一步要构建什么。

保持新鲜

“检查飞行员指数是否最新”

将索引与实时图表进行比较。如果飞行员自上次索引以来发生了变化：

“重新索引过时的飞行员”

只有更改的页面才会被重新处理。

______________________________________________________________________

写可见性插件

Roam扩展将建议的写入内联到您的图中，这样您就可以在不离开Roam的情况下批准或拒绝它们。

它做什么

当代理人来电时 propose_write_batch，插件会接受该提议，并在目标父级的位置呈现虚拟DOM块。每批显示：

• 带有绿色左边框的虚拟块，预览将要创建的内容
• 批准 和 拒绝 每批按钮
• 一个固定的任务栏（右下角），显示批次计数和总区块计数，批次之间有箭头导航，批量批准/拒绝所有操作

同时向不同父母提出多项建议。该插件会自动将新批次滚动到视图中，并在适当的位置展开折叠的祖先链（从不放大到单个块）。

安装

1. 从repo根目录构建：

   npx tsx apps/roam/scripts/build.ts

1. 在Roam中，打开 开发者工具 （Ctrl+Shift+I或Cmd+Opt+I）
2. 负载 apps/roam/dist/extension.js 作为自定义扩展

插件民意调查 http://127.0.0.1:3597/write-visibility/current 每1.2秒。如果MCP服务器正在运行，则不需要配置。

调试

window.dgMcpWriteLocator.getState()   // current plugin state
window.dgMcpWriteLocator.refresh()    // force an immediate poll

______________________________________________________________________

工具参考

48个工具：23个漫游库+21个话语图+4个缓冲写入可见性。

Graph Management — connect and inspect your Roam graph

Pages — create, read, update, and delete pages

Blocks — create, read, update, delete, and move blocks

Search & Query — find content across the graph

Files — manage file attachments

UI Control — interact with the Roam Desktop window

Discourse Node Types — understand the graph's schema

Discourse Node Discovery — find and inspect nodes

Discourse Graph Exploration — traverse relationships

Discourse Content & Analysis — sections, contributions, activity

Discourse Query Builder — run structured queries

Pilot Analysis — understand pilot user feedback

Indexing Pipeline (internal) — used by Claude during indexing, not called directly

这些是索引工作流程的一部分。当你说“索引所有试点页面”时，克劳德会自动编排这些页面。你不需要直接给他们打电话。

Buffered Write Visibility — multi-batch Roam-native write approval

代理人应在投票表决决议之前提出所有书面建议。求婚后，致电 get_pending_write_batch(batchId) 检查结果。

______________________________________________________________________

建筑

Claude (any MCP client)
    |
    | stdio (JSON-RPC 2.0)
    v
discourse-graph-mcp
    |-- 23 Roam base tools (from @roam-research/roam-tools-core)
    |-- 21 Discourse Graph tools
    |-- 4 Buffered write-visibility tools
    |-- Write-visibility bridge (127.0.0.1:3597)
    |
    | HTTP to localhost
    v
Roam Desktop (Local API)        Roam Plugin (apps/roam/)
    v                               |
Your Roam Graph                     polls bridge, renders virtual blocks,
                                    approve/reject per batch

Local data:
    ~/.discourse-graph-mcp/pilot-index.json (knowledge index, never shared)

• 话语图工具是 只读写入操作使用Roam基础工具。
• Auth重用 ~/.roam-tools.json 从 roam-mcp connect。无需单独设置。
• 知识索引是您机器的本地索引。这是一个缓存——随时重建。
• 写可见性桥和漫游插件允许对拟议的写进行图内批准。

______________________________________________________________________

已知限制

• 漫游桌面必须正在运行。 连接到本地主机上的本地API。
• 对于大页面，抓取树很慢。 每个块的每个树级别一个API调用。知识索引的存在是为了完成这项工作。当页面达到遍历上限时，基于树的工具现在会显示深度元数据。
• 某些数据日志功能无法通过本地API工作。 pull, :keys，和几个 clojure.string 功能不安全或无声地失败。服务器通过元组查询、基于正则表达式的匹配和JS侧过滤来解决这个问题。
• 查询生成器不是完全浏览器奇偶校验。 日期条件和上下文相关目标({current}, {this page}, {current user})仍然不受支持。
• 某些查询构建器的选择是故意不完整的。 不支持的选择会在工具输出中报告，而不是自动删除。

______________________________________________________________________

发展

npm install

# Type check
npx tsc --noEmit --skipLibCheck

# Verify tools register
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' | timeout 5 npx tsx src/index.ts 2>/dev/null

许可证

麻省理工学院