axomind-mcp

Principio

El MCP reside en el lado del consumidor, no en el servidor de Axomind. No contiene lógica de negocio: realiza peticiones HTTP POST a bot_api.php y devuelve el JSON. Toda la seguridad (autenticación, limitación de velocidad, bloqueos de IP, comprobaciones bots @>) permanece en el lado 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

Qué hace este MCP

Este servidor expone 26 herramientas de bot que permiten a una IA interactuar con los recursos de Axomind donde hay un bot asignado:

• Mindmap (10 herramientas): leer, crear, actualizar y eliminar nodos; gestionar estilos

• Messenger (4 herramientas): enviar, leer, actualizar y eliminar mensajes del bot

• Planning (9 herramientas): listar actividades, gestionar asignaciones, leer franjas horarias

• Tree (3 herramientas): escanear directorios locales e inyectarlos como estructuras de mindmap

Instalación

uv pip install -e .

Dependencias: mcp (SDK oficial), httpx (cliente HTTP).

Configuración

Copia .env.example a .env y completa tus credenciales de bot:

cp .env.example .env

Variables obligatorias

Opcionales

Cómo obtener las credenciales del bot

1. Abre la aplicación de escritorio de Axomind

2. Ve a la gestión de bots

3. Crea un nuevo bot → obtendrás un ID de bot y una clave de acceso del bot

4. Asigna el bot a los recursos a los que quieras que acceda (mindmaps, actividades, conversaciones)

5. Introduce las credenciales en tu archivo .env

El bot solo puede acceder a los recursos donde su ID aparece en la columna JSONB bots; esto lo aplica Axomind en el lado del servidor.

Herramientas disponibles (26)

Mindmap (10) — bot API

Modificación segura de nodos: el algoritmo gestiona el JSON

update_node y delete_node son la forma segura de modificar un mindmap. Leen el mindmap completo, aplican cambios específicos a nodos concretos y sincronizan todo. Los demás nodos (incluidas sus descripciones) se conservan intactos.

La IA nunca construye el JSON completo del nodo: solo pasa los campos a modificar y el algoritmo hace el resto:

// 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)

Validaciones que aplica el algoritmo (no la IA):

• Autorreferencia: parent == order_index → rechazada

• Detección de ciclos: new_parent es descendiente de order_index → rechazado

• El parent debe existir en el mindmap

• El nodo raíz (parent=0) no se puede eliminar

• free_links no puede apuntar a sí mismo; todos los destinos deben existir

• size_box debe estar entre 0 y 11

Formato simplificado para replace_mindmap / add_nodes

La IA proporciona un JSON compacto; el MCP expande automáticamente ~25 campos por defecto:

[
  {"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]}
]

Campos:

• title (obligatorio): título del nodo

• parent (obligatorio): order_index del nodo padre (0 = raíz, 1 = primer nodo)

• color (opcional): color hexadecimal (por defecto: 0xFF7A8FF5)

• pos_x, pos_y (opcional): posición en el lienzo (por defecto: 0)

• size_box (opcional): 0=normal, 1=categoría, 2=raíz (por defecto: 0)

• bold, italic, underline (opcional): estilo de texto

• line_type (opcional): 0=curva, 1=redondeada, 2=cuadrada

• line_style (opcional): 0=sólida, 1=discontinua

• stroke_width, dot_radius, radius, border_size, label_size (opcional)

• icon_id (opcional): ID del icono

• active_bg_colors (opcional): colores de fondo activos

• descriptions (opcional): texto descriptivo (markdown → Quill Delta)

• free_links (opcional): lista de order_index para enlaces libres entre nodos

• spacing_h, spacing_v (opcional): multiplicadores de espaciado (0-10)

• is_write_children (opcional): propaga el estilo a los hijos (de una sola vez)

El UID y el order_index se asignan automáticamente. add_nodes lee el mindmap existente y añade después de los nodos existentes.

Tree / Escaneo de directorios (3) — local + bot API

Estas herramientas escanean el sistema de archivos local para construir estructuras de mindmap a partir de árboles de directorios.

Flujo de trabajo: inyectar un directorio en un 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.

• Solo se leen y convierten a Quill Delta los archivos .md, .markdown y .txt

• Los archivos de más de 500 KB y los formatos no textuales (.docx, .pdf, imágenes) reciben nodos con descripciones vacías

• Los archivos ocultos y los directorios de control de versiones (.git, node_modules, __pycache__) se omiten automáticamente

• Nunca llames a get_mindmap para verificar una inyección: el resumen + el recuento de tree_scope son suficientes

Messenger (4) — bot API

Actividad / Planificación (9) — bot API

Todas las herramientas de planificación usan la bot API (ruta bot_api.php → api_activity). El bot opera con el user_id del propietario del bot: la misma cadena de autenticación que add_assignment / update_assignment / delete_assignment.

Herramientas de alto nivel (prefiere estas)

Herramientas de bajo nivel (JSON crudo)

Estrategia de lectura eficiente en tokens

1. list_mindmaps() — solo metadatos (id, título, participantes). Sin nodos.

2. get_mindmap_summary(id_mindmap) — resumen compacto: número de nodos, títulos, estructura, indicador has_description. Sin descripciones, sin posiciones, sin estilos.

3. get_node_description(id_mindmap, order_index) — lee la descripción de un solo nodo (limitada a ~4 KB).

La IA nunca debe llamar a get_mindmap (completo) a menos que necesite inspeccionar campos individuales de nodos antes de una modificación. Para entender la estructura, usa get_mindmap_summary. Para leer contenido, usa get_node_description en nodos específicos.

Integración con Hermes

Para consumir la API del Bot Axomind desde Hermes, añade el servidor MCP a ~/.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"

⚠️ Todos los valores de env deben ser cadenas (YAML interpreta 72 como int → pydantic lo rechaza).
⚠️ PYTHONPATH es obligatorio — workdir establece el cwd pero no la ruta de importación de Python.

Después de editar la configuración, reinicia Hermes o ejecuta /reload-mcp — las 26 herramientas se descubren automáticamente con el prefijo mcp_axomind_ (por ejemplo, mcp_axomind_list_mindmaps, mcp_axomind_send_message, mcp_axomind_read_planning).

Otros clientes MCP (Claude Desktop, Cursor, etc.)

Usa las mismas variables de entorno y comando. El servidor MCP utiliza transporte stdio estándar.

Pruebas

PYTHONPATH=src python -m pytest tests/ -v

149 pruebas — mock de httpx, sin llamadas de red al servidor Axomind.

Arquitectura

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)

Seguridad

• El MCP no toca la base de datos ni contiene lógica de negocio

• Las credenciales provienen de variables de entorno (nunca codificadas)

• El servidor Axomind no puede saber que es un MCP — ve solicitudes normales de bot_api

• Las herramientas de árbol (escaneo del sistema de archivos local) solo escanean la máquina local donde se ejecuta el MCP

• La ruta del archivo .env se establece mediante AXOMIND_ENV_FILE — no se puede descubrir desde el repositorio público

Licencia

Propietario — ver LICENSE. Copyright © 2025 VEZZANI Sébastien. Todos los derechos reservados.