axomind-mcp

Prinzip

Der MCP lebt auf der Verbraucherseite, nicht auf dem Axomind-Server. Er enthält keine Geschäftslogik — er sendet HTTP-POST-Anfragen an bot_api.php und gibt das JSON zurück. Die gesamte Sicherheit (Authentifizierung, Ratenbegrenzung, IP-Sperren, bots @>-Prüfungen) bleibt auf der PHP-Seite.

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

Was dieser MCP tut

Dieser Server stellt 26 Bot-Tools bereit, die es einer KI ermöglichen, mit Axomind-Ressourcen zu interagieren, denen ein Bot zugewiesen ist:

• Mindmap (10 Tools) — Knoten lesen, erstellen, aktualisieren, löschen; Stile verwalten

• Messenger (4 Tools) — Bot-Nachrichten senden, lesen, aktualisieren, löschen

• Planung (9 Tools) — Aktivitäten auflisten, Zuweisungen verwalten, Zeitfenster lesen

• Baum (3 Tools) — lokale Verzeichnisse scannen und als Mindmap-Strukturen einfügen

Installation

uv pip install -e .

Abhängigkeiten: mcp (offizielles SDK), httpx (HTTP-Client).

Konfiguration

Kopieren Sie .env.example in .env und füllen Sie Ihre Bot-Anmeldedaten aus:

cp .env.example .env

Erforderliche Variablen

Optional

So erhalten Sie Bot-Anmeldedaten

1. Öffnen Sie die Axomind-Desktop-App

2. Gehen Sie zur Bot-Verwaltung

3. Erstellen Sie einen neuen Bot → Sie erhalten eine Bot-ID und einen Bot-Zugriffsschlüssel

4. Weisen Sie den Bot den Ressourcen zu, auf die er zugreifen soll (Mindmaps, Aktivitäten, Konversationen)

5. Tragen Sie die Anmeldedaten in Ihre .env-Datei ein

Der Bot kann nur auf Ressourcen zugreifen, in denen seine ID in der bots-JSONB-Spalte aufgeführt ist — dies wird serverseitig von Axomind erzwungen.

Verfügbare Tools (26)

Mindmap (10) — Bot-API

Sichere Knotenänderung — der Algorithmus verarbeitet das JSON

update_node und delete_node sind der sichere Weg, eine Mindmap zu ändern. Sie lesen die vollständige Mindmap, wenden gezielte Änderungen auf bestimmte Knoten an und synchronisieren alles zurück. Andere Knoten (einschließlich ihrer Beschreibungen) bleiben unverändert erhalten.

Die KI erstellt nie das vollständige Knoten-JSON — sie übergibt nur die zu ändernden Felder, und der Algorithmus erledigt den Rest:

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

Vom Algorithmus erzwungene Validierungen (nicht von der KI):

• Selbstreferenz: parent == order_index → abgelehnt

• Zykluserkennung: new_parent ist ein Nachkomme von order_index → abgelehnt

• parent muss in der Mindmap vorhanden sein

• Der Wurzelknoten (parent=0) kann nicht gelöscht werden

• free_links können nicht auf sich selbst zeigen, alle Ziele müssen vorhanden sein

• size_box muss 0–11 sein

Vereinfachtes Format für replace_mindmap / add_nodes

Die KI liefert ein kompaktes JSON — der MCP erweitert automatisch ~25 Standardfelder:

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

Felder:

• title (erforderlich) — Knotentitel

• parent (erforderlich) — order_index des übergeordneten Knotens (0 = Wurzel, 1 = erster Knoten)

• color (optional) — Hex-Farbe (Standard: 0xFF7A8FF5)

• pos_x, pos_y (optional) — Canvas-Position (Standard: 0)

• size_box (optional) — 0=normal, 1=Kategorie, 2=Wurzel (Standard: 0)

• bold, italic, underline (optional) — Textstil

• line_type (optional) — 0=Kurve, 1=abgerundet, 2=eckig

• line_style (optional) — 0=durchgezogen, 1=gestrichelt

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

• icon_id (optional) — Symbol-ID

• active_bg_colors (optional) — aktive Hintergrundfarben

• descriptions (optional) — beschreibender Text (Markdown → Quill Delta)

• free_links (optional) — Liste von order_index für freie Verknüpfungen zwischen Knoten

