Synapse MCP 服务器

模型上下文协议 (MCP) 服务器，公开 Synapse 实体（数据集、项目、文件夹、文件、表）及其注释并支持 OAuth2 身份验证。

概述

此服务器提供 RESTful API，用于通过模型上下文协议 (MCP) 访问 Synapse 实体及其注释。它允许您：

使用 Synapse 进行身份验证
通过 ID 检索实体
按名称检索实体
获取实体注释
获取实体子项
根据各种条件查询实体
查询 Synapse 表
获取 Croissant 元数据格式的数据集

Related MCP server: SourceSync.ai MCP Server

安装

# Clone the repository
git clone https://github.com/SageBionetworks/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

从 PyPI 安装

# Install from PyPI
pip install synapse-mcp

用法

启动服务器

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

这将在默认端口（9000）上启动 MCP 服务器。

使用 CLI

# Start the server using the CLI
synapse-mcp --host 127.0.0.1 --port 9000 --debug

命令行选项

usage: server.py [-h] [--host HOST] [--port PORT] [--debug]

Run the Synapse MCP server with OAuth2 support

options:
  -h, --help       show this help message and exit
  --host HOST      Host to bind to
  --port PORT      Port to listen on
  --debug          Enable debug logging
  --server-url URL Public URL of the server (for OAuth2 redirect)

运行测试

# Run all tests with coverage
./run_tests.sh

# Or run pytest directly
python -m pytest

测试服务器

python examples/client_example.py

身份验证方法

环境变量

服务器支持以下环境变量：

HOST ：要绑定的主机（默认值：127.0.0.1）
PORT ：监听的端口（默认值：9000）
MCP_TRANSPORT ：要使用的传输协议（默认值：stdio）
- stdio ：使用标准输入/输出进行本地开发
- sse ：使用服务器发送事件进行云部署
MCP_SERVER_URL ：服务器的公共 URL（默认值：mcp://127.0.0.1:9000）
- 用于 OAuth2 重定向和服务器信息

服务器支持两种认证方式：

Auth Token ：使用 Synapse 身份验证令牌进行身份验证
OAuth2 ：使用 Synapse 的 OAuth2 服务器进行身份验证
- 需要在 Synapse 中注册 OAuth2 客户端（ https://www.synapse.org/#!PersonalAccessTokens:OAuth ）

API 端点

服务器信息

GET /info获取服务器信息

工具

GET /tools - 列出可用工具
POST /tools/authenticate - 使用 Synapse 进行身份验证
POST /tools/get_oauth_url - 获取 OAuth2 授权 URL
POST /tools/get_entity - 通过 ID 或名称获取实体
POST /tools/get_entity_annotations - 获取实体的注释
POST /tools/get_entity_children - 获取容器实体的子实体
POST /tools/query_entities - 根据各种条件查询实体
POST /tools/query_table - 查询 Synapse 表

资源

GET /resources - 列出可用资源
GET /resources/entity/{id} - 通过 ID 获取实体
GET /resources/entity/{id}/annotations - 获取实体注释
GET /resources/entity/{id}/children - 获取实体子项
GET /resources/query/entities/{entity_type} - 按类型查询实体
GET /resources/query/entities/parent/{parent_id} - 通过父 ID 查询实体
GET /resources/query/entities/name/{name} - 按名称查询实体
GET /resources/query/table/{id}/{query} - 使用类似 SQL 的语法查询表

OAuth2 端点

GET /oauth/login - 重定向到 Synapse OAuth2 登录页面
GET /oauth/callback - 处理来自 Synapse 的 OAuth2 回调

示例

验证

您需要使用真实的 Synapse 凭据进行身份验证才能使用服务器：

import requests

# Authenticate with Synapse
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "email": "your-synapse-email@example.com",
    "password": "your-synapse-password"
})
result = response.json()
print(result)

# Alternatively, you can authenticate with an API key
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "api_key": "your-synapse-api-key"
})

