Mind Elixir

Mind Elixir MCP 服务

让 AI 助手在 Mind Elixir Desktop 中构建和编辑真实的思维导图。

这是一个 stdio ↔ HTTP 桥接器，可将仅支持 stdio 的 MCP 客户端——Claude Desktop、Claude Code、Cursor、VS Code、Cline、Roo Code、Windsurf——连接到 Mind Elixir Desktop 应用内置的 MCP 服务。

需要安装并运行 Mind Elixir Desktop。 此服务是桌面应用的本地控制器，并非独立的云服务。桥接器会将工具调用转发至 http://127.0.0.1:6595/mcp，并将结果流式传回。

• 注册表名称：io.github.mind-elixir/mcp
• npm 包：@mind-elixir/mcp
• 设置指南：https://app.mind-elixir.com/blog/use-mcp

---

目录

• 可以用它做什么
• 要求
• 快速开始
• 客户端配置
• 不使用桥接器连接（HTTP）
• 工具参考
• 推荐的 Agent 工作流
• CLI 参考
• 工作原理
• 故障排除
• 安全与隐私
• 开发
• 许可证

---

可以用它做什么

七种工具可让助手读取和修改应用中当前打开的思维导图：

• 新建思维导图，或用模型设计的结构替换当前思维导图。
• 查看当前思维导图中的所有主题、节点 ID 以及父子关系。
• 重命名节点、添加子节点，并获取刚创建节点的 ID。
• 添加摘要节点，将一组相邻节点折叠为一个想法。
• 在任意两个节点之间绘制带标签的箭头，表达树状结构无法表示的关系。

典型用途：将对话或文档整理成结构化思维导图、将项目拆解为工作分解结构、把会议内容归纳为主题，或让助手重新整理你已经手动记录的笔记。

---

要求

要求	详情
Mind Elixir Desktop	已安装并且正在运行。应用会在 127.0.0.1:6595 上托管实际的 MCP 服务。
Node.js	18 或更高版本——仅在通过 npx、npm i -g 或本地安装运行桥接器时需要。
MCP 客户端	任意支持通过 stdio 使用 MCP 的客户端，或能直接连接到 Streamable HTTP 端点的客户端。
端口	环回地址上的 6595 必须空闲。如果端口被占用，请通过 --port 更改。

---

快速开始

先启动 Mind Elixir Desktop，然后验证桥接器能否连接：

npx -y @mind-elixir/mcp@latest

运行中的桥接器不会向 stdout 输出任何内容（该通道专用于 JSON-RPC），并会在前台持续运行。诊断信息会输出到 stderr。按 Ctrl+C 退出。

如需改为全局安装 CLI：

npm install -g @mind-elixir/mcp
mind-elixir-mcp

然后配置 MCP 客户端——请参阅下一节。

---

客户端配置

Claude Desktop

编辑 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

保存后重启 Claude Desktop。

Claude Code

claude mcp add mind-elixir -- npx -y @mind-elixir/mcp@latest

Cursor

创建或编辑 ~/.cursor/mcp.json（或使用设置 → 功能 → MCP → + 添加新的 MCP 服务）：

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

VS Code（GitHub Copilot Agent 模式）

添加到工作区中的 .vscode/mcp.json，或用户级别的 mcp.json：

{
  "servers": {
    "mind-elixir": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

Cline、Roo Code、Windsurf

这些扩展使用与 Cursor 相同的 mcpServers 结构：

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

非默认端口

如果 Mind Elixir Desktop 监听的端口不是 6595，请传入对应端口：

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest", "--port", "7000"]
    }
  }
}

---

不使用桥接程序进行连接（HTTP）

如果你的客户端可以直接使用 Streamable HTTP 通信，则完全跳过此软件包，直接连接到应用：

{
  "mcpServers": {
    "mind-elixir": {
      "type": "http",
      "url": "http://127.0.0.1:6595/mcp"
    }
  }
}

应用提供以下端点：

端点	方法	用途
/mcp	POST / GET	MCP Streamable HTTP 端点（推荐使用此端点）。
/ping	GET	存活探测；返回 pong。

已为 Mind Elixir Cloud 源启用 CORS，因此托管在浏览器中的客户端也可以调用本地服务。

---

工具参考

所有工具均返回纯文本结果。成功执行变更的工具会返回 OK（对于 add_child，则返回新节点的 ID）；失败时会返回以 Error: 开头的字符串。

