ImmunoGraph MCP

ImmunoGraph MCP

用于计算表位研究的标准模型上下文协议服务。 调用 46 个类型化工具，开展序列处理、免疫证据分析、结构与化学分析、对接和可供审查的导出。结果附带溯源信息，因此实时提供方的结果会与测试样例或合成演示明确区分。

问题 · 适用对象 · 用户流程 · 快速开始 · 真实 3D 结果 · 全部 46 个工具 · 参与贡献

重要

ImmunoGraph 支持的是计算研究，而非临床或实验验证。预测出的表位、对接姿势、评分或导出的 3D 模型，都不能证明结合、疫苗有效性或安全性。测试样例和合成结果仅用于演示，并会明确标注。

问题

表位研究工作流涉及多种软件：序列处理、免疫预测工具、HLA 覆盖率分析、结构数据库、分子制备、对接、相互作用分析和报告。每个步骤都有各自的输入格式、运行时和科学假设。当大模型或研究应用将这些步骤串联起来时，还必须跟踪每个结果由哪些输入和方法产生。如果缺少来源信息，看起来可信的评分或 3D 视图很容易被误读。

ImmunoGraph 为 MCP 宿主提供了统一的类型化接口来完成这些步骤。宿主可以发现并调用各个工具，在工具间传递输出，并检查明确的来源标签和导出内容。这能减少构建可供审查的计算工作流所需的自定义集成代码；但它不能取代科学判断，也不能自行验证预测结果。

适用对象

受众	典型用途
计算免疫学和疫苗研究团队	整理并审查序列、MHC、B 细胞、覆盖率和结构证据，以探索候选方案
结构生物信息学和药物化学研究人员	准备坐标、运行已配置的对接工具、检查姿势和接触，并导出实际文件
构建大模型研究助手的开发者	通过标准 MCP 提供类型化科学操作，无需为每个步骤单独编写适配器
教育工作者和可复现性审查者	使用明确标注的测试样例演示工作流，随后检查方法边界、溯源信息和产物

这些输出仅用于研究和教育。临床决策、有效性声明和实验验证都需要独立的方法和证据。

可以做什么

探索	分析	审核与分享
验证 FASTA、生成肽段窗口、检索 PDB 结构和 PubChem 化合物	调用已启用的 IEDB 预测器；计算共识和覆盖率；在已安装的情况下运行 RDKit、FreeSASA、fpocket、Meeko、Vina 和 PLIP	对调用方提供的证据进行排序；导出 CSV、PDB、SDF、PDBQT、对接姿势、Mol* 或对接查看器，以及带校验和的研究 ZIP 文件

这是一个包含 46 个工具的服务，而不是 46 个独立的实时数据提供方。每个工具都可单独调用。构建工作流时，客户端会在各次调用之间传递结果。

用户流程

研究人员在启用了 MCP 的聊天或应用中工作。客户端选择要调用的工具并传递证据；ImmunoGraph 执行每项请求的操作并返回带类型的结果。

步骤	研究人员或客户端操作	ImmunoGraph 响应
1. 连接	将 stdio 服务添加到 MCP 主机；仅启用研究所需的实时连接器	主机发现 46 个工具及其输入架构
2. 定义输入	提供 FASTA 序列和研究标准	validate_sequence 会检查并哈希序列；generate_candidate_peptides 会枚举真实的肽段窗口
3. 收集证据	请求可用的 MHC-I/II、B 细胞、群体或其他计算	每次调用都会返回分数，或包含来源状态的结构化失败信息；实时预测器需要使用其配置的服务
4. 确定优先级	将选定的证据、阈值和覆盖率数据传入评分与约束工具	归一化分数、共识、排除项和候选项排名取决于所提供的证据
5. 检查结构	可选地获取 PDB/化合物数据，并运行可及性、口袋、配体、对接或接触工具	在安装了科学计算运行时的情况下，返回基于坐标的输出、姿势文件、3D 查看器 HTML 和分析数据
6. 审核与导出	检查来源标签和参数，然后请求报告、CSV、追踪记录或研究 ZIP 文件	返回文件字节、长度和 SHA-256 哈希，供独立保存和验证

此流程具有模块化特性：用户可以调用单个工具，而无需运行所有阶段。run_agentic_workflow 会执行调用方提供且已获批准的工具调用；如果没有这些调用，它会返回计划，而不会悄悄启动完整研究。有关确切的执行边界，请参阅架构和工具实际能力矩阵。

开始使用

安装公开发行版

需要 Node.js 20 或更高版本。带版本号的 tarball 托管在 GitHub 上，并通过 npm 安装；immunograph-mcp 尚未发布到 npm 注册表。

npm install --global https://github.com/Ajey95/immuno-graph/releases/download/v0.2.1/immunograph-mcp-0.2.1.tgz

