Munplanum MCP Server

Munplanum 任务管理系统的 MCP (Model Context Protocol) 服务端实现。它允许 AI Agent（如 Cursor, Windsurf, Claude Desktop）直接管理 Munplanum 中的任务。

核心特性

• 智能聚焦：get_focused_tasks 工具提供任务滑动窗口，在保持上下文的同时最大程度节省 Token。
• 长短期记忆增强：集成 Mem0，支持 L1 (详情增强)、L2 (聚焦增强)、L3 (搜索增强) 三级 RAG 检索。
• Token 优化：自动过滤冗余字段并压缩 JSON 响应。
• 上下文裁剪：自动裁剪过期的 agentContext，减少干扰。
• 树形嵌套：完整支持父子任务层级管理。

快速开始

# 进入目录并安装
cd munplanum-mcp
pnpm install

# 编译代码
pnpm run build

# 运行测试
pnpm test

# 本地测试启动
node dist/index.js

配置说明

通过环境变量或根目录下的 .env 文件进行配置。推荐参考 mcp.example.json 进行配置。

基础参数

• MUNPLANUM_CORE_URL: Munplanum Core 服务地址 (默认: http://localhost:3000)
• MUNPLANUM_API_KEY: 用户的 API Key (必填)
• MUNPLANUM_PROJECT_SLUG: 工作项目标识符 (必填)

日志参数

• MCP_LOG_FILE: MCP 主日志文件路径 (默认: ./logs/mcp-main.log)
• LOG_LEVEL: 日志级别 (debug, info, warn, error)
• LOG_FORMAT: 日志格式 (text, json)

Mem0 增强参数 (可选)

• MEM0_INTEGRATION_ENABLED: 是否启用 Mem0 集成 (true/false)
• MEM0_PYTHON_PATH: Python 解释器路径 (需安装了相关依赖的 venv)
• MEM0_SERVER_SCRIPT: Mem0 MCP Server 启动脚本路径
• MEM0_PROFILE: 配置 Profile 名称
• MEM0_LOG_FILE: 桥接服务日志路径
• MEM0_DEFAULT_USER_ID: Mem0 系统内部默认用户 ID（传递给 Mem0 子进程）
• MEM0_USER_ID: munplanum-mcp 系统默认用户 ID（Agent 不传 userId 参数时使用）
• CLOUD_IP: 后端数据库/服务 IP

用户 ID 说明：

• MEM0_DEFAULT_USER_ID：这是传递给 Mem0 子进程的环境变量，Mem0 内部使用。当调用 Mem0 工具时不传 user_id 参数，Mem0 系统会使用这个默认值（通常设为 global）。
• MEM0_USER_ID：这是 munplanum-mcp 自己使用的默认用户 ID。当 Agent 调用 get_task_detail、get_focused_tasks、search_tasks 时不传 userId 参数，系统会使用这个值传递给 Mem0 进行记忆检索。

多用户/多项目隔离：

在多用户或多项目场景下，建议：

1. 设置 MEM0_USER_ID 为项目特定的标识（如 project-alpha）
2. Agent 在需要切换记忆空间时，主动传递 userId 参数

测试说明

本项目使用 vitest 进行测试。

# 运行单元测试
pnpm test

Mem0 集成测试

为了方便进行包含记忆状态的集成测试，Mem0BridgeService 提供了直接调用的方法（不暴露为 MCP Tool）：

• addMemory(text, userId, metadata): 添加一条测试记忆。
• getMemories(userId): 获取记忆列表。
• deleteAllMemories(userId): 清空特定用户的记忆。

在测试用例中，可以通过导入 mem0Bridge 实例来预置测试数据：

import { mem0Bridge } from './services/mem0-bridge.service.js';

// 测试前先清空并添加指定记忆
await mem0Bridge.deleteAllMemories('test-user');
await mem0Bridge.addMemory('用户的偏好是使用 TypeScript', 'test-user');

在 Cursor / Claude Desktop 中使用

添加新的 MCP Server 配置：

• Command: node
• Args: /绝对路径/到/munplanum-mcp/dist/index.js
• Env: 设置上述环境变量

发布说明

本项目配置了自动化发布流程：

# 1. 确保代码已编译并测试通过
pnpm run build
pnpm run test

# 2. 执行发布流程 (使用 release-it)
# 它会自动更新版本号、生成 Changelog、打 Tag 并发布到 NPM
pnpm run release

注意事项：

• 发布前请确保已通过 npm login 登录到正确账号。
• 发布采用 ESM 格式，入口文件为 dist/index.js。
• bin 字段已配置，安装后可使用 npx munplanum-mcp 直接运行。