项目简介

Synapse MCP 服务器是基于Model Context Protocol (MCP) 构建的应用后端，旨在为大型语言模型（LLM）客户端提供访问Synapse数据平台（Sage Bionetworks）的标准化接口。它允许AI代理通过定义好的工具和资源，检索Synapse实体（如项目、文件夹、文件、表格）、获取批注、列出子实体、搜索以及查询实体溯源信息。该服务器支持多用户隔离和灵活的身份验证机制（OAuth2或个人访问令牌PAT）。

主要功能点

实体检索: 根据ID获取Synapse实体的核心元数据，支持项目、文件夹、文件、表格等多种类型。
批注获取: 检索与Synapse实体关联的自定义批注（annotations）。
溯源查询: 获取Synapse实体的溯源（provenance）和活动记录，可按版本进行查询，了解数据生成过程。
子实体列表: 列出项目或文件夹等容器实体的所有子实体。
全局搜索: 通过关键词、实体类型、父ID等过滤器在整个Synapse数据平台中进行高级搜索。
Sage Blog RSS资源: 提供Sage Bionetworks最新博客文章的实时RSS XML订阅。
多用户认证: 支持OAuth2（推荐用于生产环境）和个人访问令牌（PAT，适用于开发环境）两种认证方式，确保不同用户的数据访问隔离和安全。

安装步骤

克隆仓库:

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

创建并激活虚拟环境:

python3 -m venv venv
source venv/bin/activate

安装依赖:

pip install -e .
# 如果需要Redis支持，请额外安装：
# pip install "redis[async]"

服务器配置

MCP客户端需要配置MCP服务器的连接信息。以下是一个JSON格式的配置示例，包含服务器名称、启动命令和参数。请注意，这里的启动命令和参数是用户在自己的环境中运行服务器时所需的指令，而不是MCP客户端直接执行的代码。

{
  "name": "Synapse MCP 服务器",
  "command": "python3",
  "args": [
    "-m",
    "synapse_mcp",
    "--http",
    "--host", "127.0.0.1",
    "--port", "9000",
    "--debug"
  ],
  "comment_args": {
    "-m synapse_mcp": "指定Python模块运行Synapse MCP服务器。",
    "--http": "启用HTTP传输协议。服务器将作为一个Web服务运行，而非通过标准输入/输出。",
    "--host 127.0.0.1": "指定服务器监听的IP地址。对于本地运行，通常设置为 '127.0.0.1'。",
    "--port 9000": "指定服务器监听的端口号。可以根据需要更改，例如 '5000'。",
    "--debug": "启用调试日志输出，帮助诊断问题（可选）。"
  },
  "environment_variables_notes": {
    "SYNAPSE_PAT": "Synapse个人访问令牌 (PAT)，用于开发模式的认证。如果使用OAuth2，则无需此项。",
    "SYNAPSE_OAUTH_CLIENT_ID": "OAuth2客户端ID，用于生产模式的OAuth认证。",
    "SYNAPSE_OAUTH_CLIENT_SECRET": "OAuth2客户端密钥，用于生产模式的OAuth认证。",
    "MCP_SERVER_URL": "MCP服务器的公开URL，用于OAuth回调等，例如 'http://127.0.0.1:9000/mcp'。服务器会自动处理 '/mcp' 后缀。",
    "REDIS_URL": "Redis数据库的URL，用于持久化会话存储。例如 'redis://localhost:6379/0'。如果未配置，将使用内存存储。"
  }
}

基本使用方法

启动服务器: 在您的终端中，根据您的认证方式（PAT或OAuth2）和所需的传输协议（HTTP为推荐），使用以下命令启动服务器。

使用PAT认证（开发模式）:

export SYNAPSE_PAT="YOUR_SYNAPSE_PERSONAL_ACCESS_TOKEN" # 将 YOUR_SYNAPSE_PERSONAL_ACCESS_TOKEN 替换为您的实际PAT
python3 -m synapse_mcp --http --host 127.0.0.1 --port 9000

使用OAuth2认证（生产模式，需要先注册OAuth客户端）:

export SYNAPSE_OAUTH_CLIENT_ID="YOUR_CLIENT_ID" # 替换为您的OAuth客户端ID
export SYNAPSE_OAUTH_CLIENT_SECRET="YOUR_CLIENT_SECRET" # 替换为您的OAuth客户端密钥
export MCP_SERVER_URL="http://127.0.0.1:9000/mcp" # 替换为服务器的公开URL
python3 -m synapse_mcp --http --host 127.0.0.1 --port 9000

服务器启动后，将在指定端口监听请求。

使用MCP客户端连接: 根据您使用的MCP客户端（如Claude），按照其说明连接到服务器。对于远程部署的服务器，连接URL为 'https://mcp.synapse.org/mcp'。对于本地运行的服务器，URL通常是 'http://127.0.0.1:9000/mcp'。

例如，在Claude中添加自定义连接器（假设服务器运行在 'http://127.0.0.1:9000'）：
- 进入 Settings > Connectors > Add custom connector
- 输入您的本地服务器URL 'http://127.0.0.1:9000/mcp'
通过代码连接（例如，使用Claude CLI）：
```
claude mcp add --transport http synapse-local -- https://127.0.0.1:9000/mcp
```
与AI代理交互（示例提示）： 一旦连接成功，您可以通过AI代理使用服务器提供的工具和资源。例如：
- "获取ID为 'syn123456' 的Synapse项目信息。" (调用 'get_entity' 工具)
- "查找所有名称中包含 'COVID' 的文件。" (调用 'search_synapse' 工具)
- "列出项目 'syn789012' 下的所有子实体。" (调用 'get_entity_children' 工具)
- "显示Sage Bionetworks的最新博客文章。" (访问 'synapse://feeds/blog' 资源)

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息