Data Commons MCP

🚀 🔭 EOSC Data Commons MCP server

EOSC Data Commons MCP server 是为 EOSC Data Commons 项目 开发的一个服务器，它基于 Model Context Protocol (MCP)，通过 HTTP POST 端点，让用户能够从各种开放访问的数据发布者处获取数据。该服务器借助搜索 API 和大语言模型（LLM），帮助用户找到所需的数据集和工具。

🚀 快速开始

开发环境准备

此项目开发需要满足以下要求：

• Rust
• 大语言模型提供商的 API 密钥，如 Mistral.ai 或 OpenAI，可使用免费套餐，只需登录即可。

推荐安装 VSCode 扩展：rust-analyzer

安装开发依赖

rustup update
cargo install cargo-release cargo-deny cargo-watch git-cliff

创建一个 .cargo/config.toml 文件，并填入你的 Mistral API 密钥 或 OpenAI API 密钥：

[env]
MISTRAL_API_KEY = "YOUR_API_KEY"
OPENAI_API_KEY = "YOUR_API_KEY"

启动开发服务器

在开发环境下启动 MCP 服务器，访问地址为 http://localhost:8000/mcp，OpenAPI UI 地址为 http://localhost:8000/docs：

cargo run

若希望在代码更改时自动重新加载服务器，可使用以下命令：

cargo watch -x run

以下是一个 curl 请求示例：

curl -X POST http://localhost:8000/search -H "Content-Type: application/json" -H "Authorization: SECRET_KEY" -d '{"messages": [{"role": "user", "content": "data about insulin in EU"}], "model": "mistral-small-latest", "stream": true}'

连接 MCP 客户端

按照客户端的说明，使用已部署服务器的 /mcp URL（例如 http://localhost:8000/mcp）进行连接。

VSCode GitHub Copilot 连接示例

通过 VSCode 界面添加新的 MCP 服务器：

• 打开命令面板（ctrl+shift+p 或 cmd+shift+p）
• 搜索 MCP: Add Server...
• 选择 HTTP，并提供 MCP 服务器 URL http://localhost:8000/mcp

你的 VSCode mcp.json 文件应如下所示：

{
    "servers": {
        "data-commons-mcp-server": {
            "url": "http://localhost:8000/mcp",
            "type": "http"
        }
    },
    "inputs": []
}

生产环境构建

在 target/release/ 目录下构建二进制文件：

cargo build --release

启动服务器的命令如下：

./target/release/data-commons-mcp

使用 Docker 部署

创建一个 keys.env 文件，并填入 API 密钥：

MISTRAL_API_KEY=YOUR_API_KEY
SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM

SEARCH_API_KEY 可用于添加一层防护，防止机器人对大语言模型进行垃圾请求。若未提供该密钥，则无需 API 密钥即可查询 API。

构建并部署服务：

docker compose up

代码格式化与检查

使用 rustfmt 自动格式化代码：

cargo fmt

使用 clippy 进行代码检查：

cargo clippy --all

自动应用可能的修复：

cargo fix

供应链检查

检查依赖项的供应链，包括许可证（仅接受 OSI 或 FSF 批准的许可证的依赖项）和漏洞（CVE 公告）：

cargo deny check

更新 Cargo.lock 中的依赖项：

cargo update

版本发布

预发布测试：

cargo release patch

也可以使用 minor 或 major 进行不同级别的版本发布。

创建正式版本：

cargo release patch --execute

✨ 主要特性

• 提供 HTTP POST 端点，方便用户从各种开放访问的数据发布者处获取数据。
• 借助搜索 API 和大语言模型（LLM），帮助用户找到所需的数据集和工具。

📦 安装指南

开发依赖安装

rustup update
cargo install cargo-release cargo-deny cargo-watch git-cliff

配置 API 密钥

创建 .cargo/config.toml 文件：

[env]
MISTRAL_API_KEY = "YOUR_API_KEY"
OPENAI_API_KEY = "YOUR_API_KEY"

生产环境构建

cargo build --release

Docker 部署

创建 keys.env 文件：

MISTRAL_API_KEY=YOUR_API_KEY
SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM

构建并部署服务：

docker compose up

💻 使用示例

启动开发服务器

cargo run

curl 请求示例

curl -X POST http://localhost:8000/search -H "Content-Type: application/json" -H "Authorization: SECRET_KEY" -d '{"messages": [{"role": "user", "content": "data about insulin in EU"}], "model": "mistral-small-latest", "stream": true}'

📚 详细文档

端点说明

HTTP API 包含 2 个主要端点：

• /mcp：MCP 服务器，使用 EOSC Data Commons 搜索 API 搜索相关数据以回答用户问题。

  • 使用 rmcp 并支持流式 HTTP 传输。
  • 可用工具：
    • [x] 搜索数据集
    • [ ] 搜索工具
    • [ ] 搜索与数据集或工具相关的引用

• /search：简单的 HTTP POST 端点（JSON），用于通过大语言模型提供商查询 MCP 服务器。

  • 使用 axum、utoipa 生成 OpenAPI 规范，使用 llm 与大语言模型提供商（如 Mistral、OpenAI）进行交互。
  • 返回流式响应：先请求工具调用，然后返回工具调用结果，最后返回最终搜索结果。

开发相关说明

开发环境要求

• Rust
• 大语言模型提供商的 API 密钥，如 Mistral.ai 或 OpenAI。

推荐扩展

推荐安装 VSCode 扩展：rust-analyzer

代码格式化与检查

• 使用 rustfmt 自动格式化代码：

cargo fmt

• 使用 clippy 进行代码检查：

cargo clippy --all

• 自动应用可能的修复：

cargo fix

供应链检查

• 检查依赖项的供应链：

cargo deny check

• 更新 Cargo.lock 中的依赖项：

cargo update

版本发布

• 预发布测试：

cargo release patch

• 创建正式版本：

cargo release patch --execute

连接说明

连接 MCP 客户端

按照客户端的说明，使用已部署服务器的 /mcp URL（例如 http://localhost:8000/mcp）进行连接。

VSCode GitHub Copilot 连接

通过 VSCode 界面添加新的 MCP 服务器：

• 打开命令面板（ctrl+shift+p 或 cmd+shift+p）
• 搜索 MCP: Add Server...
• 选择 HTTP，并提供 MCP 服务器 URL http://localhost:8000/mcp

你的 VSCode mcp.json 文件应如下所示：

{
    "servers": {
        "data-commons-mcp-server": {
            "url": "http://localhost:8000/mcp",
            "type": "http"
        }
    },
    "inputs": []
}

🔧 技术细节

该项目使用 Rust 语言开发，借助了多个开源库来实现其功能。

• 使用 rmcp 实现流式 HTTP 传输。
• 使用 axum、utoipa 生成 OpenAPI 规范。
• 使用 llm 与大语言模型提供商进行交互。

通过这些技术，项目能够高效地处理用户请求，搜索相关数据，并提供流式响应。同时，项目还提供了丰富的开发工具和命令，如代码格式化、检查、供应链检查和版本发布等，方便开发者进行开发和维护。