Biolab MCP Server

Biolab MCP 服务

“AI Agent 查询生物数据库，却不会留下审计记录。六个月后，没人能回答：究竟是哪条查询返回了这个结果？是什么时候返回的？当时那篇论文经过同行评审了吗？Biolab 就是为了解决这个问题。”

这是一个本地优先的科学证据工作区，提供 Python 和 Go 客户端。它位于科学家或 AI Agent 与 PubMed、Europe PMC、ClinicalTrials.gov、UniProt、Open Targets 以及 bioRxiv/medRxiv 之间。每次检索都会保留源响应并返回一个 retrieval_id；项目、已审核集合、证据监控和声明关联则在此基础上构建出可追溯的工作流。

刚接触 MCP？ MCP 是一项开放标准，可让 AI 助手（Codex、 ChatGPT、Claude、Cursor 等）在对话中调用外部工具。 添加 Biolab 后，助手就能检索、保存、整理、监控并引用 科学证据，同时确保之后仍可检查每个结果。

立即使用——无需安装

我们提供了一个托管实例：https://srikarjy025-biolab-mcp.hf.space/mcp。将客户端指向该实例即可。托管功能以当前部署的版本为准；若要使用本仓库中完整的 0.4 工作区，请在本地运行。

Claude Code：

claude mcp add --transport http biolab https://srikarjy025-biolab-mcp.hf.space/mcp

Claude Desktop / Cursor — 将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "biolab": {
      "url": "https://srikarjy025-biolab-mcp.hf.space/mcp"
    }
  }
}

（获得密钥后，在 "url" 旁添加 "headers": {"Authorization": "Bearer <your key>"} — 参见下方的速率限制说明。）

0.4 版服务提供统一搜索、特定来源搜索、标准 search/fetch、检索检查、项目、集合、监控、声明和报告。每次检索都会写入哈希链式审计记录，供之后检查（参见下方的审计记录架构）。

跨来源研究可通过一次调用使用 search_evidence 搜索 PubMed、Europe PMC、 ClinicalTrials.gov、UniProt 和 Open Targets，同时保留各来源的 明确结果和错误信息。

如果你更愿意从其他地方发现并安装，也可以在官方 MCP Registry 和 Smithery 上找到它。

关于速率限制。 托管服务由多人共用且始终开放——日常使用无需注册——但未提供 API 密钥的调用方会共用一个较小、吞吐量较低的额度（对 PubMed 为 1 req/s），以免某个匿名用户独占资源，影响其他所有人。如果你要执行的查询不止几次，请申请密钥（见下文），即可获得独立且额度更高的资源。

获取密钥：

Authorization: Bearer <your key>

在客户端的 MCP 配置中添加该请求头（Claude Code：claude mcp add --transport http biolab <url> --header "Authorization: Bearer <key>"）。密钥通过 biolab keys create <label> 创建——如果你运行的是自己的实例，请参见下方的管理 API 密钥；否则，请向维护者申请。

想运行自己的副本吗（用于本地开发、使用自己的存储或自托管）？请继续阅读。

问题

一个药物发现团队使用 AI Agent 研究基因靶点。Agent 在三天内查询 PubMed 200 次，并找到一篇声称基因 X 在胰腺癌中上调的论文。一位科学家据此做出了决定。六个月后，提交 FDA 申请期间：

• 返回这篇论文的具体查询是什么？
• 检索日期是什么时候？
• 检索时它经过了同行评审，还是后来才发表的预印本？
• Agent 是否准确地总结了论文，还是编造了细节？

没有 Biolab，没人能回答这些问题。检索过程不可见。

Biolab 的功能

Biolab 是一个拦截和日志记录层，而不是检索层。它不会解读证据、对证据排序或进行总结，而是逐字记录发生的事情，让 Agent 的主张始终可以追溯到不可伪造的原始记录。

Your AI Agent
    ↓  MCP tool call (e.g. search_pubmed)
Biolab MCP Server
    ↓  HTTP
Source API (PubMed, Europe PMC, ClinicalTrials.gov, bioRxiv/medRxiv)
    ↓  paper
Biolab writes a hash-chained retrieval record to the audit database
    ↓  paper + retrieval_id
Back to your agent

Agent 会获取它请求的论文。Biolab 会永久保存一份可查询、防篡改的记录，精确记录发生的一切。

支持的数据源

