benchling-mcp

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

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

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

• 条目：实验室笔记本条目和实验记录
• 序列：带有注释的DNA、RNA和蛋白质序列
• 项目：项目组织和协作数据
• 搜索：跨所有Benchling实体的综合搜索

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

MCP是一种协议，它弥合了AI系统与专业领域知识之间的差距。它支持：

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

预备条件

你需要：

• 具有API访问权限的Benchling账户
• Benchling API密钥
• 你的Benchling域（例如："yourcompany.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?) - 跨Benchling实体搜索

可用资源

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

快速开始

安装uv

# 下载并安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version
uvx --version

使用uvx运行

你可以直接使用uvx运行benchling-mcp服务器：

# 设置环境变量
export BENCHLING_API_KEY="your_api_key_here"
export BENCHLING_DOMAIN="yourcompany.benchling.com"

# 在流式HTTP模式下运行服务器（默认）
uvx benchling-mcp

<details> <summary>其他uvx模式（STDIO，HTTP，SSE）</summary>

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

# 或明确指定stdio模式
uvx benchling-mcp stdio

HTTP模式（Web服务器）

# 在默认端口（3001）上以流式HTTP模式运行服务器
uvx benchling-mcp server

# 在特定端口上运行
uvx benchling-mcp server --port 8000

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

# 以SSE模式运行服务器
uvx benchling-mcp sse

</details>

配置文件

对于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"
      }
    }
  }
}

开发设置

# 克隆仓库
git clone https://github.com/your-org/benchling-mcp.git
cd benchling-mcp

# 安装依赖
uv sync

# 设置环境变量
export BENCHLING_API_KEY="your_api_key_here"
export BENCHLING_DOMAIN="yourcompany.benchling.com"

运行MCP服务器（开发）

# 在本地启动MCP服务器（HTTP模式）
uv run server

# 或在STDIO模式下启动
uv run stdio

# 或在SSE模式下启动
uv run sse

运行测试

# 运行所有测试
uv run pytest

# 带覆盖率运行
uv run pytest --cov=benchling_mcp

# 运行特定测试文件
uv run pytest test/test_benchling_mcp.py

使用示例

获取实验室条目

# 从特定项目获取最近的条目
entries = await mcp.get_entries(project_id="proj_12345", limit=10)

# 从特定文件夹获取条目
entries = await mcp.get_entries(folder_id="lib_67890")

搜索序列

# 获取DNA序列
dna_sequences = await mcp.get_sequences(sequence_type="dna", limit=20)

# 从文件夹中获取蛋白质序列
proteins = await mcp.get_sequences(
    sequence_type="aa", 
    folder_id="lib_proteins", 
    limit=50
)

跨Benchling搜索

# 搜索包含“CRISPR”的条目
results = await mcp.search(
    query="CRISPR",
    entity_types=["entries"],
    limit=25
)

# 搜索具有特定名称的序列
results = await mcp.search(
    query="GFP",
    entity_types=["dna_sequences", "aa_sequences"]
)

API参考

认证

服务器使用Benchling的API密钥认证。API密钥应通过BENCHLING_API_KEY环境变量提供。

速率限制

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

错误处理

所有API调用都使用eliot库进行了适当的错误处理和日志记录。

与AI系统的集成

只需将你的AI客户端（如Cursor、Windsurf、ClaudeDesktop、VS Code with Copilot等）指向使用适当的配置文件。

贡献

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

许可

本项目采用MIT许可 - 详情见LICENSE文件。

GitHub Actions CI/CD

该项目包括通过GitHub Actions自动执行的测试，这些测试既运行单元测试也针对Benchling API的实际集成测试。

设置GitHub Secrets

要启用CI/CD中的完整集成测试，你需要向你的GitHub仓库添加以下秘密：

1. 转到你的GitHub仓库
2. 导航至设置→Secrets and variables→Actions
3. 添加以下仓库秘密：

秘密名称	描述	示例
BENCHLING_API_KEY	你的Benchling API密钥	sk_BWKVnUFsCDDO966aCCVJN6oAdfnee
BENCHLING_DOMAIN	你的Benchling域	benchling.com

CI/CD工作流程

GitHub Actions工作流程（.github/workflows/test.yml）将：

1. 始终运行：不需要API访问的单元测试
2. 仅当秘密可用时：
   • 使用实际Benchling API的真实集成测试
   • 运行示例脚本以确保其端到端工作
3. 清理：测试后删除任何下载的文件
4. 上传工件：如果测试失败保存日志以便调试

手动触发工作流程

你可以从GitHub Actions标签使用“运行工作流程”按钮手动触发工作流程。

测试结构

• test/test_benchling_mcp.py - 使用模拟依赖项的单元测试
• test/test_benchling_mcp_real.py - 使用真实Benchling API的集成测试
• 两个测试文件均基于实际run_example.py输出包含详尽的断言

真实集成测试作为：

• 活文档，具有API响应的具体示例
• 回归测试，确保MCP服务器与实际Benchling数据一起工作