axomind-mcp

原則

MCP は Axomind サーバー側ではなくコンシューマー側に存在します。ビジネスロジックは含まれず、bot_api.php に HTTP POST リクエストを送信して JSON を返すだけです。すべてのセキュリティ（認証、レート制限、IP 禁止、bots @> チェック）は PHP 側に残ります。

AI (any MCP client — Hermes, Claude, Cursor, etc.)
  → MCP server Python (FastMCP)
    → HTTP POST → bot_api.php
      → PHP does the work (auth, DB, WS notify)
    ← JSON response
  ← MCP tool result → AI

Related MCP server: telegram-api-mcp

この MCP が行うこと

このサーバーは、ボットが割り当てられている Axomind リソースと AI が対話できるようにする26 個のボットツールを公開します：

• マインドマップ（10 ツール）— ノードの読み取り、作成、更新、削除、スタイル管理

• メッセンジャー（4 ツール）— ボットメッセージの送信、読み取り、更新、削除

• プランニング（9 ツール）— アクティビティの一覧表示、割り当て管理、時間枠の読み取り

• ツリー（3 ツール）— ローカルディレクトリをスキャンしてマインドマップ構造として注入

インストール

uv pip install -e .

依存関係：mcp（公式 SDK）、httpx（HTTP クライアント）。

設定

.env.example を .env にコピーし、ボットの認証情報を入力します：

cp .env.example .env

必須変数

オプション

ボット認証情報の取得方法

1. Axomind デスクトップアプリを開く

2. ボット管理に移動

3. 新しいボットを作成 → ボット ID とボットアクセスキーが取得できる

4. アクセスさせたいリソース（マインドマップ、アクティビティ、会話）にボットを割り当てる

5. 認証情報を .env ファイルに記入する

ボットは、その ID が bots JSONB 列にリストされているリソースにのみアクセスできます。これは Axomind によってサーバー側で強制されます。

利用可能なツール（26）

マインドマップ（10）— ボット API

安全なノード変更 — アルゴリズムが JSON を処理

update_node と delete_node はマインドマップを変更する安全な方法です。完全なマインドマップを読み取り、特定のノードに的を絞った変更を適用し、すべてを同期し直します。他のノード（説明を含む）は変更されずに保持されます。

AI は完全なノード JSON を構築せず、変更するフィールドのみを渡し、残りはアルゴリズムが処理します：

// update_node: rename node 33
{"title": "messenger.md test"}

// update_node: change description (markdown → Quill Delta conversion is automatic)
{"descriptions": "# Module Messenger\n\nThis module handles..."}

// update_node: re-parent with cycle detection
{"parent": 2}

// update_node: change style + propagate to children
{"color": "0xFFFF6F91", "bold": true, "is_write_children": true}

// delete_node: just the order_index, no JSON at all
// delete_node(id_mindmap=100, order_index=33)

アルゴリズムによって強制される検証（AI によるものではありません）：

• 自己参照：parent == order_index → 拒否

• 循環検出：new_parent が order_index の子孫である場合 → 拒否

• 親はマインドマップ内に存在する必要がある

• ルートノード（parent=0）は削除できない

• free_links は自分自身をターゲットにできず、すべてのターゲットが存在する必要がある

• size_box は 0〜11 である必要がある

replace_mindmap / add_nodes の簡略化形式

AI はコンパクトな JSON を提供します — MCP が約 25 のデフォルトフィールドを自動展開します：

[
  {"title": "Root", "parent": 0, "color": "0xFFF0BA6D", "size_box": 2, "bold": true},
  {"title": "Category A", "parent": 1, "color": "0xFF7A8FF5", "size_box": 1, "line_style": 1},
  {"title": "Item 1", "parent": 2},
  {"title": "Item 2", "parent": 2, "color": "0xFFFF6F91", "free_links": [3]}
]

フィールド：

• title（必須）— ノードのタイトル

• parent（必須）— 親ノードの order_index（0 = ルート、1 = 最初のノード）

• color（オプション）— 16 進カラー（デフォルト：0xFF7A8FF5）

• pos_x、pos_y（オプション）— キャンバス上の位置（デフォルト：0）

• size_box（オプション）— 0=通常、1=カテゴリ、2=ルート（デフォルト：0）

• bold、italic、underline（オプション）— テキストスタイル

• line_type（オプション）— 0=曲線、1=角丸、2=四角

• line_style（オプション）— 0=実線、1=破線

• stroke_width、dot_radius、radius、border_size、label_size（オプション）

• icon_id（オプション）— アイコン ID

• active_bg_colors（オプション）— アクティブな背景色

• descriptions（オプション）— 説明テキスト（markdown → Quill Delta）

• free_links（オプション）— ノード間のフリーリンク用の order_index リスト

• spacing_h、spacing_v（オプション）— 間隔の乗数（0〜10）

• is_write_children（オプション）— スタイルを子に伝播（ワンショット）

UID と order_index は自動的に割り当てられます。add_nodes は既存のマインドマップを読み取り、既存ノードの後に追加します。

ツリー / ディレクトリスキャン（3）— ローカル + ボット API

これらのツールはローカルファイルシステムをスキャンして、ディレクトリツリーからマインドマップ構造を構築します。

ワークフロー：ディレクトリをマインドマップに注入

