Standards Explorer MCP

Bridge2AI标准浏览器MCP

Bridge2AI标准浏览器的模型上下文协议（MCP）服务器，提供使用SQL从Synapse平台搜索和查询标准数据的工具。

概述

此MCP服务器提供对Bridge2AI标准资源管理器表的编程访问(syn63096833)在Synapse上，使LLM应用程序能够通过Synapse表查询API查询和检索标准信息。服务器使用FastMCP，并通过自动轮询实现Synapse的异步查询模式。

特性

• 基于SQL的表查询：直接对Bridge2AI标准资源管理器表执行SQL查询
• 文本搜索：方便的搜索工具，用于跨多列查找文本
• 异步作业处理：通过轮询自动处理Synapse的异步查询模式
• 分页支持：控制分页查询的结果数量和偏移量
• 表信息：获取有关Bridge2AI标准资源管理器表和项目的元数据

工具

query_table

直接对Bridge2AI标准资源管理器表执行SQL查询。

参数：

• sql_query （str，必填）：要执行的SQL查询字符串（例如。， "SELECT * FROM syn63096833 WHERE name LIKE '%FHIR%' LIMIT 10")
• max_wait_seconds （int，可选）：等待查询结果的最长时间（默认值：30）

退货： 包含以下内容的词典：

• success：布尔值，指示查询是否成功
• sql_query：执行的SQL查询
• row_count：返回的行数
• total_rows：匹配行总数
• columns：包含名称和类型的列定义数组
• rows：结果行及其数据的数组

示例查询：

-- Simple query
SELECT * FROM syn63096833 LIMIT 10

-- Search for FHIR standards
SELECT * FROM syn63096833 WHERE Standard LIKE '%FHIR%'

-- Search across multiple columns
SELECT id, Standard, ShortDescription 
FROM syn63096833 
WHERE ShortDescription LIKE '%metadata%' 
LIMIT 5

-- Complex filtering with pagination
SELECT id, Standard, Category 
FROM syn63096833 
WHERE Standard LIKE '%format%' 
  AND Category IS NOT NULL
LIMIT 10 OFFSET 5

search_standards

在Bridge2AI标准资源管理器表中搜索文本（方便包装 query_table).

参数：

• search_text （str，必填）：要搜索的文本（不区分大小写）
• columns_to_search （list\[str\]，可选）：要搜索的列名列表（默认值： ["Standard", "ShortDescription"])
• max_results （int，可选）：返回的最大结果数（默认值：10）
• offset （int，可选）：分页时要跳过的结果数（默认值：0）

退货： 格式与 query_table，加上：

• search_text：原始搜索文本
• searched_columns：搜索的列列表

例子：

# Search in default columns (Standard, ShortDescription)
result = await client.call_tool(
    "search_standards",
    {"search_text": "FHIR", "max_results": 5}
)

# Search in custom columns
result = await client.call_tool(
    "search_standards",
    {
        "search_text": "metadata",
        "columns_to_search": ["ShortDescription", "LongDescription"],
        "max_results": 10
    }
)

get_standards_table_info

获取有关Bridge2AI标准资源管理器表的信息。

退货： 包含表格和项目信息的词典，包括：

• table_id：表的Synapse ID
• project_id：项目的Synapse ID
• 在Synapse上查看表和项目的URL

安装

# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

开发安装

对于具有测试依赖关系的开发：

uv pip install -e ".[dev]"

配置

服务器配置为查询：

• 表id: syn63096833 （Bridge2AI标准浏览器表）
• 项目ID: syn63096806 （Bridge2AI标准浏览器项目）
• 基础URL: https://repo-prod.prod.sagebase.org
• 认证：可选通过 SYNAPSE_AUTH_TOKEN 环境变量（见下文）

身份验证（可选）

此MCP仅访问公共Synapse表，因此不需要身份验证。如果出于某种原因你仍然需要它，请执行以下操作。

对于经过身份验证的访问，请设置 SYNAPSE_AUTH_TOKEN 环境变量：

export SYNAPSE_AUTH_TOKEN="your_synapse_personal_access_token"

要获取Synapse个人访问令牌：

1. 登录到 突触
2. 转到帐户设置→ 个人访问令牌
3. 创建具有适当作用域的新令牌（至少：查看、下载）

用法

运行服务器

# Using uv (recommended)
uv run standards-explorer-mcp

# Or using the CLI entry point directly
standards-explorer-mcp