数据源	MCP 工具	CLI 命令	说明
PubMed	search_pubmed	biolab search	E-utilities，存储完整 XML
Europe PMC	search_europepmc	biolab search-europepmc	免费，可索引 bioRxiv/medRxiv
ClinicalTrials.gov	search_clinicaltrials	biolab search-clinicaltrials	API v2，基于疾病状况搜索
UniProt	search_evidence	biolab evidence	蛋白质记录和序列
Open Targets	search_evidence	biolab evidence	通过 GraphQL 获取靶点、疾病和药物实体
bioRxiv/medRxiv	search_biorxiv	biolab search-biorxiv	按日期范围分页（API 限制）

所有数据源共用一个审计数据库（本地使用 SQLite，生产环境使用 Turso——一种托管的 SQLite 兼容数据库），并采用一个与数据源无关的架构。

自行构建

无需了解 Python 或 Go，即可在本地运行；只需按顺序完成以下步骤。所有命令都在终端中运行。

先决条件

• Python 3.11 或更高版本——使用 python3 --version 检查。如果尚未安装，请从 python.org 获取。
• Git——用于下载（克隆）代码。使用 git --version 检查。

Python 路径确实只需要这些——无需安装数据库服务器，也不需要 API 密钥（PubMed 支持匿名访问，只是速率限制较低）。

1. 获取代码

git clone https://github.com/srikarjy/biolab-mcp-server.git
cd biolab-mcp-server

2. 安装

python3 -m venv .venv          # creates an isolated Python environment
source .venv/bin/activate      # on Windows: .venv\Scripts\activate
pip install -e ".[dev]"        # installs the package + test tools
# Add the optional remote Turso driver only if needed: pip install -e ".[turso]"

3. 试用

biolab demo --query "BRCA1 pancreatic cancer"

这会实际搜索 PubMed，将每条结果存储在本地的 biolab.db 文件中（自动创建，无需设置），并打印每篇论文对应的 retrieval_id——AI Agent 通过 MCP 获取的也是同一个 ID。

4. 运行测试套件（可选，用于确认一切正常）

pytest -m "not live and not benchmark" -v

网络访问和本地套接字绑定可用时，请单独运行 pytest -m live -v。这些测试会访问真实的 PubMed、Europe PMC、ClinicalTrials.gov 和 bioRxiv 服务；默认命令则保持确定性并离线运行。

5. 将其作为 MCP 服务运行（AI Agent 实际连接的服务）

python -m biolab.server

这会在 http://localhost:8000/mcp 启动 HTTP 服务——像 立即使用 中那样，将 Claude Desktop、Claude Code 或 Cursor 指向这个 URL，只需将托管 URL 换成 localhost:8000。

6. 构建 Docker 镜像（可选）

如果你完全不想在本地安装 Python：

docker build -f space/Dockerfile -t biolab-mcp .
docker run -p 8000:8000 biolab-mcp

（除非设置了 TURSO_DATABASE_URL/TURSO_AUTH_TOKEN，否则存储默认使用容器内的临时文件——参见下方的环境变量。）

想使用预构建版本？

pipx install biolab-mcp      # or: pip install biolab-mcp

# Or the Go binary, no Python required at all:
curl -L https://github.com/srikarjy/biolab-mcp-server/releases/latest/download/biolab_darwin_arm64.tar.gz | tar xz
./biolab search "BRCA1 pancreatic cancer" --max 3

用法

CLI（面向科学家）

# Search several evidence sources in one audited workflow
biolab evidence "KRAS pancreatic cancer" \
  --sources pubmed,europepmc,clinicaltrials,uniprot,opentargets --max 5

# Search PubMed
biolab search "BRCA1 pancreatic cancer" --max 5

# Search Europe PMC
biolab search-europepmc "BRCA1 pancreatic cancer" --max 5

# Search ClinicalTrials.gov
biolab search-clinicaltrials "pancreatic cancer" --max 5

# List bioRxiv preprints (no free-text search - API limitation)
biolab search-biorxiv neuroscience --max 10
biolab search-biorxiv all --server medrxiv --max 10

# Retrieve full audit record
biolab get <retrieval_id>

# List recent retrievals
biolab list --source pubmed --limit 10

# Export for analysis
biolab export evidence.jsonl --source clinicaltrials

# Verify the complete tamper-evident audit chain
biolab verify --db biolab.db

# Run demo
biolab demo --query "BRCA1 pancreatic cancer"

