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 的功能

此服务器暴露了 26 个机器人工具，使 AI 能够与分配了机器人的 Axomind 资源进行交互：

• 思维导图（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（可选）——十六进制颜色（默认：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）

节省 Token 的读取策略

MCP 提供了一种三层读取策略，以保持 AI 上下文精简：

1. list_mindmaps() — 仅元数据（id、title、participants）。无节点。

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 进行 mock，不向 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 请求

• Tree 工具（本地文件系统扫描）只扫描 MCP 运行所在的本地机器

• .env 文件路径通过 AXOMIND_ENV_FILE 设置 — 无法从公共仓库中发现

许可证

专有 — 参见 LICENSE。版权所有 © 2025 VEZZANI Sébastien。保留所有权利。