Saturday Materials MCP server

Saturday —— 材料计算的插件运行时

简体中文 | English

Everything is a plugin。 Saturday 不是又一套材料计算引擎，不替代 DFT / MD / FEM / CFD 的任何求解器； 它是材料计算的组合层：引擎、结构源、工作流、分析工具全部以插件形态挂载到 DeepSeek Harness (dsh) / @deepseek-ai/cordis v4 运行时上，由 Agent 在运行时自由挂载、卸载与组合。

插件接口规范见 packages/bridge/docs/plugin-contract-v0.md（中文原本，英文摘要版同目录）。

60 秒上手

不需要 Python、不需要装任何求解器——有 Node ≥ 22 就能让 Agent 拿到真实的材料回算数值 （无 ASE 时自动走零依赖 lj-js 引擎；能量由引擎回算，非玩具占位假数）。

最快一行（连客户端都不配）：npx -y @toki0413/mcp-server --relax Cu 直接打印 Cu 的每原子能量与所用引擎（装了 MACE/ASE 会自动升真物理）。

免装 Node/Python（全保真容器）：docker run --rm ghcr.io/toki0413/saturday --relax Cu 一行拿 EMT 真值，镜像已内含 Node + Python + ASE（构建/推镜像由 GitHub Actions + GHCR 承担，本地不装工具链）。

路径 A：接进任意 MCP 客户端（Claude Desktop / Cursor / Cherry Studio 等）——在客户端配置里加：

{
  "mcpServers": {
    "saturday-materials": { "command": "npx", "args": ["-y", "@toki0413/mcp-server"] }
  }
}

存盘重启客户端，对它说一句“把 Cu 弛豫一下并给出每原子能量”，它会调 potential.relax 返回 energyPerAtom（eV）；material.load / workflow.screen（掺杂筛选）/ analysis.phonon（声子） 等 54 个工具都在。想要真实 EMT/LAMMPS 物理，再装 Python≥3.10 + ASE（见下“环境矩阵”）， 引擎按能力自动升级，插件面契约与单位/指纹门禁不变。

路径 B：本地跑起来看全链

git clone https://github.com/toki0413/dsh-saturday && cd dsh-saturday
npm install && npm test        # 全量回归（纯 Node 即可）
npm run demo                   # 一条十阶段端到端：加载→采样→筛选→声子→回算，环境自适应
npm run demo:agent             # 一个 prompt 驱动整个发现链（mock LLM，无外部依赖）

想知道“我该调哪个工具”→ 见 docs/recipes.md（按意图找工具与参数）； 5 分钟上手与拒绝伪造证据的演示 → docs/agent-e2e-demo.md。

核心范式

时空可组合性（Spatiotemporal Composability）

理论依据为 Cordis 配套论文：

A Programming Paradigm for Spatiotemporal Composability，Yifan Shi, Wei Zhang, Tianyi Cui，

arXiv:2608.25512 [cs.PL]（北京大学 / DeepSeek-AI）。

Saturday 把论文的两个正交维度落到材料计算域：

材料计算 = 双通道事件流

各引擎（DFT/MD/FEM/CFD）的运行时行为投影为两类事件，Saturday 的总线只做路由不改物理：

• 瀑布事件（因果链）：弛豫步、SCF 迭代、MD 步进——传递"当前状态接力棒"，全序、可回放，承载时间维；
• 广播事件（一对多）：收敛达成、能量异常、属性算出——多消费方订阅联动，承载空间维。

事件粒度因引擎而异（迭代级 ↔ 任务级），由能力握手显式声明。

原子化操作（Atomic Operations）

一切研发动作分解为可独立调用、自由组合的原语（relax / calculate / substitute …）， 同一组原语同时暴露给 Agent 工具、DSL 与编程 API。原子性按作用域分级： 软件资源域完全可逆（cordis effect）、计算任务域幂等 + 可取消、物理设备域永不回滚。

活的材料上下文

材料上下文 = 瀑布事件累积器之上的响应式谱系图：每个导出量声明推导来源， 上游变化沿谱系自动传播失效与重算。推导登记簿（@toki0413/plugin-derivation） 是这一形态的运行时载体，已接入真实筛选工作流（势函数热替换沿引擎引用全链失效）。 掺杂操作 Material.substitute 的不可变 fork 语义保证谱系全程可追溯。

能力（v0.3）

Shortened. The full README is on GitHub.