1. tree_scope(root_path, root_title) → reference count (1 root + N dirs + M files)
2. inject_directory_to_mindmap(root_path, root_title, id_mindmap) → scan + read + Quill Delta + sync
3. Compare the returned summary (total_nodes, descriptions_filled, errors) with tree_scope count
4. If they match and errors is empty → injection validated. DONE.

• .md、.markdown、.txt ファイルのみが読み取られ、Quill Delta に変換されます

• 500 KB を超えるファイルと非テキスト形式（.docx、.pdf、画像）は、説明が空のノードになります

• 隠しファイルと VCS ディレクトリ（.git、node_modules、__pycache__）は自動的にスキップされます

• 注入の検証に get_mindmap を呼び出さないでください — 要約 + tree_scope のカウントで十分です

メッセンジャー（4）— ボット API

アクティビティ / プランニング（9）— ボット API

すべてのプランニングツールはボット API（bot_api.php → api_activity ルート）を使用します。ボットはボット所有者の user_id として動作します — add_assignment / update_assignment / delete_assignment と同じ認証チェーンです。

高レベルツール（こちらを推奨）

低レベルツール（生のJSON）

トークン効率の高い読み取り戦略

MCPはAIコンテキストを小さく保つための3層の読み取り戦略を提供します：

1. list_mindmaps() — メタデータのみ（id、タイトル、参加者）。ノードは含まれません。

2. get_mindmap_summary(id_mindmap) — コンパクトなサマリー：ノード数、タイトル、構造、has_description フラグ。説明、位置、スタイルは含まれません。

3. get_node_description(id_mindmap, order_index) — 単一ノードの説明を読み取ります（~4 KBに制限）。

AIは、変更前に個々のノードフィールドを検査する必要がある場合を除き、get_mindmap（完全版）を決して呼び出すべきではありません。構造を理解するには get_mindmap_summary を使用してください。コンテンツを読むには、特定のノードに対して get_node_description を使用してください。

Hermesとの統合

HermesからAxomind Bot APIを利用するには、MCPサーバーを ~/.hermes/config.yaml に追加します：

mcp_servers:
  axomind:
    command: "python3"
    args: ["-m", "axomind_mcp.serveur.server"]
    env:
      # Bot API — URL to bot_api.php on the Axomind server
      AXOMIND_BASE_URL: "https://quantive-studio.fr/app/bot_api.php"
      # Bot credentials (from Axomind UI → bot management)
      AXOMIND_BOT_ID: "<your_bot_id>"
      AXOMIND_BOT_KEY: "<your_key_access>"
      # Python import path (required — workdir sets cwd but not the import path)
      PYTHONPATH: "/path/to/axomind-mcp/src"
    workdir: "/path/to/axomind-mcp"

⚠️ すべての env 値は文字列でなければなりません（YAMLは 72 をintとして解析するため、pydanticが拒否します）。 ⚠️ PYTHONPATH が必要です — workdir はcwdを設定しますが、Pythonのインポートパスは設定しません。

設定を編集したら、Hermesを再起動するか /reload-mcp を実行してください — 26個のツールが mcp_axomind_ プレフィックス付きで自動的に検出されます（例：mcp_axomind_list_mindmaps、mcp_axomind_send_message、mcp_axomind_read_planning）。

その他のMCPクライアント（Claude Desktop、Cursorなど）

同じ環境変数とコマンドを使用します。MCPサーバーは標準のstdioトランスポートを使用します。

テスト

PYTHONPATH=src python -m pytest tests/ -v

149件のテスト — httpxをモックし、Axomindサーバーへのネットワーク呼び出しはありません。

アーキテクチャ

src/axomind_mcp/
├── __init__.py
├── _common.py              — FastMCP instance, env config, _post() helper, node defaults
├── _planning.py            — 9 tools planning/activity (bot API)
├── imports.py              — Single import hub (registers all @mcp.tool() decorators)
├── messaging/              — Messaging tools
│   ├── __init__.py
│   └── _messenger.py       — 4 tools messenger (bot API)
├── serveur/
│   ├── __init__.py
│   └── server.py           — Entry point stdio, mcp.run()
├── mindmap/
│   ├── __init__.py
│   ├── _mindmap.py         — 10 tools mindmap (bot API)
│   ├── node_operations.py  — Shared algo: update/delete/patch nodes, cycle detection, style propagation
│   └── config_layout_mindmap.py — Node expansion, validation, auto-positioning
└── tools/
    ├── __init__.py
    ├── _file_reader.py     — File reading by extension → Quill Delta
    ├── md_to_quill_delta.py — Markdown → Quill Delta converter
    └── _tree.py            — 3 tools tree (local + bot API)

セキュリティ

• MCPはデータベースに触れず、ビジネスロジックも含みません

• 認証情報は環境変数から取得されます（ハードコードされません）

• AxomindサーバーはそれがMCPであることを認識できません — 通常のbot_apiリクエストとして見えます

• ツリーツール（ローカルファイルシステムスキャン）は、MCPが実行されているローカルマシンのみをスキャンします

• .env ファイルのパスは AXOMIND_ENV_FILE で設定されます — 公開リポジトリからは発見できません

ライセンス

プロプライエタリ — LICENSE を参照してください。Copyright © 2025 VEZZANI Sébastien. 無断転載を禁じます。