# Run the offline portfolio demo (no network or scientific claims)
biolab portfolio-demo

# Run the real end-to-end scientist workflow against a local server
python scripts/scientist_workflow_demo.py --url http://127.0.0.1:8000

# Start the private local dashboard and REST API
biolab web
# Open http://127.0.0.1:8000

# Create a project, organize evidence, and trace a claim
biolab projects create "KRAS target review" --description "Pancreatic cancer evidence"
biolab collections create <project_id> "Reviewed evidence"
biolab collections add <collection_id> <retrieval_id> --relevance relevant --note "Reviewed"
biolab claims create <project_id> "KRAS is a therapeutic target"
biolab claims link <claim_id> <retrieval_id> --stance supports --assessment human_reviewed

# Monitor a source for added, removed, or revised records
biolab watches create <project_id> pubmed "KRAS pancreatic cancer"
biolab watches run-all

# Export a complete project report
biolab projects report <project_id> --output report.md

仪表板默认绑定到 127.0.0.1。REST 端点涵盖证据、项目、集合、监控项、声明和报告。可通过 /openapi.json 发现这些端点；使用 /health、/metrics 和 /v1/verify 执行运维操作。 在远程公开服务前，请运行 biolab web --require-auth，并使用 biolab keys create 创建密钥；或者在统一 MCP 服务上使用 BIOLAB_REQUIRE_AUTH=true。

MCP 工具（面向 Agent）

// Search any source
{"name": "search_evidence", "arguments": {"query": "KRAS pancreatic cancer", "agent_id": "research:target-validation", "sources": ["pubmed", "europepmc", "clinicaltrials", "uniprot", "opentargets"], "max_results": 5}}
{"name": "search_pubmed", "arguments": {"query": "BRCA1 pancreatic cancer", "agent_id": "aletheia:advocate", "max_results": 5}}
{"name": "search_europepmc", "arguments": {"query": "BRCA1 pancreatic cancer", "agent_id": "aletheia:advocate", "max_results": 5}}
{"name": "search_clinicaltrials", "arguments": {"query": "pancreatic cancer", "agent_id": "aletheia:advocate", "max_results": 5}}
{"name": "search_biorxiv", "arguments": {"category": "neuroscience", "agent_id": "aletheia:advocate", "max_results": 5, "server": "biorxiv"}}

// Retrieve full audit record (works for ALL sources)
{"name": "get_retrieval", "arguments": {"retrieval_id": "uuid-from-search"}}

BioClaw

项目中包含可直接复制使用的 BioClaw 技能，位于 integrations/bioclaw/biolab-evidence。它将 BioClaw 容器化的研究助手连接到本地 REST API，并支持跨来源搜索、检索检查和链验证，无需额外安装 Python 包。

Codex 和 ChatGPT

• 使用 python -m biolab.server 启动完整的本地服务。
• 将 integrations/codex/config.toml.example 复制到 Codex 配置中，并在开发期间将工具审批保持为 prompt。
• 可移植的 Agent Plugin 捆绑包位于 plugins/biolab/（包含 plugin.json、mcp.json 和证据工作区技能）。发布或提交前，请将 mcp.json 中的远程 URL 更改为你的 HTTPS 部署地址。
• MCP 服务包含标准的 search 和 fetch 知识工具，以及功能更丰富的 Biolab 工具。工具注释会向客户端说明只读、写入、外部数据和幂等行为。

因此，ChatGPT/Codex 可以搜索并保留证据、创建项目状态、运行监控项并追踪声明。助手可以提出关系建议；当某项关系确实经过审阅时，科学家必须使用 human_reviewed。

REST 和 API 网关

一个 python -m biolab.server 进程即可在 /mcp 提供 MCP 服务、在 / 提供仪表板，并在 /v1 下提供 REST。重要路由如下：

路由	用途
POST /v1/evidence/search	经审计的多源搜索
GET /v1/retrievals/{id}	完整的已保留检索记录
GET, POST /v1/projects	列出或创建项目
POST /v1/collections	创建经过审阅的集合
GET, POST /v1/watches	列出或创建监控查询
POST /v1/watches/run-all	定期漂移检测
POST /v1/claims	创建声明，但不宣称其为真
GET /v1/claims/{id}	追踪声明与证据之间的关系
GET /v1/projects/{id}/report	JSON 或 ?format=markdown 格式的报告
GET /openapi.json	网关/API 发现文档

