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 與大語言模型提供商進行交互。

通過這些技術，項目能夠高效地處理用戶請求，搜索相關數據，並提供流式響應。同時，項目還提供了豐富的開發工具和命令，如代碼格式化、檢查、供應鏈檢查和版本發佈等，方便開發者進行開發和維護。