UniProt MCP 服务器

<!-- mcp-name: io.github.josefdc/uniprot-mcp -->

一个提供无缝访问 UniProtKB 蛋白质数据的 Model Context Protocol (MCP) 服务器。通过一个设计用于 LLM 代理的类型化且健壮的接口查询蛋白质条目、序列、基因本体注释，并执行 ID 映射。

✨ 功能

• 🔌 双传输模式：本地开发使用 Stdio，远程部署使用可流式传输的 HTTP
• 📊 丰富的数据访问：获取完整的蛋白质条目，包括序列、特征、GO 注释、交叉引用和分类学
• 🔍 高级搜索：全文搜索并按审核状态、生物体、关键词等进行过滤
• 🔄 ID 映射：在 200 多种数据库标识符类型之间转换，并跟踪进度
• 🛡️ 生产就绪：自动重试带有指数退避、CORS 支持、Prometheus 指标
• 📝 类型化响应：结构化的 Pydantic 模型确保数据一致性
• 🎯 MCP 原语：资源、工具和提示，专为代理工作流程设计

🚀 快速开始

安装

pip install uniprot-mcp

运行服务器

本地开发（stdio）：

uniprot-mcp

远程部署（HTTP）：

uniprot-mcp-http --host 0.0.0.0 --port 8000

HTTP 服务器提供：

• MCP 端点：http://localhost:8000/mcp
• 健康检查：http://localhost:8000/healthz
• 指标：http://localhost:8000/metrics（Prometheus 格式）

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector uniprot-mcp

📚 MCP 原语

资源

通过 URI 模式访问静态或动态数据：

URI	描述
uniprot://uniprotkb/{accession}	任何准入编号的原始 UniProtKB 条目 JSON
uniprot://help/search	搜索查询语法的文档

工具

执行操作并检索类型化数据：

工具	参数	返回值	描述
fetch_entry	accession, fields?	Entry	获取完整的蛋白质条目及其所有注释
get_sequence	accession	Sequence	获取蛋白质序列及其长度和元数据
search_uniprot	query, size, reviewed_only, fields?, sort?, include_isoform	SearchHit[]	全文搜索并进行高级过滤
map_ids	from_db, to_db, ids	MappingResult	在 200 多种数据库之间转换标识符
fetch_entry_flatfile	accession, version, format	string	检索历史条目版本（txt/fasta）

进度跟踪：map_ids 报告长运行任务的进度（0.0 → 1.0）。

提示

预构建模板用于常见工作流程：

• 总结蛋白质：从 UniProt 准入编号生成结构化的摘要，包括生物体、功能、GO 术语和显著特征。

🔧 配置

环境变量

变量	默认值	描述
UNIPROT_ENABLE_FIELDS	未设置	请求最小字段子集以减少负载大小
UNIPROT_LOG_LEVEL	info	日志级别：debug, info, warning, error
UNIPROT_LOG_FORMAT	plain	日志格式：plain 或 json
UNIPROT_MAX_CONCURRENCY	8	最大并发 UniProt API 请求
MCP_HTTP_HOST	0.0.0.0	HTTP 服务器绑定地址
MCP_HTTP_PORT	8000	HTTP 服务器端口
MCP_HTTP_LOG_LEVEL	info	Uvicorn 日志级别
MCP_HTTP_RELOAD	0	启用自动重新加载：1 或 true
MCP_CORS_ALLOW_ORIGINS	*	CORS 允许的来源（逗号分隔）
MCP_CORS_ALLOW_METHODS	GET,POST,DELETE	CORS 允许的方法
MCP_CORS_ALLOW_HEADERS	*	CORS 允许的头

CLI 标志

# HTTP 服务器标志
uniprot-mcp-http --host 127.0.0.1 --port 9000 --log-level debug --reload

📖 使用示例

获取蛋白质条目

# 使用 MCP 客户端
result = await session.call_tool("fetch_entry", {
    "accession": "P12345"
})

# 返回结构化的 Entry 包含：
# - 主准入编号，蛋白质名称，生物体
# - 序列（长度，质量，序列字符串）
# - 特征（域，修饰，变异）
# - GO 注释（生物学过程，分子功能，细胞成分）
# - 到其他数据库的交叉引用

