Metadata-Version: 2.3
Name: tidy3d-mcp
Version: 0.16.6
Summary: Local stdio FastMCP server for Tidy3D
Author: Flexcompute
License: Proprietary
Requires-Dist: fastmcp>=3.4.4,<4
Requires-Dist: tomli>=2.2.1
Requires-Dist: typing-extensions>=4.12
Requires-Python: >=3.10, <3.15
Description-Content-Type: text/markdown

# Tidy3D MCP

`tidy3d-mcp` is the independently installable and released implementation of the Tidy3D MCP
runtime. It exposes the remote FlexAgent tools and, when an authenticated compatible editor bridge
is already active, Tidy3D local/editor tools over stdio.

The distribution and command are both named `tidy3d-mcp`. A separate `tidy3d mcp` command in the
Tidy3D client may delegate to this package, but this package does not depend on that facade.

## Run

```bash
uvx --from tidy3d-mcp==0.16.6 tidy3d-mcp
```

The server resolves the FlexAgent API key in this order:

1. `--api-key`
2. `SIMCLOUD_APIKEY`
3. `TIDY3D_BASE_DIR` config locations
4. `~/.config/tidy3d/config.toml` under `[web].apikey`
5. `~/.tidy3d/config`

`REMOTE_MCP_URL` can replace the default `https://flexagent.simulation.cloud/` endpoint. The URL is
forwarded exactly, including a custom path.

The established marketplace compatibility modes remain supported:

- Flex RF launches the default command and supplies `package="flex-rf"` to the remote documentation
  tools.
- PhotonForge launches `tidy3d-mcp --product photonforge`, which retains its branded remote
  documentation and feedback tools and never advertises Tidy3D editor tools.

## Local editor tools

The server never installs, registers, recommends, bootstraps, or launches an editor extension. It
starts normally when no bridge is present and exposes only the remote FlexAgent surface.

An editor publishes a private per-window discovery record with `schemaVersion: 1`,
`protocolVersion: 1`, a loopback URL, a session token, workspace roots, and capabilities. The server
authenticates `POST /viewer/ping` and advertises only tools whose complete capability requirements
are present. Unknown capabilities are ignored. An unsupported protocol, malformed manifest, failed
authentication, or unavailable bridge exposes no local tools.

The extension removes its registration during normal shutdown. If authenticated discovery instead
proves that an unchanged private registration points to a refused or incompatible endpoint, the MCP
consumer removes that exact stale record. It preserves timed-out, replaced, malformed, untrusted,
and symlinked records.

The #19281 base bridge advertises `viewer.open` and `viewer.control`; the #19517 adapter adds
`python.detect`, `viewer.simulations`, `viewer.validate`, and the receipt-backed
`viewer.file.open` identity route. The package withholds `open_simulation`, `rotate_viewer`,
`capture_viewer`, and `set_structure_visibility` unless the complete identity and operation
requirements are present, rather than guessing an opaque viewer ID.

The provider-backed local surface is:

```text
detect_python             list_simulations          validate_simulation
open_simulation           rotate_viewer             capture_viewer
set_structure_visibility  render_report             open_report
get_report                set_report_step
```

Generic viewer controls, results inspection, and annotation tools land with the extension routes
that provide their complete bounded contracts. They are not advertised or defined speculatively in
this package.

Source operations accept saved local `.py` or `.ipynb` paths only. They do not forward inline or
base64 source. Validation may return session-scoped artifact receipts; `open_simulation` opens HDF5
only through an artifact ID or the exact registered artifact path/URI. Report operations accept a
saved workspace `.qmd` and preserve the renderer command, working directory, environment, and
bounded stdout/stderr in their structured result.

## Explicit bridge override

Discovery is the normal path. Tests and controlled integrations may select one bridge explicitly,
but URL and token must be supplied together:

```bash
tidy3d-mcp \
  --viewer-bridge http://127.0.0.1:5123 \
  --viewer-bridge-token "$TIDY3D_VIEWER_BRIDGE_TOKEN"
```

`TIDY3D_VIEWER_BRIDGE_URL` and `TIDY3D_VIEWER_BRIDGE_TOKEN` provide the same authenticated override.
The legacy unauthenticated URL variable is ignored unless a token is also present.

## Develop and release

```bash
uv sync --locked
uv run ruff format --check src tests
uv run ruff check src tests
uv run pyrefly check
uv run pytest
uv build
uv run tidy3d-mcp --version
```

The machine-readable local `tools/list` acceptance matrix lives at
`tests/fixtures/tools_list_matrix.json`. Publishing is owned by
`.github/workflows/frontend_tidy3d-mcp.yaml`, whose trusted publisher targets this directory.
