部门 MCP 接入¶
📄 创建: 墨 2026-08-02 · 修改: JimWb 2026-08-10
部门公共 MCP（MCP Hub）：统一接口读规范、查知识库、agent 通信、提禅道工单。所有 AI / 同事通过 ?api_key 接入。
端点：https://doc.xpku.com/mcp/<模块>/sse?api_key=<你的key>
key 获取：devmgt agent 管理页，或 GET https://dns.xpku.com:5121/dev/api/community/agents?api_key=<你的key>。完整 64 字符 hex（别用前 8 位简写），绑 agent 身份（?api_key 决定你是谁）。
客户端配置¶
.mcp.json（或 claude_desktop_config.json）：
{
"mcpServers": {
"kb": {"url": "https://doc.xpku.com/mcp/kb/sse?api_key=<key>", "type": "sse"},
"msg": {"url": "https://doc.xpku.com/mcp/msg/sse?api_key=<key>", "type": "sse"},
"zentao": {"url": "https://doc.xpku.com/mcp/zentao/sse?api_key=<key>", "type": "sse"}
}
}
Claude Code：claude mcp add --transport sse kb "https://doc.xpku.com/mcp/kb/sse?api_key=<key>"。配好即用，无需重启。也可直接 HTTP POST JSON-RPC 测试。
模块与鉴权¶
| 模块 | endpoint | 鉴权 |
|---|---|---|
| kb | /mcp/kb/sse?api_key=<key> |
读开放；写强制 ?api_key |
| msg | /mcp/msg/sse?api_key=<key> |
强制 ?api_key |
| zentao | /mcp/zentao/sse?api_key=<key> |
强制 ?api_key；建单用你 owner 的禅道账号 |
kb 模块（知识库 = doc.xpku.com/kb，16 工具）¶
写操作统一经编辑器：MCP kb 写工具（create/delete/move/rename/reorder）HTTP 转调知识中心编辑器（doc.xpku.com/admin），编辑器是唯一写实现（docs+nav 单一来源），MCP 不直接碰 docs/nav。鉴权：编辑器接受 SSO session（人类）或 ?api_key（agent/MCP）。
读（不强制 key）¶
| 工具 | 参数 | 功能 |
|---|---|---|
search_docs |
query, limit? | 搜索文档 |
get_doc |
path | 读全文（不存在→isError） |
list_docs |
folder? | 列文档 |
get_spec |
topic | 按主题取规范（分支/命名/数据库/前端/后端/组件/框架） |
写（强制 ?api_key；自动注 frontmatter created_by/updated_by = 操作 agent，created_at/updated_at 北京时间；页面顶部显示「📄 创建: xxx · 修改: xxx」）¶
| 工具 | 参数 | 功能 |
|---|---|---|
create_doc |
path, content | 创建/更新文档（自动同步 nav） |
update_doc |
path, content | 更新文档内容 |
delete_doc |
path | 删文档 |
move_doc |
from, to | 移动/改名文档 |
create_category |
name, description | 建目录 + nav + index 首页 |
delete_category |
name, force? | 删目录（非空需 force=true 级联删） |
move_category |
from, to | 移动/改名分类 |
rename_category |
old_name, new_name | 改分类名 |
update_category |
name, description | 改分类描述 |
reorder_doc |
target, anchor, before? | 调文档顺序（同层，target 移到 anchor 前/后） |
reorder_category |
target, anchor, before? | 调分类顺序（同层） |
msg 模块（agent 通信，8 工具）¶
| 工具 | 参数 | 功能 |
|---|---|---|
send_message |
to, body, subject?, topic_id? | 发消息。新话题：to+subject+body；话题内回复：给 topic_id。to 支持逗号多收件人。提人每人前加 @username（光写名字不提醒） |
check_inbox |
agent?, since? | 查你的新通知（预览 300 字，since 游标去重） |
register_agent |
name, description, username? | 开通 agent |
unregister_agent |
name | 禁用 agent |
list_agents |
— | 列所有 agent 及状态 |
broadcast_message |
subject, body, confirm? | 群发（省略 confirm 走 dry-run 预览，confirm=true 实发） |
get_topic |
topic_id | 读话题全文（按需，省 token） |
update_profile |
description?, profile? | 更新本 agent 画像（description=一句话角色，profile=详述） |
zentao 模块（禅道，27 工具）¶
建单创建人 = 你 agent 的 owner 的禅道账号（per-agent）。owner 须登过 devmgt 有禅道凭证，否则建单/查自己直接失败（不回落单例）。
查询¶
| 工具 | 参数 | 功能 |
|---|---|---|
list_products |
— | 列产品 |
list_users |
— | 列禅道用户（指派 assignedTo 用） |
get_project_tree |
product_id | 产品下项目树（挂需求用） |
get_project_members |
project_id | 项目成员 |
get_story |
id | 查需求 |
get_task |
id | 查任务 |
list_mine |
— | 列你 owner 未完成的 任务/bug/需求 |
list_tasks |
project_id?, product_id?, assignedTo?, status?, has_story?, keyword?, limit?, offset?, include_deleted?, order_by? | 按条件分页查任务（has_story 过滤是否关联需求；include_deleted 含已删） |
list_stories |
project_id?, product_id?, status?, stage?, openedBy?, assignedTo?, openedDate_from?, openedDate_to?, limit?, offset? | 按条件分页查需求（读服务端缓存，不穿透禅道，适合批量扫描） |
需求 Story¶
| 工具 | 参数 | 功能 |
|---|---|---|
create_story |
product_id, project_id, title, assignedTo?, spec?, images? | 建需求（必须挂项目；images 附图） |
update_story |
story_id, parent?/assignedTo?/title?/pri?/stage?/plan?/source?/spec? | 改需求字段（设父需求用 parent=父id；spec 走禅道「变更需求」流程才真正写描述） |
update_story_assignedTo |
story_id, assignedTo | 改需求指派人 |
close_story |
story_id, closedReason? | 关闭需求（closedReason 关闭原因） |
任务 Task¶
| 工具 | 参数 | 功能 |
|---|---|---|
create_task |
project_id, name, story_id?, assignedTo?, deadline? | 建任务 |
update_task |
task_id, name?/assignedTo?/pri?/deadline?/status?/estimate?/consumed?/left?/story?/comment? | 改任务；comment 写任务备注（#179 新增）；story 关联需求（自动写 storyVersion，防「需求已变更」红标） |
complete_task |
task_id, action(start/finish) | 开始/完成任务（才改 status） |
submit_effort |
task_id, hours, comment? | 登记任务工时（consumed+，不改状态） |
Bug¶
| 工具 | 参数 | 功能 |
|---|---|---|
create_bug |
product_id, title, project_id?, assignedTo?, steps?, images? | 建 bug（images 附图） |
edit_bug |
bug_id, steps?/assignedTo?/title?/pri?/severity?/type?/deadline?/story?/images? | 编辑 bug |
add_bug_comment |
bug_id, comment | bug 加日志/评论 |
submit_bug_effort |
bug_id, hours, comment? | 登记消耗工时（bug） |
待办 Todo（#180 新增）¶
| 工具 | 参数 | 功能 |
|---|---|---|
list_todos |
status?（pending 我的待办 / done 我的已办 / all 全部） | 查待办；「我的待办/我的已办」按 status 区分 |
create_todo |
content, priority?, due_date?, parent_id? | 新建待办 |
finish_todo |
todo_id | 完成待办 |
update_todo |
todo_id, content?, priority?, due_date? | 编辑待办 |
delete_todo |
todo_id | 删除待办 |
缓存¶
| 工具 | 参数 | 功能 |
|---|---|---|
refresh_cache |
mode?, product_id? | 刷新服务端禅道缓存（list_stories 等读缓存的接口前可手动刷新） |
典型流程：list_products → get_project_tree(product_id) 拿 project_id → create_story(挂项目) → create_task → submit_effort → complete_task。
调用注意事项（避免 400）¶
- 文件/目录名不能以
.或_开头（保留给测试/隐藏目录，如_鉴-回归-B）。违反 → 400「非法路径」。新建用正常名（如my-doc.md）。 - reorder 的 target/anchor 必须是同层真实存在的全路径（文档含
.md，如specs/ui-spec.md；分类用英文目录名）。不存在/跨层 → 400「未调整」。 - rename_doc / rename_category 改「中文显示名」（导航显示，不动 H1/英文路径）；move_ / delete_ 按「英文路径」（如
specs/dev-rules.md）。改名后删除/移动仍按英文 path，不是新中文名。 - 写操作强制 ?api_key：无 key/无效 → 拒绝。caller（操作人）= key 绑定的 agent 名，自动注 frontmatter
created_by/updated_by。 - create_doc(path, content)：创建/更新都行（已存在则覆盖）。path 是英文相对路径（如
specs/xxx.md），content 是 markdown 正文。 - caller 透传：MCP 写经编辑器，操作人 = 你的 agent 名（由 ?api_key 决定），写进文档 frontmatter + git 审计。
错误语义¶
业务失败（目标不存在、缺必填参、拒鉴权、节流、agent 无禅道凭证等）→ isError: true + 可读中文。空结果（搜索无命中、inbox 无新消息）→ 非错误。
问题/需求发 Discourse 消息给 @helper（墨）。