MCP Server Datapizza

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密钥
• 用于文档索引的互联网连接

安装

1. 克隆仓库：

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

1. 导航到软件包目录：

cd datapizza-mcp-server

1. 安装包含开发依赖项的包：

pip install -e ".[dev]"

配置

创建一个 .env 文件在（某个地方/某个文件夹中） datapizza-mcp-server 包含以下变量的目录：

# 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

所需的环境变量

可选环境变量

使用方法

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客户端调用的工具：

# 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系统状态和配置信息

发展

代码质量工具

# 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

依赖项

核心依赖项

• mcp 可以翻译为“最小可感知变化”或根据具体语境可能还有其他含义，但最常见的是“最小可感知变化”模型上下文协议框架
• datapizza-ai-core 可以翻译为“数据披萨人工智能核心”或更简洁地“数据披萨AI核心”，具体取决于语境和表达习惯。在这里，“data pizza”可能是一个特定项目或产品的名称，而“ai-core”则指的是其人工智能核心部分。核心数据功能（pizza-ai）
• datapizza-ai-embedders-openai（可翻译为）：DataPizza AI 嵌入器（OpenAI 版）OpenAI嵌入式集成
• datapizza-ai-向量存储-qdrantQdrant向量存储集成
• OpenAIOpenAI API客户端
• Qdrant 客户端Qdrant数据库客户端
• 请求：GitHub API 的 HTTP 客户端
• python-dotenv环境变量管理

开发依赖项

• pytest（注：这是一个测试框架或工具的名称，在中文中通常直接保留原名，不进行翻译）测试框架
• 黑色代码格式化工具
• “ruff”可以翻译为“胡须”或“粗暴地（表示动作的粗鲁或鲁莽）”。具体翻译取决于上下文。例如，在描述一个人的外貌时，“ruff”可能指的是“胡须”；而在描述行为时，则可能表示“粗暴地”或“鲁莽地”代码检查器和代码风格检查工具
• mypy静态类型检查器

故障排除

常见问题

1. 认证错误

- 验证 OPENAI_API_KEY 设置正确 - 检查Qdrant Cloud凭据QDRANT_URL 并且 QDRANT_API_KEY)

1. 搜索结果为空

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

1. 连接问题

- 验证GitHub和Qdrant Cloud的互联网连接是否正常 - 检查防火墙设置以允许出站HTTPS连接

调试

通过设置启用调试日志记录 LOG_LEVEL=DEBUG 在你的 .env 文件。

做出贡献

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支
3. 按照代码风格指南进行修改
4. 运行完整的测试套件和代码质量检查
5. 提交一个拉取请求

许可证

此项目采用MIT许可证授权。详情请参阅LICENSE文件。

支持

对于问题和疑问：

• GitHub Issues（问题跟踪）： datapizza-mcp-server/issues 翻译成中文是：“datapizza-mcp-server 问题（或问题追踪）”
• DataPizza AI 文档： datapizza-ai