Bertron MCP

伯特伦·麦克普

模型上下文协议（MCP）服务器，提供对BERtron API的访问，该服务器聚合来自多个生物和环境研究（BER）数据源的基因组和环境数据，包括EMSL、ESS-DIVE、JGI、MONET和NMDC。

快速开始

直接从GitHub安装并运行

# Run directly without installing
uvx --from git+https://github.com/ber-data/bertron-mcp.git bertron-mcp

# Or install first, then run
uvx --from git+https://github.com/ber-data/bertron-mcp.git bertron-mcp --version

特性

• 🔍 地理空间搜索：查找指定地理坐标半径内的实体
• 💊 健康检查：验证BERtron API连接和数据库状态
• 🌍 多源数据：访问主要BER研究设施的数据
• 🔌 MCP集成：与Claude、Goose和其他MCP兼容的AI工具无缝集成

需求

• Python 3.12+
• UV包管理器（推荐）
• 访问BERtron API(https://bertron-api.bertron.production.svc.spin.nersc.org)

安装

来源（发展）

git clone https://github.com/ber-data/bertron-mcp.git
cd bertron-mcp
make dev

来自PyPI（即将推出）

pip install bertron-mcp

可用工具

geosearch

搜索地理坐标指定距离内的实体。

参数：

• latitude （浮动）：纬度坐标（-90.0到90.0）
• longitude （浮动）：经度坐标（-180.0到180.0）
• search_radius_km （浮动，可选）：搜索半径，单位为公里（默认值：1.0）

退货： 包含实体、计数和元数据的QueryResponse

bbox_search

在矩形地理边界框内搜索实体。

参数：

• southwest_lat （浮动）：西南角纬度（-90.0至90.0）
• southwest_lng （浮动）：西南角经度（-180.0至180.0）
• northeast_lat （浮动）：东北角纬度（-90.0至90.0）
• northeast_lng （浮动）：东北角经度（-180.0至180.0）

退货： 具有边界框内实体的QueryResponse

entity_lookup

通过特定实体的唯一ID检索其详细信息。

参数：

• entity_id （string）：实体的唯一标识符（例如，“nmdc:bsm-12-abc123”）

退货： 具有完整元数据的实体对象

advanced_query

通过过滤、投影和排序执行复杂的MongoDB查询。

参数：

• filter_dict （dict，可选）：MongoDB过滤条件（例如，{“entity_type”：“sample”}）
• projection （dict，可选）：要包含/排除的字段（例如，{“name”：1，“coordinates”：1}）
• skip （int，可选）：分页时要跳过的文档数（默认值：0）
• limit （int，可选）：要返回的最大文档数（默认值：100）
• sort （dict，可选）：排序条件（例如，{“name”：1}表示升序）

退货： 具有匹配实体的QueryResponse

search_by_source

从特定的BER数据源中查找实体。

参数：

• source （string）：BER数据源名称（EMSL、ESS-DIVE、JGI、NMDC、MONET）

退货： QueryResponse包含来自指定源的实体

search_by_type

查找特定实体类型的实体。

参数：

• entity_type （string）：实体类型（生物数据、样本、序列、分类群、jgi_biosample）

退货： 具有指定类型实体的QueryResponse

search_by_name

使用正则表达式模式匹配按名称搜索实体。

参数：

• name_pattern （string）：要搜索的名称模式（支持正则表达式）
• case_sensitive （bool，可选）：搜索是否应区分大小写（默认值：False）

退货： 具有与名称模式匹配的实体的QueryResponse

health_check

检查BERtron API的运行状况。

参数： 无

退货： 带web_server和数据库布尔状态的词典

API限制和约束

为了防止压倒性的响应并保护系统资源，执行了以下限制：

默认限制

• 默认结果限制：每个查询100个项目
• 最大结果限制：每个查询1000个项目
• 最大分页偏移量：50000个项目

约束报告

应用限制时，工具会自动在响应元数据中报告约束：

{
  "entities": [...],
  "count": 1000,
  "metadata": {
    "constraints_applied": {
      "requested_limit": 5000,
      "actual_limit": 1000,
      "reason": "Exceeded maximum limit of 1000"
    }
  }
}

具有限制参数的工具

以下工具接受可选 limit 参数：

• search_by_source(source, limit=100)
• search_by_type(entity_type, limit=100)
• search_by_name(name_pattern, case_sensitive=False, limit=100)
• advanced_query(filter_dict=None, limit=100, skip=0, ...)

安全功能

• advanced_query 需要筛选条件以防止意外的完整数据库转储
• 所有限制都是通过自动约束报告在服务器端强制执行的
• 阻止深度分页（跳过>50000）以防止性能问题

设置

发展

安装开发依赖项：

make dev

测试

运行完整的测试套件：

make all

测试特定组件：

# API integration tests
make test-integration

# MCP protocol tests  
make test-mcp
make test-mcp-extended

# Test with Claude CLI
make test-claude-mcp

# Version check
make test-version

MCP集成

Claude桌面配置

选项1：来自GitHub（推荐） 增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bertron-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ber-data/bertron-mcp.git", "bertron-mcp"]
    }
  }
}

