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가 하는 일

이 서버는 봇이 할당된 Axomind 리소스와 AI가 상호작용할 수 있게 해주는 26개의 봇 도구를 제공합니다:

• 마인드맵(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(선택) — 16진수 색상(기본값: 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로 변환됩니다

• 500KB 초과 파일 및 비텍스트 형식(.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)

토큰 효율적 읽기 전략

MCP는 AI 컨텍스트를 작게 유지하기 위한 3계층 읽기 전략을 제공합니다:

1. list_mindmaps() — 메타데이터만 포함(id, 제목, 참가자). 노드는 없음.

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 import 경로는 설정하지 않습니다.

구성을 편집한 후 Hermes를 다시 시작하거나 /reload-mcp를 실행하세요. 26개의 도구가 mcp_axomind_ 접두사로 자동 검색됩니다(예: mcp_axomind_list_mindmaps, mcp_axomind_send_message, mcp_axomind_read_planning).

기타 MCP 클라이언트(Claude Desktop, Cursor 등)

동일한 env 변수와 명령을 사용하세요. MCP 서버는 표준 stdio 전송을 사용합니다.

테스트

PYTHONPATH=src python -m pytest tests/ -v

149개의 테스트 — 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을 통해 설정되며 공개 저장소에서 찾을 수 없습니다.

라이선스

사유 라이선스 — LICENSE를 참조하세요. Copyright © 2025 VEZZANI Sébastien. 모든 권리 보유.