# confluence-mcp

面向 **Atlassian Confluence Server 6.x** 的 MCP，把某个页面层级下的文档树拉出来，供 Cursor / Codex 等 AI IDE 分析。

支持两种运行方式：

| 模式 | 适用场景 |
|------|----------|
| **stdio**（默认） | 本机 Cursor 直接拉起进程 |
| **HTTP / Streamable HTTP** | 部署到局域网机器，多台 IDE 共用 |

## 工具

| Tool | 作用 |
|------|------|
| `find_page` | 按标题查找页面（可带 spaceKey） |
| `list_subtree` | 递归列出某页下的子树（id / 路径 / depth） |
| `get_page` | 取单页正文（纯文本，可选 HTML） |
| `get_subtree_docs` | 一次拉取整棵子树正文，供 AI 分析 |

示例：以某项目的需求文档根页面为例，`pageId=<pageId>`，空间 `<space-key>`。

## 配置

复制 `.env.example`，用环境变量注入（**不要把密码写进仓库**）：

```bash
CONFLUENCE_BASE_URL=http://<confluence-host>:<port>
CONFLUENCE_USERNAME=<your-username>
CONFLUENCE_PASSWORD=********
CONFLUENCE_SPACE_KEY=<space-key>
```

# HTTP mode (LAN / K8s) — server only needs base URL; users send Basic auth
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=3100
```

## 本机运行（stdio）

```bash
cd confluence-mcp
npm install
npm run build

# Windows PowerShell 示例
$env:CONFLUENCE_BASE_URL="http://<confluence-host>:<port>"
$env:CONFLUENCE_USERNAME="<your-username>"
$env:CONFLUENCE_PASSWORD="********"
$env:CONFLUENCE_SPACE_KEY="<space-key>"
node dist/index.js
```

Cursor `mcp.json`：

```json
{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["D:/vscode/mcps/confluence-mcp/dist/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "http://<confluence-host>:<port>",
        "CONFLUENCE_USERNAME": "<your-username>",
        "CONFLUENCE_PASSWORD": "********",
        "CONFLUENCE_SPACE_KEY": "<space-key>"
      }
    }
  }
}
```

## 部署到局域网（推荐）

**可以。** 把 MCP 跑在能访问 Confluence 的内网机器上（跳板机 / 同网段服务器），Cursor 通过 HTTP 连过去。

### 1. 在局域网机器上启动

```bash
cd confluence-mcp
npm install && npm run build

export CONFLUENCE_BASE_URL=http://<confluence-host>:<port>
export CONFLUENCE_SPACE_KEY=<space-key>
export MCP_TRANSPORT=http
export MCP_HOST=0.0.0.0
export MCP_PORT=3100

node dist/index.js --http
# → listening; clients must send Authorization: Basic ...
```

健康检查：`GET http://<lan-ip>:3100/health`

也可用 systemd / nssm / Docker / K8s 常驻。防火墙放行 `3100`。

### 2. Cursor 连远端

每位同事在自己的 `mcp.json` 里填**自己的** Confluence 账号（Basic）：
```json
{
  "mcpServers": {
    "confluence": {
      "url": "http://<lan-ip>:3100/mcp",
      "headers": {
        "X-Confluence-Username": "你的用户名",
        "X-Confluence-Password": "你的密码"
      }
    }
  }
}
```

> 不同 Cursor 版本对远端 MCP 字段略有差异；若 `url` 不被识别，可用本机 stdio，或在本机用反向代理/SSH 隧道：  
> `ssh -L 3100:127.0.0.1:3100 user@lan-host`，再把 `url` 写成 `http://127.0.0.1:3100/mcp`。

### 部署拓扑

```
[Cursor / Codex] --X-Confluence-Username/Password--> [confluence-mcp] --REST(同一账号)--> [Confluence]
```

要点：

1. **MCP 必须放在能访问 Confluence 的网段**。
2. **每人在 mcp.json 填 `X-Confluence-Username` / `X-Confluence-Password`**，权限随账号走。
3. 服务端只配置 `CONFLUENCE_BASE_URL`，不要存共享账号密码。
4. 工具参数可直接贴 `viewpage.action?pageId=` 链接。
5. 大子树用 `maxDepth` / `maxPages`，避免一次塞爆模型上下文。

## Podman 构建 & Kubernetes 部署

### Podman 本地构建 / 试跑

```bash
cd confluence-mcp

podman build -t confluence-mcp:1.0.0 .

podman run --rm -p 3100:3100 \
  -e CONFLUENCE_BASE_URL=http://<confluence-host>:<port> \
  -e CONFLUENCE_SPACE_KEY=<space-key> \
  confluence-mcp:1.0.0
```

验证：`curl http://127.0.0.1:3100/health`

HTTP 模式**不在服务端存用户密码**。每位同事在 Cursor 里填两个字段即可：

```json
{
  "mcpServers": {
    "confluence": {
      "url": "http://<ingress-host>:3100/mcp",
      "headers": {
        "X-Confluence-Username": "你的用户名",
        "X-Confluence-Password": "你的密码"
      }
    }
  }
}
```

也可仍用 `Authorization: Basic ...`（兼容）。

工具参数 `page` 支持直接粘贴链接，例如：

`http://<confluence-host>:<port>/pages/viewpage.action?pageId=<pageId>`

会自动抽出 `pageId`。也可用工具 `resolve_page_link` 先解析。

推到你们的镜像仓库（按实际 registry 改）：

```bash
podman tag confluence-mcp:1.0.0 registry.example.com/confluence-mcp:1.0.0
podman push registry.example.com/confluence-mcp:1.0.0
```

### 部署到 K8s

1. 编辑 `deploy/deploy.yaml`：改 `image`、Secret 里的 `CONFLUENCE_BASE_URL`
2. 集群 Pod 必须能访问 Confluence 地址
3. 应用清单：

```bash
kubectl apply -f deploy/deploy.yaml
kubectl get svc confluence-mcp confluence-mcp-nodeport -n <namespace>
```

- 集群内：`http://confluence-mcp.<namespace>:3100/mcp`
- 局域网同事：用 Ingress / NodePort，Cursor 配置里填自己的 Basic 账号（见上）

```json
{
  "mcpServers": {
    "confluence": {
      "url": "http://<ingress>/mcp",
      "headers": {
        "X-Confluence-Username": "你的用户名",
        "X-Confluence-Password": "你的密码"
      }
    }
  }
}
```

## 在对话里怎么用

- 「解析这个链接并列出子树：http://confluence.../pages/viewpage.action?pageId=<pageId>」
- 「用 confluence 拉《示例项目》下文档」（标题 / pageId / 链接均可）
- 「拉取示例文档整棵子树正文并总结需求」
- `get_subtree_docs` + `maxDepth: 1` 只拿当前层级
- `find_page` / `resolve_page_link` 按标题或链接定位

## 开发

```bash
npm run dev          # stdio
npm run dev:http     # http://0.0.0.0:3100/mcp
```