Confluence MCP Demo

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.pyMCP 服务主程序，包含 mock 客户端、真实 Confluence 客户端和工具注册逻辑。
2. requirements.txtPython 依赖。
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. 更精细的搜索与摘要裁剪