内容
Confluence MCP一款 Model Context Protocol (MCP) 服务器，使 AI 助手能够从 Confluence 页面中搜索和检索内容。这使得 AI进行更改之前了解上下文和设计文档。
## 功能特点
- **搜索 Confluence 页面**：按标题、内容或关键词搜索页面
- **检索页面内容**：获取包括正文、元数据和附件在内的完整页面内容
- **列出空间**：浏览可用的 Confluence 空间
- **按 ID 获取页面**：通过 Confluence ID 检索特定页面
- **上下文感知操作**：AI 可以在建议了解现有的文档
- **每周状态（全栈）**：从 Jira生成 **每周进度** 和 **每周经理评审**，在小型 Web UI 中编辑，并复制/粘贴到
- **混合搜索重新排序（RAG：将 Confluence 页面索引到本地向量存储中，然后通过向量相似性、本地 BM关键词匹配进行搜索，两 Reciprocal Rank Fusion ，或通过本地交叉编码和重新排序 — @k/MRR 比较它们。参见 [docs/RAG.md](docs.md)
## 工作原理
```mermaid
flowchart Client(["AI 助手<br/>Cursor / Claude Desktop Client -->|MCP 工具| Server["confluence 服务器"]
Server --> 读取["search_pages · get_page<br/>list_spaces · search_by_title"]
读取 --> ConfluenceAPI[("Confluence API")]
Server --> Jira 工具["get_jira_summary · get_jira_weekly_report<br/>search_jira_tickets_by_email"]
Jira 工具iraAPI[("Jira API")]
Server --> 草稿["generate_weekly_drafts"]
ConfluenceAPI -.稿
JiraAPI -.-> 草稿
--> 数据库[("SQLite")] --> Web UI["Web UIlocalhost:5173"]
Server --> 索引["index_confluence_pages"]
ConfluenceAPI -.-> 索引 索引 --> 分块["heading-aware<br/>chunking"] --> 嵌入["local embeddings<br/>fastembed"] --> 本地索引[("本地向量存储 +<br/>BM25 索引")]
Server --> 搜索["bm25 / semantic / hybrid /<br/>rerank search_pages"]
搜索 --> 本地索引
```
三组工具位于一个 MCP 服务器后面：**直接 Confluence/Jira 查询**（实时访问 Atlassian API），**每周稿**（从 中提取，渲染通过 模板，持久化 以供 Web UI 使用 **本地混合搜索**索引到本地向量 + BM25 索引中，然后从中提供 `bm25` / `semantic` / `hybrid_search `rerank_search 而无需再次访问 Confluence）。参见 [docs/RAGdocs/RAG.md) 以获取详细索引和检索管道，包括为什么通过 RRF 融合 BM25 + 向量使用交叉编码器重新排序。
## 解决问题
每周更新容易被遗忘且难以保持一致性。该项目将ira 活动（可选地与几个 Confluence “上下文结合）转化为具有可重复结构的经理级每周草稿、进展、风险步骤和请求。
截图
## 先决条件 推荐 Python 3+（与现 设置一起工作）
- Confluence Cloud 或服务器实例
身份验证的 Confluence API 令牌或用户名
- Node.js （用于 Web UI） 安装
### 选项使用 `venv`（推荐）
1. 创建 venv 并安装依赖项：
```python3 -m venv
.venv/bin/python pip install -r requirements.txt
```
2. 通过env` 文件进行配置bash
cp env.example
# 使用您的编辑 .env
```
### 选项 B：Docker Compose
```bash
docker compose -f docker-compose.yml up --build
```
## 配置
服务器需要以下环境变量：
- `CONFLUENCE_URL`: 您的 Confluence 实例 URL
- 对于云：`https://your-domain.atlassian.net`
- 对于服务器：`https://confluence.your-domain.com`
- `CONFLUENCE_EMAIL`: 您的 Confluence 电子邮件/用户名
- `CONFLUENCE_API_TOKEN`: 您的 Confluence API 令牌（首选）或密码
**注意：** 服务器自动检测 Confluence Cloud 与服务器，并使用正确的 API 端点（`/wiki/rest/api/` 用于云，`/rest/api/` 用于服务器）。
### 获取 Confluence API 令牌
1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击“创建 API 令牌”
3. 复制令牌并在您的配置中使用它
## 快速入门
1. **测试您的连接：**
```bash
python3 python/test_connection.py
```
2. **启动每周草稿后端 API：**
```bash
PYTHONPATH="python/backend:python:." .venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```
3. **启动 Web UI：**
```bash
cd frontend
npm install
npm run dev
```
然后打开 `http://localhost:5173`。
4. **配置您的 MCP 客户端**（详见 `docs/CONFIGURATION.md`）
## 用法
### 测试连接
在配置 MCP 客户端之前，请测试一切是否正常工作：
```bash
# 设置环境变量或使用 .env 文件
export CONFLUENCE_URL="https://your-domain.atlassian.net"
export CONFLUENCE_EMAIL="your-email@example.com"
export CONFLUENCE_API_TOKEN="your-api-token"
# 运行测试脚本
python3 python/test_connection.py
```
### 作为 MCP 服务器运行
服务器实现了 MCP 协议，可以与 Cursor、Claude Desktop 等兼容的 MCP 客户端一起使用。
在您的 MCP 客户端设置中配置：
```json
{
"mcpServers": {
"confluence": {
"command": "python",
"args": ["/path/to/confluence-mcp/python/server.py"],
"env": {
"CONFLUENCE_URL": "https://your-domain.atlassian "CONFLU "your-email@example.com",
"CONFLUENCE_API_TOKEN": "your-api-token"
}
}
}
}
```
### 可用工具
1. **search_pages**：按查询搜索 Confluence 页面
- 参数：`query`（字符串），`space_key`（可选），`limit`（可选，默认为 10）
2. **get_page**：通过 ID 获取特定页面
- 参数：`page_id`（字符串）
3. **get_page_content**：获取页面的完整内容
- 参数：`page_id`（字符串），`expand`（可选，默认为 "body.storage,version,space"）
4. **list_spaces**：列出所有可访问的 Confluence 空间
- 参数：`limit`（可选，默认为 50）
5. **search_by_title**：按精确或部分标题匹配搜索页面
- 参数：`title`（字符串），`space_key`（可选），`limit`（可选）
6. **get_jira_summary**：获取您在过去 N 天内分配的 Jira 工单摘要
- 参数：`days`（可选，默认为 14），`save_to_file`（可选，默认为 true）
- 按状态和问题类型分组返回格式化摘要
- 如果 `save_to_file` 为 true，则自动保存到 `2026/YYYYMM/jira_summary_YYYYMMDD.md`
7. **get_jira_weekly_report**：生成具有商业利益的高级每周报告
- 参数：`days`（可选，默认为 14），`save_to_file`（可选，默认为 true）
- 分析工单以提取价值主张，并为利益相关者格式化
- 分类为“本周”（已完成/进行中/评审中）和“下周”（待办）
- 如果 `save_to_file` 为 true，则自动保存到 `2026/YYYYMM/weekly_report_YYYYMMDD.md`
8. **search_jira_tickets_by_email**：按特定用户的电子邮件地址搜索 Jira 工单
- 参数：`email`（必填），`days`（可选，默认为 14），`search_type`（可选，默认为 "assignee"）
- 自动从电子邮件中查找用户的账户 ID，然后搜索他们的工单
- `search_type` 可以是：“assignee”（分配给用户的工单），“reporter”（用户报告的工单）或“all”（两者）
- 按状态返回格式化摘要
- 有助于了解团队成员一直在处理什么
- **注意**：Jira Cloud 需要账户 ID（而非电子邮件）进行搜索。此工具自动处理查找。
9. **generate_weekly_drafts**：生成两个 Markdown 草稿（每周进度 + 经理评审）
- 参数：`week_start`（可选的 ISO 日期），`week_end`（可选的 ISO 日期），`jira_days_lookback`（可选），`confluence_page_ids`（可选的数组），`save_to_files`（可选），`save_to_db`（可选）
- 将 Markdown 保存到 `2026/YYYYMM/` 并（可选地）将草稿存储在 SQLite 中以供 Web UI 使用
10. **index_confluence_pages**：分块、嵌入和索引 Confluence 页面以进行语义搜索
- 参数：`page_ids`（可选的数组）或 `query` + `space_key`（可选）以发现要索引的页面，`（可选，默认为 20）
每个页面分成标题块，本地嵌入它们，并将它们存储在持久的本地向量索引中。页面会替换其块。
11._search_pages**：索引的页面块进行向量搜索
- 参数：`query`（字符串），`top_k`（默认为 5），`space（可选）
- 返回匹配的块文本以及页面标题、URL 和标题面包屑，按语义相似性而非关键词重叠排序。需要首先通过 `index_confluence_pages` 索引页面。
12. **bm25_search_pages**：对已索引的页面块进行本地 BM25 关键词搜索
- 参数：`query`（字符串），`top_k`（可选，默认为 5），`space_key`（可选）
- 在本地索引上进行关键词排名（不是 Confluence 的 CQL 搜索）— 在索引页面中查找确切术语并与/混合工具进行比较非常有用。
13. **hybrid_search_pages**：BM25 + 向量搜索通过 Reciprocal Rank Fusion 融合
- 参数：`query`（字符串），_k`（可选，默认为 5），`space_key`（可选），`candidate_k`（可选，默认为 20）
- 捕获纯向量搜索可能排名不足的确切术语，同时仍然找到具有无共享措辞的概念匹配。
14. **rerank_search_pages**：`hybrid_search_pages` 候选者，由本地交叉编码器重新评分
- 参数：`query`（字符串），`top_k`（可选，默认为 5），`space_key`（可选），`candidate_k`（可选，默认为 20）
- 精确度最高，延迟高于其他搜索工具 — 当结果质量比速度更重要时，推荐使用默认设置。有关设计细节、权衡和如何评估检索质量（Recall@k/MRR），请参见 [docs/RAG.md](docs/RAG.md)。
## 示例用法
配置完成后，AI 助手可以像这样使用服务器：
```
用户：“搜索有关数据库设计的页面”
AI：[使用 search_pages 工具查找相关页面]
用户：“Beta Pipeline 设计文档中说了什么？”
AI：[使用 search_pages 查找文档，然后使用 get_page_content 检索它]
用户：“总结我最近 2 周的 Jira 工单”
AI：[使用 get_jira_summary 获取并总结工单，保存到 2026/YYYYMM 文件夹]
用户：“根据我的 Jira 工单生成一份具有商业利益的周报”
AI：[使用 get_jira_weekly_report 创建对利益相关者友好的周更新]
用户：“user@example.com 在过去 2 周内一直在处理什么？”
AI：[使用 search_jira_tickets_by_email 查找并总结他们的工单]
用户：“为上一周生成我的周进度和经理评审草稿”
AI：[使用 generate_weekly_drafts 工具，返回两个 Markdown 草稿]
用户：“索引 ENG 空间中所有关于我们数据管道的页面”
AI：[使用 index_confluence_pages，查询=“数据管道”，space_key=“ENG”]
用户：“我们如何处理事件表的模式迁移？”
AI：[使用 rerank_search_pages 查找并精确排名概念相关的块，即使它们从未使用“迁移”一词]
```
## 安全注意事项
- 永远不要将您的 `.env` 文件或 API 令牌提交到版本控制中
- 尽可能使用 API 令牌而不是密码
- 服务器尊重 Confluence 权限 - 用户只能访问他们有权查看的页面
- 如果您在文档或聊天中意外共享了令牌，**立即在 Atlassian 中将其轮换**，并用占位符替换
## 故障排除
### 身份验证错误
- 验证您的 API 令牌是否正确
- 检查您的电子邮件是否与 Confluence 账户匹配
- 确保您的 Confluence URL 正确（包括 https://）
### 权限错误
- API 令牌必须属于具有适当 Confluence 权限的用户
- 某些页面可能受到限制，需要特定权限
### 连接错误
- 验证您的 Confluence URL 是否
- 检查网络连接性
- 对于 Confluence 服务器，确保启用了 REST## 开发
要使用附加功能扩展服务器：
1. 在 `python/server.py` 中按照 MCP 工具格式添加新2. 在 `fluence_client.py` 中实现 Confluence API 调用
3. 用新工具文档更新此 README
## 许可证
MIT
