axomind-mcp

Принцип работы

MCP работает на стороне потребителя, а не на сервере Axomind. Он не содержит бизнес-логики — он отправляет HTTP POST-запросы к bot_api.php и возвращает 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 бот-инструментов, которые позволяют ИИ взаимодействовать с ресурсами Axomind, к которым привязан бот:

• Mindmap (10 инструментов) — чтение, создание, обновление, удаление узлов; управление стилями

• Messenger (4 инструмента) — отправка, чтение, обновление, удаление сообщений бота

• Планирование (9 инструментов) — список активностей, управление назначениями, чтение временны́х слотов

• Дерево (3 инструмента) — сканирование локальных каталогов и внедрение их в виде структур mindmap

Установка

uv pip install -e .

Зависимости: mcp (официальный SDK), httpx (HTTP-клиент).

Конфигурация

Скопируйте .env.example в .env и заполните учётные данные бота:

cp .env.example .env

Обязательные переменные

Необязательные

Как получить учётные данные бота

1. Откройте настольное приложение Axomind

2. Перейдите в управление ботами

3. Создайте нового бота → вы получите ID бота и ключ доступа бота

4. Назначьте бота на ресурсы, к которым нужен доступ (mindmap, активности, беседы)

5. Внесите учётные данные в файл .env

Бот может получить доступ только к тем ресурсам, где его ID указан в JSONB-колонке bots — это обеспечивается на стороне сервера Axomind.

Доступные инструменты (26)

Mindmap (10) — Bot API

Безопасное изменение узлов — JSON обрабатывает алгоритм

update_node и delete_node — это безопасный способ изменения mindmap. Они читают полную mindmap, вносят точечные изменения в конкретные узлы и синхронизируют всё обратно. Остальные узлы (включая их описания) сохраняются без изменений.

ИИ никогда не формирует полный 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)

Проверки, выполняемые алгоритмом (а не ИИ):

• Самоссылка: parent == order_index → отклоняется

• Обнаружение циклов: new_parent является потомком order_index → отклоняется

• Родитель должен существовать в mindmap

• Корневой узел (parent=0) удалить нельзя

• free_links не может ссылаться на самого себя, все цели должны существовать

• size_box должен быть в диапазоне 0–11

Упрощённый формат для replace_mindmap / add_nodes

ИИ предоставляет компактный 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 (необязательное) — цвет в HEX (по умолчанию: 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 читает существующую mindmap и добавляет узлы после существующих.

Дерево / сканирование каталогов (3) — локально + Bot API

Эти инструменты сканируют локальную файловую систему для построения структур mindmap из деревьев каталогов.

Рабочий процесс: внедрение каталога в 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.

• Читаются и преобразуются в Quill Delta только файлы .md, .markdown, .txt

• Файлы > 500 КБ и нетекстовые форматы (.docx, .pdf, изображения) получают узлы с пустыми описаниями

• Скрытые файлы и каталоги VCS (.git, node_modules, __pycache__) автоматически пропускаются

• Никогда не вызывайте get_mindmap для проверки внедрения — достаточно сводки + счётчика tree_scope

Messenger (4) — Bot API

Активности / Планирование (9) — Bot API

Все инструменты планирования используют Bot API (bot_api.php → маршрут api_activity). Бот действует от имени user_id владельца бота — та же цепочка аутентификации, что и у add_assignment / update_assignment / delete_assignment.

Высокоуровневые инструменты (предпочтительны они)

Низкоуровневые инструменты (сырой JSON)

Стратегия токен-эффективного чтения

MCP предоставляет трёхуровневую стратегию чтения, чтобы контекст ИИ оставался небольшим:

1. list_mindmaps() — только метаданные (id, название, участники). Без узлов.

2. get_mindmap_summary(id_mindmap) — компактная сводка: количество узлов, названия, структура, флаг has_description. Без описаний, позиций и стилей.

3. get_node_description(id_mindmap, order_index) — чтение описания одного узла (ограничено ~4 КБ).

ИИ не должен вызывать get_mindmap (полную версию), если ему не нужно просматривать отдельные поля узла перед изменением. Для понимания структуры используйте get_mindmap_summary. Для чтения содержимого используйте get_node_description на конкретных узлах.

Интеграция с Hermes

Чтобы использовать Axomind Bot API из Hermes, добавьте 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 задаёт рабочую директорию, но не путь импорта 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 тестов — mock httpx, никаких сетевых вызовов к серверу 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-запросы

• Дерево инструментов (локальное сканирование файловой системы) сканирует только ту локальную машину, где запущен MCP

• Путь к файлу .env задаётся через AXOMIND_ENV_FILE — он не доступен из публичного репозитория

Лицензия

Proprietary — см. LICENSE. Copyright © 2025 VEZZANI Sébastien. Все права защищены.