
Saturday Materials
io.github.toki0413Published by GitHub account toki0413v0.3.14Updated Oct 24, 2026
Materials computing tools for AI agents: structures, engines, phonons, EOS, NEB, sampling, lineage.
Overview
Gives an assistant materials-science computation tools: structure loading, relaxation, doping screening, phonons, EOS, NEB and sampling.
- What you can do
- Saturday is a plugin runtime that exposes materials computation as MCP tools. Reported capabilities include material.load for chemical formulas to structures, structure.fromSmiles for SMILES to 3D conformers, potential.relax for periodic and molecular relaxation, workflow.screen for batch doping screening with energy ranking, plus analysis.phonon, analysis.eos, analysis.neb, analysis.elasticity, sampler.* and workflow.* tools. The README states 56 tools are exposed over stdio, shrinking to 55 when no MP_API_KEY is set.
- When to use it
- Use it when an assistant should run materials calculations rather than only discuss them: relaxing a structure, ranking doped variants, computing phonons, equations of state, migration barriers or elastic tensors, and sampling candidate structures for later re-evaluation.
- Requirements
- Runs locally over stdio via npx @toki0413/mcp-server; Node >= 22 is required. Python >= 3.10 with ASE >= 3.22 unlocks real EMT physics; without it a zero-dependency LJ engine is used. Optional MP_API_KEY enables structure.resolve against Materials Project. An optional streamable-http mode and a Docker image are described.
Installation
In SourceWeft
- Open Saturday Materials in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
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 承担,本地不装工具链)。当前状态:镜像构建与容器内冒烟已在 CI 跑通,但 GHCR 推送只在打 v* tag 时发生,因此该命令自 v0.3.14 起可拉;现在就要零安装跑用上面那行 npx。
路径 A:接进任意 MCP 客户端(Claude Desktop / Cursor / Cherry Studio 等)——在客户端配置里加:
存盘重启客户端,对它说一句“把 Cu 弛豫一下并给出每原子能量”,它会调 potential.relax 返回
energyPerAtom(eV);material.load / workflow.screen(掺杂筛选)/ analysis.phonon(声子)
等 56 个工具都在。想要真实 EMT/LAMMPS 物理,再装 Python≥3.10 + ASE(见下“环境矩阵”),
引擎按能力自动升级,插件面契约与单位/指纹门禁不变。
路径 B:本地跑起来看全链
想知道“我该调哪个工具”→ 见 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)
MCP server:任意 MCP 宿主接入
上述工具面经 @toki0413/mcp-server 以 Model Context Protocol 全量暴露(56 工具,
stdio 传输;工具面随环境如实收缩——无 MP_API_KEY 时 structure.resolve 不注册 = 55 工具,
环境不可用的引擎/结构源挂载即跳过并显式报告,不展示注定失败的能力):
Claude Desktop / Cursor / Cline 等任何 MCP 宿主零代码接入,
参数 schema 由各工具的契约声明直通,工具失败以 MCP isError 携带结构化错误码。
宿主配置(Claude Desktop / Cursor / Cherry Studio 等通用 mcpServers 格式):
环境档位声明:纯 Node 环境下工具面为 lj-js 教学档(零依赖玩具势);本地安装 Python ≥ 3.10 + ASE ≥ 3.22 后自动解锁 EMT 真物理与全量 31 工具(启动横幅如实呈报,非静默降级)。
宿主适配层边界:MCP server 只依赖 @toki0413/kernel 的无宿主引导
(bootstrapPlugins,cordis 的 import 收敛在 kernel 包内)与插件包,
插件本身对 MCP 无感知——防腐层纪律不变。
引擎插件矩阵(均接入 @toki0413/contract-tests 标准套件):
emt-mock(核心,ASE EMT / LJ)、lj-js(零依赖纯 JS,玩具势教学档,优雅回退数据面)、lammps(批处理,粒度 job)、mace(ML 势,可用性预检)、ase(通用 ASE 计算器,自带 sidecar)。
EMT 能量零点为各元素平衡 fcc 晶体,energyPerAtom 近似形成焓。Cu 掺杂筛选实测: Cu3Pt (-0.10) < Cu3Au (-0.02) < Cu (0) < Cu3Ni (+0.01) < Cu3Ag (+0.02) eV/atom—— 有序化(Cu-Pt / Cu-Au)与相分离(Cu-Ni / Cu-Ag)倾向与实验冶金学一致。
环境矩阵
开箱即用:git clone → npm install 后,纯 Node 环境即可跑全部演示与全量回归(无额外依赖;无 ASE 时走零依赖 lj-js)。
数据面形态随环境自适应,启动横幅如实呈报(非静默降级:回退引擎是显式注册的独立引擎)。
- Node ≥ 22(dsh 硬性要求;裸 cordis 测试可在 Node 20 运行)
- Python 数据面依赖:numpy + scipy(仅升级精度时需要)
- Windows 下默认使用
python命令,可用bridge.python配置覆盖 - pnpm
CI(数据面双档矩阵)
每次推送/PR 自动跑两档(.github/workflows/ci.yml),与上方环境矩阵一一对应:
两档跑同一份测试:套件内环境自适应(HAS_ASE/dataPlane 探测 + 显式 skip,诚实不静默);
真物理断言(晶格常数、严格形成焓、互转自检)仅在精度档执行,零依赖档如实跳过不伪造。
结构(npm workspaces)
运行
挂载到 dsh(完整运行时)
demo:agent 展示 Agent 会话的完整编排能力:裸 cordis 进程内组装全部真实 dsh 服务 +
脚本化 mock 模型,覆盖材料加载、真实弛豫、采样联合排序、锚点持久化与恢复、血缘审计、
修复验收与回填十个阶段,全部以自然语言驱动。
设计原则
- 契约即宪法:
@toki0413/contract-tests提供 structure-resolver / potential-provider / workflow / sampler / derivation 五条 seam 的标准断言集,新插件npm test即过宪法; 兼容性由测试而非文档承诺 - 防腐层(依赖卫生):领域代码不 import cordis,上游变更的影响面收敛到适配层一个文件; dsh 为唯一官方宿主,裸 cordis 作为开发/CI 模式
- 单位与能力指纹入契约:引擎注册即校验单位三元组与能力指纹;换算只能由调用方显式发起;
异源/异单位能量进入比较路径前显式拒绝;实测版本可回读盖章(
demo:cross-engine/demo:availability展示全链) - 热力学诚实:能量零点显式声明——严格形成焓 + 凸包判据需要显式参考态, 不可得时降级并明说;自由能零点(锚点)同理
- 采样语义:逆解是对相容分布的采样而非求逆;似然可求值性显式声明; 候选必须可回算验证,引擎是唯一 oracle
- 谱系即活性:导出量登记推导来源,失效沿推导图传播;落盘载荷携带可追溯声明, 跨会话可撤回
- 摘要可再生:
npm run summary从测试输出与契约实证表机械汇编SUMMARY.md, 不手写、不人工维护
引用
Saturday 的架构范式基于以下工作:
许可
MIT
Source: README.md at commit bee0960
Tools
0Version history
8- v0.3.14LatestSep 21, 2026
- v0.3.13Sep 21, 2026
- v0.3.12Sep 21, 2026
- v0.3.11Sep 21, 2026
- v0.3.10Sep 20, 2026
- v0.3.9Sep 19, 2026
- v0.3.8Sep 19, 2026
- v0.3.7Sep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts