uniprot-mcp-server

<div align="center"> <h1>UniProt MCP 服务器</h1> <p><b>通过蛋白质功能搜索 UniProtKB，获取精选记录，在数据库之间映射 ID，并通过 MCP 获取参考蛋白质组、分类和序列。</b> <div>6 个工具 • 2 个资源 • 1 个提示</div> </p> </div> <div align="center"> [](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/uniprot-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/uniprot-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/) </div> <div align="center"> [](https://github.com/cyanheads/uniprot-mcp-server/releases/latest/download/uniprot-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=uniprot-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdW5pcHJvdC1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22uniprot-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A5B%22-y%22%2C%22%40cyanheads%2Funiprot-mcp-server%22%5D%7D) [](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) </div> --- ## 工具 六个用于基于蛋白质研究的 UniProt 工具 - 发现搜索是入口点，`uniprot_map_ids` 是桥梁，将任何同源标识符转换为 UniProtKB 访问编号，其余工具获取精选记录、蛋白质组、分类和序列： | 工具 | 描述 | |:---|:---| | `uniprot_search_proteins` | 通过纯文本或 Lucene 字段查询搜索 UniProtKB，重点关注已审查（Swiss-Prot）的筛选和可选的服务器端分面计数。光标分页。发现入口点。 | | `uniprot_get_entry` | 通过访问编号批量获取完整的精选条目（最多 20 个）- 功能、催化活性、疾病、变异、异构体、GO 术语、交叉引用。部分成功输出；大型记录返回章节大纲。 | | `uniprot_map_ids` | 通过 UniProt 的异步 ID 映射服务在数据库之间转换标识符 - 基因名称、Ensembl、RefSeq、ChEMBL、PDB、GeneID ↔ UniProtKB 访问编号。在预算内轮询；如果超出则返回可恢复的票据。 | | `uniprot_get_proteome` | 通过 UPID 或 NCBI 分类编号获取参考蛋白质组 - 蛋白质数量、BUSCO 完整性、基因组组装内联，以及蛋白质的可选分页。 | | `uniprot_get_taxonomy` | 通过 NCBI 分类编号或科学名称解析分类记录 - 名称、等级、父级、完整谱系和可选的直接子级。 | | `uniprot_get_sequence` | 获取访问编号的规范氨基酸序列（FASTA）- 长度和解析的头部 - 以及可选的异构体序列。廉价的仅序列路径。 | ### `uniprot_search_proteins` 搜索 UniProtKB 并返回精选的蛋白质记录 - 发现入口点。 - `text_search` 用于自然语言（80% 的情况）**或** `query` 用于完整的 Lucene 字段语法（`gene`、`organism_id`、`keyword`、`go`、`reviewed`、`protein_name`、`family`、`length`、`existence`、`accession`）- 恰好一个 - `reviewed` 默认值为 `true`（仅限 Swiss-Prot），以便代理不会被 TrEMBL 预测淹没；设置为 `false` 以包含它们 - `organism_id` 便捷筛选器，与查询 AND 运算 - 可选的 `facets` 用于服务器端计数分解（例如 `reviewed`、`model_organism`） - 前向光标分页（UniProtKB 没有偏移分页）；返回 `totalResults` 和有效的查询 - 每个命中记录都带有 `reviewed`、`annotationScore` 和 `proteinExistence`，以便可以衡量策划质量 --- ### `uniprot_get_entry` 通过访问编号批量获取完整的 UniProtKB 精选条目 - 此工具不进行搜索。 - 批量处理最多 20 个访问编号 - 分段记录：功能、催化活性、辅因子、亚细胞位置、疾病、PTM、天然变异、异构体、域、GO 术语、关键词、交叉引用 - 部分成功输出 - 在 `succeeded[]` 中解析的条目，在 `failed[]` 中未知的/已撤回的条目；整个批次不会因一个错误的访问编号而中止 - `fields` 修剪上游投影；身份和出处字段始终保留 - 单个大型记录返回 `kind: "outline"`（章节列表）而不是溢出上下文 - 重新调用相同的访问编号，带有 `sections: [...]` 以获取所需的內容 - 访问编号来自 `uniprot_search_proteins` 或 `uniprot_map_ids`；首先删除任何 `-N` 异构体后缀 --- ### `uniprot_map_ids` 通过 UniProt 的 ID 映射服务在数据库之间转换标识符 - 桥梁，从任何同源服务器的标识符转换为 UniProtKB 访问编号。 - `from_db` / `to_db` 是验证的枚举（例如 `Gene_Name`、`Ensembl`、`RefSeq_Protein`、`ChEMBL`、`PDB`、`GeneID`、`UniProtKB_AC-ID`），因此不支持的对在上游调用之前失败 - 目标 `UniProtKB-Swiss-Prot` 仅限于已审查的访问编号（通常的意图），或 `UniProtKB` / `UniProtKB_AC-ID` 包括未审查的 TrEMBL - 作业异步运行；工具提交它并在预算内轮询。完成时间 → `status: "finished"` 带有映射；运行时间长 → `status: "running"` 带有可恢复的票据 - 重新调用票据本身（服务器端持有作业） - 将基因符号 `from_db` 与 `tax_id` 配对以消除物种歧义 - 报告未映射的输入 ID 以及已解析的映射 --- ### `uniprot_get_proteome` 通过 UPID 或 NCBI 分类编号获取指定生物的参考蛋白质组 - 提供恰好一个。 - 内联元数据：蛋白质组类型、蛋白质总数、BUSCO 完整性（分数、完整/片段/缺失计数、谱系数据集）、基因组组装访问编号 - 蛋白质集通过 `include_proteins` 可选（它很大 - 人类有 ~147,506）并返回带有前向光标和截断披露的分页 - 使用 `query` 过滤器（UniProtKB Lucene 语法）缩小蛋白质列表以获取子集 - 使用 `uniprot_get_taxonomy` 将生物名称解析为分类编号 --- ### `uniprot_get_taxonomy` 通过 NCBI 分类编号或科学名称解析分类记录 - 提供恰好一个。 - 返回科学和常用名称、助记符、等级、父级和完整谱系（根 → 近祖先） - `include_children` 通过后续搜索获取直接子分类（不在记录中内联） - 将生物名称转换为 `uniprot_search_proteins` （`organism_id`）和 `uniprot_get_proteome` （`taxon_id`）期望的分类编号 --- ### `uniprot_get_sequence` 获取访问编号的规范氨基酸序列（FASTA）- 廉价的仅序列路径（对于完整的函数记录，请使用 `uniprot_get_entry`）。 - 返回具有长度和解析的 FASTA 头部的规范序列 - `include_isoforms` 还返回替代剪接的异构体序列 - 访问编号来自 `uniprot_search_proteins` 或 `uniprot_map_ids`；首先删除任何 `-N` 异构体后缀 ## 资源和提示 | 类型 | 名称 | 描述 | |:---|:---|:---| | 资源 | `uniprot://entry/{accession}` | 通过访问编号获取精选的 UniProtKB 条目 - `uniprot_get_entry` 用于单个访问编号的资源镜像。 | | 资源 | `uniprot://taxonomy/{taxonId}` | 通过 NCBI 分类编号获取分类记录 - 名称、等级、父级、完整谱系。 `uniprot_get_taxonomy` 按 ID 的镜像。 | | 提示 | `uniprot_protein_dossier` | 引导蛋白质研究工作流程 - 解析标识符、获取精选条目、提取疾病和变异，并显示结构、引用和生物活性的交叉引用。 | 所有资源数据也可以通过工具获取 - 仅限工具的客户端不会损失任何内容。 UniProtKB 太大，无法枚举，因此没有资源 `list()`；发现是 `uniprot_search_proteins` 的工作。 ## 特色 基于 [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)： - 声明式工具、资源和提示定义 - 每个基元一个文件，框架处理注册和验证 - 统一错误处理 - 处理程序抛出，框架捕获、分类和格式化 - 可插拔身份验证：`none`、`jwt`、`oauth` - 可交换存储后端：`in-memory`、`filesystem`、`Supabase`、`Cloudflare KV/R2/D1` - 带有可选 OpenTelemetry 跟踪的结构化日志记录 - STDIO 和 Streamable HTTP 传输 UniProt 特定： - 无密钥 - UniProt REST 不需要 API 密钥；针对任何兼容 `rest.uniprot.org` 的基站（覆盖 `UNIPROT_BASE_URL` 以获取私有镜像） - 所有四个 REST 集合上的一个薄 `fetch` 客户端（UniProtKB、ID 映射、蛋白质组、分类）带有重试/退避和 HTML 错误页面检测 - 批量条目获取 - 一个往返中的 N 个访问编号，交叉引用请求以标记任何缺失的编号 - 异步 ID 映射运行 → 轮询 → 结果受时钟预算限制，在溢出时带有可恢复的服务器端票据 代理友好输出: - 来源是数据，而不是装饰 - `reviewed`、`annotationScore`、`proteinExistence` 和每个字段的 PubMed/ECO 证据在每个记录上都有，以便代理可以衡量手动与预测的注释 - 宽容的部分失败 - `uniprot_get_entry` 返回每个访问编号的 `succeeded[]` / `failed[]` 行，而不是中止批次 - 区分输出契约 - `uniprot_get_entry` 返回 `kind: "full" | "outline"`，`uniprot_map_ids` 返回 `status: "finished" | "running"`；调用者根据数据分支，而不是字符串解析 - 保留稀疏性 - 缺失的上游字段保持缺失，永不捏造（大多数精选部分在 TrEMBL 条目中合法缺失） ## 快速入门 将以下内容添加到您的 MCP 客户端配置文件中。 UniProt REST 是无密钥的 - 不需要 API 密钥。 ```json { "mcpServers": { "uniprot-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/uniprot-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或使用 npx（不需要 Bun）： ```json { "mcpServers": { "uniprot-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/uniprot-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或使用 Docker： ```json { "mcpServers": { "uniprot-mcp-server": { "type": "stdio", "command": "docker", "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/uniprot-mcp-server:latest"] } } } ``` 对于 Streamable HTTP，设置传输并启动服务器： ```sh MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http # 服务器监听 http://localhost:3010/mcp ``` ### 先决条件 - [Bun v1.3.11](https://bun.sh/) 或更高版本（或 Node.js v24+）。 - 无 API 密钥 - UniProt REST 是无密钥且开放的。数据来自 [UniProt](https://www.uniprot.org)，CC BY 4.0。 ### 安装 1. **克隆仓库：** ```sh git clone https://github.com/cyanheads/uniprot-mcp-server.git ``` 2. **进入目录：** ```sh cd uniprot-mcp-server ``` 3. **安装依赖项：** ```sh bun install ``` ## 配置 所有配置在启动时通过 `src/config/server-config.ts` 中的 Zod 模式验证。 UniProt REST 是无密钥的，因此以下每个服务器特定变量都是可选的重写。 | 变量 | 描述 | 默认值 | |:---|:---|:---| | `UNIPROT_BASE_URL` | UniProt REST 基站 URL。覆盖私有镜像或测试。 | `https://rest.uniprot.org` | | `UNIPROT_TIMEOUT_MS` | 每个请求的 HTTP 超时毫秒数。 | `30000` | | `UNIPROT_ID_MAPPING_BUDGET_MS` | 内联 ID 映射轮询循环的时钟预算，在返回可恢复的票据之前。必须小于 `UNIPROT_TIMEOUT_MS`。 | `8000` | | `UNIPROT_DEFAULT_PAGE_SIZE` | 调用者未设置时，搜索和蛋白质组蛋白质列表的默认页面大小。 | `25` | | `MCP_TRANSPORT_TYPE` | 传输：`stdio` 或 `http`。 | `stdio` | | `MCP_HTTP_PORT` | HTTP 服务器端口。 | `3010` | | `MCP_AUTH_MODE` | 身份验证模式：`none`、`jwt` 或 `oauth`。 | `none` | | `MCP_LOG_LEVEL` | 日志级别（RFC 5424）。 | `info` | | `LOGS_DIR` | 日志文件目录（仅限 Node.js）。 | `<project-root>/logs` | | `STORAGE_PROVIDER_TYPE` | 存储后端。 | `in-memory` | | `OTEL_ENABLED` | 启用 [OpenTelemetry 仪表盘](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)（跨度、指标、完成日志）。 | `false` | 参见 [.env.example](./.env.example) 获取完整的覆盖项列表。 ## 运行服务器 ### 本地开发 - **构建并运行： ```sh # 一次性构建 bun run rebuild # 运行构建的服务器 bun run start:stdio # 或 bun run start:http ``` - **运行检查和测试： ```sh bun run devcheck # 校验、格式化、类型检查、安全 bun run test # Vitest 测试套件 bun run lint:mcp # 验证 MCP 定义是否符合规范 ``` ### Docker ```sh docker build -t uniprot-mcp-server . docker run --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/uniprot-mcp-server:latest ``` Dockerfile 默认使用 HTTP 传输、无状态会话模式和日志记录到 `/var/log/uniprot-mcp-server`。OpenTelemetry 对等依赖项默认安装 - 构建时添加 `--build-arg OTEL_ENABLED=false` 以省略它们。 ## 项目结构 | 目录 | 用途 | |:---|:---| | `src/index.ts` | `createApp()` 入口点 - 注册工具/资源/提示并初始化 UniProt 服务。 | | `src/config` | 服务器特定环境变量解析和验证与 Zod。 | | `src/mcp-server/tools` | 工具定义 (`*.tool.ts`)。六种工具，涵盖 UniProtKB、ID 映射、蛋白质组、分类、序列。 | | `src/mcp-server/resources` | 资源定义 (`*.resource.ts`)。按 ID 镜像条目和分类。 | | `src/mcp-server/prompts` | 提示定义 (`*.prompt.ts`)。蛋白质档案工作流程提示。 | | `src/services/uniprot` | `rest.uniprot.org` REST 客户端 - 搜索、批量条目、ID 映射、蛋白质组、分类、FASTA - 以及规范的域类型。 | | `tests/` | 镜像 `src/` 的单元测试和集成测试。 | ## 开发指南 参见 [CLAUDE.md](./CLAUDE.md)（和字节相同的 [AGENTS.md](./AGENTS.md)）获取开发指南和架构规则。简短版本： - 处理程序抛出，框架捕获 - 工具逻辑中没有 `try/catch` - 使用 `ctx.log` 记录请求范围的日志，使用 `ctx.state` 记录租户范围的存储 - 在 `createApp()` 数组中注册新的工具和资源 - 包装 UniProt API：验证原始 → 规范化为域类型 → 返回输出模式；绝不捏造缺失的字段 ## 贡献 欢迎提出问题和拉取请求。在提交之前运行检查和测试： ```sh bun run devcheck bun run test ``` ## 许可证 Apache-2.0 - 详见 [LICENSE](LICENSE) 。