星战科技xingzhan.cloud
返回市场
数据共享mcp

数据共享mcp

作者：EOSC-Data-Commons9 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

🔭 EOSC 数据共享 MCP 服务器

构建 Docker 镜像 PyPI - 版本 PyPI - Python 版本

这是一个 模型上下文协议（MCP） 服务器，它暴露了一个 HTTP POST 端点，用于从各种开放访问的数据发布者获取数据，该服务器是为 EOSC 数据共享项目开发的。

它使用一个搜索 API 和一个大型语言模型（LLM）来帮助用户找到他们需要的数据集和工具。

🧩 端点

HTTP API 包含两个主要端点：

  • /mcp: MCP 服务器，使用 EOSC 数据共享 OpenSearch 服务搜索相关数据以回答用户的问题
    • 使用可流式传输的 HTTP 传输
    • 可用工具：
      • 搜索数据集
      • 获取数据集中文件的元数据（名称、描述、文件类型）
      • 搜索工具
      • 搜索与数据集或工具相关的引用
  • /chat: HTTP POST 端点（JSON），通过 LLM 提供商与 MCP 服务器工具进行聊天（部署时通过环境变量提供 API 密钥）
    • 流式传输符合 AG-UI 协议 的 Server-Sent Events (SSE) 响应

[!TIP]

它也可以仅作为 MCP 服务器通过 pip 包使用。

🔌 连接客户端到 MCP 服务器

系统可以直接作为 MCP 服务器使用，采用 STDIO 或可流式传输的 HTTP 传输。

[!WARNING]

您需要访问预索引的 OpenSearch 实例，以便 MCP 服务器能够正常工作。

遵循客户端的说明，并使用您已部署服务器的 /mcp URL（例如 http://localhost:8000/mcp）

要向 VSCode GitHub Copilot 添加新的 MCP 服务器：

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

您的 VSCode mcp.json 应如下所示：

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

或者使用 STDIO 传输：

{
   "servers": {
      "data-commons-mcp": {
         "type": "stdio",
         "command": "uvx",
         "args": ["data-commons-mcp"],
         "env": {
            "OPENSEARCH_URL": "OPENSEARCH_URL"
         }
      }
   }
}

或者使用本地文件夹进行开发：

{
   "servers": {
      "data-commons-mcp": {
         "type": "stdio",
         "cwd": "~/dev/data-commons-mcp",
         "env": {
            "OPENSEARCH_URL": "OPENSEARCH_URL"
         },
         "command": "uv",
         "args": ["run", "data-commons-mcp"]
      }
   }
}

🛠️ 开发

[!IMPORTANT]

要求：

  • uv，用于轻松处理脚本和虚拟环境
  • docker，用于部署 OpenSearch 服务（或访问正在运行的实例）
  • LLM 提供商的 API 密钥：e-infra CZ，Mistral.ai，或 OpenRouter

📥 安装开发依赖

uv sync --extra agent

安装 pre-commit 钩子：

uv run pre-commit install

创建一个包含您的 LLM 提供商 API 密钥的 keys.env 文件：

EINFRACZ_API_KEY=YOUR_API_KEY
MISTRAL_API_KEY=YOUR_API_KEY
OPENROUTER_API_KEY=YOUR_API_KEY

⚡️ 启动开发服务器

在 http://localhost:8000 启动开发服务器，MCP 端点位于 http://localhost:8000/mcp

uv run uvicorn src.data_commons_mcp.main:app --log-config logging.yml --reload

默认 OPENSEARCH_URL=http://localhost:9200

通过环境变量自定义服务器配置：

SERVER_PORT=8001 OPENSEARCH_URL=http://localhost:9200 uv run uvicorn src.data_commons_mcp.main:app --host 0.0.0.0 --port 8001 --log-config logging.yml --reload

[!TIP]

示例 curl 请求：

curl -X POST http://localhost:8000/chat \
	-H "Content-Type: application/json" -H "Authorization: SECRET_KEY" \
	-d '{"messages": [{"role": "user", "content": "来自瑞士的教育数据集，涵盖学生评估、语言能力以及学习成果，包括对学童或学生的实验性或纵向研究。"}], "model": "einfracz/qwen3-coder"}'

推荐的模型按支持的提供商：

  • einfracz/qwen3-coder 或 einfracz/gpt-oss-120b（较小，更快）
  • mistralai/mistral-medium-latest（较大的较旧，且在调用工具方面不如前者）
  • groq/moonshotai/kimi-k2-instruct
  • openai/gpt-4.1

[!IMPORTANT]

要构建并集成前端 Web 应用到服务器，请从 前端文件夹 运行：

npm run build && rm -rf ../data-commons-mcp/src/data_commons_mcp/webapp/ && cp -R dist/spa/ ../data-commons-mcp/src/data_commons_mcp/webapp/

📦 构建生产版本

在 dist/ 中构建二进制文件

uv build

🐳 使用 Docker 部署

创建一个包含 API 密钥的 keys.env 文件：

EINFRACZ_API_KEY=YOUR_API_KEY
MISTRAL_API_KEY=YOUR_API_KEY
OPENROUTER_API_KEY=YOUR_API_KEY
SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM

[!TIP]

SEARCH_API_KEY 可用于防止可能的垃圾邮件攻击 LLM 的机器人，如果没有提供，则无需 API 密钥即可查询 API。

您可以使用预构建的 Docker 镜像 ghcr.io/eosc-data-commons/data-commons-mcp:main

示例 compose.yml：

services:
  mcp:
    image: ghcr.io/eosc-data-commons/data-commons-mcp:main
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      OPENSEARCH_URL: "http://opensearch:9200"
      EINFRACZ_API_KEY: "${EINFRACZ_API_KEY}"

构建并部署服务：

docker compose up

[!IMPORTANT]

当前部署到暂存服务器的操作是通过 GitHub Actions 在每次推送到 main 分支时自动执行的。

当推送发生时，工作流程将：

  • 从前端仓库拉取 main 分支
  • 构建前端，并将其添加到 src/data_commons_mcp/webapp
  • 构建服务器的 Docker 镜像
  • 将 Docker 镜像发布为 main/latest
  • 暂存基础设施随后会自动拉取 latest 版本的镜像并进行部署。

✅ 运行测试

[!CAUTION]

您需要首先在端口 8001 上启动服务器（参见启动开发服务器部分）

uv run pytest

调试时显示所有日志：

uv run pytest -s

🧹 格式化代码和类型检查

uvx ruff format
uvx ruff check --fix
uv run mypy

♻️ 重置环境

升级 uv：

uv self update

清理 uv 缓存：

uv cache clean

🏷️ 发布过程

[!IMPORTANT]

在 pypi.org/manage/account 获取 PyPI API 令牌。

运行发布脚本，提供版本提升：fix，minor，或 major

.github/release.sh fix

[!TIP]

将您的 PyPI 令牌添加到您的环境中，例如在 ~/.zshrc 或 ~/.bashrc 中：

export UV_PUBLISH_TOKEN=YOUR_TOKEN

🤝 致谢

LLM 提供商 einfracz 是由 e-INFRA CZ 提供的服务，并由 CERIT-SC 摩拉维亚大学运营。

计算资源由 e-INFRA CZ 项目（ID:90254）提供，该项目得到了捷克共和国教育部、青年和体育部的支持。