DataPizza MCP 服务器 🍕
一个模型上下文协议(MCP)服务器,它通过向量相似性搜索和检索增强生成技术,提供对datapizza-ai文档的智能访问。
概述
这个MCP服务器使AI助手和应用程序能够使用自然语言查询全面的datapizza-ai文档。它对datapizza-ai仓库中的文档进行索引,并通过RAG(检索增强生成)管道提供上下文相关的、有针对性的响应。
特点/功能
- 智能文档搜索跨datapizza-ai文档的自然语言查询
- 基于向量的检索使用OpenAI嵌入和Qdrant向量数据库进行语义搜索
- MCP协议合规性标准模型上下文协议实现,以确保广泛兼容性
- 自动索引自动从GitHub下载并索引文档
- 已准备好接入云端支持Qdrant Cloud进行可扩展向量存储
- 可配置的基于环境的配置以实现灵活部署
建筑
服务器由四个主要组件构成:
- MCP 服务器基于FastMCP的服务器,提供(或暴露)
query_datapizza工具 - 索引器下载并处理datapizza-ai文档,将其拆分为可搜索的部分
- 寻回犬(或泛指寻回类犬种)用于语义搜索和响应生成的RAG引擎
- 配置基于环境的设置管理与验证
先决条件
- Python 3.10 或更高版本
- OpenAI API密钥
- Qdrant Cloud账户和API密钥
- 用于文档索引的互联网连接
安装
- 克隆仓库:```bash
git clone https://github.com/datapizza-labs/mcp_server_datapizza.git
cd datapizza-mcp-server
2. 导航到软件包目录:```bash
cd datapizza-mcp-server
- 安装包含开发依赖项的包:```bash
pip install -e ".[dev]"
## 配置
创建一个 `.env` 文件在(某个地方/某个文件夹中) `datapizza-mcp-server` 包含以下变量的目录:```env
# Required Configuration
OPENAI_API_KEY=your_openai_api_key_here
QDRANT_URL=your_qdrant_cloud_url
QDRANT_API_KEY=your_qdrant_api_key
# Optional Configuration
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
COLLECTION_NAME=datapizza_docs
MAX_RESULTS=5
CHUNK_SIZE=1024
CHUNK_OVERLAP=200
LOG_LEVEL=INFO
所需的环境变量
| OPENAI_API_KEY 用于生成嵌入的OpenAI API密钥
| QDRANT_URL Qdrant Cloud 实例 URL
| QDRANT_API_KEY Qdrant Cloud API密钥
可选环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
EMBEDDING_MODEL |
text-embedding-3-small |
OpenAI 嵌入模型 |
EMBEDDING_DIMENSIONS |
1536 |
嵌入向量维度 |
COLLECTION_NAME |
datapizza_docs |
Qdrant集合名称 |
MAX_RESULTS |
5 |
返回的最大搜索结果数量 |
CHUNK_SIZE |
1024 |
用于索引的文档块大小 |
CHUNK_OVERLAP |
200 |
文档块之间的重叠 |
LOG_LEVEL |
INFO |
日志级别(DEBUG,INFO,WARNING,ERROR) |
使用方法
1. 索引文档
在使用服务器之前,请先为datapizza-ai文档建立索引:```bash
python -m datapizza_mcp.indexer
强制重新索引(清除现有数据):```bash
python -m datapizza_mcp.indexer --force
2. 启动MCP服务器```bash
python -m datapizza_mcp.server
或者使用提供的Windows批处理脚本:```bash
../run_datapizza.bat
3. 查询文档
服务器暴露了一个 query_datapizza 可由MCP客户端调用的工具:```python
Example query
result = await client.call_tool("query_datapizza", {
"query": "come creare un agente con OpenAI",
"max_results": 5
})
## MCP 工具与资源
### 工具
- **`query_datapizza`**搜索datapizza-ai文档
- `query` (字符串):自然语言搜索查询
- `max_results` (int, 可选): 最大结果数量(默认:5)
### 资源
- **`datapizza://status`**系统状态和配置信息
## 发展
### 代码质量工具```bash
# Format code
black src/
# Lint code
ruff check src/
ruff check src/ --fix # Auto-fix issues
# Type checking
mypy src/
# Run tests
pytest
项目结构```
datapizza-mcp-server/
├── src/datapizza_mcp/
│ ├── init.py # Package exports
│ ├── config.py # Configuration management
│ ├── server.py # MCP server implementation
│ ├── indexer.py # Documentation indexing
│ └── retriever.py # RAG retrieval engine
├── pyproject.toml # Package configuration
├── .env # Environment variables
└── README.md # This file
```
依赖项
核心依赖项
- datapizza-ai-向量存储-qdrantQdrant向量存储集成
- OpenAIOpenAI API客户端
- Qdrant 客户端Qdrant数据库客户端
- 请求:GitHub API 的 HTTP 客户端
- python-dotenv环境变量管理
开发依赖项
- 黑色代码格式化工具
- mypy静态类型检查器
故障排除
常见问题
- 认证错误
- 验证
OPENAI_API_KEY设置正确 - 检查Qdrant Cloud凭据
QDRANT_URL并且QDRANT_API_KEY)
- 搜索结果为空
- 确保文档已编制索引:
python -m datapizza_mcp.indexer - 检查系统状态:查询
datapizza://status资源
- 连接问题
- 验证GitHub和Qdrant Cloud的互联网连接是否正常
- 检查防火墙设置以允许出站HTTPS连接
调试
通过设置启用调试日志记录 LOG_LEVEL=DEBUG 在你的 .env 文件。
做出贡献
- 为仓库创建分支(或“克隆仓库”)
- 创建一个特性分支
- 按照代码风格指南进行修改
- 运行完整的测试套件和代码质量检查
- 提交一个拉取请求
许可证
此项目采用MIT许可证授权。详情请参阅LICENSE文件。
支持
对于问题和疑问:
- DataPizza AI 文档: datapizza-ai
