---

Principle

The MCP lives on the consumer side, not on the Axomind server. It contains no business logic — it makes HTTP POST requests to bot_api.php and returns the JSON. All security (auth, rate limiting, IP bans, bots @> checks) stays on the PHP side.

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

What this MCP does

This server exposes 26 bot tools that let an AI interact with Axomind resources where a bot is assigned:

• Mindmap (10 tools) — read, create, update, delete nodes; manage styles
• Messenger (4 tools) — send, read, update, delete bot messages
• Planning (9 tools) — list activities, manage assignments, read time slots
• Tree (3 tools) — scan local directories and inject them as mindmap structures

Installation

uv pip install -e .

Dependencies: mcp (official SDK), httpx (HTTP client).

Configuration

Copy .env.example to .env and fill in your bot credentials:

cp .env.example .env

Required variables

Variable	Description
AXOMIND_BASE_URL	URL to bot_api.php on the Axomind server (e.g. https://quantive-studio.xyz/app/bot_api.php)
AXOMIND_BOT_ID	Bot ID (from Axomind UI → bot management)
AXOMIND_BOT_KEY	Bot access key (generated when creating the bot in the UI)

Optional

Variable	Default	Description
AXOMIND_TIMEOUT	30	HTTP timeout in seconds
AXOMIND_ENV_FILE	—	Explicit path to .env file (recommended for production)

How to get bot credentials

1. Open Axomind desktop app
2. Go to bot management
3. Create a new bot → you get a Bot ID and a Bot access key
4. Assign the bot to the resources you want it to access (mindmaps, activities, conversations)
5. Put the credentials in your .env file

The bot can only access resources where its ID is listed in the bots JSONB column — this is enforced server-side by Axomind.

Available tools (26)

Mindmap (10) — bot API

Tool	Description	Destructive?
list_mindmaps	List mindmaps where the bot is assigned (metadata only)	No
get_mindmap	Read a mindmap (metadata + all nodes). ⚠️ Response can exceed 2 MB for 60+ nodes with descriptions	No
get_mindmap_summary	Compact summary — node count, titles, structure, has_description. Context-safe, no descriptions or styles	No
get_node_description	Read a single node's description by order_index (capped at ~4 KB). Use after get_mindmap_summary	No
sync_nodes	Replace ALL nodes (full JSON, ~25 fields per node). ⚠️ DESTRUCTIVE — sends 1 node → deletes the other 98	⚠️ Yes
add_nodes	Append nodes to an existing mindmap (simplified format). Reads existing, appends, syncs	No
replace_mindmap	Replace all nodes (simplified format). Validates hierarchy before sending	⚠️ Yes (validated)
update_node	Update a single node — all fields supported (title, descriptions, parent, style, positions, free_links). Reads full mindmap, patches one node, syncs back. The algorithm handles the JSON, not the AI	No (safe)
delete_node	Delete a node + its subtree. Cleans free_links pointing to deleted nodes. Root node (parent=0) cannot be deleted. The algorithm handles the JSON, not the AI	No (safe)
update_nodes_style	Update style fields on multiple nodes (color, bold, size_box, etc.). Reads, patches, syncs back	No (safe)

Safe node modification — the algorithm handles the JSON

update_node and delete_node are the safe way to modify a mindmap. They read the full mindmap, apply targeted changes to specific nodes, and sync everything back. Other nodes (including their descriptions) are preserved untouched.

The AI never builds the full node JSON — it passes only the fields to modify, and the algorithm does the rest:

// 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)

Validations enforced by the algorithm (not by the AI):

• Self-reference: parent == order_index → rejected
• Cycle detection: new_parent is a descendant of order_index → rejected
• Parent must exist in the mindmap
• Root node (parent=0) cannot be deleted
• free_links cannot target self, all targets must exist
• size_box must be 0–11

Simplified format for replace_mindmap / add_nodes

The AI provides a compact JSON — the MCP auto-expands ~25 default fields:

[
  {"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]}
]

Fields:

• title (required) — node title
• parent (required) — order_index of the parent node (0 = root, 1 = first node)
• color (optional) — hex color (default: 0xFF7A8FF5)
• pos_x, pos_y (optional) — canvas position (default: 0)
• size_box (optional) — 0=normal, 1=category, 2=root (default: 0)
• bold, italic, underline (optional) — text style
• line_type (optional) — 0=curve, 1=rounded, 2=square
• line_style (optional) — 0=solid, 1=dashed
• stroke_width, dot_radius, radius, border_size, label_size (optional)
• icon_id (optional) — icon ID
• active_bg_colors (optional) — active background colors
• descriptions (optional) — descriptive text (markdown → Quill Delta)
• free_links (optional) — list of order_index for free links between nodes
• spacing_h, spacing_v (optional) — spacing multipliers (0-10)
• is_write_children (optional) — propagate style to children (one-shot)

UID and order_index are assigned automatically. add_nodes reads the existing mindmap and appends after existing nodes.

Tree / Directory scanning (3) — local + bot API

These tools scan the local filesystem to build mindmap structures from directory trees.

Tool	Description	HTTP?
tree_scope	Compact telemetry of a directory (title, type, size, hierarchy). Does NOT read file content. Use before injection to get a reference node count	No (local)
inject_directory_to_mindmap	One-shot scan + read + inject — scans the directory, reads .md/.markdown/.txt files, converts to Quill Delta, and syncs everything into the mindmap. Returns a compact summary for validation	Yes (sync_nodes)
tree_to_mindmap	Scan → JSON nodes (simplified format, no file content). Ready for replace_mindmap or add_nodes	No (local)

Workflow: inject a directory into a mindmap

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.

• Only .md, .markdown, .txt files are read and converted to Quill Delta
• Files > 500 KB and non-text formats (.docx, .pdf, images) get nodes with empty descriptions
• Hidden files and VCS directories (.git, node_modules, __pycache__) are skipped automatically
• Never call get_mindmap to verify an injection — the summary + tree_scope count are sufficient

Messenger (4) — bot API

Tool	Description
send_message	Send a message (targeted or broadcast to all conversations)
get_messages	Read bot messages in a conversation
update_message	Update a bot message
delete_message	Delete a bot message

Activity / Planning (9) — bot API

All planning tools use the bot API (bot_api.php → api_activity route). The bot operates as the bot owner's user_id — the same authentication chain as add_assignment / update_assignment / delete_assignment.

High-level tools (prefer these)

Tool	Description
create_assignment	Create an assignment (single-day or recursive) with human-friendly params (dates, hours, weekday names). Builds the JSON internally
modify_assignment	Modify an existing assignment group. Server marks tombstone, removes old slots, creates new ones
verify_assignment	Read an activity and return a telemetry report (groups, slots, consistency checks)
read_planning	Read all planning slots for a given year via the bot API. Returns actual time slot data (start/end times, day of year, user assignments) and group controls. Uses PlanningsUsers::getList() + GstGroupControlPlanning::getList() with the bot owner's user_id

Low-level tools (raw JSON)

Tool	Description
list_activities	List activities where the bot is assigned
get_activity	Read a specific activity (full metadata)
add_assignment	Assign time slots (raw planning_list + recursive_group JSON)
update_assignment	Update an assignment group (raw JSON)
delete_assignment	Delete an assignment group

Token-efficient reading strategy

The MCP provides a 3-tier reading strategy to keep AI context small:

1. list_mindmaps() — metadata only (id, title, participants). No nodes.
2. get_mindmap_summary(id_mindmap) — compact summary: node count, titles, structure, has_description flag. No descriptions, no positions, no styles.
3. get_node_description(id_mindmap, order_index) — read a single node's description (capped at ~4 KB).

The AI should never call get_mindmap (full) unless it needs to inspect individual node fields before a modification. For understanding structure, use get_mindmap_summary. For reading content, use get_node_description on specific nodes.

Integration with Hermes

To consume the Axomind Bot API from Hermes, add the MCP server to ~/.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.xyz/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"

⚠️ All env values must be strings (YAML parses 72 as int → pydantic rejects it). ⚠️ PYTHONPATH is required — workdir sets the cwd but not the Python import path.

After editing the config, restart Hermes or run /reload-mcp — the 26 tools are discovered automatically with the mcp_axomind_ prefix (e.g. mcp_axomind_list_mindmaps, mcp_axomind_send_message, mcp_axomind_read_planning).

Other MCP clients (Claude Desktop, Cursor, etc.)

Use the same env vars and command. The MCP server uses standard stdio transport.

Tests

PYTHONPATH=src python -m pytest tests/ -v

149 tests — mock httpx, no network calls to the Axomind server.

Architecture

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)

Security

• The MCP does not touch the database or contain any business logic
• Credentials come from environment variables (never hardcoded)
• The Axomind server cannot tell it's a MCP — it sees normal bot_api requests
• Tree tools (local filesystem scan) only scan the local machine where the MCP runs
• The .env file path is set via AXOMIND_ENV_FILE — not discoverable from the public repo

License

Proprietary — see LICENSE. Copyright © 2025 VEZZANI Sébastien. All rights reserved.

---