wiki-qx-mcp

内网 Confluence / Wiki MCP（stdio only），对齐本仓 export-wiki-bundle 的鉴权与地址约定。

环境变量

| 变量 | 必填 | 说明 | |------|------|------| | WIKI_BASE_URL | 是 | Wiki 根地址，本仓默认 http://wiki.ops.zocf | | CONFLUENCE_WIKI_TOKEN | 是 | Confluence PAT（Bearer） | | WIKI_LOG_LEVEL | 否 | debug / info / warn / error，默认 info |

Token 解析顺序（与 export-wiki-bundle 一致）：

1. CONFLUENCE_WIKI_TOKEN / WIKI_TOKEN 环境变量
2. 仓库根目录 confluence-wiki.local.env（已 gitignore）

MCP 配置

Cursor / Claude Code（推荐发布后用 npx）

"wiki": {
  "command": "npx",
  "args": ["-y", "[email protected]", "--stdio"],
  "env": {
    "WIKI_BASE_URL": "http://wiki.ops.zocf",
    "CONFLUENCE_WIKI_TOKEN": "<你的PAT>",
    "WIKI_LOG_LEVEL": "info"
  }
}

仓内构建（未发布 / 本地开发）

"wiki": {
  "command": "node",
  "args": ["tools/wiki-qx-mcp/dist/cli.js", "--stdio"],
  "env": {
    "WIKI_BASE_URL": "http://wiki.ops.zocf",
    "CONFLUENCE_WIKI_TOKEN": "<你的PAT>",
    "WIKI_LOG_LEVEL": "info"
  }
}

路径相对工作区根；Windows 可用绝对路径。

使用本机 token 文件（不写进 mcp.json）

"wiki": {
  "command": "node",
  "args": ["C:\\Users\\<you>\\IdeaProjects\\mobile\\tools\\wiki-qx-mcp\\dist\\cli.js", "--stdio"],
  "env": {
    "WIKI_BASE_URL": "http://wiki.ops.zocf",
    "WIKI_LOG_LEVEL": "info"
  }
}

启动时会自动读仓库根 confluence-wiki.local.env（若 cwd 为 mobile 项目）。

工具

| Tool | 读/写 | 用途 | |------|------|------| | wiki_get_system_info | 读 | 连通性 + 当前用户 | | wiki_list_spaces | 读 | 列出空间 | | wiki_search_pages | 读 | CQL 搜索页面 | | wiki_get_page | 读 | 按 pageId 取正文 | | wiki_get_page_by_title | 读 | 按 space + 标题取页 | | wiki_get_page_children | 读 | 子页面列表 | | wiki_list_page_attachments | 读 | 附件元数据 + 下载 URL | | wiki_download_attachment | 读 | 附件下载到本地 temp（给 vision 用） | | wiki_list_page_comments | 读 | 页面评论列表 | | wiki_create_page | 写 | 新建页面 | | wiki_update_page | 写 | 更新标题/正文 | | wiki_upload_attachment | 写 | 上传附件（本地路径或 base64；同名默认覆盖；默认写入正文可点下载链接 embedInBody=true） | | wiki_upload_easymind | 写 | 上传 EasyMind：强制 application/namymap+json + 同名 .png + 可选 easymind 宏；支持 EasyMind JSON / XMind Zen | | wiki_embed_easymind | 写 | 仅插入 easymind 宏（附件已存在时） | | wiki_add_page_comment | 写 | 添加评论 | | wiki_delete_page | 写 | 删除页面（慎用） |

EasyMind 上传契约（wiki_upload_easymind）

| 项 | 要求 | |----|------| | 附件名 | = 宏参数 name，无扩展名 | | MIME | 必须 application/namymap+json（octet-stream 会编辑器报错） | | 预览 | 同名 {name}.png（image/png）；占位图可先传，编辑器 Save 后会刷新 | | JSON | formatVersion + rootTopic.subtopics；topic 哨兵：note/image="notDefined"，label=[]，sideChildren/floatingProperties={} | | 保真 | 不保证 XMind 主题色/自由定位/图片/关系线/折叠；Skill 也无法保证——这是转换上限不是放错层 |

输入：filePath（.json / .xmind）或 documentJson / contentBase64。返回含 mediaTypeOk；为 false 时工具 isError=true。

与 Atlassian 官方 Rovo MCP 对比：本包仅覆盖 内网 Confluence 页面读写子集，不含 Jira/Bitbucket/Compass，也不含 Cloud OAuth。

开发与验证

cd tools/wiki-qx-mcp
npm install
npm run build
# Client 直连 Wiki API：
npm run smoke
# 经 MCP stdio（官方 SDK Client）走工具冒烟：
npm run mcp-smoke
# 清理残留冒烟页（需目标空间 DELETE 权限）：
npm run cleanup-smoke -- test

冒烟默认在 test 空间做「建页 → 更新 → 上传附件 → 评论 → 删页」闭环（WIKI_SMOKE_SPACE 可改）。部分空间（如 MOBILE）可能允许建页但不允许删页（HTTP 403）；无删权时清理脚本会失败，可将页标题标为 [TO-DELETE] 后请有权限的同学删除。

wiki_delete_page 会先删除子评论再删页面；需目标空间的删除权限。

已写入项目 .cursor/mcp.json 的 wiki 项（token 从仓库根 confluence-wiki.local.env 自动读取）。Cursor 需 Reload MCP / 重启 后才会出现 wiki 工具。

安全

• 仅 stdio；出站 HTTP 限制在 WIKI_BASE_URL 的 /rest/api/*
• 日志中 token 脱敏
• 勿将 PAT 提交 Git