关键词

Synapse科研数据数据服务LLM上下文OAuth2

Synapse MCP Server 使用说明

项目简介

Synapse MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为大型语言模型 (LLM) 应用提供对 Synapse 科研数据平台的结构化访问能力。通过该服务，LLM 可以安全、高效地获取 Synapse 中的数据集、项目、文件、表格等资源及其元数据，并利用预置工具执行数据查询和检索操作。

主要功能点

  • 资源访问 (Resources):
    • 提供 RESTful API 访问 Synapse 中的实体 (Entities)，包括项目 (Projects)、数据集 (Datasets)、文件夹 (Folders)、文件 (Files) 和表格 (Tables)。
    • 支持通过 ID 或名称检索实体，获取实体的基本信息、注释 (Annotations) 和子实体 (Children)。
    • 提供基于实体类型、父 ID、名称等条件查询实体的功能。
    • 支持查询 Synapse 表格数据，并以 JSON 格式返回结果。
    • 可以 Croissant metadata 格式获取公共数据集信息。
  • 工具调用 (Tools):
    • 提供工具 API，支持通过 Synapse 账户的 Auth Token 或 OAuth2 方式进行身份验证。
    • 提供获取 OAuth2 授权 URL 的工具，支持 OAuth2 授权流程。
    • 提供多种数据查询工具，如按 ID/名称获取实体、获取实体注释、获取子实体、查询实体、查询表格等。
  • 安全认证:
    • 支持基于 Synapse Auth Token 的认证方式。
    • 支持基于 Synapse OAuth2 的认证方式，保障数据访问安全。
  • 部署灵活:
    • 支持本地标准输入/输出 (stdio) 和云端 Server-Sent Events (SSE) 等多种传输协议。
    • 提供 Docker 镜像和 Fly.io 部署指南，方便快速部署和扩展。

安装步骤

  1. 克隆仓库

    git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

  2. 创建并激活虚拟环境 (推荐)

    python -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows

  3. 安装依赖

    pip install -e .

    或者从 PyPI 安装:

    pip install synapse-mcp

服务器配置 (MCP 客户端配置)

要将 Synapse MCP Server 集成到 MCP 客户端（例如 Claude Desktop），您需要配置 MCP 服务器的启动命令和参数。以下是一个示例 JSON 配置，请根据您的实际环境进行调整：

{
  "synapse-mcp": {
    "command": "python",
    "args": [
      "/path/to/synapse-mcp/server.py",  // 请替换为 server.py 脚本的实际路径
      "--host", "127.0.0.1",             // 服务器监听地址，默认为本地地址
      "--port", "9000"                    // 服务器监听端口，默认为 9000
    ]
  }
}

参数说明:

  • 'command': 启动服务器的命令，通常为 'python' 或 'python3'。
  • 'args': 传递给 'server.py' 脚本的参数列表：
    • '/path/to/synapse-mcp/server.py': [必填] 'server.py' 脚本的绝对路径。请根据您克隆仓库的实际位置修改。
    • '--host': [可选] 指定服务器绑定的主机地址。默认为 '127.0.0.1' (本地地址)。如果需要从外部访问，请设置为服务器的公共 IP 或域名。
    • '--port': [可选] 指定服务器监听的端口。默认为 '9000'。可以根据需要修改端口号。

注意:

  • '/path/to/synapse-mcp/server.py' 需要替换为 'server.py' 脚本在您本地文件系统中的绝对路径。例如，如果您将仓库克隆到 '/Users/yourusername/Documents/synapse-mcp'，则路径应为 '/Users/yourusername/Documents/synapse-mcp/server.py'。
  • 确保 MCP 客户端能够访问到您配置的服务器地址和端口。

基本使用方法

  1. 启动服务器 在仓库根目录下，运行以下命令启动 Synapse MCP Server：

    python server.py --host 127.0.0.1 --port 9000

    或使用 CLI 方式：

    synapse-mcp --host 127.0.0.1 --port 9000

  2. 通过 MCP 客户端连接 配置 MCP 客户端，使其连接到运行中的 Synapse MCP Server。具体的配置方法请参考 MCP 客户端的文档。在配置中，您需要提供服务器的地址 (例如 'http://127.0.0.1:9000') 以及上面生成的启动命令配置。

  3. 使用示例 (通过 HTTP 请求) 以下是一些通过 HTTP 请求与服务器交互的示例，您可以使用 'curl' 或 'requests' 等工具进行测试：

    • 获取服务器信息:

      curl http://127.0.0.1:9000/info

    • 列出可用工具:

      curl http://127.0.0.1:9000/tools

    • 获取实体信息 (替换 'syn123456' 为实际 Synapse ID):

      curl http://127.0.0.1:9000/resources/entities/syn123456

    • 查询表格数据 (替换 'syn123456' 和 SQL 查询语句):

      curl "http://127.0.0.1:9000/resources/table/syn123456/SELECT * FROM syn123456 LIMIT 10"

    • 使用工具进行身份验证 (需要提供 Synapse Auth Token):

      curl -X POST -H "Content-Type: application/json" -d '{"auth_token": "YOUR_SYNAPSE_AUTH_TOKEN"}' http://127.0.0.1:9000/tools/authenticate

    更多使用示例请参考仓库 'README.md' 文件中的 "Examples" 部分。

部署

该项目提供了 Docker 和 Fly.io 部署指南，您可以根据需要选择合适的部署方式。请参考 'README.md' 文件中的 "Deployment" 部分获取详细信息。

信息

分类

数据库与文件

访问项目