DataPizza MCP Server 🍕

一款基于模型上下文协议（MCP）的服务器，通过向量相似性搜索和检索增强生成（RAG）提供对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密钥
• 互联网连接，用于文档索引

安装

1. 克隆仓库：

git clone https://github.com/datapizza-labs/mcp_server_datapizza.git
cd datapizza-mcp-server

2. 导航到包目录：

cd datapizza-mcp-server

3. 安装带有开发依赖项的包：

pip install -e ".[dev]"

配置

在datapizza-mcp-server目录中创建一个.env文件，包含以下变量：

# 必需配置
OPENAI_API_KEY=your_openai_api_key_here
QDRANT_URL=your_qdrant_cloud_url
QDRANT_API_KEY=your_qdrant_api_key

# 可选配置
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	1_536	嵌入向量维度
COLLECTION_NAME	datapizza_docs	Qdrant集合名称
MAX_RESULTS	5	返回的最大搜索结果数
CHUNK_SIZE	1024	文档分块大小
CHUNK_OVERLAP	200	文档分块之间的重叠
LOG_LEVEL	INFO	日志级别（DEBUG, INFO, WARNING, ERROR）

使用方法

1. 索引文档

在使用服务器之前，索引DataPizza-AI文档：

python -m datapizza_mcp.indexer

要强制重新索引（清除现有数据）：

python -m datapizza_mcp.indexer --force

2. 启动MCP服务器

python -m datapizza_mcp.server

或者使用提供的Windows批处理脚本：

../run_datapizza.bat

3. 查询文档

服务器公开了一个query_datapizza工具，可以被MCP客户端调用：

# 示例查询
result = await client.call_tool("query_datapizza", {
    "query": "如何使用OpenAI创建代理",
    "max_results": 5
})

MCP工具和资源

工具

• query_datapizza：搜索DataPizza-AI文档
  • query (字符串)：自然语言搜索查询
  • max_results (整数，可选)：返回的最大结果数（默认：5）

资源

• datapizza://status：系统状态和配置信息

开发

代码质量工具

# 格式化代码
black src/

# 检查代码
ruff check src/
ruff check src/ --fix  # 自动修复问题

# 类型检查
mypy src/

# 运行测试
pytest

项目结构

datapizza-mcp-server/
├── src/datapizza_mcp/
│   ├── __init__.py          # 包导出
│   ├── config.py            # 配置管理
│   ├── server.py            # MCP服务器实现
│   ├── indexer.py           # 文档索引
│   └── retriever.py         # RAG检索引擎
├── pyproject.toml           # 包配置
├── .env                     # 环境变量
└── README.md               # 本文件

依赖项

核心依赖项

• mcp：模型上下文协议框架
• datapizza-ai-core：DataPizza-AI核心功能
• datapizza-ai-embedders-openai：OpenAI嵌入集成
• datapizza-ai-vectorstores-qdrant：Qdrant向量存储集成
• openai：OpenAI API客户端
• qdrant-client：Qdrant数据库客户端
• requests：用于GitHub API的HTTP客户端
• python-dotenv：环境变量管理

开发依赖项

• pytest：测试框架
• black：代码格式化工具
• ruff：代码检查和风格检查工具
• mypy：静态类型检查工具

故障排除

常见问题

1. 身份验证错误

   • 验证OPENAI_API_KEY是否正确设置
   • 检查Qdrant Cloud凭据（QDRANT_URL和QDRANT_API_KEY）

2. 空搜索结果

   • 确保已索引文档：python -m datapizza_mcp.indexer
   • 检查系统状态：查询datapizza://status资源

3. 连接问题

   • 验证互联网连接，以便访问GitHub和Qdrant Cloud
   • 检查防火墙设置，允许HTTPS出站连接

调试

通过在.env文件中设置LOG_LEVEL=DEBUG启用调试日志。

贡献

1. 分叉仓库
2. 创建功能分支
3. 根据代码风格指南进行更改
4. 运行完整的测试套件和代码质量检查
5. 提交拉取请求

许可

本项目根据MIT许可发布。详情参见LICENSE文件。

支持

对于问题和疑问：

• GitHub Issues：datapizza-mcp-server/issues
• DataPizza AI文档：datapizza-ai