mindmap.io

mindmapio-mcp

ヒント： この README をエージェントに渡して、MCP のインストールを依頼してください。

AI エージェントが学んだことを構築し、保存できる場所を用意しましょう。mindmap.io に接続すると、調査、計画、会話が、開いて、成長させ、共有できる実際のマップになります。エージェントは既存のマップを読み取り、ノードを追加・編集し、マップに対してプロンプトを実行し、あらゆるトピックから関連する質問を展開できます。すべて、ご自身の mindmap.io アカウントを通じて行われます。

セットアップ方法は 3 つあります。

1. Claude プラグイン。 インストールコマンドを 1 つ実行し、トークン用のマスクされたプロンプトに入力します。
2. MCP サーバー。 MCP クライアント設定に 1 行追加します（Claude Desktop、Cursor、その他の MCP クライアント）。
3. エージェントスキル。 npx skills でインストールすると、MCP クライアントなしでエージェントが mindmap.io を直接利用できます。

トークンを取得する

すべての呼び出しで、アカウントの個人用アクセストークンを使用します。

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 トークンの入力を求め、マスクして OS のキーチェーンに保存します。再起動すると、ツールを使えるようになります。SETUP.md では、同じ手順と、接続できない場合に確認すべきことを Claude に案内します。

このプラグインには、MCP サーバー、マップを適切に構成する方法を説明するスキル、および以下のダイレクト HTTP スキルが含まれています。スラッシュコマンドやサブエージェントはありません。

オプション 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 では、同じ設定を 1 行で行えます。

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 です。

エージェントができること

Mindmap.io ノード API の操作ごとに 1 つずつ、19 個のツールがあります。

ツール	説明
list_maps	マップを新しい順に一覧表示します。
get_map	マップ全体とノードツリーを読み取ります。
get_node	1 つのノードを読み取ります。
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	ノードから、エージェントが実行する関連質問を生成します。
retry_node	失敗したノードを再実行します。
interrupt_node	実行中のノードを停止します。
upload_attachment	このマシンから画像または PDF をアップロードし、ノードに添付します。
read_attachment	アップロードしたファイルをこのマシンに保存します。

create_node では、ノード ID を省略すると自動的に生成されるため、エージェントは 1 回の操作でブランチ全体を構成できます。

各ツールの説明と title／readOnlyHint／destructiveHint アノテーションは、ここに記述されているのではなく OpenAPI ドキュメントから生成されます。そのため、エージェントが読み取る内容は API が適用する仕様そのものです。ツール一覧の再生成を参照してください。

オプション 3：エージェントスキル

次のコマンドでスキルをインストールします。

npx skills add MohGanji/mindmapio-mcp

これは Claude Code や、スキルに対応したほかのエージェントで動作します（skills.shでスキルをご覧いただけます）。ここには 2 つのスキルが含まれています。

• skills/mindmapio/SKILL.mdでは、MCP クライアントを使わずに、プレーンな HTTP で同じ操作を行う方法を説明します。
• 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/

ツール一覧の再生成

ツールの説明と注釈は、公開されている https://mindmap.io/api/openapi.json の同梱ミラーである server/spec/openapi.json を基にしています。次のコマンドで更新します。

npm run sync:openapi

差分は 1 行のコマンドで確認できます。

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 のパリティ不変条件を支える 3 つ目の要素です。スキルの対応状況がいつの間にか 17 操作中 15 操作にずれるまで、この条件は適用されていませんでした。

このスキルの編集は変更の半分にすぎません。mindmap.io は SHA-256 ダイジェスト付きのミラーを配信しているため、こちらに編集をプッシュした後、marketing/scripts/sync-agent-skills.mjs をそこで再実行する必要があります。

ライセンス

MIT