axomind-mcp

<div align="center"> <img src="image/logo_axomind.png" alt="Axomind Logo" width="150"/> <h1>axomind-mcp</h1> <p><strong>MCP server (Model Context Protocol) for Axomind — a harmless proxy to the Bot API.</strong></p> </div>

---

Principle

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

AI (Hermes/Atlas)
  → stdio → MCP server Python (FastMCP)
    → HTTP POST → bot_api.php (lib_api_access/*)
      → PHP does the work (auth, DB, WS notify)
    ← JSON response
  ← MCP tool result → AI

Installation

uv pip install -e .

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

Configuration

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

cp .env.example .env

Variables:

• AXOMIND_BASE_URL — URL to bot_api.php (e.g. http://xx.xx.xx.xx/app/bot_api.php)
• AXOMIND_BOT_ID — Bot ID (from Axomind UI → bot management)
• AXOMIND_BOT_KEY — Bot access key
• AXOMIND_TIMEOUT — HTTP timeout in seconds (default: 30)

Available tools (14)

Activity / Planning (5)

Tool	Description
list_activities	List activities where the bot is assigned
get_activity	Read a specific activity
add_assignment	Assign time slots to an activity
update_assignment	Update an assignment group
delete_assignment	Delete an assignment group

Mindmap (5)

Tool	Description
list_mindmaps	List mindmaps where the bot is assigned
get_mindmap	Read a mindmap (metadata + nodes)
replace_mindmap	Replace all nodes (simplified format) — the AI only needs {title, parent, color?, size_box?}
add_nodes	Append nodes to an existing mindmap (simplified format)
sync_nodes	Raw sync (full node JSON, for advanced use)

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
• free_links (optional) — list of order_index for free links between nodes

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

Messenger (4)

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

Tests

PYTHONPATH=src python -m pytest tests/ -v

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

Hermes configuration

In ~/.hermes/config.yaml:

mcp_servers:
  axomind:
    command: "python3"
    args: ["-m", "axomind_mcp.server"]
    env:
      AXOMIND_BASE_URL: "http://xx.xx.xx.xx/app/bot_api.php"
      AXOMIND_BOT_ID: "72"
      AXOMIND_BOT_KEY: "your_key_access"
      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.

Restart Hermes → tools are discovered automatically with the mcp_axomind_ prefix.

Security

• The MCP does not touch the database, read files, or contain any business logic
• Credentials come from environment variables
• The Axomind server cannot tell it's a MCP — it sees normal bot_api requests
• The MCP does not run on production — zero additional attack surface

License

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

---

<div align="center"> <a href="https://sebastien-vezzani.xyz/" target="_blank"><img src="https://img.shields.io/badge/Portfolio-3423A6?style=for-the-badge&logo=firefox-browser&logoColor=white" alt="Link to Portfolio"/></a> </div>