• spacing_h, spacing_v (optional) — Abstands-Multiplikatoren (0-10)

• is_write_children (optional) — Stil an untergeordnete Knoten weitergeben (einmalig)

UID und order_index werden automatisch zugewiesen. add_nodes liest die bestehende Mindmap und hängt nach den vorhandenen Knoten an.

Baum / Verzeichnisscan (3) — lokal + Bot-API

Diese Tools scannen das lokale Dateisystem, um Mindmap-Strukturen aus Verzeichnisbäumen zu erstellen.

Arbeitsablauf: Ein Verzeichnis in eine Mindmap injizieren

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.

• Nur .md, .markdown, .txt-Dateien werden gelesen und in Quill Delta konvertiert

• Dateien > 500 KB und Nicht-Text-Formate (.docx, .pdf, Bilder) erhalten Knoten mit leeren Beschreibungen

• Versteckte Dateien und VCS-Verzeichnisse (.git, node_modules, __pycache__) werden automatisch übersprungen

• Nie get_mindmap aufrufen, um eine Injektion zu überprüfen — die Zusammenfassung + die tree_scope-Anzahl sind ausreichend

Messenger (4) — Bot-API

Aktivität / Planung (9) — Bot-API

Alle Planungstools verwenden die Bot-API (bot_api.php → api_activity-Route). Der Bot arbeitet mit der user_id des Bot-Besitzers — dieselbe Authentifizierungskette wie bei add_assignment / update_assignment / delete_assignment.

Hochrangige Tools (diese bevorzugen)

Low-Level-Tools (Roh-JSON)

Token-effiziente Lesestrategie

Das MCP bietet eine dreistufige Lesestrategie, um den KI-Kontext klein zu halten:

1. list_mindmaps() — nur Metadaten (id, Titel, Teilnehmer). Keine Knoten.

2. get_mindmap_summary(id_mindmap) — kompakte Zusammenfassung: Knotenanzahl, Titel, Struktur, has_description-Flag. Keine Beschreibungen, keine Positionen, keine Stile.

3. get_node_description(id_mindmap, order_index) — liest die Beschreibung eines einzelnen Knotens (begrenzt auf ~4 KB).

Die KI sollte get_mindmap (vollständig) nie aufrufen, außer sie muss vor einer Änderung einzelne Knotenfelder prüfen. Für das Verständnis der Struktur verwende get_mindmap_summary. Zum Lesen von Inhalten verwende get_node_description für bestimmte Knoten.

Integration mit Hermes

Um die Axomind Bot API aus Hermes zu nutzen, füge den MCP-Server zur ~/.hermes/config.yaml hinzu:

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"

⚠️ Alle env-Werte müssen Strings sein (YAML parst 72 as int → pydantic lehnt es ab). ⚠️ PYTHONPATH ist erforderlich — workdir setzt das Arbeitsverzeichnis (cwd), aber nicht den Python-Importpfad.

Nach dem Bearbeiten der Konfiguration starte Hermes neu oder führe /reload-mcp aus — die 26 Werkzeuge werden automatisch mit dem Präfix mcp_axomind_ erkannt (z. B. mcp_axomind_list_mindmaps, mcp_axomind_send_message, mcp_axomind_read_planning).

Andere MCP-Clients (Claude Desktop, Cursor, usw.)

Verwende dieselben Umgebungsvariablen und denselben Befehl. Der MCP-Server verwendet den Standard-Stdio-Transport.

Tests

PYTHONPATH=src python -m pytest tests/ -v

149 Tests — gemocktes httpx, keine Netzwerkaufrufe an den Axomind-Server.

Architektur

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)

Sicherheit

• Das MCP greift nicht auf die Datenbank zu und enthält keine Geschäftslogik

• Anmeldedaten stammen aus Umgebungsvariablen (niemals hartkodiert)

• Der Axomind-Server kann nicht erkennen, dass es ein MCP ist — er sieht normale bot_api-Anfragen

• Die Tree-Werkzeuge (lokaler Dateisystemscan) scannen nur den lokalen Rechner, auf dem das MCP läuft

• Der Pfad zur .env-Datei wird über AXOMIND_ENV_FILE festgelegt — nicht aus dem öffentlichen Repository erkennbar

Lizenz

Proprietär — siehe LICENSE. Copyright © 2025 VEZZANI Sébastien. Alle Rechte vorbehalten.