vara-mcp-server

本地 stdio MCP server，把 Vara 研算的 /v1 数据接口包成 25 个 agent 工具。配好后不用开网页，直接对 AI 助手（Claude Code / Claude 桌面版 / Codex 等）说人话，它就代你查 / 搜 / 建 / 补充实验、传附件、管文献与物料，甚至把一篇论文变成可复现的实验草稿。

日常的查、搜、建、补充实验都用大白话说就行，不用开网页；只有「论文导入」最后一步需要你到 Vara 网页点确认。

适合谁

• 不想在网页里一条条手动录入实验的人
• 习惯在 AI 助手里干活、希望顺手把实验存进 Vara 的人
• 想把论文 / 协议 / 实验笔记快速结构化成可复现实验的人

能帮你做的事

1. 查看 / 搜索（只读）—「列出我最近的 Vara 实验」「搜含 Triton X-100 的实验」，跨实验 / 子实验 / 参数匹配。vara_get_experiment 现在连附件（实验 / 子实验 / 运行各层级）和挂接的文献一起返回。
2. 新建 / 补充 / 更新（写）—「新建实验…」「加一个子实验…」「记录这次运行…」「把那次运行的结论补上」
3. 📎 附件—「把这张结果图传到那个步骤上」：给本地图片 / PDF / CSV / Excel 路径，直接上传绑定到实验 / 子实验 / 运行（也能删）
4. 📚 文献库—「把这几个 DOI 加进文献库」「这篇 PDF 提取元数据入库」「把这篇挂到 XX 实验上」（列 / 加 DOI / 从 PDF 加 / 删 / 挂接 / 取消挂接）
5. 🧪 物料—「列出我的细胞株」「建一个培养基物料」
6. 🗓 实验计划—「列出今天的实验计划」「明天加一项 qPCR」
7. ⭐ 论文 → 可复现实验草稿（导入）—「这篇论文的 Methods 帮我导进 Vara」（详见下文）

安装

先在 https://www.varaapp.site/settings/api 创建一个 vara_sk_ key（要用写功能就选 read_write，只查看用只读 key 即可）。需要 Node 18+。

方式 A — npx（推荐，无需源码）：不用 clone 仓库，在下方配置里直接用 npx -y vara-research-mcp，npm 会自动拉取并运行最新版。

方式 B — 从源码 build（开发者）：

cd mcp && npm install && npm run build

配置

Claude Code（CLI） — npx 版，无需源码：

claude mcp add vara \
  -e VARA_API_KEY="vara_sk_你的key" \
  -e VARA_BASE_URL="https://www.varaapp.site/api/v1" \
  -- npx -y vara-research-mcp

Codex（CLI）：

codex mcp add vara \
  -e VARA_API_KEY="vara_sk_你的key" \
  -e VARA_BASE_URL="https://www.varaapp.site/api/v1" \
  -- npx -y vara-research-mcp

Claude Desktop / 其它（JSON 配置）

{
  "mcpServers": {
    "vara": {
      "command": "npx",
      "args": ["-y", "vara-research-mcp"],
      "env": {
        "VARA_API_KEY": "vara_sk_xxx",
        "VARA_BASE_URL": "https://www.varaapp.site/api/v1"
      }
    }
  }
}

从源码 build 的版本（方式 B）：把 command 换成 "node"、args 换成 ["/绝对路径/mcp/dist/index.js"]。

重启客户端后 vara_* 工具才会出现（MCP 工具在启动时加载）。验证：对 AI 说「列出我的 Vara 实验」。

完整工具清单（25 个）

只读（任何有效 key 都能用）

| 工具 | 作用 | 关键输入 | |---|---|---| | vara_get_import_schema | 取导入规则 + schema + 示例（导入前必先调） | 无 | | vara_list_experiments | 列出你的实验（最新在前） | limit 1–100，默认 50 | | vara_get_experiment | 取单个实验的全部细节（含附件 + 挂接文献） | id | | vara_search | 关键词搜实验 / 子实验 / 参数 | q（≥2 字符） | | vara_plan_list | 列出某天 / 某区间的实验计划 | date 或 from/to | | vara_list_references | 列出文献库 | limit 1–500、state（默认 active） | | vara_list_materials | 列出物料（细胞株 / 培养基 / 试剂…） | 无 |

写（需要 read_write 权限的 key）

| 工具 | 作用 | 关键输入 | |---|---|---| | vara_import_experiment | 导入整份实验为待确认草稿 | bundle 或 markdown | | vara_create_experiment | 直接新建实验（立即入库） | name（必填）/ purpose / description / kind | | vara_update_experiment | 改名称 / 目的 / 描述 / 状态 | id + 要改的字段 | | vara_add_step | 给实验加一个子实验 | experimentId / title（必填）/ action / durationMin / notes | | vara_update_step | 改子实验 | id + 要改的字段 | | vara_log_run | 记录一次运行（可挂到某子实验） | experimentId / observations / deviations / conclusion / runDate | | vara_update_run | 改已有运行的观察 / 偏差 / 结论 / 日期 | id + 要改的字段 | | vara_plan_add | 加一条实验计划 | date（必填）/ title（必填）/ startTime / durationMin | | vara_plan_update | 改一条计划（含勾完成） | id + 要改的字段 | | vara_plan_remove | 删一条计划 | id | | vara_attach_file | 传本地文件并绑定到实验 / 子实验 / 运行 | entityType / entityId / filePath / caption? | | vara_delete_attachment | 删附件 | id | | vara_add_references | 按 DOI 批量加文献（≤50） | dois[] 或 text | | vara_add_reference_from_pdf | 从本地 PDF 提元数据入库 | filePath（.pdf） | | vara_delete_reference | 归档文献（软删） | id | | vara_link_reference | 把文献挂到实验 | experimentId + referenceId 或 doi | | vara_unlink_reference | 取消文献与实验的挂接（不删文献） | experimentId / referenceId | | vara_create_material | 建物料 | type / name / identityFields? |