搜索蛋白质

# 搜索已审核的人类蛋白质
result = await session.call_tool("search_uniprot", {
    "query": "kinase AND organism_id:9606",
    "size": 50,
    "reviewed_only": True,
    "sort": "annotation_score"
})

# 返回 SearchHit 对象列表，包含准入编号和分数

映射标识符

# 将 UniProt ID 转换为 PDB 结构
result = await session.call_tool("map_ids", {
    "from_db": "UniProtKB_AC-ID",
    "to_db": "PDB",
    "ids": ["P12345", "Q9Y6K9"]
})

# 返回 MappingResult，包含成功和失败的映射

🛠️ 开发

前提条件

• Python 3.11 或 3.12
• uv（推荐）或 pip

设置

# 克隆仓库
git clone https://github.com/josefdc/Uniprot-MCP.git
cd Uniprot-MCP

# 安装依赖
uv sync --group dev

# 安装开发工具
uv tool install ruff
uv tool install mypy

运行测试

# 运行所有测试并生成覆盖率报告
uv run pytest --maxfail=1 --cov=uniprot_mcp --cov-report=term-missing

# 运行特定测试文件
uv run pytest tests/unit/test_parsers.py -v

# 仅运行集成测试
uv run pytest tests/integration/ -v

代码质量

# 检查
uv tool run ruff check .

# 格式化
uv tool run ruff format .

# 类型检查
uv tool run mypy src

# 运行所有检查
uv tool run ruff check . && \
uv tool run ruff format --check . && \
uv tool run mypy src && \
uv run pytest

本地开发服务器

# Stdio 服务器
uv run uniprot-mcp

# 带有自动重新加载的 HTTP 服务器
uv run python -m uvicorn uniprot_mcp.http_app:app --reload --host 127.0.0.1 --port 8000

🏗️ 架构

src/uniprot_mcp/
├── adapters/           # UniProt REST API 客户端和响应解析器
│   ├── uniprot_client.py  # 带有重试逻辑的 HTTP 客户端
│   └── parsers.py         # 将 UniProt JSON 转换为 Pydantic 模型
├── models/
│   └── domain.py       # 类型化数据模型（Entry, Sequence 等）
├── server.py           # MCP stdio 服务器（FastMCP）
├── http_app.py         # MCP HTTP 服务器（Starlette + CORS）
├── prompts.py          # MCP 提示模板
└── obs.py              # 可观察性（日志记录，指标）

tests/
├── unit/               # 解析器、模型、工具的单元测试
├── integration/        # 使用 VCR 固件的端到端测试
└── fixtures/           # 测试数据（UniProt JSON 响应）

📦 发布

此服务器发布到：

• PyPI：uniprot-mcp
• MCP 注册表：io.github.josefdc/uniprot-mcp

构建和发布

# 构建分发包
uv build

# 发布到 PyPI（需要令牌）
uv publish --token pypi-YOUR_TOKEN

# 发布到 MCP 注册表（需要 GitHub 认证）
mcp-publisher login github
mcp-publisher publish

查看 docs/registry.md 获取详细的注册表发布说明。

🤝 贡献

欢迎贡献！请：

1. 阅读我们的 贡献指南
2. 遵循我们的 行为准则
3. 查看 安全政策 以报告漏洞
4. 查阅 变更日志 了解最近的变化

快速入门贡献者：

1. 分叉仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 编写测试并进行更改
4. 运行质量检查：uv tool run ruff check . && uv tool run mypy src && uv run pytest
5. 使用 常规提交消息 提交（feat:，fix:，docs: 等）
6. 推送并打开拉取请求

📄 许可证

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。

🙏 致谢

• UniProt 联盟：通过他们的 REST API 提供全面、高质量的蛋白质数据
• Anthropic：提供 Model Context Protocol 规范和 Python SDK
• 社区：提供反馈、错误报告和贡献

🔗 链接

• 文档：GitHub 仓库
• UniProt API：REST API 文档
• MCP 规范：Model Context Protocol
• 问题和支持：GitHub 问题

⚠️ 免责声明

这是一个独立项目，未经 UniProt 联盟正式认可或支持。使用其数据时，请查阅 UniProt 的 使用条款。

---

为生物信息学和 AI 社区打造 ❤️