生物样本mcp
一个MCP服务器，为AI代理提供结构化、可追溯的EMBL-EBI生物样本数据库访问权限。无需触摸网络浏览器即可搜索、获取和提交生物样本元数据。
目录
- 图1-系统概述 - 图2-提交工作流程 - 图3-文件结构
- 首页 - 架构页面 - 搜索样本 - 获取样本详细信息 - 人工智能辅助提交 - 自然语言搜索
为什么这个项目很重要
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/toolsMCP工具参考
| 工具 | 目的 | 输入 | 输出 |
|---|---|---|---|
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/