AI导哈

生物样本数据库访问工具

一个MCP服务器，为AI代理提供结构化、可追溯的EMBL-EBI BioSamples数据库访问功能，支持搜索、获取和提交生物样本元数据。

  • by Anas9-8
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Anas9-8/biosamples-mcp

使用说明

生物样本mcp

一个MCP服务器，为AI代理提供结构化、可追溯的EMBL-EBI生物样本数据库访问权限。无需触摸网络浏览器即可搜索、获取和提交生物样本元数据。

目录

为什么这个项目很重要

BioSamples保存了来自全球实验室和医院的数百万个生物样本的元数据。REST API适用于直接查询，但AI代理无法可靠地使用它，他们需要显式的工具模式、定义的输入和可预测的输出来避免虚构。

该项目将BioSamples API封装在MCP服务器中。每个工具都有一个严格的模式。每个响应都直接来自API。智能提交工具添加了一个小型NLP层，可以从纯英文文本中提取结构化字段，当研究人员想要用自己的话描述样本而不是填写表格时非常有用。

在开发过程中，向生产数据库提交了两个样品：SAMEA122005222和SAMEA122005523。这两个都在EMBL-EBI网站上公开可见，这证实了提交管道与真正的API不符。

系统架构

下图显示了系统的所有组件是如何连接和通信的。每个层都是彩色编码的：蓝色表示客户端，绿色表示服务器，橙色表示标准工具，红色表示AI驱动工具，紫色表示智能层，灰色表示外部API。

图1——系统概述

  • 三种客户端类型：端口8501上的Streamlit UI、通过stdio的Claude Desktop和任何REST客户端
  • FastAPI REST服务器（端口8000）处理HTTP流量；FastMCP处理克劳德桌面
  • 五个MCP工具，三个标准工具和两个AI驱动工具
  • nlp_parser.py和checklist_validator.py位于这两个智能工具之后
  • 一切最终都会进入EMBL-EBI BioSamples REST API

图2——人工智能辅助提交工作流程

  • 步骤1：用户编写一个简单的英文示例描述
  • 步骤2:nlp_parser.py自动提取生物体、组织、疾病、位置和日期
  • 步骤3:checklist_validator.py检查必填字段
  • 步骤4：如果缺少字段，则向用户返回澄清问题
  • 步骤5：将用户答案与提取的元数据合并
  • 第6步：将完整记录提交给EMBL-EBI API
  • 步骤7：返回真实生物样本登录

图3——存储库文件结构

  • src/包含服务器、工具、NLP解析器和检查表验证器
  • ui/具有Streamlit应用程序和五个页面模块
  • 21项测试/，全部通过
  • 检查表/保存两个验证JSON文件（默认+human_sample）
  • Docker和Docker组成一个命令部署
  • GitHub Actions CI在每次向main推送时运行

现场演示证据

在开发过程中，这两个样本被提交到真实的EMBL-EBI生物样本数据库：

加入 描述 通过提交
SAMEA122005222 人类血液样本，德国 提交生物样本（结构化）
SAMEA122005223 人类肝活检，伦敦，肝硬化 smart_submit_biosample（简明英语）

实时查看：https://www.ebi.ac.uk/biosamples/samples/SAMEA122005222

实时查看：https://www.ebi.ac.uk/biosamples/samples/SAMEA122005223

网络界面

Streamlit界面提供了对所有五个MCP工具的可视化访问。以下屏幕截图显示了每个页面，并简要描述了其主要功能。

启动界面：

# Terminal 1 — start the MCP server
export $(cat .env) && uvicorn src.server:app --reload

# Terminal 2 — start the Streamlit UI
pip install -r requirements-ui.txt
streamlit run ui/app.py

打开http://localhost:8501在您的浏览器中。

首页

  • 服务器状态指示灯，当MCP服务器在端口8000上可访问时为绿色
  • 列出的所有五个工具都有一行描述
  • 快速演示：点击获取SAMEA122005222，确认连接成功

架构页面

  • 三个颜色编码的图表，涵盖系统概述、提交工作流程和文件结构
  • 在浏览器中呈现为实时HTML，而不是静态图像
  • 在技术演示和面试演示中表现良好

