# 生信 MCP 平台

本项目把现有的 volcano.R 封装为一个可发现、可异步执行、可追踪产物的 MCP Plot 工具。当前聚焦单机 MVP：

- MCP JSON-RPC：/mcp
- REST 调试接口：/api
- 工具注册：扫描 bioinformatics/**/manifest.yaml
- Job：SQLite 持久化、单 Worker、取消、超时和日志
- 执行器：local（直接调用 Rscript）或 docker（独立容器）
- 产物：本地 artifacts/，通过 artifact://job-id/path 引用

## 快速开始

    python -m venv .venv
    . .venv/bin/activate
    python -m pip install -r requirements.txt
    mkdir -p data/input artifacts data/work
    cp bioinformatics/plots/volcano/examples/minimal.csv data/input/
    export BIO_MCP_EXECUTOR=local
    uvicorn apps.mcp_api.main:app --host 127.0.0.1 --port 8000

健康检查和工具发现：

    curl http://127.0.0.1:8000/health
    curl http://127.0.0.1:8000/api/tools

提交任务时，input_file 必须是 data/input 下文件的绝对 file URI：

    curl -X POST http://127.0.0.1:8000/api/jobs \
      -H 'content-type: application/json' \
      -d '{
        "unit": "volcano",
        "inputs": {
          "input_file": "file:///绝对路径/MCP/data/input/minimal.csv"
        },
        "parameters": {
          "feature_column": "gene_id",
          "p": 0.05,
          "drawFC": 1
        }
      }'

返回 job_id 后查询：

    curl http://127.0.0.1:8000/api/jobs/<job-id>
    curl http://127.0.0.1:8000/api/jobs/<job-id>/artifacts

MCP Client 配置见 部署教程.md，完整约束见 开发规范.md。

## 目录

    apps/mcp_api/                        MCP API、注册表、Store、Runner
    bioinformatics/plots/volcano       volcano 单元、Schema、Dockerfile、样例
    check/                              通用文件检查和 check_volcano_input
    data/input/                          允许提交的本地输入根目录
    data/work/                           Job 临时工作目录
    artifacts/                           Job 产物
    deploy/                              Compose 和 API 镜像
    tests/                               注册表、协议和契约测试
    项目计划.md                           分阶段架构和验收计划
    文件流向图.md                         输入检查、Runner、Docker 和产物流向
    部署教程.md                           本地、Compose、Docker 执行部署
    开发规范.md                           manifest、CLI、测试和安全规范

## 执行模式

local 模式适合开发：Runner 直接调用宿主机 Rscript，速度快但隔离较弱。

docker 模式适合验证容器契约：

    docker build -f bioinformatics/plots/volcano/Dockerfile \
      -t local/bio/volcano .
    BIO_MCP_EXECUTOR=docker uvicorn apps.mcp_api.main:app \
      --host 127.0.0.1 --port 8000

Docker 模式要求 Docker CLI 可用，并且 Runner 能访问 Docker Engine。生产环境不要把 Docker Socket 直接暴露给公网 API，应拆出受策略约束的 Runner Service。

## 验证

    python -m compileall -q apps
    pytest -q
    ruff check apps tests

R 端到端测试需要安装 volcano.R 依赖；Docker 构建会在镜像内安装公开 R 包。