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. 安装与运行

安装依赖

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

运行本地 demo

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

python3 confluence_mcp_demo.py --mode mock --demo

启动 MCP Server

python3 confluence_mcp_demo.py --mode mock

切到真实 Confluence

先准备环境变量：

cp env.example .env

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

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

5. 示例代码

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

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. 把工具结果再回传给模型生成最终回答

运行方式

先准备环境变量：

cp env.example .env

填写以下几个关键值：

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页面，并总结页面标题。

然后运行：

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. 更精细的搜索与摘要裁剪