deploy/gateway/ 中的零成本 Caddy/Docker 示例添加了反向代理边界和持久化卷。默认情况下，它仅绑定到 localhost。公开使用前，请配置真实域名、HTTPS、备份以及组织专属的授权机制。

Python API

from biolab.pubmed_client import search_and_fetch
from biolab.retrieval_log import write_retrieval, get_retrieval
from biolab.db import connect

conn = connect("biolab.db")
papers = search_and_fetch("BRCA1 pancreatic cancer", 3)
for p in papers:
    record = write_retrieval(conn, query="...", pmid=p.pmid, ...)
    print(record.retrieval_id)

管理 API 密钥

按照设计，服务允许未经身份验证的调用方访问，但这些调用方共用一个容量小、吞吐量低的速率限制额度（参见立即使用）。为用户发放密钥后，他们便拥有独立且更高的额度。这并不会限制访问权限，而纯粹是一种公平机制，确保某个调用方不会耗尽所有人共享的 PubMed 实际速率限制额度。

# Issue a key — the raw key is shown once, save it immediately
biolab keys create alice

# List issued keys (never shows the raw key — only a hash is stored)
biolab keys list

# Revoke all of a label's active keys
biolab keys revoke alice

调用方通过 Authorization: Bearer <key> 将密钥发送回来。默认情况下，缺少此标头时会使用匿名层级，而无效或已撤销的密钥会返回 401。 设置 BIOLAB_REQUIRE_AUTH=true 后，也会拒绝不带密钥的请求。

环境变量

全部为可选项 — 即使不设置任何变量，服务也会使用合理的默认值运行。

变量	用途	默认值
BIOLAB_DB_PATH	本地 SQLite 文件路径（如果设置了 TURSO_DATABASE_URL，则忽略）	biolab.db
TURSO_DATABASE_URL	可选的远程 Turso URL；需要执行 pip install "biolab-mcp[turso]"	未设置（使用本地文件）
TURSO_AUTH_TOKEN	上述 Turso 数据库的身份验证令牌	未设置
BIOLAB_HOST	MCP 服务绑定的主机；非环回地址需要设置 BIOLAB_REQUIRE_AUTH=true 或 BIOLAB_ALLOW_ANONYMOUS=true	127.0.0.1
BIOLAB_PORT	MCP 服务监听的端口	8000
BIOLAB_REQUIRE_AUTH	要求 MCP/REST 请求提供有效的 Bearer API 密钥	false
NCBI_API_KEY	将 PubMed 速率限制从 3 req/s 提高到 10 req/s	未设置（不设置也能正常工作）

审计追踪架构（v2）

CREATE TABLE retrievals (
    retrieval_id     TEXT PRIMARY KEY,  -- UUID
    source           TEXT NOT NULL,     -- pubmed, europepmc, trials, UniProt, Open Targets, etc.
    external_id      TEXT NOT NULL,     -- PMID, NCT ID, DOI, etc.
    query_text       TEXT NOT NULL,     -- exact query sent to source
    retrieved_at     TEXT NOT NULL,     -- ISO 8601 UTC
    agent_id         TEXT NOT NULL,     -- e.g. "aletheia:advocate"
    source_metadata  TEXT NOT NULL,     -- JSON: source-specific fields
    raw_response     TEXT NOT NULL,     -- verbatim XML/JSON from source
    snapshot         TEXT NOT NULL,     -- JSON: structured fields (title, abstract, authors, journal, DOI, pub types, MeSH/conditions)
    response_hash    TEXT NOT NULL,     -- SHA-256(prev_hash + raw_response + retrieval_id + retrieved_at)
    prev_hash        TEXT NOT NULL      -- response_hash of the previous row — makes this a hash chain
);

主要特性：

• 每次论文检索一行（而非每次查询一行）
• 原始响应按原样存储 — 即使解析出现错误，也可以恢复
• 采用哈希链，而不只是哈希：每行的哈希也涵盖上一行的哈希，因此删除或编辑任何一行（即使直接在数据库中操作），都会破坏其后所有行的哈希链。调用 retrieval_log.verify_chain(conn) 可检查整个日志；如果有行损坏，该函数会准确指出是哪一行。
• 后台写入队列通过单一路径串行处理所有写入，因此即使 Agent 并发调用，也能保持哈希链一致

篡改证据与执行运行时