在支持 stdio 服务的 MCP 主机中注册已安装的命令：

{
  "mcpServers": {
    "immunograph": {
      "command": "immunograph-mcp"
    }
  }
}

该服务通过 stdio 使用 MCP，因此请通过主机启动它。如果主机找不到全局安装的命令，请配置其绝对路径。GitHub 发行版还包含源代码和 tarball 的 SHA-256 校验和。下载的公开 tarball 与该校验和匹配。

运行公开容器

官方 MCP Registry 条目指向公开的 OCI 镜像。在本地 stdio 主机中使用：

{
  "mcpServers": {
    "immunograph": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/ajey95/immuno-graph:0.2.1",
        "node", "dist/index.js"
      ]
    }
  }
}

该容器还支持受保护的 Streamable HTTP，路径为 /mcp。其必需的安全设置请参阅 HTTP 部署。

从源代码构建

git clone https://github.com/Ajey95/immuno-graph.git
cd immuno-graph
npm ci
npm run check
npm start

npm start 会提供 stdio MCP 服务。npm run check 会运行软件测试、构建、所有工具的示例调用、语义审计、依赖项审计和软件包试运行。对于主机，请将 command 指向 node，并将 args 指向 dist/index.js 的绝对路径。

工作原理

flowchart LR
    A["FASTA · PDB · SMILES"] --> H["MCP host"]
    H --> S["ImmunoGraph<br/>46 typed tools"]
    S --> D["Local calculations<br/>and exact fixtures"]
    S --> L["Optional live<br/>connectors"]
    D --> R["Results + provenance"]
    L --> R
    R --> O["Reports · 3D files · ZIP"]

由宿主选择要调用的工具。ImmunoGraph 会验证类型化输入、执行处理程序，并返回包含运行元数据和来源标签的结构化成功或失败数据。服务器不会在不告知的情况下运行完整研究，也不会将固定样例值当作实时证据。传输和模块详情请参阅架构。

技术设计

关注点	实现方式	重要性
客户端互操作性	官方 MCP SDK；本地宿主使用 stdio，部署环境使用带防护的 Streamable HTTP	一套可发现的工具契约可供支持 MCP 的客户端使用
输入和结果契约	Zod 模式、类型化处理程序、结构化 MCP 结果、显式错误	客户端可以验证参数并以编程方式处理失败
科学溯源	来源状态、方法／运行元数据，以及带版本的精确匹配固定样例	审查者可以区分已配置的实时任务与离线演示
导出完整性	内嵌制品字节、字节长度和 SHA-256 摘要	宿主可以保存实际的 PDB/PDBQT/CSV/ZIP 文件并进行验证
运行边界	可选连接器与本地科学二进制文件分别配置	缺少提供方时会明确报错，或仅使用请求指定且带标签的回退方案

注册表条目指向已发布的 OCI 镜像。可选科学二进制文件、模型下载和第三方服务的可用性仍是独立的运行时要求。

研究工作流

flowchart LR
    FASTA["Protein FASTA"] --> V["Peptide windows"]
    V --> E["Immune evidence"]
    E --> R["Constraints + ranking"]
    R --> X["Reviewable exports"]
    E -.->|Optional| S["Structure + docking"]
    S -.-> X

这些是相互独立的 MCP 调用。排名和报告取决于客户端提供的证据。禁用实时预测时，系统不会自动为任意新蛋白质给出科学上的结合结果。

分子对接和 3D 文件

已配置的实时工具可以使用实际坐标，而非装饰性模型：

flowchart LR
    P["Protein PDB"] --> R["Meeko receptor<br/>PDBQT"]
    L["Compound / SMILES"] --> M["RDKit + Meeko ligand<br/>SDF + PDBQT"]
    R --> V["AutoDock Vina"]
    M --> V
    V --> POSE["Pose PDBQT<br/>complex PDB"]
    POSE --> VIEW["3D viewer HTML"]
    POSE --> PLIP["PLIP contacts"]
    POSE --> ZIP["Research ZIP"]

真实 3D 结果

1IEP + 伊马替尼：导出的 Vina 最佳构象。 此图根据通过 LIVE_ONLY MCP 对接调用生成的已保存复合物 PDB渲染而成。面板 A 描绘蛋白质 Cα 坐标并显示配体；面板 B 显示配体和 5 Å 范围内的蛋白质原子。渲染脚本可根据这些坐标复现图像。这是对接能力示例，并非表位候选；构象评分是计算估值，并非实测亲和力。

1UYD + PubChem CID 2244：三个计算所得构象。 此图来自实时对接研究 ZIP 文件，其中包含受体、配体、Vina 构象、复合物和图像。其运行溯源信息和摘要标明了来源和生成的九个构象；图中展示了其中三个。标注框显示根据坐标计算的距离；虚线表示由几何关系推断的极性接触，并非经实验确认的化学键。

