Mind Elixir

Mind Elixir MCP サーバー

AI アシスタントが Mind Elixir Desktop で実際のマインドマップを作成・編集できるようにします。

これは、stdio のみを扱う MCP クライアント（Claude Desktop、Claude Code、Cursor、VS Code、Cline、Roo Code、Windsurf）を、Mind Elixir Desktop アプリに組み込まれた MCP サーバーに接続する stdio ↔ HTTP ブリッジです。

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）
• ツールのリファレンス
• おすすめのエージェントワークフロー
• CLI リファレンス
• 仕組み
• トラブルシューティング
• セキュリティとプライバシー
• 開発
• ライセンス

---

できること

7 つのツールを使って、アプリで現在開いているマインドマップをアシスタントが読み取り、変更できます。

• 新しいマップを作成するか、モデルが設計した構造で現在のマップを置き換えます。
• 現在のマップにあるすべてのトピック、ノード ID、親子関係を調べます。
• ノードの名前を変更したり、子ノードを追加したりして、作成したノードの ID を取得します。
• 範囲内の兄弟ノードを 1 つのアイデアにまとめる 要約ノードを追加します。
• ツリーでは表現できない関係を示すため、任意の 2 つのノード間に ラベル付き矢印を描画します。

一般的な用途：会話や文書を構造化されたマップに変換する、プロジェクトを作業分解構成図に分解する、会議をテーマごとに要約する、または手作業で作成したメモをアシスタントに整理し直してもらう、といった使い方ができます。

---

要件

要件	詳細
Mind Elixir Desktop	インストール済みで、起動していること。アプリは実際の MCP サーバーを 127.0.0.1:6595 でホストします。
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 を作成または編集します（または Settings → Features → MCP → + Add New MCP Server を使用します）。

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

VS Code（GitHub Copilot エージェントモード）

ワークスペースの .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	ラベル付きの矢印で2つのノードをつなぐ	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（string）と id（string）が必要です。
• 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 はアプリが生成し、結果に含まれます。

パラメーター	型	説明
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	含める最初の子ノードの0始まりインデックス。
end	integer	含める最後の子ノードの0始まりインデックス（このインデックスを含む）。

例 — ノード 1 の最初の3つの子ノードを要約します：

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

add_arrow

ツリーでは表現できない関係について、2つのノードをラベル付きの矢印で接続します。

パラメーター	型	説明
label	string	矢印上または矢印の近くに表示されるテキストです。例：leads to、depends on。
from	string	接続元ノードの ID です。
to	string	接続先ノードの ID です。
bidirectional	boolean	true の場合は ↔、false の場合は → です。

---

推奨されるエージェントのワークフロー

1. まず状況を把握します。 何かを変更する前に get_all_nodes を呼び出し、実際の ID と構造を確認します。ID を決めつけてはいけません。
2. 新規作成か修正かを判断します。 新しいマップを作成する場合は、階層 ID を使って generate_mindmap を使用します。既存のマップを段階的に編集する場合は、add_child と edit_topic を使用します。
3. 生成された ID を記録します。 add_child は UUID を返します。ノードを後で再編集する場合は、その 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 の2つがインストールされます。

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 順序で再生されます。ブリッジは1秒間隔で3回接続を再試行します。
3. プロトコルのバージョンをネゴシエーションします。 ブリッジは 2024-11-05 で開始し、initialize ハンドシェイクで確定したバージョンを採用してアプリに転送します。
4. 失敗は明示されます。 アプリに接続できない場合、バッファーに保存されたすべてのリクエストに、Mind Elixir Desktop is not running. Please open Mind Elixir Desktop and try again. (<url>) という内容の JSON-RPC エラー（-32000）が返されます。stderr には人が読める説明が出力され、プロセスは終了コード 1 で終了します。操作中に発生したエラーは握りつぶされず、元のメッセージのまま呼び出し元に返されます。

---

トラブルシューティング

症状	原因と対処法
Mind Elixir Desktop is not running	デスクトップアプリを起動してから、クライアントで MCP サーバーに再接続してください。
ツール呼び出しで Timeout waiting for mindmap operation to complete が返される	アプリが15秒以内に応答しませんでした。通常はモーダルダイアログが表示されているか、ウィンドウがビジー状態です。アプリを前面に表示して再試行してください。
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 のシバンを含む、単一のバンドル済み ESM ファイルが生成されます。prepublishOnly は npm publish のたびにビルドを実行します。

---

ライセンス

MIT © Mind Elixir