Benchling MCP

钳制mcp

 

用于Benchling平台集成的MCP（模型上下文协议）服务器

该服务器实现了用于基准处理的模型上下文协议（MCP），为访问实验室数据管理和研究工作流程提供了标准化的接口。MCP使AI助手和代理能够通过结构化界面与Benchling的综合生物数据平台进行交互。

Benchling MCP服务器提供对以下内容的访问：

• 条目：实验室笔记本条目和实验记录
• 序列：带有注释的DNA、RNA和蛋白质序列
• 项目：项目组织和协作数据
• 搜索：对所有基准实体进行全面搜索

关于MCP（模型上下文协议）

MCP是一种弥合人工智能系统和专业领域知识之间差距的协议。它能够：

• 结构化访问：直接连接到Benchling的实验室数据
• 自然语言查询：简化了与复杂生物数据集的交互
• 类型安全：通过FastMCP进行强大的打字和验证
• 人工智能集成：与人工智能助手和代理无缝集成

先决条件

您需要：

• 拥有API访问权限的Benchling帐户
• Benchling API键
• 您的Benchling域名（例如“yourcompanie.Benchling.com”）

配置

设置以下环境变量：

export BENCHLING_API_KEY="your_api_key_here"
export BENCHLING_DOMAIN="yourcompany.benchling.com"

可用工具

此服务器提供以下工具用于与Benchling交互：

1. benchling_get_entries(folder_id?, project_id?, limit?) -获取实验室笔记本条目
2. benchling_get_sequences(sequence_type?, folder_id?, limit?) -获取DNA/RNA/蛋白质序列
3. benchling_get_projects(limit?) -获取项目及其元数据
4. benchling_search(query, entity_types?, limit?) -跨基准实体搜索

可用资源

1. resource://benchling_api-info -API Benchling文件和使用指南

快速开始

安装uv

# Download and install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version
uvx --version

用uvx运行

您可以使用uvx直接运行基准mcp服务器：

# Set environment variables
export BENCHLING_API_KEY="your_api_key_here"
export BENCHLING_DOMAIN="yourcompany.benchling.com"

# Run the server in streamable HTTP mode (default)
uvx benchling-mcp

Other uvx modes (STDIO, HTTP, SSE)

STDIO模式（适用于需要STDIO的MCP客户端）

# Or explicitly specify stdio mode
uvx benchling-mcp stdio

HTTP模式（Web服务器）

# Run the server in streamable HTTP mode on default (3001) port
uvx benchling-mcp server

# Run on a specific port
uvx benchling-mcp server --port 8000

SSE模式（服务器发送事件）

# Run the server in SSE mode
uvx benchling-mcp sse

配置文件

对于AI客户端，根据您的首选模式创建配置文件：

STDIO模式配置（mcp-config STDIO.json）

{
  "mcpServers": {
    "benchling-mcp": {
      "command": "uvx",
      "args": ["benchling-mcp", "stdio"],
      "env": {
        "BENCHLING_API_KEY": "your_api_key_here",
        "BENCHLING_DOMAIN": "yourcompany.benchling.com"
      }
    }
  }
}

HTTP模式配置（mcp-config.json）

{
  "mcpServers": {
    "benchling-mcp": {
      "command": "uvx",
      "args": ["benchling-mcp", "server"],
      "env": {
        "BENCHLING_API_KEY": "your_api_key_here",
        "BENCHLING_DOMAIN": "yourcompany.benchling.com"
      }
    }
  }
}

开发设置

# Clone the repository
git clone https://github.com/your-org/benchling-mcp.git
cd benchling-mcp

# Install dependencies
uv sync

# Set environment variables
export BENCHLING_API_KEY="your_api_key_here"
export BENCHLING_DOMAIN="yourcompany.benchling.com"

运行MCP服务器（开发）

# Start the MCP server locally (HTTP mode)
uv run server

# Or start in STDIO mode  
uv run stdio

# Or start in SSE mode
uv run sse

运行测试

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=benchling_mcp

# Run specific test file
uv run pytest test/test_benchling_mcp.py

使用示例

获取实验室条目

# Get recent entries from a specific project
entries = await mcp.get_entries(project_id="proj_12345", limit=10)

# Get entries from a specific folder
entries = await mcp.get_entries(folder_id="lib_67890")

搜索序列

# Get DNA sequences
dna_sequences = await mcp.get_sequences(sequence_type="dna", limit=20)

# Get protein sequences from a folder
proteins = await mcp.get_sequences(
    sequence_type="aa", 
    folder_id="lib_proteins", 
    limit=50
)

跨基准搜索

# Search for entries containing "CRISPR"
results = await mcp.search(
    query="CRISPR",
    entity_types=["entries"],
    limit=25
)

# Search for sequences with specific names
results = await mcp.search(
    query="GFP",
    entity_types=["dna_sequences", "aa_sequences"]
)

api参考

认证

服务器使用Benchling的API密钥身份验证。API密钥应通过 BENCHLING_API_KEY 环境变量。

速率限制

Benchling对API调用有速率限制。服务器为速率限制响应实现了适当的延迟和错误处理。

错误处理

所有API调用都使用 eliot 图书馆。

与人工智能系统集成

只需将您的AI客户端（如Cursor、Windsurf、ClaudeDesktop、带Copilot的VS Code或其他客户端）指向使用适当的配置文件即可。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 运行测试套件
6. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

GitHub操作CI/CD

该项目包括通过GitHubActions进行的自动化测试，该测试针对Benchling API运行单元测试和实际集成测试。

设置GitHub机密

要在CI/CD中启用完整的集成测试，您需要将以下机密添加到GitHub存储库中：

1. 转到您的GitHub存储库
2. 引导到 设置 → 秘密和变量 → 行动
3. 添加以下存储库机密：

CI/CD工作流程

GitHub操作工作流(.github/workflows/test.yml)将：

1. 始终运行：不需要访问API的单元测试
2. 只有当秘密可用时:

- 使用实际Benchling API进行实际集成测试 - 运行示例脚本以确保其端到端工作

1. 清理：测试后删除所有下载的文件
2. 上传工件：如果调试测试失败，请保存日志

手动工作流触发器

您可以使用“运行工作流”按钮从GitHub Actions选项卡手动触发工作流。

测试结构

• test/test_benchling_mcp.py -具有模拟依赖关系的单元测试
• test/test_benchling_mcp_real.py -使用真正的Benchling API进行集成测试
• 这两个测试文件都包含基于实际run_example.py输出的全面断言

真正的集成测试兼具以下两种功能：

• 生活文件 API响应的具体示例
• 回归测试 确保MCP服务器使用实际的基准处理数据