• 检索行对每个经过审计的列都采用哈希链（hash_version 2）；旧版 v1 行仍可通过验证。
• biolab anchor out.json [--chain retrievals|executions] 会写入链头的 HMAC 签名检查点（BIOLAB_ANCHOR_KEY）。请将其保存在数据库主机之外；随后运行 biolab verify-anchor out.json，即可检测仅靠哈希链无法发现的尾部截断和完整重写。
• biolab run-tool <tool> -i '{...}' 会运行已注册的工具（sequence_stats；如果 mmseqs 位于 PATH 中，也可运行 mmseqs2_search），并通过内容寻址的产物封存不可变的 ExecutionRecord。biolab executions {list,show,verify,replay,artifact} 可检查、验证并重放这些记录。如果无法封存记录，则不会返回结果。
• Go 版本（go-biolab/）写入相同的 v2 哈希链，并提供 verify、anchor 和 verify-anchor；其哈希与 Python 按字节兼容，并由共享测试向量固定。Go 版本未实现执行运行时。

架构

biolab/
├── cli.py                   # Search plus scientist workspace commands
├── server.py                # Unified MCP + REST + dashboard process
├── evidence.py              # Shared multi-source orchestration and audit persistence
├── workspace.py             # Projects, collections, watches, claims, reports
├── web.py                   # Local dashboard + versioned REST API
├── db.py                    # Connection + schema (local SQLite or remote Turso)
├── models.py                 # RetrievalRecord dataclass
├── retrieval_log.py          # Only writer + background queue + hash chain
├── pubmed_client.py           # PubMed E-utilities wrapper + rate limiter
├── europepmc_client.py        # Europe PMC adapter
├── clinicaltrials_client.py   # ClinicalTrials.gov adapter
├── uniprot_client.py          # UniProt adapter
├── opentargets_client.py      # Open Targets GraphQL adapter
├── biorxiv_client.py          # bioRxiv/medRxiv adapter
└── migrations/                # Schema migration scripts

integrations/
├── bioclaw/                   # BioClaw evidence skill and REST client
└── codex/                     # Local MCP configuration template

plugins/biolab/                # Portable Codex/ChatGPT Agent Plugin bundle
deploy/gateway/                # Caddy + Docker Compose deployment template

space/                      # Files pushed to the hosted Hugging Face Space
├── Dockerfile                # Python-server-specific image (see repo-root Dockerfile for the Go one)
└── README.md                  # Space config (title, hosting metadata)

设计原则：

• Python 和 Go 实现（接口相同，运行时不同）
• 共享核心，通过 CLI、MCP、REST 和 Web 提供服务
• 使用数据库，而非日志文件 — 支持跨时间的结构化查询
• 失败时直接报错，绝不降级 — 缺少 retrieval_id 的论文比报错更糟
• 离线验收测试，以及明确的在线连接器测试
• 使用单写入者队列，而非行级锁 — 以最简单的方式确保并发时哈希链保持一致

开发

# Python
pip install -e ".[dev]"
pytest -m "not live and not benchmark" -v

# Go
cd go-biolab
go test ./...
go build -o biolab ./cmd/cli
go build -o biolab-server ./cmd/server

部署

目标	方式
托管（无需安装）	https://srikarjy025-biolab-mcp.hf.space/mcp — 功能取决于已部署的 Space 版本
本地	pipx install biolab-mcp 或下载二进制文件
CI/CD	GitHub Actions → PyPI（Trusted Publishing/OIDC）+ GHCR + GitHub Releases
容器	docker pull ghcr.io/srikarjy/biolab-mcp:latest，或自行构建 space/Dockerfile
Linux 软件包	通过 goreleaser 提供 .deb、.rpm、.apk
发现	MCP 注册表 · Smithery

**学生低成本方案：**本地 SQLite、CLI、仪表板、MCP 服务、BioClaw 客户端和 Caddy 网关均无需付费服务。免费托管套餐也可能适用， 但其配额和持久化策略可能会变化；依赖公共部署前，请先确认相关情况。

路线图

• 通过响应哈希监控证据的新增、删除和内容变更
• 项目、集合、声明、报告、REST、仪表板和 Agent 打包
• 溯源图（按 DOI 跨来源关联）
• Nextflow/Snakemake 插件
• 速率限制和缓存（符合审计要求）
• 组织账户和细粒度项目授权
• 撤稿/更正动态源，并持久化传递警报

许可证

MIT — 请参阅 LICENSE

作者

Srikar Jy — [email protected]