mindmap.io

mindmapio-mcp

提示： 将此 README 提供给你的 Agent，并让它安装 MCP。

为你的 AI Agent 提供一个构建和保存所学内容的空间。将它连接到 mindmap.io，就能把研究、计划和对话变成一张真正的思维导图，你可以打开、扩展和分享。你的 Agent 可以读取现有思维导图、添加和编辑节点、对节点运行提示词，还可以围绕任意主题发散出后续问题，所有操作都通过你自己的 mindmap.io 账户完成。

有三种设置方式：

1. Claude 插件。 使用一条安装命令，并通过一个经过掩码处理的提示输入令牌。
2. MCP 服务。 在 MCP 客户端配置中添加一行（Claude Desktop、Cursor 和其他 MCP 客户端均适用）。
3. Agent 技能。 使用 npx skills 安装，让你的 Agent 直接使用 mindmap.io，无需 MCP 客户端。

获取令牌

每次调用都使用你账户中的个人访问令牌。

1. 打开 mindmap.io，进入设置，再打开 API 访问。
2. 生成令牌并复制。令牌只会显示一次。
3. 将其保存为 MINDMAP_API_TOKEN，或粘贴到插件的令牌提示中。

该令牌会以你的身份操作。你可以随时重新生成令牌，旧令牌会立即失效。

选项 1：Claude 插件

/plugin marketplace add MohGanji/mindmapio-mcp
/plugin install mindmapio@mindmap-io

Claude Code 会提示你输入 API 令牌，对其进行掩码处理，并将其存储在操作系统的钥匙串中。重启后，工具即可使用。SETUP.md 会引导 Claude 完成相同的步骤，并说明无法连接时该检查什么。

该插件包含 MCP 服务、介绍如何构建优质思维导图的技能，以及下文介绍的直接 HTTP 技能。没有斜杠命令，也没有子 Agent。

选项 2：MCP 服务

将以下内容添加到 MCP 客户端配置中。npx 会为你获取并运行此软件包：

{
  "mcpServers": {
    "mindmapio": {
      "command": "npx",
      "args": ["-y", "github:MohGanji/mindmapio-mcp"],
      "env": {
        "MINDMAP_API_TOKEN": "<your personal access token>"
      }
    }
  }
}

使用 Claude Code CLI 时，也可以用一行命令完成相同操作：

claude mcp add mindmapio --env MINDMAP_API_TOKEN=<your token> -- npx -y github:MohGanji/mindmapio-mcp

首次运行会从源代码构建，因此需要多花几秒钟。之后的运行会使用缓存。

设置

环境变量	必需	默认值	功能
MINDMAP_API_TOKEN	是	—	你的个人访问令牌。以 Authorization: Bearer <token> 的形式发送。不会记录日志。
MINDMAP_API_BASE_URL	否	https://mindmap.io	API 基础 URL。

Agent 可以做什么

共 19 个工具，对应 Mindmap.io 节点 API 中的各项操作。

工具	功能
list_maps	列出你的思维导图，按创建时间从新到旧排序。
get_map	读取整个思维导图及其节点树。
get_node	读取单个节点。
get_subtree	读取一个节点及其子节点，深度由你决定。
create_map	新建思维导图。
delete_map	删除思维导图及其中的全部内容。
publish_map	发布思维导图，并获取可分享链接和嵌入链接。
unpublish_map	将已发布的思维导图重新设为私有。
set_map_layout	将思维导图排列为树状、从上到下，或在两侧展开分支。
send_feedback	将用户的错误报告或想法反馈给 mindmap.io 团队。
create_node	在父节点下添加节点。
update_node	编辑节点的内容、备注、类型或模型。
delete_node	移除节点及其子节点。
submit_node	使用模型处理节点并获取回答。
auto_expand	将节点扩展为供 Agent 处理的后续问题。
retry_node	重新运行处理失败的节点。
interrupt_node	停止仍在运行的节点。
upload_attachment	将此机器上的图像或 PDF 上传并附加到节点。
read_attachment	将已上传的文件保存回此机器。

如果不提供节点 ID，create_node 会为你生成一个，让 Agent 可以一次性构建完整分支。

每个工具的说明及其 title / readOnlyHint / destructiveHint 注释均根据 OpenAPI 文档生成，而非在此处编写，因此 Agent 读取的内容就是 API 强制执行的契约。请参阅重新生成工具列表。

