Tidy3D Research MCP

一个独立的 Tidy3D MCP 服务，用于声明式 FDTD 配置校验、受控云端任务流程，以及把 Tidy3D 结果归一化为元数据和有限的 CSV 观测数据。它与应用层 tutor 解耦，不会把 Tidy3D 凭据或云端执行权限加入其他服务。

An independent Tidy3D MCP server for declarative FDTD validation, guarded cloud-task workflows, and normalization of Tidy3D results into metadata plus bounded CSV observables. It is decoupled from application-level tutors and does not add Tidy3D credentials or cloud-execution privileges to other services.

Repository relationship / 仓库关系

本仓库是 Industrial_Local_Agent superproject 的独立 child component；父仓库通过 components/tidy3d-research-mcp submodule 固定本仓库的具体 commit。

This repository is an independent child component of the Industrial_Local_Agent superproject; the parent pins its exact commit through the components/tidy3d-research-mcp submodule.

Related MCP server: MCP Powered AI Assistance

安装 / Install

cd tidy3d-research-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/pytest

Tidy3D 认证使用官方客户端配置，不把 key 写入仓库。可以使用 SIMCLOUD_APIKEY 环境变量，或在本机执行 tidy3d configure。服务本身不会返回、记录或转发 key。

Tidy3D authentication uses the official client configuration; the key is never stored in this repository. Use the SIMCLOUD_APIKEY environment variable or run tidy3d configure locally. The server never returns, logs, or forwards the key.

MCP 配置 / MCP Configuration

在 MCP 客户端中配置 STDIO server：

Configure a STDIO server in the MCP client:

{
  "mcpServers": {
    "tidy3d-research": {
      "command": "path/to/tidy3d-research-mcp/.venv/bin/tidy3d-research-mcp",
      "env": {
        "TIDY3D_MCP_WORKSPACE_DIR": "path/to/your/project"
      }
    }
  }
}

默认只允许本地校验和结果读取。云端 upload/start 必须同时满足：

Cloud upload/start requires all of the following:

1. TIDY3D_MCP_ALLOW_CLOUD_SUBMISSION=1；

2. MCP 调用参数中的显式确认；

3. start_simulation 提供正的 max_flexcredits，且预估成本不超过上限。

4. TIDY3D_MCP_ALLOW_CLOUD_SUBMISSION=1;

5. explicit confirmation in the MCP call;

6. a positive max_flexcredits on start_simulation, with the estimate at or below that cap.

export TIDY3D_MCP_ALLOW_CLOUD_SUBMISSION=1

这不是预算保证；FlexCredit 价格和账户限制由 Tidy3D 服务端决定。执行前仍需人工检查配置、预估成本和研究授权。

This is not a budget guarantee; FlexCredit pricing and account limits are controlled by the Tidy3D service. A researcher must still inspect the configuration, estimate cost, and confirm authorization before execution.

工具 / Tools

• validate_simulation：校验序列化的 tidy3d.Simulation JSON，返回 digest、配置摘要和科学复核标记。

• upload_simulation：在显式确认后上传草稿，但不启动求解。

• estimate_task_cost：读取任务的最大 FlexCredit 预估。

• start_simulation：在显式确认、环境开关和成本上限都满足后启动任务。

• get_simulation_status：读取任务的 allowlisted 状态字段。

• download_simulation_result：在显式确认后下载到私有 artifact 目录，并生成归一化摘要。

• normalize_local_result：只读取 TIDY3D_MCP_WORKSPACE_DIR 下的相对路径，拒绝绝对路径、路径穿越和 symlink。

• read_normalized_artifact：读取由本服务生成的 metadata.json 和受限 observables.csv。

• validate_simulation: validate serialized tidy3d.Simulation JSON and return a digest, configuration summary, and scientific-review flags.

• upload_simulation: upload a draft after explicit confirmation without starting the solver.

• estimate_task_cost: read the maximum FlexCredit estimate for a task.

• start_simulation: start only after explicit confirmation, the environment gate, and a cost cap pass.

• get_simulation_status: read allowlisted task-status fields.

• download_simulation_result: download after explicit confirmation into a private artifact directory and normalize it.

• normalize_local_result: read only a relative path under TIDY3D_MCP_WORKSPACE_DIR; absolute paths, traversal, and symlinks are rejected.

• read_normalized_artifact: read the generated metadata.json and bounded observables.csv.

MCP 接口不接受 Python 代码，不执行模型生成的代码，不提供 shell、任意 URL、任意路径、删除任务或 key 管理工具。结果是仿真证据，不是实验验证；网格/时间收敛必须由研究人员设计并检查。

The MCP accepts no Python code, executes no model-generated code, and exposes no shell, arbitrary URL, arbitrary path, task deletion, or key-management tool. Results are simulation evidence, not experimental validation; mesh and time convergence must be designed and checked by a researcher.

Skill / Skill

本仓库同时发布可复用的 tidy3d-research skill。入口文件为 skills/tidy3d-research/SKILL.md，其中包含 MCP workflow、Tidy3D API 和 scientific checks references。

This repository also publishes the reusable tidy3d-research skill. Its entry point is skills/tidy3d-research/SKILL.md, with references for the MCP workflow, Tidy3D API, and scientific checks.

License / 许可证

当前仓库未附许可证文件。公开可见不等于授予复制、修改或再分发权；许可证决定应在后续独立决策中明确。

No license file is included at this time. Public visibility does not by itself grant rights to copy, modify, or redistribute; a licensing decision should be made separately.

最小 JSON 示例 / Minimal JSON Example

下面的 JSON 可以由 Tidy3D Simulation.model_dump_json() 生成，再交给 validate_simulation。MCP 不要求使用特定 Python 代码来构造模型。

The JSON below can be produced by Tidy3D Simulation.model_dump_json() and passed to validate_simulation. The MCP does not require a particular Python code generator for model construction.

import tidy3d as td

sim = td.Simulation(
    size=(2, 2, 2),
    run_time=1e-13,
    grid_spec=td.GridSpec.auto(wavelength=1.5, min_steps_per_wvl=10),
    sources=[
        td.PointDipole(
            center=(0, 0, 0),
            source_time=td.GaussianPulse(freq0=2e14, fwidth=2e13),
            polarization="Ex",
        )
    ],
    monitors=[
        td.FieldMonitor(
            name="field",
            center=(0, 0, 0),
            size=(2, 2, 0),
            freqs=[2e14],
            fields=["Ex"],
        )
    ],
)
simulation_json = sim.model_dump_json()

以上配置仅用于接口测试，不代表研究结果或收敛结论。

The configuration above is only an interface fixture; it is not a research result or a convergence claim.