术语提醒： vara_add_step 里的 "step" 指子实验（API 端点 /steps）。子实验内部更细的「操作步骤 (procedureSteps)」目前通过导入整批写入，不单独提供逐条增删工具。

实验状态 可选：DRAFT / READY / RUNNING / COMPLETED / FAILED。类型 kind：PILOT（预实验）/ FORMAL（正式，默认）。

附件白名单：png / jpg / jpeg / gif / webp / pdf / csv / xls / xlsx，单文件 ≤50MB（本地先校验，省一次往返）。

加记录前先问：你没说清「加到哪个实验 / 哪种记录」时，AI 会先列候选让你确认，不瞎猜、不默认新建。

⭐ 论文 → 可复现实验（导入流程）

手动把论文录进系统极枯燥，是最大的「冷启动」门槛。导入让 AI 替你干，而且做得很严谨。

流程（AI 自动完成，你只需提供原文 + 最后确认）：

1. AI 先调 vara_get_import_schema 拿到 schema 版本、转换规则和一个标准示例。
2. 你把来源贴给 AI —— 完整 Methods 章节、试剂盒说明、实验笔记，甚至一句话研究意图都行。
3. AI 按规则生成结构化 bundle，调 vara_import_experiment。
4. 返回 reviewUrl + status: pending_review —— 到 Vara 网页确认后才入库。未确认的草稿不会进入你的实验列表，导错了不用慌。

一份导入会捕获： 实验 / 子实验 / 操作步骤（严格按原文顺序）· 参数（值 / 单位 / 来源章节）· 评估基线（evaluationBaselines）· 材料（materials）· 复现风险（reproductionRisks）· AI 推断（aiInferences）。

严谨性（和「让 AI 随便写」的关键区别）：

• 每个字段标来源：explicit🟢原文逐字 · partial🟡缺值 · inferred🔴常识补 · missing⚫没提，都带置信度
• 缺的不瞎编 → 进「复现风险」，提示你核对 / 联系作者
• AI 补的不混入原文 → 单独进「AI 推断」，附原文引用 + 核对提示
• 只从本研究 Methods 提取，不从 Introduction / 他人工作 / 对比表里借数字
• 来源语言不限：中文论文也能导，字段默认翻译为英文输出（试剂名 / 型号 / CAS 号 / 公式等保留原样）

重要规则与边界

| 规则 | 说明 | |---|---| | 草稿 vs 直接入库 | import_experiment = 待确认草稿（网页确认后才生效）；create_experiment = 立即入库 | | 核心数据删不掉 | 实验 / 子实验 / 运行没有删除工具，删不了。可删的仅：附件、文献（软删归档）、文献与实验的挂接 | | 读 / 写权限 | 读工具任何 key 都能用；写工具需 read_write key。报 403 = 你的 key 是只读的 | | 数据隔离 | 只能看到 / 修改这个 key 所属账号的实验 | | 频率限制 | 写操作 60 次/分钟，超了报 429 | | 响应截断 | 单次响应超 25000 字符会截断 → 换更具体的查询，或直接用 id 取单个 |

报错速查： 401 key 无效 → 检查 VARA_API_KEY｜403 无写权限 → 去 /settings/api 建 read_write key｜404 id 不存在 / 不属于你 → 先 vara_search｜422 校验失败 → 按提示改字段｜429 限流 → 等一下｜连不上 → 检查 VARA_BASE_URL 与服务是否在线

常见问题

• 工具没出现 → 客户端没重启；或用 claude mcp list 看连接状态（应为 ✓ Connected）
• 一写就 403 → 你的 key 是只读，去 https://www.varaapp.site/settings/api 建一个 read_write key
• 连不上 → 检查 VARA_BASE_URL 是否为 https://www.varaapp.site/api/v1，以及服务是否在线

附：典型对话示例

| 你对 AI 说 | 它会调用 | |---|---| | 「我有哪些 Vara 实验？」 | vara_list_experiments | | 「搜含 qPCR 的实验」 | vara_search | | 「把 xxx 实验的步骤和参数列给我」 | vara_get_experiment | | 「新建实验『SFRP1 qPCR 检测』，预实验」 | vara_create_experiment | | 「给它加一步：退火 60°C，约 30 分钟」 | vara_add_step | | 「记录今天的运行：Ct 值偏高，已重做」 | vara_log_run | | 「这篇论文的 Methods（贴入）导进 Vara」 | vara_get_import_schema → vara_import_experiment |