实时对接指南介绍了输入、运行时要求、示例文件，以及如何验证导出的构象链。交互式 3D 查看器可视化返回的坐标数据；这些图像均不能证明存在实验测得的结合。

可检查的来源信息

结果路径	含义	科学用途
LIVE	已配置的外部提供方或本地科学运行时使用提供的输入执行了操作	检查其方法、参数和局限性
FIXTURE	经批准的离线精确匹配重放	仅用于演示
SYNTHETIC	演示工具生成的确定性教学数据	仅用于演示
调用方提供的计算	排名、约束、校准和报告会转换提供的证据	取决于这些证据的质量和来源

46 工具现实情况矩阵记录了每个工具实际计算或获取的内容，以及执行的验证。特别是，GraphBepi 在此版本中仅使用 fixture；Parker 用于计算亲水性；启用后，BepiPred-3.0 是受支持的实时 B 细胞选项。

工具目录

分组	工具数	示例
预测	6	FASTA 验证、肽段窗口、MHC-I/II、B 细胞
证据与优先级排序	9	分数归一化、共识、HLA 覆盖率、排名
约束	5	重叠、重复项、阈值、候选项规则
结构	7	RCSB/AlphaFold、可及性、口袋、Mol*
化学	5	PubChem、RDKit 描述符、配体制备
对接	5	受体制备、Vina、姿势聚类、PLIP
报告与实用工具	9	CSV/报告数据、说明、工作流跟踪、ZIP
总计	46	一个 MCP 服务

请参阅完整工具目录和输入约定。如需尝试一次调用，请使用以下参数调用 validate_sequence：

{
  "fasta": ">protein\nACDEFGHIK",
  "profileVersion": "mvp-v1.0"
}

它会返回规范化序列、长度和 SHA-256 标识，或返回结构化验证错误。

启用实时连接器

大多数实时连接器默认处于禁用状态。请在 MCP 服务的环境中设置标志，并安装相关提供方运行时或允许其网络端点访问。.env.example 列出了相关设置。

功能	开关	其他要求
IEDB MHC-I/II、BepiPred-3.0、群体覆盖率	IEDB_LIVE_ENABLED、IEDB_BCELL_ENABLED、IEDB_POPULATION_COVERAGE_ENABLED	可访问相关 IEDB API
RCSB PDB、AlphaFold DB、PubChem	RCSB_PDB_ENABLED、ALPHAFOLD_DB_ENABLED、PUBCHEM_ENABLED	可访问提供方网络
RDKit、Meeko、FreeSASA、fpocket	请参阅环境配置	已安装的 Python 包或原生二进制文件
AutoDock Vina 和 PLIP	VINA_ENABLED、PLIP_ENABLED	已安装的运行时以及有效的坐标输入

如果所需提供方或二进制文件不可用，工具会根据请求的策略返回明确的失败信息或带标签的回退结果。npm 压缩包和容器不会捆绑可选科学二进制文件或模型下载内容。

HTTP 部署

npm run start:http 会在本地提供 http://127.0.0.1:3000/mcp，并将 GET /health 作为健康检查端点。若要使用远程端点，请设置 HOST=0.0.0.0、较长的 IMMUNOGRAPH_API_KEY、精确的 IMMUNOGRAPH_ALLOWED_HOSTS 和 IMMUNOGRAPH_ALLOWED_ORIGINS，并在入口处终止 TLS。镜像默认运行 HTTP 入口；发布镜像并不会创建托管端点。部署前请阅读 SECURITY.md。

验证与范围

CI 工作流会在 Node.js 20 和 22 上检查 Windows 和 Linux。标准 MCP 客户端已运行全部 46 个文档示例；语义审计会检查计算、来源信息和产物哈希。v0.2.1 容器发布运行测试了 46 个工具的发现，以及通过 Docker stdio、受保护的 HTTP 和测试 TLS 入口进行的实际调用。协议审计还会检查每个工具是否都提供参数说明和结构化结果架构。这些检查可以证明软件行为和打包符合预期，但不能证明每种科学方法都准确，也不能保证第三方服务始终可用。

表位研究中的动机很常见：Grifoni 等人（2020）的研究和 Ferreira 等人（2021）的研究等，会结合序列分析、预测、保守性分析以及其他工具提供的证据。ImmunoGraph 让计算流程中的交接更易于检查；独立审查和实验验证仍然必不可少。

贡献与获取帮助

欢迎贡献和可复现的错误报告。请先阅读 CONTRIBUTING.md，然后提交问题；安全问题请通过 SECURITY.md 报告。已发布的更改请参阅 CHANGELOG.md。ImmunoGraph 采用 MIT 许可证。