搜索样本

  • 在BioSamples数据库中进行全文关键字搜索
  • 结果表，包括登录、生物体和疾病栏
  • 登录ID直接链接到EMBL-EBI记录页面
  • 一键示例查询：“人类”、“血液”、“肝脏”

获取样本详细信息

  • 粘贴任何条目以提取完整的元数据记录
  • 将基本信息与生物属性分离的两列布局
  • 可扩展部分提供原始特性
  • 预装SAMEA122005222和SAMEA122005523的按钮，用于快速测试

人工智能辅助提交

  • 用简单的英语写一个示例描述，而不是填写表格
  • NLP解析器自动提取生物体、组织、疾病、位置和日期
  • 在默认（最小字段）或human_sample（更严格）检查表之间进行选择
  • 缺失的字段会引发特定的澄清问题
  • 一旦一切检查完毕，提交样品并返回登记表
  • SAMEA122005222和SAMEA122005523均通过此页面提交

自然语言搜索

  • 用简单的英语键入查询，没有特殊语法
  • 服务器显示它提取了哪些过滤器（生物体、组织、疾病、位置）
  • 结果以登录、生物体、组织和疾病栏返回
  • 示例按钮：“人类肺癌”、“柏林2022年人类肾脏活检”、“德国新冠肺炎人类血液”

快速开始

# Clone the repository
git clone https://github.com/Anas9-8/biosamples-mcp
cd biosamples-mcp

# Copy environment file and add your token (only needed for submit)
cp .env.example .env

# Start with Docker Compose
docker-compose up --build

# Check it's running
curl http://localhost:8000/health
# {"status": "ok", "version": "1.0.0"}

# List available tools
curl http://localhost:8000/tools

MCP工具参考

工具 目的 输入 输出
search_biosamples 跨生物样本的关键字搜索 query: str 匹配样本列表
fetch_biosample 按登录方式提供完整元数据 accession: str 完整的样品记录
submit_biosample 提交结构化样本 元数据字段+AAP令牌 分配的登录
smart_submit_biosample 用简单的英语提交 description: str 加入或澄清问题
natural_search_biosamples NL查询到结构化搜索 query: str 过滤结果+解释

示例：搜索

curl -X POST http://localhost:8000/tools/search_biosamples/call \
  -H "Content-Type: application/json" \
  -d '{"query": "human lung cancer", "organism": "Homo sapiens"}'

示例：提取

curl -X POST http://localhost:8000/tools/fetch_biosample/call \
  -H "Content-Type: application/json" \
  -d '{"accession": "SAMEA112654119"}'

用例

医院研究团队经常需要找到与患者队列、相同组织、相同疾病、相似收集窗口相匹配的公共样本。该服务器允许AI助手以编程方式运行这些搜索，而不是通过BioSamples web界面点击。

向公共档案馆提交实验样本的制药团队可以使用智能提交工具，避免重复填写相同的元数据表格。用简单的英语描述样品，回答任何澄清问题，并提交记录。

构建人工智能辅助分析管道的生物信息学团队可以将此MCP服务器直接连接到他们的LLM层。工具模式可防止产生幻觉的加入，并确保每次样本查找都返回真实数据。

该项目最初是EMBL-EBI GSoC 2026项目想法#16（导师：Dipayan Gupta）的独立实施，这是在编码期开始之前证明概念有效的好方法。参考：https://www.ebi.ac.uk/about/events/gsoc/

路线图

静态检查表JSON文件可以工作，但理想情况下，服务器应该从BioSamples API实时获取它们，以便它们自动保持最新。澄清工作流程是单循环的，一个适当的会话存储会使多步骤提交更清晰。响应缓存将有助于重复查询。由于MCP工具模式相同，该架构自然扩展到其他EMBL-EBI资源，如ENA和ArrayExpress。

技术栈

  • Python 3.11 --贯穿始终的类型提示，现代异步模式
  • 快速API --带有自动OpenAPI文档的异步HTTP服务器
  • httpx -用于BioSamples API调用的异步HTTP客户端
  • Pydantic v2 --工具输入和输出的数据验证
  • MCP-SDK --模型上下文协议集成
  • 码头工人 --非root用户的容器化部署
  • GitHub 操作 --每次向main推送CI

本地开发

# Install dependencies
pip install -r requirements.txt

# Run the server locally
uvicorn src.server:app --reload

# Run tests
pytest tests/ -v

# Lint
ruff check src/

相关 MCP