# 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.

## 安装 / Install

```bash
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:

```json
{
  "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`，且预估成本不超过上限。

1. `TIDY3D_MCP_ALLOW_CLOUD_SUBMISSION=1`;
2. explicit confirmation in the MCP call;
3. a positive `max_flexcredits` on `start_simulation`, with the estimate at or below that cap.

```bash
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.

```python
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.