STARWARCLOUD STARWAR.AI
返回市场
伯特龙-mcp

伯特龙-mcp

作者：ber-data2 星标更新：2025-09-18
安装使用来源：spider==github.com

项目介绍

bertron-mcp

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

快速开始

直接从GitHub安装并运行

# 直接运行而不安装
uvx --from git+https://github.com/ber-data/bertron-mcp.git bertron-mcp

# 或者先安装，然后运行
uvx --from git+https://github.com/ber-data/bertron-mcp.git bertron-mcp --version

功能

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

要求

安装

源码安装（开发）

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

从PyPI安装（即将推出）

pip install bertron-mcp

可用工具

geosearch

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

参数：

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

返回值： 包含实体、计数和元数据的QueryResponse

bbox_search

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

参数：

  • southwest_lat (float): 西南角纬度 (-90.0 到 90.0)
  • southwest_lng (float): 西南角经度 (-180.0 到 180.0)
  • northeast_lat (float): 东北角纬度 (-90.0 到 90.0)
  • northeast_lng (float): 东北角经度 (-180.0 到 180.0)

返回值： 包含边界框内实体的QueryResponse

entity_lookup

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

参数：

  • entity_id (string): 实体的唯一标识符（例如："nmdc:bsm-12-abc123"）

返回值： 包含完整元数据的Entity对象

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): 实体类型（biodata, sample, sequence, taxon, jgi_biosample）

返回值： 包含指定类型实体的QueryResponse

search_by_name

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

参数：

  • name_pattern (string): 要搜索的名称模式（支持正则表达式）
  • case_sensitive (bool, 可选): 是否进行大小写敏感搜索（默认值：False）

返回值： 包含匹配名称模式的实体的QueryResponse

health_check

检查BERtron API的健康状态。

参数： 无

返回值： 包含web_server和database布尔状态的字典

API限制和约束

为了防止响应过载和保护系统资源，实施了以下限制：

默认限制

  • 默认结果限制：每个查询100项
  • 最大结果限制：每个查询1,000项
  • 最大分页偏移量：50,000项

约束报告

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

{
  "entities": [...],
  "count": 1000,
  "metadata": {
    "constraints_applied": {
      "requested_limit": 5000,
      "actual_limit": 1000,
      "reason": "超过最大限制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 需要过滤条件以防止意外的全库导出
  • 所有限制都在服务器端强制执行，并自动报告约束
  • 深度分页（skip > 50,000）被阻止以防止性能问题

设置

开发

安装开发依赖：

make dev

测试

运行完整的测试套件：

make all

测试特定组件：

# API集成测试
make test-integration

# MCP协议测试  
make test-mcp
make test-mcp-extended

# 使用Claude CLI测试
make test-claude-mcp

# 版本检查
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"
    }
  }
}

Claude代码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

Goose设置

从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"

使用示例

与Claude一起使用

在佛罗里达州奥兰多附近100公里范围内搜索基因组样本：
> 使用bertron-mcp搜索纬度28.5383，经度-81.3792附近的实体，半径100公里

在覆盖黄石国家公园的边界框内搜索实体：
> 使用bbox_search在西南角(44.0, -125.0)和东北角(49.0, -110.0)之间查找实体

查找所有NMDC样本实体：
> 从NMDC数据源搜索所有样本实体

查找特定实体的详细信息：
> 使用entity_lookup获取实体ID "nmdc:bsm-12-abc123" 的详细信息

直接MCP协议

# 测试geosearch工具
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

# 测试边界框搜索
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

# 测试按数据源搜索
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

# 测试带有过滤条件的高级查询
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

开发

代码质量

# 格式化和检查代码
make format
make lint

# 类型检查
make mypy

# 依赖分析
make deptry

构建和发布

# 构建包
make build

# 完整发布工作流
make release

数据源

BERtron聚合了来自以下数据源的数据：

  • EMSL - 环境分子科学实验室
  • ESS-DIVE - ESS数据和信息虚拟生态系统
  • JGI - 联合基因组研究所
  • MONET - 分子观测网络
  • NMDC - 国家微生物组数据协作组织

贡献

  1. 分叉仓库
  2. 创建功能分支：git checkout -b feature/your-feature
  3. 修改代码并添加测试
  4. 运行测试套件：make all
  5. 提交更改：git commit -m "添加你的功能"
  6. 推送到分支：git push origin feature/your-feature
  7. 提交拉取请求

许可证

BSD-3-Clause