方案2：地方发展 增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bertron-mcp": {
      "command": "uv",
      "args": ["run", "python", "src/bertron_mcp/main.py"],
      "cwd": "/path/to/bertron-mcp"
    }
  }
}

克劳德代码MCP设置

来自GitHub：

claude mcp add bertron-mcp "uvx --from git+https://github.com/ber-data/bertron-mcp.git bertron-mcp"

地方发展：

claude mcp add -s project bertron-mcp uv run python src/bertron_mcp/main.py

生产（发布到PyPI后）：

claude mcp add -s project bertron-mcp uvx bertron-mcp

鹅设置

来自GitHub：

goose session --with-extension "uvx --from git+https://github.com/ber-data/bertron-mcp.git bertron-mcp"

地方发展：

goose session --with-extension "uv run python src/bertron_mcp/main.py"

使用示例

与克劳德一起使用

Search for genomic samples near Orlando, FL within 100km radius:
> Use the bertron-mcp to search for entities near latitude 28.5383, longitude -81.3792 within 100km

Search for entities in a bounding box covering Yellowstone National Park:
> Use bbox_search to find entities between southwest corner (44.0, -125.0) and northeast corner (49.0, -110.0)

Find all NMDC sample entities:
> Search for all sample entities from the NMDC data source

Look up detailed information for a specific entity:
> Use entity_lookup to get details for entity ID "nmdc:bsm-12-abc123"

直接MCP协议

# Test geosearch tool
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "geosearch", "arguments": {"latitude": 28.5383, "longitude": -81.3792, "search_radius_km": 100.0}}, "id": 1}' | uv run python src/bertron_mcp/main.py

# Test bounding box search
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "bbox_search", "arguments": {"southwest_lat": 44.0, "southwest_lng": -125.0, "northeast_lat": 49.0, "northeast_lng": -110.0}}, "id": 2}' | uv run python src/bertron_mcp/main.py

# Test search by data source
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "search_by_source", "arguments": {"source": "NMDC"}}, "id": 3}' | uv run python src/bertron_mcp/main.py

# Test advanced query with filtering
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "advanced_query", "arguments": {"filter_dict": {"entity_type": "sample"}, "limit": 10}}, "id": 4}' | uv run python src/bertron_mcp/main.py

发展

代码质量

# Format and lint code
make format
make lint

# Type checking
make mypy

# Dependency analysis
make deptry

建筑与出版

# Build package
make build

# Full release workflow
make release

数据源

BERtron汇总了以下数据：

• EMSL -环境分子科学实验室
• ESS-DIVE -虚拟生态系统的ESS数据和信息
• 古道尔研究会 -联合基因组研究所
• 多波长光网络 -分子观测网络
• 印度国家矿业开发公司 -国家微生物组数据协作

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/your-feature
3. 进行更改并添加测试
4. 运行测试套件： make all
5. 提交您的更改： git commit -m "Add your feature"
6. 推到分支： git push origin feature/your-feature
7. 提交拉取请求

许可证

BSD-3条款