threadmap-mcp

🗺️ Claude 的 ThreadMap MCP

为 Claude 提供对话偏移可视化与分叉功能。

别再丢失最初的意图。准确查看对话从哪里开始偏移。从任意位置分叉，并以干净的上下文继续。

---

实际效果

每条消息旁的彩色圆点——实时跟踪偏移：

时间线面板在每个转折点都提供分叉按钮：

---

使用 ThreadMap 的两种方式

	MCP 服务	Chrome 扩展程序
适用环境	Claude Code（终端）	claude.ai（浏览器）
安装	claude mcp add threadmap npx threadmap-mcp	从 chrome-extension/ 文件夹加载未打包的扩展程序
可用功能	7 个工具——跟踪、时间线、分叉、分支	每条消息旁的彩色圆点、时间线面板、一键分叉
适合人群	使用 Claude Code 构建项目的开发者	每天使用 claude.ai 的所有人

两者都在此仓库中。可单独使用，也可同时使用。

---

Chrome 扩展程序——在 claude.ai 中显示可视化圆点

Chrome 扩展程序会将 ThreadMap 直接注入 claude.ai 界面。无需配置，安装后打开 Claude 即可。

安装（2 分钟）

1. Clone or download this repo
2. Open Chrome → chrome://extensions
3. Enable Developer mode (top right toggle)
4. Click Load unpacked → select the chrome-extension folder
5. Open any Claude conversation — ThreadMap activates automatically

显示内容

• 彩色圆点显示每条消息相对于最初意图的偏移百分比
• 置顶栏显示实时偏移状态和消息数量
• ↺ 重新扫描——加载较长历史对话中的所有消息
• 时间线——完整的对话地图，点击任意行即可跳转到对应消息
• ⑂ 分叉——打开新的 Claude 聊天，并将完整上下文预先载入输入框

分叉的工作方式

1. 点击时间线中或任意消息气泡旁的 ⑂ 分叉
2. 新的 claude.ai 标签页会自动打开
3. 完整上下文（初始意图 + 截至该位置的所有消息）会粘贴到输入框中
4. 检查内容并点击发送——Claude 会从干净的版本继续

Chrome 扩展程序文件

chrome-extension/
├── manifest.json     — Extension config (Manifest v3)
├── content.js        — Core drift engine + DOM injection
├── threadmap.css     — All injected styles
├── popup.html        — Extension popup with color legend
├── icon16.png        — Icons
├── icon48.png
└── icon128.png

**注意：**此扩展程序使用开发者模式（加载未打包的扩展程序）。Chrome 应用商店版本已列入计划。

---

MCP 服务——集成 Claude Code

MCP 服务为 Claude Code 添加 7 个工具，用于以编程方式跟踪偏移。

安装

claude mcp add threadmap npx threadmap-mcp

或者手动添加到 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "threadmap": {
      "command": "npx",
      "args": ["threadmap-mcp"]
    }
  }
}

快速开始

threadmap_track(sessionId="myproject", role="user", content="build me a login system with JWT auth")
→ 🔵 Blue — Drift: 0% — Origin intent set

threadmap_track(sessionId="myproject", role="user", content="the refresh token keeps expiring after 30 seconds")
→ 🟠 Orange — Drift: 63% — ⚡ INFLECTION POINT detected

threadmap_timeline(sessionId="myproject")
→ Full color-coded map of all messages with fork instructions

threadmap_fork(sessionId="myproject", messageIndex=6, branchName="jwt-debug")
→ 🌿 Branch created — clean context from messages 1–7

全部 7 个工具

工具	功能
threadmap_track	跟踪一条消息，获取偏移评分和颜色
threadmap_timeline	完整的彩色编码对话地图
threadmap_fork	从任意消息索引处分叉
threadmap_branch_context	获取任意分支的干净上下文包
threadmap_status	快速检查当前偏移状态
threadmap_reset	归档对话线程并重新开始
threadmap_legend	显示颜色参考指南

---

颜色系统

颜色	偏移	含义
🔵 蓝色	0–15%	正轨——核心意图
🟢 绿色	16–35%	有益扩展
🟡 黄色	36–55%	相邻偏移
🟠 橙色	56–72%	转折点——明显转向
🔴 红色	73–88%	上下文完全断裂
🟣 紫色	89–95%	元讨论——讨论这段对话
⚪ 白色	96–100%	解决

橙色和红色 = 可分叉候选点。对话已经偏离最初的意图。

---

实际应用场景

Claude Code——保持架构完整性 构建过程中跟踪每条消息。橙色 = 范围蔓延。在偏移加剧前分叉。前 10 条消息中的架构决策能保持清晰。

较长的历史对话 点击 Chrome 扩展程序中的 ↺ 重新扫描。ThreadMap 会滚动到顶部，加载所有消息，扫描每条消息，然后返回底部——所有圆点都会显示。

团队交接 使用 threadmap_branch_context 提取清晰的决策摘要。将其粘贴到新会话中——无需翻阅 200 条消息。

---

为什么选择开源？

非线性对话导航是 AI 原生工作所缺少的基础能力。如今，Claude 对话就像一本本没有目录、章节和书签的书。

ThreadMap 就是目录。如果它成为标准，就能适用于 Claude、GPT、Gemini 和其他任何平台。没有人拥有它，所有人都能受益。

---

路线图

• 本地嵌入模型（MiniLM），以实现更丰富的语义评分
• 在 Chrome 网上应用店发布 Chrome 扩展程序（无需启用开发者模式）
• 跨会话持久化（SQLite 模式）
• 导出可视化时间线（SVG/HTML）
• 兼容 GPT / Gemini

---

贡献

采用 MIT 许可证。请参阅 CONTRIBUTING.md。

git clone https://github.com/Advertflair/threadmap-mcp
cd threadmap-mcp
npm install
npm run build

欢迎提交 PR，尤其是改进漂移评分、优化 Chrome 扩展程序，以及支持其他 AI 平台方面的贡献。

---

许可证

MIT — 请参阅 LICENSE

---

由 Advertflair 构建。开源。立即发布。