工具	用途	返回值
new_mindmap	创建空白思维导图，并将应用切换到编辑器	OK
get_all_nodes	读取当前思维导图的全部内容	节点树 JSON
generate_mindmap	根据结构化数据替换当前思维导图	OK
edit_topic	重命名节点	OK
add_child	添加子节点	Done. New Node's ID is <id>.
add_node_summary	汇总一系列同级节点	OK
add_arrow	用带标签的箭头连接两个节点	OK

每个工具的操作时限均为 15 秒。如果应用未能及时返回结果，工具会返回 Timeout waiting for mindmap operation to complete。

new_mindmap

创建一个新的空白思维导图，并将应用导航到其编辑器页面。

无参数。

get_all_nodes

以嵌套节点树的形式返回当前思维导图，包括每个主题、其 ID 及其子节点。

无参数。 响应结构如下：

{
  "topic": "Root Topic",
  "id": "1",
  "children": [
    { "topic": "Child Topic", "id": "b3f1c0e2-…", "children": [] }
  ]
}

编辑或添加到本次会话中并非由你创建的思维导图之前，请务必先调用此工具——只有通过 ID 才能定位节点。

generate_mindmap

根据你提供的结构替换整个当前思维导图。

参数	类型	说明
mindmap_data	string	包含 nodeData 根对象的 JSON 字符串。

{
  "nodeData": {
    "topic": "Root Topic",
    "id": "1",
    "children": [
      { "topic": "Child Topic 1", "id": "1-1", "children": [] },
      { "topic": "Child Topic 2", "id": "1-2" }
    ]
  }
}

要求：

• 每个节点都需要包含 topic（字符串）和 id（字符串）。
• children 为可选项。
• 使用分层编号（1、1-1、1-2、2、2-1、……），以便后续工具能准确定位节点。

edit_topic

原地更改节点文本，同时保留其位置、子节点、摘要和箭头。

参数	类型	说明
node_id	string	要重命名的节点 ID，例如 1、1-1 或 UUID。
topic	string	新的主题文本。

如果 node_id 不存在，则返回 Error: Node not found；请调用 get_all_nodes 刷新视图。

add_child

在现有父节点下添加子节点。应用会生成 ID，因此结果中会包含该 ID。

参数	类型	说明
parent_id	string	父节点的 ID。
topic	string	新子节点的主题文本。

返回 Done. New Node's ID is <id>.——如果计划稍后编辑此节点，请保留该 ID。找不到父节点时，返回 Error: Parent node not found。

add_node_summary

添加一个摘要节点，用于汇总父节点子节点中连续的一段范围。

参数	类型	说明
text	string	摘要文本。
parent	string	要汇总其子节点的父节点 ID。
start	integer	要包含的第一个子节点的从零开始的索引。
end	integer	要包含的最后一个子节点的从零开始的索引（包含该节点）。

示例——汇总节点 1 的前三个子节点：

{ "text": "These three all concern onboarding", "parent": "1", "start": 0, "end": 2 }

add_arrow

在两个节点之间绘制带标签的连接，用于表示树形结构无法表达的关系。

参数	类型	描述
label	string	显示在箭头上或附近的文本，例如 leads to、depends on。
from	string	源节点的 ID。
to	string	目标节点的 ID。
bidirectional	boolean	true 表示 ↔，false 表示 →。

---

推荐的 Agent 工作流

1. 先了解情况。 调用 get_all_nodes，在进行任何操作前了解实际 ID 和结构。切勿假设 ID。
2. 决定是新建还是修改。 对于全新的导图，使用分层 ID 调用 generate_mindmap。对于现有导图的增量修改，使用 add_child 和 edit_topic。
3. 记录生成的 ID。 add_child 会返回一个 UUID——如果之后还要编辑该节点，请记录下来。
4. 不要假定应用当前位于编辑器页面。 任何工具调用都会将应用切换到前台并打开编辑器；如果应用尚未在编辑导图，就会先创建一个新的空白导图。因此，写入前务必使用 get_all_nodes 确认当前状态。
5. 按顺序调用。 修改会按顺序应用，且 MCP 未提供撤销功能。

---

CLI 参考

USAGE:
  npx -y @mind-elixir/mcp [options]

