Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-project-mcp get the project briefing and check for stale, blocked, or unowned tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
跨 agent 项目管理 MCP Server：任何支持 MCP 的 agent（Claude Code、Cursor、Windsurf、Codex、Gemini CLI 等）共用同一套工具维护项目状态，解决对话中断、各 agent 格式各异、文件散落的问题。
除了 MCP，还能直接用 CLI（apm）操作，人和 agent 走同一套读写逻辑。
每个被管理的项目根目录下自动生成：
<项目>/.apm/
├── PROJECT.md # 目标、创建时间
├── DECISIONS.md # 决策日志（时间/agent/标题/决定/理由）
├── TASKS.md # 唯一任务清单（todo/doing/done/blocked）
├── handoff/ # 每次会话结束必须写的交接记录
├── .gitignore # 内容为 .lock，避免把残留锁文件提交进 Git
└── .lock # 写操作时的进程锁（自动创建并删除，可安全忽略）纯 Markdown，可直接进 Git 版本管理，无数据库、无外部服务。
TASKS.md 里有一行 <!-- next-id: N --> 记录任务 id 高水位，get_briefing 会自动隐藏它。
Related MCP server: Baton
旧版（单文件 server.py）写出的 .apm/ 目录可直接继续用，无需迁移：老任务行原样保留，任务 id 从最大 id 往后接，第一次写入时自动补上 <!-- next-id: --> 标记。
核心（CLI + 可视化界面）零第三方依赖，只用标准库：
pip install -e . # apm init / briefing / task-* / decide / handoff / insights / ui
pip install -e ".[mcp]" # 额外装上 fastmcp，才能用 apm serve 跑 MCP server
pip install -e ".[dev]" # 再加 pytest + ruffapm serve 是唯一需要 fastmcp 的命令；其余命令在没装 fastmcp 的环境里照常可用。
工具 | 参数 | 用途 |
|
| 创建 |
|
| 会话开场：目标 + 任务 + 最近决策 + 最新交接 |
|
| 追加一条决策记录 |
|
| 新增任务，返回新 id |
|
| 改状态，仅接受 |
|
| 删除任务，id 不复用 |
|
| 写会话交接记录 |
|
| 检查项目：过期任务、长期 doing、阻塞漂移等，每条带出处 |
apm -C <项目路径> init "my-app" "把登录页做完"
apm -C <项目路径> task-add "接入 SSO" --agent codex
apm -C <项目路径> task-update T001 doing
apm -C <项目路径> decide "选数据库" "sqlite" "部署简单" --agent codex
apm -C <项目路径> briefing
apm -C <项目路径> handoff --agent codex --done "登录页" --next "接 SSO" --blockers none
apm -C <项目路径> task-remove T001
apm -C <项目路径> insights # 检查项目有没有真实问题
apm serve # 以 stdio 方式启动 MCP server
apm ui # 打开浏览器看板apm insights 或 MCP 工具 get_insights 会从 .apm/ 里算出下面这些事实。每一条都带「出处」，指向造成它的那一行或那个文件；没有出处的结论不会输出。全部阈值可用参数覆盖。
code | 级别 | 触发条件 | 默认阈值 |
| 中/高 | todo/doing 任务最后更新距今过久 | 7 天（超 2 倍升为高） |
| 中 | 任务挂在 doing 太久 | 3 天 |
| 中 | blocked 任务创建至今太久 | 5 天 |
| 高 | 有 blocked 任务，但最新交接写 | — |
| 高 | 最新交接说有阻塞，但任务表里没有 blocked | — |
| 中 | 还有未完成任务，但最新交接距今太久 | 3 天 |
| 低 | 任务没有任何 agent 归属 | — |
| 低 | 交接里引用的任务 id 已不存在 | — |
| 低 | id 高水位远高于现存任务数（删过很多） | 差 4 个 |
| 低 | 什么都没有 | — |
设计约束：不猜意图。唯一的自由文本检查是把交接里的 T### 当字面 id 去比对，匹配不上就报「引用了不存在的任务」，不会去猜它想说什么。也不打分、不预测、不给建议。
apm insights # 人类可读，有高危项时退出码 1（可直接进 CI）
apm insights --json # 机器可读
apm insights --stale-days 3 # 覆盖阈值MCP 侧：get_insights(project_root, now_iso="") 返回同样的 summary + findings。now_iso 可注入分析时间，便于做可复现的检查。
顶部一行结论：严重度配色 + 「高 N · 中 N · 低 N」+ 最需要处理的那条。
只把高危项直接摊开，中低危项收在「逐条展开」里，每条带出处。
任务卡片默认折叠：一行 T002 · codex · 今天 · 标题，点击才展开创建/更新时间和状态按钮（拖拽卡片仍然直接改状态）。
决策和历史交接按天分组，每组一个默认折叠的 <details>，组内最多渲染 8 条，其余点「展开其余 N 条」——几百条交接也不会卡。
apm ui # 打开浏览器看板（自动挑空闲端口）
apm ui --port 8787 # 指定端口
apm ui --no-browser # 不自动开浏览器看板把 .apm/ 渲染成：顶部一行检测结论、任务看板（可拖拽改状态）、决策时间线、最新/历史交接、增删改任务与写决策/交接的表单。所有改动都走同一套 apm.core 写接口，所以和 CLI、MCP 工具共享同一份文件与校验；看板、CLI、其它 agent 可以同时在线。
默认视图刻意做得很短：一行结论 + 折叠的任务卡片 + 按天分组的折叠历史。想看细节时再点开，长列表分块加载。
实时更新：走 SSE（/api/events）。服务端监听 .apm/ 下文件的 mtime+size 变化，另一个进程里的 agent 或你手敲的 apm task-add 一落盘，页面 ~350ms 内自动更新，不用刷新。右上角显示「实时」还是「轮询」——流建立失败会自动退回 5 秒轮询，功能不减。
前端是 vendored 进仓的 preact + htm（约 16KB，零构建、零 npm 依赖、零远程请求），时间线是内联 SVG。
安全边界（本地 HTTP 写接口，务必了解）：
只绑 127.0.0.1，不监听任何外部地址。
每次启动生成一次性 token，每个请求都必须带（URL 上的 ?t= 或 X-APM-Token 头），token 用常量时间比较。
Host 头必须是回环地址，否则 403 —— 这挡住 DNS rebinding。
不发任何 Access-Control-* 头，网页无法驱动它。
CSP 用每响应随机 nonce，且不含任何远程域名：页面引用的是仓内 vendored 的 preact/htm，时间线是内联 SVG，断网也完整可用。
apm ui 是前台进程，Ctrl-C 停止。
Claude Code / Cursor / Windsurf 的 MCP 配置里加：
{
"mcpServers": {
"agent-project-manager": {
"command": "python",
"args": ["-m", "apm", "serve"],
"cwd": "C:\\path\\to\\agent-project-mcp"
}
}
}仓库根目录的 server.py 是等价的兼容入口，老配置指向它仍可用：
"args": ["C:\\path\\to\\agent-project-mcp\\server.py"]注意：server.py 只在用源码 checkout（或 pip install -e .）时存在。用 pip install 装 wheel 时该文件不进包，MCP 配置应改用 "args": ["-m", "apm", "serve"] 或直接调用 apm serve。
本地调试用 inspector：
fastmcp dev apm/mcp_server.py开工前先调 get_briefing，不基于对话记忆假设项目状态。
改变方向前先 log_decision，再动手。
任务状态变化立即 add_task / update_task / remove_task。
会话结束必须 write_handoff（done / next / blockers）。
产物文件一律按既有目录结构存放，不自造新目录。
写操作走 .apm/.lock 进程锁，多个 agent 同时写不会互相覆盖；读取（get_briefing）也取同一把锁，避免 Windows 上读句柄让并发写失败。
先写临时文件再 os.replace 原子替换，中途失败保留原文件；PermissionError（Windows 共享冲突）自动重试。
任务 id 单调递增（TASKS.md 里的 <!-- next-id: N --> 高水位），删除后不复用。
标题里的 | 和 & 会被转义，不会破坏 Markdown 表格。
锁等不到（进程被强杀留下残留锁）时报 TimeoutError，CLI 输出 apm: ... 并返回退出码 1，不会挂死；删掉 .apm/.lock 即可恢复。
pip install -e ".[dev]"
pytest
ruff check apm server.py testsdev 依赖里含 pytest 与 ruff。裸 pytest 也行，因为 pyproject.toml 的 pythonpath = ["."] 让测试不依赖已安装。
This server cannot be deployed
Project management shared by people and AI agents, with persistent project state through MCP.
Project management MCP for AI agents with safe task reads and writes.
Shared project wiki for AI agents: read and write pages, next actions, and activity logs over MCP.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
