axomind-mcp

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

Related MCP server: @isteamhq/mcp

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

Optional

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

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.

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

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)

Low-level tools (raw JSON)

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.