# Or using Python module
python -m standards_explorer_mcp

服务器使用MCP协议通过stdio进行通信，并将等待来自MCP客户端的消息。

与MCP客户端一起使用

使用FastMCP客户端的示例：

from fastmcp import Client

async with Client("standards-explorer-mcp") as client:
    # Execute a SQL query
    results = await client.call_tool(
        name="query_table",
        arguments={"sql_query": "SELECT * FROM syn63096833 WHERE Standard LIKE '%FHIR%' LIMIT 5"}
    )
    print(results.data)
    
    # Search for text across columns
    results = await client.call_tool(
        name="search_standards",
        arguments={"search_text": "metadata", "max_results": 5}
    )
    print(results.data)
    
    # Get table information
    info = await client.call_tool(name="get_standards_table_info")
    print(info.data)

客户端示例

完整的示例客户端可在 tests/example_client.py:

uv run python tests/example_client.py

测试

运行所有测试

# Run complete test suite
uv run pytest tests/ -v

# Run with coverage report
uv run pytest tests/ --cov=src/standards_explorer_mcp --cov-report=html

注： 集成测试使用FastMCP的内存传输，自动启动和停止服务器，无需手动启动服务器！

建筑

实施方法

服务器使用 Synapse的表查询API 它提供特定于表的SQL查询功能：

异步作业模式：

1. 张贴到 /entity/{id}/table/query/async/start → 回报 asyncToken
2. 投票前往 /entity/{id}/table/query/async/get/{asyncToken}

- 处理时返回202已接受 - 完成后返回200 OK和结果

1. 每隔1秒自动重试
2. 可配置超时（默认30秒）

优点：

• ✅ 表特定查询（仅来自syn63096833的结果）
• ✅ 完全支持SQL WHERE子句
• ✅ 用于子字符串匹配的LIKE运算符
• ✅ 灵活的立柱选择
• ✅ 内置带LIMIT/OFFSET的分页功能
• ✅ 没有来自其他Synapse实体的交叉污染

编码结构

该实现将业务逻辑与MCP装饰器分离，以实现可测试性：

# Implementation function (testable)
async def query_table_impl(sql_query: str, max_wait_seconds: int = 30) -> dict:
    # Business logic here
    ...

# MCP Wrapper (thin layer)
@mcp.tool
async def query_table(sql_query: str, max_wait_seconds: int = 30) -> dict:
    return await query_table_impl(sql_query, max_wait_seconds)

这种设计允许：

• 无需模拟MCP框架即可直接测试业务逻辑
• 快速测试执行
• 易于调试
• 明确区分关注点

发展

项目结构

standards-explorer-mcp/
├── src/
│   └── standards_explorer_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       └── main.py          # Main server implementation
├── tests/
│   ├── conftest.py          # Shared test fixtures
│   ├── test_api_endpoints.py    # API layer tests
│   ├── test_tools.py            # Business logic tests
│   ├── test_mcp_integration.py  # Integration tests
│   └── example_client.py        # Example usage
├── pyproject.toml           # Project configuration
└── README.md

依赖项

• fastmcp>=2.12.5 -MCP服务器框架
• httpx>=0.27.0 -API调用的异步HTTP客户端
• pytest>=8.0.0 -测试框架（开发）
• pytest-asyncio>=0.23.0 -异步测试支持（开发）

资源

• Synapse REST API文档
• FastMCP文档
• 模型上下文协议规范
• Synapse上的Bridge2AI标准浏览器
• Bridge2AI标准浏览器表

故障排除

服务器无法启动

确保已安装依赖项：

uv pip install -e .

查询失败

• 检查互联网连接 repo-prod.prod.sagebase.org
• 验证SQL语法是否正确
• 对于私人桌子，请确保 SYNAPSE_AUTH_TOKEN 已设置

测试失败

• 确保您具有开发依赖关系： uv pip install -e ".[dev]"
• 检查您是否可以通过网络访问Synapse API
• 某些测试可能需要身份验证才能实现完整功能

身份验证问题

• 验证您的令牌是否有效且未过期
• 确保令牌具有适当的作用域（查看、下载）
• 检查环境变量是否正确导出

支持

关于以下问题：

• FastMCP: https://discord.gg/uu8dJCgttd或https://github.com/jlowin/fastmcp
• API突触: https://help.synapse.org/
• MCP协议: https://github.com/modelcontextprotocol