# IC-CAP MCP Server

IC-CAP MCP Server connects ChatGPT desktop (Codex), Claude Code, ZCode, and
other Model Context Protocol clients to Keysight IC-CAP. It provides 128 MCP
tools and 15 embedded guides for project automation, measurement, simulation,
optimization, and device-model extraction.

The gateway starts automatically with IC-CAP. An external broker isolates MCP
dependencies from IC-CAP, reconnects after IC-CAP restarts, reports long-running
job progress, captures supported Status-window feedback, and rejects unsafe
paths before they reach the proprietary API.

## Install in three steps

Requirements: Windows 11 x64, a Keysight IC-CAP installation using Python 3.8
through 3.12, and an MCP client. IC-CAP 2025 with Python 3.12 is the verified
configuration; other accepted runtimes are compatibility candidates until
they receive live IC-CAP testing.

1. Download `iccap-mcp-server-<version>-windows-x64-setup.exe` from
   [GitHub Releases](https://github.com/Solitario119/iccap-mcp-server/releases).
2. Run the installer, confirm the detected IC-CAP Python directory, and choose
   ChatGPT desktop (Codex), Claude Code CLI, and/or ZCode desktop.
3. Restart IC-CAP once, then restart the selected MCP client or open a new task.

The installer is fully offline after download. Users do not need to install
Python, Git, or pip. If the IC-CAP Python directory is protected, only the small
bootstrap command requests administrator approval; the main installer remains
per-user.

A standard IC-CAP installation does not require `ICCAP_PYTHONHOME`; setup
searches for its built-in `tools\python` runtime. If IC-CAP uses a custom
Python, select that same directory in setup.

IC-CAP Status should show:

```text
IC-CAP MCP gateway ready: session=... pid=... port=...
```

For supported versions, client-specific checks, repair, diagnostics, upgrade,
uninstall, and source installation, see the
[Windows installation guide](docs/installation.md).

## Test the connection

Start a new task in the configured MCP client and ask:

```text
Perform a read-only IC-CAP MCP connection test. Call iccap_sessions_list,
iccap_health, iccap_status_get, and main_get_models. Do not simulate, save,
create, edit, delete, or run a macro. Report the session ID, IC-CAP PID,
gateway health, open models, and current Status warnings/errors.
```

If more than one IC-CAP process is open, select the intended session with
`iccap_session_select` before reading model data. Gateway authentication tokens
stay in the local session registry and are never returned by MCP tools.

## What is included

- Automatic gateway startup with no recurring Macro click.
- Stdio transport for ChatGPT desktop (Codex), Claude Code, ZCode, and
  compatible clients.
- Optional Streamable HTTP on loopback for URL-based clients.
- Automatic discovery and reconnection after IC-CAP restarts.
- Explicit session selection for multiple IC-CAP processes.
- Asynchronous simulation, measurement, transform, Macro, and plot jobs.
- Incremental Status output and supported optimizer progress.
- Best-effort modal error-dialog capture and structured failures.
- Stable validation, non-overwriting defaults, recovery checkpoints, and a
  redacted operation journal.

The process and failure boundaries are documented in
[Architecture and failure semantics](docs/architecture.md).

## Long-running work

`setup_simulate`, `setup_measure`, `transform_execute`, `macro_execute`, and
`plot_display` accept `run_async=true` and return a `job_id`.

- `iccap_job_get` returns state, result, errors, and parsed progress.
- `iccap_job_list` lists recent jobs.
- `iccap_job_logs` returns incremental Status output.
- `iccap_job_cancel` requests IC-CAP Stop Activity when available.
- `iccap_status_get` reads the current Status snapshot, including supported
  optimizer progress started manually in IC-CAP.

Cancellation is confirmed only when Stop Activity is found and invoked. A
blocked native IC-CAP call cannot be killed safely by Python.

## Safety boundary

- Existing targets are preserved unless `overwrite=true` is explicit.
- Overwrite and delete operations first create a managed `Save As No Data`
  checkpoint under `%LOCALAPPDATA%\iccap-mcp\checkpoints`.
- A failed checkpoint blocks mutation unless
  `allow_without_checkpoint=true` is explicitly accepted.
- IC-CAP locators must be absolute and are validated before dispatch.
- Calls are serialized on the IC-CAP UI thread.
- The redacted journal is stored at
  `%LOCALAPPDATA%\iccap-mcp\operations.jsonl`.

These safeguards cannot make proprietary C extensions transactional. A vendor
crash, arbitrary Macro, instrument operation, malformed transform, or native
deadlock can still block IC-CAP or lose work since the last save. Work on
project copies and save verified milestones.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `ICCAP_PYTHONHOME` | unset | Optional custom Python directory used by IC-CAP |
| `ICCAP_MCP_GATEWAY_PORT` | `0` | Gateway port; `0` selects a free loopback port |
| `ICCAP_MCP_TOOL_TIMEOUT` | `60` | Interactive broker wait timeout in seconds |
| `ICCAP_MCP_JOB_TIMEOUT` | `86400` | Long-job gateway deadline in seconds |
| `ICCAP_MCP_WORKSPACE` | `./iccap_mcp_workspace` | Allowed plot/export workspace |
| `ICCAP_MCP_ALLOW_EXTERNAL_FILES` | unset | Set `1` to allow MDM files outside the workspace |

Do not expose the broker or in-process gateway to an untrusted network.

## Development

The packaged installer is recommended for normal use. Contributors can use a
separate Python 3.12 environment:

```powershell
git clone https://github.com/Solitario119/iccap-mcp-server.git
cd iccap-mcp-server
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
```

Build the offline runtime and installer with:

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[installer-build]"
.\scripts\build_runtime.ps1 -Python .\.venv\Scripts\python.exe
.\scripts\build_installer.ps1 -SkipRuntime
```

Inno Setup 6 is required only to compile the installer. Live verification
scripts under `scripts/verify_live_*.py` require a licensed IC-CAP process;
mutation checks require an explicitly confirmed disposable model.

## License and trademarks

Released under the MIT License. This independent open-source project is not
affiliated with, endorsed by, or sponsored by Keysight Technologies. IC-CAP and
Keysight are trademarks of their respective owner.