AI导哈

文档智能搜索服务器

一个基于模型上下文协议（MCP）的服务器，通过向量相似性搜索和检索增强生成技术，提供对datapizza-ai文档的智能访问。

  • by mat1312
  • Python
  • 本地部署
  • 18 星标
  • 更新于
在 GitHub 查看 mat1312/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

所需的环境变量

变量 描述
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文档建立索引：

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)

  2. 搜索结果为空

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

  3. 连接问题

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

调试

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

做出贡献

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

许可证

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

支持

对于问题和疑问：

相关 MCP