OPTIONS:
  -u, --url <url>            Target Mind Elixir MCP URL (default: http://127.0.0.1:6595/mcp)
  -p, --port <port>          Change target port (default: 6595)
  -t, --transport <sse|http> Force transport mode ('sse' or 'http', default: auto)
  -v, --version              Show version
  -h, --help                 Show this help message

ENVIRONMENT VARIABLES:
  MIND_ELIXIR_MCP_URL        Target URL to connect to

此软件包会安装两个功能相同的二进制文件：mind-elixir-mcp 和 mcp。

在 auto 模式下选择传输方式：如果目标 URL 路径以 /mcp 结尾，则使用 Streamable HTTP；否则桥接程序会回退到旧版 SSE 传输方式。可使用 --transport 强制指定一种方式。

---

工作原理

+--------------------------+
| Claude Desktop / Cursor  |
+------------+-------------+
             | stdio (stdin / stdout), JSON-RPC
             v
+------------+-------------+
|    @mind-elixir/mcp      |   bridge process
+------------+-------------+
             | Streamable HTTP -> http://127.0.0.1:6595/mcp
             v
+------------+-------------+
|  Mind Elixir Desktop     |   Tauri app, owns the tools
+--------------------------+

1. 桥接程序会将 stdio JSON-RPC 消息转换为 HTTP 请求，并原样流式返回响应。
2. 启动过程具有容错性。 如果应用仍在启动，消息会先进入缓冲区，并在连接建立后严格按照 FIFO 顺序重放。桥接程序会尝试重新连接三次，每次间隔一秒。
3. 会协商协议版本。 桥接程序会以 2024-11-05 作为初始版本，并采用 initialize 握手最终确定的版本，再将该版本转发给应用。
4. 错误会明确报告。 如果始终无法连接到应用，所有缓冲请求都会收到一条 JSON-RPC 错误（-32000），内容为 Mind Elixir Desktop is not running. Please open Mind Elixir Desktop and try again. (<url>)；stderr 会输出易于理解的说明，进程则以代码 1 退出。操作期间发生的错误会以原始消息的形式返回给调用方，而不会被吞掉。

---

故障排除

症状	原因及解决方法
Mind Elixir Desktop is not running	启动桌面应用，然后在客户端中重新连接 MCP 服务。
工具调用返回 Timeout waiting for mindmap operation to complete	应用在 15 s 内未响应——通常是因为存在模态对话框或窗口繁忙。将应用切换到前台后重试。
在 6595 上连接被拒绝	该端口被其他进程占用，或者应用使用了其他端口。重启应用，或传入 --port <port> / 设置 MIND_ELIXIR_MCP_URL。
客户端未列出任何工具	在终端中运行 npx -y @mind-elixir/mcp@latest，确认桥接程序能启动，然后重启客户端，使其重新读取 MCP 配置。
意外出现空白导图	工具运行时应用不在编辑器页面，因此创建了一个新导图。写入前使用 get_all_nodes 读取导图。
Error: Node not found / Error: Parent node not found	ID 已失效或来自其他导图。使用 get_all_nodes 重新读取。
客户端日志中没有任何内容	所有桥接程序诊断信息都会写入 stderr；stdout 仅承载协议流量。

安全和隐私

• 该应用的 MCP 服务仅绑定到 127.0.0.1——不会暴露到你的网络，也没有身份验证。你机器上的任何本地进程都可以通过它控制该应用，因此请像对待其他本地控制接口一样谨慎对待端口 6595。
• 桥接程序是 MCP 客户端的本地子进程。它不会读取或写入磁盘；唯一的网络流量是向该应用发起的环回 HTTP 调用。
• 所有操作都在你的机器上完成。此软件包或桌面应用的 MCP 端点不会将任何思维导图内容、提示词或遥测数据发送到服务器。
• 请像对待任何可以编辑文档的工具一样谨慎使用该服务：它可以重写你当前打开的导图。处理重要内容时，建议使用设置为运行工具前先询问的客户端。

---

开发

需要 Node.js 18+ 和 pnpm 11+（pnpm-workspace.yaml 中的 allowBuilds 条目依赖此版本）。

pnpm install
pnpm build     # tsup -> dist/index.js
pnpm dev       # tsup --watch

构建会生成一个带有 #!/usr/bin/env node shebang 的 ESM 打包文件；每次执行 npm publish 前，prepublishOnly 都会重新构建。

---

许可证

MIT © Mind Elixir