# Avizo MCP and Codex Skill

Local Model Context Protocol server and Codex skill for Thermo Scientific Amira-Avizo automation on Windows.

This repository is designed as a conservative bridge around an existing local Avizo installation. It does not call private Avizo APIs from outside the Avizo process. Instead, it helps an MCP client:

- discover Avizo, AvizoToGo, Amira, bundled Python, docs, demos, and a job workdir;
- inventory Avizo/Amira project trees containing `.hx`, `.am`, `.measure.am`, TIFF stacks, `Header.txt`, DVC outputs, and deep-learning artifacts;
- inspect `.hx` workflows and extract command patterns plus referenced files;
- create reproducible `.hx` and Python scripts in a job directory;
- generate `.pyscro` plus `.rc` script-object skeletons using the public Amira-Avizo extension pattern;
- launch Avizo/AvizoToGo/Amira or run Avizo's bundled Python;
- capture and read job logs.

## Repository Layout

```text
src/avizo_mcp/           MCP server package
skills/avizo/            Codex skill that teaches agents how to use the MCP
examples/                Example MCP config and smoke-test scripts
pyproject.toml           Python package metadata
```

## Install

Use standard Windows CPython, not MSYS Python. The `mcp` dependency pulls `pywin32` on Windows, which is not available for MSYS Python builds.

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

## Environment

Set these variables in your MCP client config or shell:

```powershell
$env:AVIZO_HOME = "C:\Program Files\Thermo Scientific Amira-Avizo3D 2024.1"
$env:AVIZO_MCP_WORKDIR = "C:\Users\<you>\Documents\avizo_mcp_jobs"
```

Optional overrides:

```powershell
$env:AVIZO_EXE = "C:\Path\To\Avizo3D.exe"
$env:AVIZO_TO_GO_EXE = "C:\Path\To\AvizoToGo.exe"
$env:AMIRA_EXE = "C:\Path\To\Amira3D.exe"
$env:AVIZO_PYTHON_EXE = "C:\Path\To\python.exe"
```

## Run Manually

```powershell
.\.venv\Scripts\python.exe -m avizo_mcp.server
```

The server uses stdio transport for MCP clients.

## Codex MCP Config

Use `examples/codex_mcp_config.toml` as a template. Replace paths with your local clone, venv Python, Avizo installation, and job workdir.

## Skill

The reusable Codex skill lives at `skills/avizo`. To install it manually, copy that folder into your Codex skills directory, for example:

```powershell
Copy-Item -Recurse .\skills\avizo "$env:USERPROFILE\.codex\skills\avizo"
```

Restart Codex after installing or changing the MCP config.

## Safety Notes

- Treat raw CT, `.am`, and `.hx` experiment folders as read-only unless a user explicitly asks for in-place edits.
- Generate scripts and logs in `AVIZO_MCP_WORKDIR`.
- For long Avizo jobs, launch with `wait=false` and inspect logs before claiming success.
- Review generated `.pyscro` and `.rc` files in a disposable `AMIRA_LOCAL` layout before installing them into a production Avizo setup.

## Publishing Notes

Choose an open-source license before publishing this repository. Do not vendor third-party Amira-Avizo automation code unless its license and attribution are handled.