选项 3：Agent 技能

用一条命令安装这些技能：

npx skills add MohGanji/mindmapio-mcp

这适用于 Claude Code 和其他支持技能的 Agent（可在 skills.sh 浏览）。此处提供两项技能：

• skills/mindmapio/SKILL.md 介绍如何通过纯 HTTP 执行相同操作，无需 MCP 客户端。
• skills/map-shaping/SKILL.md 介绍如何构建地图：根节点应包含哪些内容、何时分支而不是追加，以及何时展开。

请先设置令牌：

export MINDMAP_API_TOKEN="<your personal access token>"

Hello world

创建地图、添加问题、运行地图并读取答案。节点内容会以 messages 的形式发送，这是一个 UIMessage 数组（{ role, parts: [{ type: "text", text }] }）。使用 MCP 服务时，请按顺序调用这些工具：

// 1. Create a map with a root node.
create_map   { "title": "Hello", "data": { "rootId": "root", "nodes": { "root": {
               "id": "root",
               "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Hello" }] }],
               "children": [] } } } }
//   -> { "id": "MAP_ID" }

// 2. Add a question under the root.
create_node  { "mapId": "MAP_ID", "nodeId": "q1", "parentId": "root", "nodeType": "prompt",
               "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Say hi in one word." }] }] }

// 3. Run it. The call waits until the answer is ready.
submit_node  { "mapId": "MAP_ID", "nodeId": "q1" }
//   -> { "nodeId": "q1", "status": "complete", "messages": [ ... ] }

// 4. Read it back.
get_node     { "mapId": "MAP_ID", "nodeId": "q1" }

API 仍接受用于节点内容的旧版 text 字段，但 messages 是规范格式。

skills/mindmapio/SKILL.md 中的技能展示了如何使用 curl 命令执行相同流程。

妥善保管令牌

• 切勿提交令牌。请将其保存在插件的令牌提示词、MCP 客户端配置或环境变量中。
• 令牌仅通过 Authorization 标头发送，绝不会被记录。配置和错误消息中不包含机密信息。
• 请像对待密码一样保管令牌。如果令牌泄露，请在设置中重新生成，旧令牌会立即失效。

目录结构

.claude-plugin/   plugin.json and the self-hosted marketplace manifest
.mcp.json         the plugin's connector: the stdio server below, token from userConfig
skills/           the agent skills, also what `npx skills add` installs
server/           the stdio MCP server (src, tests, and the vendored OpenAPI document)
SETUP.md          first-install instructions for Claude

根目录中的 package.json 属于服务，因此 npx -y github:MohGanji/mindmapio-mcp 仍然可以正常解析：它会构建 server/dist 并运行。

开发

npm install
npm test        # vitest against a mocked HTTP layer, no live backend needed
npm run build   # tsc -> server/dist/

重新生成工具列表

工具描述和注释来自 server/spec/openapi.json，这是已发布的 https://mindmap.io/api/openapi.json 的随仓镜像。使用以下命令刷新：

npm run sync:openapi

一行命令即可检查是否存在差异：

npm run sync:openapi && git diff --exit-code server/spec

它会有意获取已发布的文档，而不是 API 仓库的本地副本；本地副本可能包含尚未推送的编辑，最终会发布出无人能够访问的工具列表。如果文档中的操作缺少 x-mcp 注释（title、readOnlyHint、destructiveHint），它会拒绝写入该文档，因为缺少这些注释的工具不符合 Anthropic 目录的收录标准；遇到这种情况时，随仓副本会保持不变。

技能也以同一文档为准

buildTools 会将工具列表与该文档双向比对，server/test/skill-parity.test.ts 也会以相同方式将 skills/mindmapio/SKILL.md 与该文档比对：每个文档中描述的操作都必须被命名、在完整示例中调用，并讲解文档为该操作声明的查询或标头输入及操作特定错误（409、413、429）；此外，如果技能中的某个章节讲解了文档未描述的端点，也会导致测试失败。这是 ADR 0029 一致性不变量的第三个支柱；在技能悄然偏离到仅涵盖 17 项操作中的 15 项之前，这项要求一直未得到强制执行。

修改该技能只是变更工作的一半：mindmap.io 会提供它的镜像及 SHA-256 摘要，因此将编辑推送到此处后，还必须在那里重新运行 marketing/scripts/sync-agent-skills.mjs。

许可证

MIT