Synapse MCP Server

Synapse MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它通过 RESTful API 暴露 Synapse 实体（数据集、项目、文件夹、文件、表格）及其注释，从而实现对 Synapse 数据资源进行编程访问。

Category
访问服务器

README

Synapse MCP 服务器

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

概述

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

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

安装

# 克隆存储库
git clone https://github.com/SageBionetworks/synapse-mcp.git
cd synapse-mcp

# 创建一个虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖项
pip install -e .

从 PyPI 安装

# 从 PyPI 安装
pip install synapse-mcp

用法

启动服务器

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

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

使用 CLI

# 使用 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_tests.sh

# 或者直接运行 pytest
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 重定向和服务器信息

服务器支持两种身份验证方法：

  1. Auth Token: 使用 Synapse 身份验证令牌进行身份验证
  2. 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

# 使用 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)

# 或者，您可以使用 API 密钥进行身份验证
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

# 获取 OAuth2 授权 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"]
# 将用户重定向到 auth_url

获取实体

import requests

# 按 ID 获取实体
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456")  # 替换为真实的 Synapse ID
entity = response.json()
print(entity)

获取实体注释

import requests

# 获取实体的注释
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456/annotations")  # 替换为真实的 Synapse ID
annotations = response.json()
print(annotations)

查询实体

import requests

# 查询项目中的文件
response = requests.get("http://127.0.0.1:9000/resources/query/entities/parent/syn123456", params={  # 替换为真实的 Synapse ID
    "entity_type": "file"
})
files = response.json()
print(files)

查询表格

import requests

# 查询表格
table_id = "syn123456"  # 替换为真实的 Synapse 表格 ID
query = "SELECT * FROM syn123456 LIMIT 10"  # 替换为真实的 Synapse 表格 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

# 以 Croissant 格式获取公共数据集
response = requests.get("http://127.0.0.1:9000/resources/croissant/datasets")
croissant_data = response.json()

# 保存到文件
with open("croissant_metadata.json", "w") as f:
    json.dump(croissant_data, f, indent=2)

部署

Docker

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

# 构建 Docker 镜像
docker build -t synapse-mcp .

# 运行容器
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：

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

# 登录到 fly.io
flyctl auth login

# 启动应用程序
flyctl launch

# 设置 OAuth2 密钥
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

# 部署
flyctl deploy

与 Claude Desktop 集成

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

设置说明

  1. 首先，克隆存储库并安装要求：
# 克隆存储库
git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

# 创建一个虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖项
pip install -e .

  1. 配置 Claude Desktop 以使用 Synapse MCP 服务器：

    • 打开 Claude Desktop
    • 单击 Claude 菜单并选择“Settings...”
    • 单击左侧栏中的“Developer”
    • 单击“Edit Config”
    • 将以下配置添加到 mcpServers 部分：
"synapse-mcp": {
  "command": "python",
  "args": [
    "/path/to/synapse-mcp/server.py",
    "--host", "127.0.0.1",
    "--port", "9000"
  ]
}

  1. 保存配置文件并重新启动 Claude Desktop

  2. 您现在可以在与 Claude 的对话中使用 Synapse 数据。例如：

    • "Get the entity with ID syn123456 from Synapse"
    • "Query all files in the Synapse project syn123456"
    • "Get annotations for the Synapse entity syn123456"

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选