OAuth2 身份验证

1. 重定向流程（基于浏览器）

将用户定向到 OAuth 登录 URL：

http://127.0.0.1:9000/oauth/login?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

2. 基于 API 的流程

对于程序化使用，首先获取授权URL：

import requests

# Get OAuth2 authorization URL
response = requests.post("http://127.0.0.1:9000/tools/get_oauth_url", json={
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "YOUR_REDIRECT_URI"
})
auth_url = response.json()["auth_url"]
# Redirect user to auth_url

获取实体

import requests

# Get an entity by ID
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456")  # Replace with a real Synapse ID
entity = response.json()
print(entity)

获取实体注释

import requests

# Get annotations for an entity
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456/annotations")  # Replace with a real Synapse ID
annotations = response.json()
print(annotations)

查询实体

import requests

# Query for files in a project
response = requests.get("http://127.0.0.1:9000/resources/query/entities/parent/syn123456", params={  # Replace with a real Synapse ID
    "entity_type": "file"
})
files = response.json()
print(files)

查询表

import requests

# Query a table
table_id = "syn123456"  # Replace with a real Synapse table ID
query = "SELECT * FROM syn123456 LIMIT 10"  # Replace with a real Synapse table ID
response = requests.get(f"http://127.0.0.1:9000/resources/query/table/{table_id}/{query}")
table_data = response.json()
print(table_data)

获取 Croissant 格式的数据集

import requests
import json

# Get public datasets in Croissant format
response = requests.get("http://127.0.0.1:9000/resources/croissant/datasets")
croissant_data = response.json()

# Save to file
with open("croissant_metadata.json", "w") as f:
    json.dump(croissant_data, f, indent=2)

部署

Docker

您可以使用 Docker 构建并运行服务器：

# Build the Docker image
docker build -t synapse-mcp .

# Run the container
docker run -p 9000:9000 -e SYNAPSE_OAUTH_CLIENT_ID=your_client_id -e SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret -e SYNAPSE_OAUTH_REDIRECT_URI=your_redirect_uri synapse-mcp
docker run -p 9000:9000 -e MCP_TRANSPORT=sse -e MCP_SERVER_URL=mcp://your-domain:9000 synapse-mcp

Fly.io

部署到 fly.io：

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login to fly.io
flyctl auth login

# Launch the app
flyctl launch

# Set OAuth2 secrets
flyctl secrets set SYNAPSE_OAUTH_CLIENT_ID=your_client_id
flyctl secrets set SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret
flyctl secrets set SYNAPSE_OAUTH_REDIRECT_URI=https://your-app-name.fly.dev/oauth/callback
flyctl secrets set MCP_TRANSPORT=sse
flyctl secrets set MCP_SERVER_URL=mcp://your-app-name.fly.dev:9000

# Deploy
flyctl deploy

与 Claude Desktop 集成

您可以将此 Synapse MCP 服务器与 Claude Desktop 集成，以使 Claude 能够在您的对话中直接访问和使用 Synapse 数据。

设置说明

首先，克隆存储库并安装要求：

# Clone the repository
git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

配置 Claude Desktop 以使用 Synapse MCP 服务器：
- 打开 Claude 桌面
- 点击 Claude 菜单并选择“设置...”
- 点击左侧栏中的“开发者”
- 点击“编辑配置”
- 将以下配置添加到mcpServers部分：

"synapse-mcp": {
  "command": "python",
  "args": [
    "/path/to/synapse-mcp/server.py",
    "--host", "127.0.0.1",
    "--port", "9000"
  ]
}

保存配置文件并重新启动Claude Desktop
您现在可以在与 Claude 的对话中使用 Synapse 数据。例如：
- “从 Synapse 获取 ID 为 syn123456 的实体”
- “查询Synapse项目syn123456中的所有文件”
- “获取 Synapse 实体 syn123456 的注释”

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

麻省理工学院

Synapse MCP Server