内容
# Confluence RAG 数据管道与 MCP 协议
一款提供来自 Confluence 页面的相关上下文的 Model Context Protocol (MCP) 服务器，使用 RAG（检索增强生成）。
## 功能特点
- 爬取 Confluence 空间和页面
- 使用 ChromaDB 存储文档向量
- 实现用于上下文检索的 MCP 协议
- 支持按空间、标签和元数据过滤
- 处理附件和评论
- 提供 REST API 端点
## 要求
- Python 3.9 或更高版本
- 使用 UV 进行依赖管理
- Confluence API 访问令牌
- ChromaDB 用于向量存储
## 安装
1. **设置 Python 环境：**
- 确保已安装 Python 3.9 或更高版本
```bash
python --version
```
- 安装 UV（如果尚未安装）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **克隆和设置项目：**
```bash
git clone <仓库网址>
cd confluence-scraper-mcp
# 创建虚拟环境
uv venv .venv
# 激活虚拟环境
source .venv/bin/activate
# 安装依赖
uv pip install -r requirements.txt
```
3. **配置环境：**
- 在项目根目录中创建 `.env` 文件：
```bash
touch .env
```
- 添加以下配置（根据需要调整值）：
```bash
# 必需设置
CONFLUENCE_BASE_URL=https://您的域名.atlassian.net
CONFLUENCE_TOKEN=您的 API 令牌
CONFLUENCE_SPACE_KEY=可选空间键
# 可选设置（带有默认值）
INITIAL_CRAWL=false
CHROMA_PERSIST_DIR=./data/chroma
EMBEDDING_MODEL="all-MiniLM-L6-v2"
MAX_PAGES=1000
INCLUDE_ATTACHMENTS=true
INCLUDE_COMMENTS=true
```
## 使用
1. **使用 uvx（推荐）：**
```bash
# 开发模式，自动重载
uvx uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 运行测试
uvx pytest
# 代码格式化和检查
uvx black .
uvx isort .
uvx mypy .
```
2. **替代：使用虚拟环境：**
```bash
# 激活虚拟环境
source .venv/bin/activate
# 然后像平常一样运行命令
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
3. **初始设置：**
```bash
# 启动 Confluence 页面的初始爬取
curl -X POST http://localhost:8000/crawl
# 验证服务器健康状况
curl http://localhost:8000/health
```
4. **使用 MCP API：**
```bash
# 获取 LLM 查询的上下文
curl -X POST http://localhost:8000/mcp/context \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "告诉我关于项目 X 的信息"}],
"query": "项目 X 文档",
"max_context_length": 1000
}'
# 响应将包括来自您的 Confluence 页面的相关上下文
```
5. **监控和维护：**
```bash
# 查看日志
tail -f logs/app.log
# 重新爬取 Confluence（例如，更新后）
curl -X POST http://localhost:8000/crawl
```
## API 端点
- `GET /health`：健康检查端点
- `POST /crawl`：触发 Confluence 爬取
- `POST /mcp/context`：获取查询的相关上下文
## 与代码助手配合使用
此 MCP 服务器专门用于 Confluence 文档，并使用 ChromaDB 的 RAG（检索增强生成），这使得它与典型的 MCP 服务器有所不同：
1. **Confluence 集成：**
- 与 Confluence API 直接集成
- 处理 Confluence 特有的内容类型（页面、附件、评论）
- 保留 Confluence 元数据（空间键、标签、作者）
2. **向量搜索：**
- 使用 ChromaDB 进行语义搜索，而不是传统文本搜索
- 使用句子转换器生成嵌入
- 基于含义而非关键词的更准确的上下文检索
3. **过滤功能：**
- 按 Confluence 空间键过滤
- 支持基于标签的过滤
- 可以包含/排除附件和评论
- 每个端点的上下文长度可配置
此 MCP 服务器可以与 GitHub Copilot 等代码助手集成，以提供来自 Confluence 文档的相关上下文。以下是设置方法：
1. **启动 MCP 服务器：**
```bash
# 确保服务器正在运行
poetry shell
uvicorn app.main:app --port 8000
```
2. **配置代码助手：**
- 对于 GitHub Copilot：
1. 打开 VS Code 设置（Cmd+,）
2. 搜索“copilot chat”
3. 在“Copilot Chat: MCP Servers”下使用以下方法之一添加新的 MCP 端点：
**选项 1：直接网址**
- 使用网址：`http://localhost:8000/mcp/context`
- 注意：此基本设置不包括过滤功能
**选项 2：MCP 配置文件（推荐）**
- 在 `examples/mcp.json` 中提供示例配置文件
- 支持 Confluence 特有的过滤
- 可以为不同空间配置多个端点
- 允许微调上下文检索
```json
{
"endpoints": [
{
"name": "API 文档",
"url": "http://localhost:8000/mcp/context",
"options": {
"max_context_length": 2000,
"filter": {
"space_key": "API",
"labels": ["technical-docs", "api-reference"],
"include_comments": true,
"include_attachments": false,
"semantic_ranking": {
"weight": 0.7,
"model": "all-MiniLM-L6-v2"
}
}
},
"authentication": {
"type": "none"
}
},
{
"name": "架构文档",
"url": "http://localhost:8000/mcp/context",
"options": {
"max_context_length": 3000,
"filter": {
"space_key": "ARCH",
"labels": ["architecture", "design"],
"include_comments": false,
"include_attachments": true,
"semantic_ranking": {
"weight": 0.8,
"model": "all-MiniLM-L6-v2"
}
}
},
"authentication": {
"type": "none"
}
}
],
"default_endpoint": "API 文档"
}
```
- 在 VS Code 设置中将此文件的路径添加到“Copilot Chat: MCP Configuration File”
- 参见 `examples/mcp.json` 获取具有多个端点和过滤选项的完整示例
3. **与 Copilot 配合使用：**
- 在 VS Code 中打开 Copilot Chat（Cmd+I）
- 您的查询现在将包括来自 Confluence 页面的相关上下文
- 示例：“如何实现功能 X？”将包括相关 Confluence 文档的上下文
- 您还可以在 Copilot Chat 中使用 `/doc` 命令显式搜索文档
4. **获得更好结果的提示：**
- 保持 Confluence 页面有序且最新
- 在 Confluence 中使用描述性标题和标签
- 在重大文档更新后重新爬取：
```bash
curl -X POST http://localhost:8000/crawl
```
## 开发
1. **安装开发依赖项：**
```bash
uv pip install -r requirements.txt
```
2. **在开发中使用 uvx：**
UV 安装了一个名为 `uvx` 的命令运行程序，可以在不显式激活虚拟环境的情况下运行 Python 脚本和模块：
```bash
# 运行 FastAPI 服务器
uvx uvicorn app.main:app --reload
# 运行测试
uvx pytest
# 代码格式化
uvx black .
uvx isort .
uvx mypy .
```
3. **环境配置：**
项目使用环境变量进行配置。复制 `.env.example` 到 `.env` 并更新值：
```bash
CONFLUENCE_BASE_URL=https://您的域名.atlassian.net
CONFLUENCE_TOKEN=您的 API 令牌
CONFLUENCE_SPACE_KEY=您的空间键
CHROMA_PERSIST_DIR=data/chroma
CHROMA_COLLECTION_NAME=confluence_docs
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
CHUNK_SIZE=512
CHUNK_OVERLAP=50
TOP_K=3
SIMILARITY_THRESHOLD=0.7
```
## 贡献
1. 分叉仓库
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 进行更改：
- 使用 `uvx black .` 和 `uvx isort .` 格式化代码
- 使用 `uvx mypy .` 进行类型检查
- 为新功能添加测试
- 根据需要更新文档
4. 运行测试（`uvx pytest`）
5. 提交更改（`git commit -m 'Add some amazing feature'`）
6. 推送到分支（`git push origin feature/amazing-feature`）
7. 打开拉取请求
## 许可证
MIT 许可证。更多信息请参见 [LICENSE](LICENSE)。
