# Confluence MCP Demo

这个目录提供了一个最小可运行的 Confluence MCP Python demo，目标是先把整体链路打通，再逐步扩展成生产可用版本。

## 1. 我们需要哪些功能

如果要做一个真正可用的 Confluence MCP，建议按下面 3 个层次来设计。

### A. 最小可用能力

这些功能足够支持“让大模型读取 Confluence 知识库并做基础写入”：

1. `health`
   用于确认 MCP 服务是否正常、当前连接的是 `mock` 还是 `real` 模式。
2. `list_spaces`
   列出空间，帮助模型知道知识分区。
3. `list_pages`
   按空间列出页面，支持基础浏览。
4. `get_page`
   读取页面正文，至少返回 `body.storage`。
5. `search_pages`
   基于 CQL 搜索页面，是最核心的检索能力。
6. `create_page`
   允许模型把整理结果或报告写回 Confluence。

### B. 生产常用能力

如果后续要真正接入业务，通常还需要：

1. `update_page`
   更新页面内容，并处理版本号冲突。
2. `delete_page` 或 `archive_page`
   清理无效内容时会用到。
3. `get_page_children`
   支持文档树遍历。
4. `get_comments` / `add_comment`
   便于做协作场景。
5. `get_attachments` / `upload_attachment`
   很多资料以附件方式存在。
6. `get_labels` / `set_labels`
   有助于主题归档与检索。

### C. 工程化能力

要稳定服务给 MCP 客户端，还应补齐：

1. 认证配置管理
   使用 API Token，避免把密钥写死在代码中。
2. 权限边界
   例如默认只读，写操作单独开关。
3. 错误处理与重试
   包括限流、401、403、404、429、5xx。
4. 内容格式转换
   Confluence 常见的是 `storage` 格式，很多模型更适合 Markdown。
5. 观测性
   增加请求日志、trace id、调用耗时。
6. 结果裁剪
   避免把超长正文一次性返回给模型。

## 2. 当前 demo 实现了什么

本 demo 已经实现以下 MCP 工具：

1. `health`
2. `list_spaces`
3. `list_pages`
4. `get_page`
5. `search_pages`
6. `create_page`

并且支持两种运行模式：

1. `mock`
   不依赖真实 Confluence，适合先演示流程。
2. `real`
   通过 Confluence REST API 访问真实实例。

## 3. 文件说明

1. `confluence_mcp_demo.py`
   MCP 服务主程序，包含 mock 客户端、真实 Confluence 客户端和工具注册逻辑。
2. `requirements.txt`
   Python 依赖。
3. `env.example`
   环境变量示例。

## 4. 安装与运行

### 安装依赖

```bash
cd /home/simon/simondisk1/NCAA2026/MCP_confluence
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 运行本地 demo

`mock` 模式下不需要真实 Confluence 账号：

```bash
python3 confluence_mcp_demo.py --mode mock --demo
```

### 启动 MCP Server

```bash
python3 confluence_mcp_demo.py --mode mock
```

### 切到真实 Confluence

先准备环境变量：

```bash
cp env.example .env
```

然后把其中的值改成真实配置，再运行：

```bash
python3 confluence_mcp_demo.py --mode real --demo
python3 confluence_mcp_demo.py --mode real
```

## 5. 示例代码

下面是直接调用业务层的演示思路，便于你理解 MCP 背后做了什么：

```python
from confluence_mcp_demo import build_service

service = build_service(mode="mock")

print(service.list_spaces(limit=5))
print(service.list_pages(space_key="ENG", limit=5))
print(service.search_pages(cql='text ~ "API"', limit=5))
print(service.get_page(page_id="1002"))
print(
    service.create_page(
        space_key="ENG",
        title="MCP Demo Page",
        content="<p>Created from demo</p>",
    )
)
```

## 6. AI Agent Client 示例

如果你希望写一个真正的 AI client 去调用 MCP server，本目录已经新增：

1. `ai_agent_client_demo.py`

这个脚本的设计目标是：

1. 通过 `stdio` 连接本地 `confluence_mcp_demo.py`
2. 自动读取 MCP tools
3. 把 tools 转成 OpenAI Chat Completions 兼容的 `tools` 格式
4. 用 HTTP `POST` 调用一个 AI 服务 URL
5. 让模型决定是否调用 `search_pages`、`get_page` 等工具
6. 把工具结果再回传给模型生成最终回答

### 运行方式

先准备环境变量：

```bash
cp env.example .env
```

填写以下几个关键值：

```bash
AI_CHAT_URL=https://api.openai.com/v1/chat/completions
AI_BEARER_TOKEN=your-token
AI_MODEL=gpt-4o-mini
MCP_MODE=mock
AGENT_USER_QUERY=请帮我搜索和API相关的Confluence页面，并总结页面标题。
```

然后运行：

```bash
python3 ai_agent_client_demo.py
```

### 说明

1. 这个 agent 会自己拉起 `confluence_mcp_demo.py --mode mock`
2. 它使用 `Authorization: Bearer <token>` 做鉴权
3. 它直接向 `AI_CHAT_URL` 发送 HTTP `POST`
4. 只要你的 AI 服务兼容 OpenAI Chat Completions 请求格式即可替换

## 7. 后续建议

如果你准备把它变成真正可接 Cursor 或 Claude Desktop 的 MCP Server，下一步最值得补的是：

1. `update_page`
2. `get_page_children`
3. Markdown 和 Confluence Storage 格式互转
4. 写操作权限开关
5. 更精细的搜索与摘要裁剪