# Confluence Wiki MCP Server

## 项目简介

面向 macOS 的 Confluence Wiki 内容获取 MCP 服务器，通过托管 Chrome Profile 自动管理认证，无需手动配置 Cookie。

## 功能

- 获取 Confluence Wiki 页面正文，支持 Markdown、HTML 和纯文本格式
- 按关键词检索 Wiki 内容，支持限定 Space 和标题搜索
- 获取页面附件、评论、引用和资源列表
- 聚合获取完整需求证据包（上下文、评论、引用、资产）
- 托管 Chrome Profile 自动登录，无需手动复制 Cookie
- Cookie 凭据值仅作为 HTTPS Cookie 请求头附加到精确源 `https://wiki.imgo.tv`（含同源重定向），永不进入日志、错误信息、认证状态/快照或 MCP 响应

## 系统要求

- macOS
- Node.js 18.17 及以上
- Google Chrome（已安装）

## 安装

```bash
npm install -g confluence-wiki-mcp-server
```

安装后可通过 `confluence-wiki-mcp` 命令使用。

## 首次登录

```bash
confluence-wiki-mcp auth login
confluence-wiki-mcp auth status
```

首次运行打开独立的本地 Chrome Profile，完成一次交互式 Wiki 登录。后续 MCP 进程自动重用会话，正常工具调用不会打开可见浏览器。认证仅使用托管 Chrome Profile，不需要也不支持通过环境变量或文件配置凭据。

```bash
confluence-wiki-mcp auth logout --confirm
```

登出需要 `--confirm` 确认，仅删除托管的标记 Profile。

## MCP 配置

```json
{
  "mcpServers": {
    "wiki-imgo": {
      "type": "stdio",
      "command": "confluence-wiki-mcp",
      "args": []
    }
  }
}
```

此配置适用于 cc-switch 导入。

## 工具

| 工具 | 说明 |
|---|---|
| `fetch_wiki_page` | 获取指定 Confluence Wiki 页面并返回 Markdown、HTML 或纯文本正文 |
| `search_wiki` | 按关键词检索 Confluence Wiki，返回标题、pageId 和页面 URL |
| `get_wiki_attachments` | 列出指定 Confluence 页面附件，适合查找原型图、截图等文件 |
| `wiki_health_check` | 返回本地托管认证状态并列出可用工具，不访问网络 |
| `get_wiki_page_context` | 获取 Wiki 页面证据上下文：正文、标题结构、表格、链接、图片、删除线和不确定关键词信号 |
| `get_wiki_comments` | 获取 Confluence 页面评论列表，返回评论正文、作者、时间和 evidence signals |
| `get_wiki_references` | 获取 Wiki 页面引用的其他页面链接，可选抓取被引用页面的标题和摘要 |
| `get_wiki_assets` | 列出 Wiki 页面的内嵌图片和附件，返回 URL、媒体类型和文件大小 |
| `download_wiki_asset` | 下载 Wiki 附件或图片到本地目录。仅支持 wiki.imgo.tv 域名 |
| `get_wiki_requirement_bundle` | 聚合获取 Wiki 页面的完整 evidence bundle：上下文、评论、引用、资产和权限问题 |
| `wiki_auth_login` | 打开专属 Chrome Profile 进行交互式 Wiki 登录 |
| `wiki_auth_status` | 探测并报告托管认证状态，不返回凭据值 |
| `wiki_auth_logout` | 登出并删除托管 Profile，需要 `confirm=true` 确认 |

## 使用规范

- 不得在日志、异常或 MCP 响应中记录或输出凭据信息。
- `wiki_health_check` 为本地检查，不访问网络，不探测服务端。
- `wiki_auth_status` 可主动探测 Profile 状态，但返回的快照永远不含凭据值。
- 登出必须调用 `wiki_auth_logout` 并传 `confirm=true`，或 CLI `--confirm`，仅删除托管的标记 Profile。
- 所有请求（含重定向）仅允许 `https://wiki.imgo.tv` 精确源，拒绝其他源。
- 401/403 响应会自动标记认证失效，提示运行 `confluence-wiki-mcp auth login`。
- 托管 Chrome Profile 仅存在于本地 `~/Library/Application Support/confluence-wiki-mcp/browser-profile`；认证凭据从不通过 MCP 网络传输。

## 常见错误

| 状态 | 说明 | 处理 |
|---|---|---|
| `missing` | 尚未确认认证状态；Profile 可能未探测或不存在 | 运行 `confluence-wiki-mcp auth login` |
| `pending` | 登录窗口已打开，等待用户完成认证 | 在浏览器中完成登录 |
| `authenticated` | 认证有效，Cookie 已就绪 | 无需操作 |
| `auth_required` | 凭据无效或过期 | 运行 `confluence-wiki-mcp auth login` |
| `cancelled` | 登录窗口在认证完成前关闭 | 重新运行 `confluence-wiki-mcp auth login` |
| `timed_out` | 登录窗口 5 分钟内未完成认证 | 重新运行 `confluence-wiki-mcp auth login` |
| `unsupported_platform` | 仅在 macOS 支持 | 使用 macOS 设备 |
| `dependency_missing` | Chrome 不可用或 playwright-core 缺失 | 确保 Google Chrome 已安装，重新安装本包 |
| `profile_locked` | 托管 Profile 被其他进程占用 | 等待完成后重试 |
| `failed` | 认证命令执行失败 | 检查 Chrome 是否安装，重试 |

## 开发验证

```bash
npm ci
npm test
npm run build
npm pack --dry-run
```

开发验证包含完整自动化测试套件和构建检查。交互式 macOS Chrome 登录为外部手工验证项，无法在 CI 中覆盖。

### npm Trusted Publishing 前置条件

正式发布使用 `release.yml` 工作流通过 OIDC Trusted Publishing 发布到 npm，附带 provenance 证明。以下前置条件全部完成并验证通过之前，Trusted Publisher 引导发布和 v0.2.0 版本必须视为未完成。首次发布前需满足：

1. 创建公开 GitHub 仓库，推送默认分支，确保 `.github/workflows/release.yml` 已包含在仓库中。
2. 使用可控的临时凭据发布一个受审计的启动包（如 `0.1.0`），该启动包发布不创建 GitHub Release。
3. 在 npm 包设置中配置 Trusted Publisher：工作流文件名为 `release.yml`，环境为 `npm`，允许 `npm publish`。
4. 上述步骤完成后，创建 `v0.2.0` GitHub Release 以触发 OIDC 自动发布。

请勿在发布工作流中添加 npm token 或其他仓库密钥。

## 许可证

MIT