axomind-mcp

<div align="center"> <img src="image/logo_axomind.png" alt="Axomind Logo" width="150"/> <h1>axomind-mcp</h1> <p><strong>MCP 服务器（模型上下文协议）适用于 Axomind — 一个无害的代理，适用于 Bot API 和用户 API。</strong></p> </div> --- ## 原理 MCP 运行在**消费者端**，而不是 Axomind 服务器。它不包含任何业务逻辑 — 它向 `bot_api.php`（机器人工具）或 `index.php`（用户工具）发送 HTTP POST 请求，并返回 JSON。所有安全措施（身份验证、速率限制、IP 禁令、`bots @>` 检查）都在 PHP 端。 ``` AI (Hermes/Atlas 或 Ollama 守护进程) → MCP 服务器 Python (FastMCP) → HTTP POST → bot_api.php / index.php → PHP 执行工作（身份验证、数据库、WebSocket 通知） ← JSON 响应 ← MCP 工具结果 → AI ``` 服务器支持两种 AI 后端： - **Hermes 模式**（`AXOMIND_USE_HERMES=true`）：守护进程持有 WebSocket 连接并缓冲事件。Hermes/Atlas（云）通过 `user_poll_events` MCP 工具轮询事件并直接响应。所有 35 个工具都可通过 MCP 标准输入/输出服务器访问。 - **Ollama 模式**（`AXOMIND_USE_HERMES=false`）：守护进程使用本地 Ollama 模型处理传入消息（工具调用）。完全自主，无需 Hermes 依赖。28 个工具可用（排除 7 个：登录、令牌续期、状态、`poll_events` 和 3 个树工具 — 本地文件系统扫描在生产服务器上无用）。 ## 安装 ```bash uv pip install -e . ``` 依赖项：`mcp`（官方 SDK）、`httpx`（HTTP 客户端）、`websockets`（守护进程模式必填）。 ## 配置 复制 `.env.example` 到 `.env` 并填写凭证： ```bash cp .env.example .env ``` 变量： - `AXOMIND_BASE_URL` — `bot_api.php` 的 URL（例如 `http://xx.xx.xx.xx/app/bot_api.php`） - `AXOMIND_BOT_ID` — 机器人 ID（来自 Axomind UI → 机器人管理） - `AXOMIND_BOT_KEY` — 机器人访问密钥 - `AXOMIND_TIMEOUT` — 秒为单位的 HTTP 超时（默认值：30） 参见 [完整配置](#完整配置) 部分获取所有变量。 ## 可用工具（35） ### 思维导图（10）— 机器人 API | 工具 | 描述 | 是否破坏性 | |---|---|---| | `list_mindmaps` | 列出分配给机器人的思维导图（仅限元数据） | 否 | | `get_mindmap` | 读取思维导图（元数据 + 所有节点）。 ⚠️ 响应可能超过 2 MB（60+ 个节点带描述） | 否 | | `get_mindmap_summary` | **紧凑摘要** — 节点数量、标题、结构、`has_description`。上下文安全，无描述或样式 | 否 | | `get_node_description` | 按 `order_index` 读取单个节点的描述（上限 ~4 KB）。在 `get_mindmap_summary` 后使用 | 否 | | `sync_nodes` | 替换所有节点（完整 JSON，~25 个字段/节点）。 ⚠️ 破坏性 — 发送 1 个节点 → 删除其他 98 个 | 是 | | `add_nodes` | **追加节点** 到现有思维导图（简化格式）。读取现有节点，追加，同步 | 否 | | `replace_mindmap` | **替换所有节点** （简化格式）。验证层次结构后发送 | 是（已验证） | | `update_node` | **更新单个节点** — 支持所有字段（标题、描述、父节点、样式、位置、自由链接）。读取完整思维导图，修补一个节点，同步回 | 否（安全） | | `delete_node` | **删除节点 + 其子树**。清理指向已删除节点的自由链接。根节点（父节点=0）不能删除。算法处理 JSON，不是 AI | 否（安全） | | `update_nodes_style` | **更新多个节点** 的样式字段（颜色、粗体、大小框等）。读取、修补、同步回 | 否（安全） | #### 安全节点修改 — 算法处理 JSON `update_node` 和 `delete_node` 是修改思维导图的**安全**方式。它们读取完整的思维导图，应用有针对性的更改到特定节点，并同步所有内容。其他节点（包括其描述）保持不变。 AI 永远不会构建完整的节点 JSON — 它只传递要修改的字段，算法完成其余工作： ```json // update_node: 重命名节点 33 {"title": "messenger.md 测试"} // update_node: 更改描述（markdown → Quill Delta 转换自动） {"descriptions": "# 模块 Messenger\n\n此模块处理..."} ``` #### `replace_mindmap` / `add_nodes` 的简化格式 AI 提供紧凑的 JSON — MCP 自动扩展 ~25 个默认字段： ```json [ {"title": "根节点", "parent": 0, "color": "0xFFF0BA6D", "size_box": 2, "bold": true}, {"title": "类别 A", "parent": 1, "color": "0xFF7A8FF5", "size_box": 1, "line_style": 1}, {"title": "项目 1", "parent": 2}, {"title": "项目 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 这些工具扫描本地文件系统以从目录树构建思维导图结构。**仅在 Hermes 模式下可用** — 从生产服务器上的守护进程中排除（无源代码可扫描）。 | 工具 | 描述 | HTTP? | |---|---|---| | `tree_scope` | 目录的**紧凑遥测**（标题、类型、大小、层次）。不读取文件内容。在注入前使用以获取参考节点计数 | 否（本地） | | `inject_directory_to_mindmap` | **一次性扫描 + 读取 + 注入** — 扫描目录，读取 `.md`/`.markdown`/`.txt` 文件，转换为 Quill Delta，并同步到思维导图。返回紧凑摘要以进行验证 | 是（`sync_nodes`） | | `tree_to_mindmap` | **扫描 → JSON 节点**（简化格式，无文件内容）。可用于 `replace_mindmap` 或 `add_nodes` | 否（本地） | #### 工作流程：将目录注入思维导图 ``` 1. tree_scope(root_path, root_title) → 参考计数（1 个根节点 + N 个目录 + M 个文件） 2. inject_directory_to_mindmap(root_path, root_title, id_mindmap) → 扫描 + 读取 + Quill Delta + 同步 3. 将返回的摘要（total_nodes, descriptions_filled, errors）与 tree_scope 计数进行比较 4. 如果它们匹配且 errors 为空 → 注入验证。完成。 ``` - 仅读取 `.md`、`.markdown`、`.txt` 文件并转换为 Quill Delta - 大于 500 KB 的文件和非文本格式（`.docx`、`.pdf`、图像）会得到空白描述的节点 - 自动跳过隐藏文件和 VCS 目录（`.git`、`node_modules`、`__pycache__`） - **永远不要** 调用 `get_mindmap` 来验证注入 — 摘要 + `tree_scope` 计数足够 ### Messenger（4）— 机器人 API | 工具 | 描述 | |---|---| | `send_message` | 发送消息（针对或广播到所有对话） | | `get_messages` | 读取对话中的机器人消息 | | `update_message` | 更新机器人消息 | | `delete_message` | 删除机器人消息 | ### 活动 / 计划（9）— 机器人 API #### 高级工具（优先使用这些） | 工具 | 描述 | |---|---| | `create_assignment` | 使用友好参数创建任务（日期、小时、星期几）。内部构建 JSON | | `modify_assignment` | 修改现有的任务组。服务器标记墓碑，移除旧时段，创建新时段 | | `verify_assignment` | 读取活动并返回遥测报告（组、时段、一致性检查） | | `read_planning` | 读取给定年份的所有计划时段（用户 API）。唯一返回实际时段数据 | #### 低级工具（原始 JSON） | 工具 | 描述 | |---|---| | `list_activities` | 列出分配给机器人的活动 | | `get_activity` | 读取特定活动（完整元数据） | | `add_assignment` | 分配时间段（原始 `planning_list` + `recursive_group` JSON） | | `update_assignment` | 更新任务组（原始 JSON） | | `delete_assignment` | 删除任务组 | ### 用户 API（9）— index.php | 工具 | 描述 | |---|---| | `user_login` | 身份验证为 Atlas，存储会话令牌。如果设置了 `AXOMIND_WS_URL`，则自动启动 WebSocket 监听器 | | `user_renew_token` | 在令牌过期前 24 小时续期 | | `user_status` | 检查当前会话状态（本地，无 HTTP） | | `user_get_pending_invitations` | 列出发送给 Atlas 的待处理邀请 | | `user_accept_invitation` | 接受邀请 → 创建关系 + 1 对 1 对话 | | `user_refuse_invitation` | 拒绝邀请 | | `user_get_conversations` | 列出 Atlas 参与的所有对话 | | `user_send_message` | 在对话中发送消息作为用户（不是机器人） | | `user_poll_events` | 排空待处理的 WebSocket 事件（消息、邀请、思维导图同步） | ## Token 高效读取策略 MCP 提供 3 级读取策略以保持 AI 上下文小： 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` 在特定节点。 在守护进程模式下，`get_mindmap` 自动重定向到 `get_mindmap_summary` 以保护 Ollama 上下文。 ## 守护进程模式（自主，无 Hermes） 守护进程将 Atlas 连接到 Axomind 消息网络，无需 Hermes。它支持由 `AXOMIND_USE_HERMES` 控制的两种后端： - **Hermes 模式**（`true`）：持有 WebSocket 连接，缓冲事件。Hermes 通过 `user_poll_events` 轮询并响应。无需 Ollama。 - **Ollama 模式**（`false`）：使用本地 Ollama 模型处理传入消息（工具调用）。完全自主。 守护进程从 `.env` 文件读取凭证。路径按以下顺序解析： 1. `AXOMIND_ENV_FILE` 环境变量（显式 - 生产） 2. `~/.env`（开发备用） 3. CWD 中的 `.env`（开发备用） ⚠️ 生产环境的 `.env` **永远不会** 在源代码中硬编码 — 通过 `AXOMIND_ENV_FILE` 设置它，以便从公共存储库中不可发现。 ### 设置 1. 使用 `AXOMIND_*` 变量创建 `.env` 文件（参见 `.env.example`） 2. 安装 websockets：`uv pip install --system --break-system-packages websockets` 3. 在系统范围内设置 env 文件路径（见下文） 4. 启动：`python -m axomind_mcp.daemon` 或 `bash scripts/start_daemon.sh` 守护进程将： - 加载 `.env` 文件（来自 `AXOMIND_ENV_FILE` 或开发备用） - 验证所有必需变量 — 如果缺少任何变量，则显示清晰的错误 - 测试 Ollama 服务（仅 Ollama 模式）— 如果无法访问或缺少模型，则显示清晰的错误 - 测试用户登录 — 如果失败，则显示返回码错误 - 连接到 WebSocket 并开始监听 ### 会话管理（对话上下文） 在 Ollama 模式下，守护进程维护每个对话的对话上下文。没有它，每个传入消息都是孤立处理的 — AI 没有之前交换的记忆。 **生命周期：** 1. **会话开始** — 收到新消息。如果不存在活动会话，则加载缓存文件以恢复历史记录。如果不存在缓存，则开始新会话。 2. **会话活动** — 消息累积在内存中。Ollama 上下文由会话历史记录构建（滑动窗口，最后 N 条消息）。工具结果也存储在会话中。 3. **定期保存** — 每个 N 条消息，会话保存到缓存文件（崩溃保护）。始终保留完整历史记录。 4. **会话关闭** — 每个响应后启动超时计时器。如果在超时之前没有收到新消息，则关闭会话：完整对话保存到缓存记录，然后从内存中清除。 5. **会话恢复** — 对话中的下一个消息重新加载缓存。AI 从前一个交互恢复完整上下文。 缓存文件： - 本地存储在守护进程的文件系统（默认：`/tmp/axomind_conv_cache/`） - 每个对话一个 JSON 文件：`<conversation_id>.json` - 包含完整的消息历史记录（用户 + 助手 + 工具结果） - 无服务器交互 — 纯本地文件系统 - 1. **会话开始** — 新消息到达。如果没有活动会话，则加载缓存文件以恢复历史记录。如果没有缓存，则开始新会话。 2. **会话活动** — 消息累积在内存中。Ollama 上下文由会话历史记录构建（滑动窗口）。工具结果也存储在会话中。 3. **定期保存** — 每 N 条消息，将会话保存到缓存文件（崩溃保护）。始终保留完整历史记录。 4. **会话关闭** — 每次响应后启动超时计时器。如果在超时之前没有收到新消息，则关闭会话：完整对话保存到缓存，然后从内存中清除。 5. **会话恢复** — 相同的对话中的下一条消息重新加载缓存。AI 从前一个交互恢复完整的上下文。 AI 被指示在每次响应后自然询问“还有其他事情需要我帮助吗？”。如果用户不响应，会话将无声关闭。 **缓存文件：** - 本地存储在守护进程的文件系统上（默认值：`/tmp/axomind_conv_cache/`） - 每个对话一个 JSON 文件：`<conversation_id>.json` - 包含完整的消息历史记录（用户 + 辅助 + 工具结果） - 无服务器交互 — 纯粹本地文件系统 - 在守护进程重启后存活 **配置：** | 变量 | 默认值 | 描述 | |---|----|----| | `AXOMIND_CONV_CACHE_DIR` | `/tmp/axomind_conv_cache` | 会话缓存文件的目录 | | `AXOMIND_SESSION_TIMEOUT` | `300` | 会话关闭前的空闲超时时间（秒） | | `AXOMIND_MAX_SESSION_MESSAGES` | `30` | 发送到 Ollama 上下文的最大消息数（滑动窗口）。缓存保留完整的历史记录 | | `AXOMIND_PERIODIC_SAVE_INTERVAL` | `5` | 每 N 条消息将会话保存到缓存（崩溃保护） | ### 在 Debian 上设置 AXOMIND_ENV_FILE #### 选项 A — 系统范围（所有用户，所有服务） ```bash echo 'AXOMIND_ENV_FILE="/etc/axomind/.env"' | sudo tee /etc/environment.d/axomind-mcp.conf ``` 重启或重新登录后，变量将生效。所有进程（守护进程、systemd、shell）都会继承它。 #### 选项 B — 单个用户（shell 配置文件） ```bash echo 'export AXOMIND_ENV_FILE="/etc/axomind/.env"' >> ~/.bashrc source ~/.bashrc ``` #### 选项 C — 仅限 systemd 服务 ```ini # /etc/systemd/system/axomind-mcp.service [Service] Environment=AXOMIND_ENV_FILE=/etc/axomind/.env ExecStart=/usr/bin/python3 -m axomind_mcp.daemon ``` ```bash sudo systemctl daemon-reload sudo systemctl enable --now axomind-mcp ``` ### 环境变量优先级 操作系统环境变量 > `.env` 文件 > systemd `Environment=` 或 Hermes 配置文件 yaml 始终覆盖 `.env` 文件值。 ## 完整配置 ### 机器人 API（bot_api.php） | 变量 | 必需 | 描述 | |---|---|---| | `AXOMIND_BASE_URL` | ✅ | `bot_api.php` 的 URL（例如 `http://host/app/bot_api.php`） | | `AXOMIND_BOT_ID` | ✅ | 机器人 ID（来自 Axomind UI → 机器人管理） | | `AXOMIND_BOT_KEY` | ✅ | 机器人访问密钥 | | `AXOMIND_TIMEOUT` | ❌ | 秒为单位的 HTTP 超时（默认值：30） | ### 用户 API（index.php — Atlas 消息传递） | 变量 | 必需 | 描述 | |---|---|---| | `AXOMIND_KEY_PASS` | ✅ | 用户 API 调用共享密钥（KEY_PASS） | | `AXOMIND_USER_EMAIL` | ✅ | Atlas 用户邮箱 | | `AXOMIND_USER_PASSWORD` | ✅ | Atlas 用户密码 | | `AXOMIND_USER_TYPE_CLIENT` | ✅ | 客户端类型标识符（例如 `axomind_desktop`） | | `AXOMIND_ROUTE_PREFIX` | ✅ | 用户 API 路由前缀。在 `app/core/_main/config_server.php` → `SUFIX_ROUTE` 常量中找到 | | `AXOMIND_USER_BASE_URL` | ❌ | 覆盖用户 API 基 URL（默认为 `BASE_URL` 将 `bot_api.php` → `index.php`） | ### 守护进程模式 | 变量 | 必需 | 描述 | |---|---|---| | `AXOMIND_USE_HERMES` | ❌ | `true` = Hermes 处理 AI，守护进程 = WebSocket 仅。`false` = 守护进程使用 Ollama（默认值：`false`） | | `AXOMIND_OLLAMA_URL` | ✅（Ollama 模式） | Ollama API 端点（必须以 `/v1/chat/completions` 结尾） | | `AXOMIND_OLLAMA_MODEL` | ✅（Ollama 模式） | Ollama 模型标签（来自 `ollama list` 的确切标签，包括量化后缀） | | `AXOMIND_OLLAMA_TIMEOUT` | ❌ | Ollama 请求超时时间（秒）（默认值：120） | | `AXOMIND_WS_URL` | ✅（守护进程） | 实时事件的 WebSocket URL（例如 `ws://host:8080/`） | | `AXOMIND_DAEMON_SYSTEM_PROMPT` | ❌ | 覆盖默认守护进程系统提示（仅 Ollama 模式） | 话管理（ Ollama 模式） | 变量名 | 默认值 | 描述 | |---|---|---| | `AXOMIND_CONV_CACHE_DIR` | `/tmp/axomind_conv_cache` | 会话缓存文件的目录（本地文件系统） | | `AXOMIND_SESSION_TIMEOUT` | `300` | 会话关闭前的空闲超时时间（秒） | | `AXOMIND_MAX_SESSION_MESSAGES` | `30` | 发送到 Ollama 上下文的最大消息数（滑动窗口）。缓存保留完整的历史记录 | | `AXOMIND_PERIODIC_SAVE_INTERVAL` | `5` | 每 N 条消息将会话保存到缓存（崩溃保护） | ⚠️ `AXOMIND_ROUTE_PREFIX` 是 **必填** 的 —— 没有它，用户 API 调用（登录、消息传递、邀请）会得到 404 错误，因为 URL 构建为 `{USER_BASE_URL}?rt={ROUTE_PREFIX}{route}`。前缀是服务器端的共享密钥，防止未经授权的路由访问。 ## Hermes 配置 在 `~/.hermes/config.yaml` 中： ```yaml mcp_servers: axomind: command: "python3" args: ["-m", "axomind_mcp.serveur.server"] env: # 机器人 API AXOMIND_BASE_URL: "http://xx.xx.xx.xx/app/bot_api.php" AXOMIND_BOT_ID: "<your_bot_id>" AXOMIND_BOT_KEY: "your_key_access" # 用户 API AXOMIND_KEY_PASS: "your_keypass" AXOMIND_USER_EMAIL: "your_bot_email" AXOMIND_USER_PASSWORD: "your_bot_password" AXOMIND_USER_TYPE_CLIENT: "axomind_desktop" AXOMIND_ROUTE_PREFIX: "<your_route_prefix>" # 守护进程模式 AXOMIND_OLLAMA_URL: "http://your-ollama-host:11434/v1/chat/completions" AXOMIND_OLLAMA_MODEL: "your_model_tag" AXOMIND_OLLAMA_TIMEOUT: "120" AXOMIND_WS_URL: "ws://your-server:8080/" # Python PYTHONPATH: "/path/to/axomind-mcp/src" workdir: "/path/to/axomind-mcp" ``` ⚠️ 所有 `env` 值必须是字符串（YAML 解析 `72` 为整数 → pydantic 拒绝它）。 ⚠️ `PYTHONPATH` 是必需的 —— `workdir` 设置了当前工作目录，但没有设置 Python 导入路径。 ⚠️ `AXOMIND_ROUTE_PREFIX` 是所有用户 API 工具（登录、消息传递、邀请）所必需的。没有它，守护进程和用户工具会收到 404 错误。 要将缺少的环境变量添加到现有的 Hermes 配置中： ```bash hermes config set mcp_servers.axomind.env.AXOMIND_ROUTE_PREFIX "<your_route_prefix>" ``` 重启 Hermes → 工具将自动发现，前缀为 `mcp_axomind_`。 ## 测试 ```bashPATH=src python -m pytest tests/ -v ``` 178 个测试 —— 模拟 httpx，无需网络调用 Axomind 服务器。 ## 架构 ``` src/axomind_mcp/ ├── __init__.py ├── _common.py — Fast 实例，环境配置post() / _post 助手，节点默认值 _planning.py — 个工具计划/活动（机器人 API） ├── _ollama_tools.py — 从 @mcp.tool() 反射自动生成的 Ollama 工具定义 ├── _doctrines.py — 守护进程系统 ├── daemon.py — 自主守护进程（Hermes 或 Ollama 模式） ├── messaging/ — 消息传递工具 + 会话管理 │ ├── __init__.py │ ├── _messenger.py — 4 个工具消息传递（机器人 API） │ ├── _user.py — 9 个工具用户（用户 API，WebSocket 监听器自动启动） │ ├── session_context.py — SessionContext 数据类（内存中的会话状态） │ ├── session_cache.py — 基于文件的本地会话缓存（备份 + 恢复） │ └── session_manager — 会话生命周期：活动会话、计时器、上下文构建 ├── serveur/ │ ├── __init__.py │ ├── server.py — 入口点标准输入/输出，注册 │ └── _ws_listener.py — WebSocket 监听器（混合 Hermes + 守护进程） ├── mindmap/ │ ├── __init__.py │ ├── _mindmap.py — 10 个工具思维导图（机器人 API） │ ├── node_operations.py — 共享算法：更新/删除/修补节点，循环检测，样式传播 │ └── config_layout_mindmap.py — 节点扩展，验证，自动定位 └── tools/ __init__.py ├── _file_reader.py — 按读取文件 → Quill Delta ├── md_to_quill_delta.py — Markdown → Quill Delta 转换器 └── _tree.py — 3 个工具树（本地 + 机器人 API） ``` ## 安全 - MCP 不接触数据库或包含任何业务逻辑 - 凭证来自环境变量（从不硬编码） - Axomind 服务器无法分辨出它是 MCP —— 它看到的是正常的 bot_api 请求 - 树工具（本地文件系统扫描）被排除在守护进程之外 —— 生产环境中没有攻击面 - `.env` 文件路径通过 `AXOMIND_ENV_FILE` 设置 —— 在公共存储库中无法发现 ## 许可证 专有 —— 请参阅 [LICENSE](LICENSE)。版权所有 © 2025 VEZZANI Sébastien。保留所有权利。 <div align="center"> <a href="https://sebastien-vezzani.xyz/" target="_blank"><img src="https://img.shields.io/badge/Portfolio-3423A6?style=for-the-badge&logo=firefox-browser&logoColor=white" alt="Link to Portfolio"/></a> </div>