MCP 服务器

axomind-mcp

MCP server for Axomind — enables AI assistants to manage activities, mindmaps, and messages through a harmless proxy to the Bot API.

README

<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.