# Creo MCP

This is a portable Creo bridge built on the standard MCP transport:

```text
any MCP client → MCP (stdio by default, streamable-http optional)
              → Python → official PTC VB API / COM → Creo
```

It uses the standard MCP transports and contains no nanobot-specific code.
It works with any compatible local MCP client, including nanobot, Codex,
Claude Desktop, and Cursor.

See [ARCHITECTURE.md](ARCHITECTURE.md) or the
[Chinese architecture guide](creo_mcp/docs/ARCHITECTURE.zh-CN.md) for the boundary between
reusable Creo capabilities, product skills, project data, safety invariants,
and the planned generic feature set. See the
[Chinese engineering delivery standard](creo_mcp/docs/ENGINEERING_STANDARD.zh-CN.md) for
human handoff, naming, editability, observability, and acceptance rules. See
[UDF_MANIFEST.zh-CN.md](creo_mcp/docs/UDF_MANIFEST.zh-CN.md) for the qualified UDF manifest
format and live qualification workflow. Real-session evidence and the remaining
qualification gaps are tracked in
[LIVE_VALIDATION.zh-CN.md](creo_mcp/docs/LIVE_VALIDATION.zh-CN.md). Client setup, protocol
compatibility, distribution options, and the prioritized improvement backlog are
documented in [CLIENT_SETUP.zh-CN.md](creo_mcp/docs/CLIENT_SETUP.zh-CN.md).
Tool naming, descriptions, annotation and payload-budget rules live in
[TOOL_CONVENTIONS.zh-CN.md](docs/TOOL_CONVENTIONS.zh-CN.md). The comparison with the
commercial ZW3D MCP (what to borrow, what not to) and the code audit are in
[docs/reference](docs/reference/).

It currently exposes these tools:

- `creo_get_status` — verifies the connection and returns the active model plus
  working directory.
- `creo_get_active_model` — returns active-model metadata only.
- `creo_get_model_geometry` — measures the true Creo envelope and solid volume
  of the active model or a named loaded model, normalized to millimetres.
- `creo_get_geometry_details` — resolves explicit surface and edge IDs into
  useful geometry: types, area or length, bounds or sample points, adjacent
  surfaces, and owning features, normalized to millimetres.
- `creo_find_surfaces` — scans all model surfaces, filters by type, area, or
  constant X/Y/Z coordinate, and returns a bounded candidate list instead of a
  complete topology dump.
- `creo_get_model_structure` — returns a bounded inventory of model-tree
  features, surfaces, edges, axes, points, coordinate systems, driving
  dimensions, and model parameters with stable IDs and names for later
  operations.
- `creo_get_handoff_report` — checks feature health, unnamed features, named
  dimensions, automation ownership parameters, units, and model envelope before
  an engineer takes over the model.
- `creo_get_operation_log` — reads recent privacy-minimized JSONL audit records
  with operation IDs, durations, outcomes, target model names, and save state.
- `creo_validate_udf_manifest` — validates a strict UDF qualification record
  and verifies the exact `.gph` SHA-256 hash without starting Creo.
- `creo_run_udf_qualification` — performs one explicitly confirmed,
  supervised placement from a candidate manifest whose
  `verified_non_interactive` flag is still false. It never saves or grants
  qualification automatically.
- `creo_place_qualified_udf` — places a fully bound, version-qualified UDF via
  the official `CreateUDFGroup` API, regenerates and measures the target, and
  leaves it unsaved. Interactive repair is disabled.
- `creo_plan_packaging_box` — validates a coarse box request and returns a
  deterministic dry-run plan. It does not connect to Creo or create a file.
- `creo_plan_product_clearance_tray` — reads the complete millimetre STEP or
  assembly, derives a conservative hard-edge cavity from its full BREP, and
  verifies static containment plus straight `+Z` insertion before creation.
- `creo_inspect_step_solids` — reports the extent and volume of each STEP solid
  in transfer order for an explicitly chosen separate-cavity layout.
- `creo_inspect_part_dimensions` — retrieves a native `.prt` file and reports
  its principal length unit and driving dimension symbols without saving it.
- `creo_inspect_step_file` — validates a local STEP file and reports its AP
  schema, products, unit, solid bodies, faces, and assembly structure without
  starting Creo.
- `creo_import_cad` — imports a supported CAD file as a new **unsaved** Creo
  part or assembly and returns its model type, unit, envelope, and solid volume
  when available. It supports automatic format detection for STEP, IGES,
  Parasolid, ACIS, STL, JT, CATIA, SolidWorks, Inventor, VDA, and Creo Neutral.
- `creo_open_native_model` — loads and measures an existing native Creo `.prt`
  or `.asm` without modifying or saving its source file.
- `creo_create_empty_part` — creates and activates a new **unsaved** Creo part.
  It requires `confirmation: "create_empty_part"` and is the first write-path
  verification.
- `creo_update_model_metadata` — renames stable model items, changes named
  driving dimensions with explicit units, creates or updates typed model
  parameters, regenerates, and leaves the model unsaved.
- `creo_update_feature_suppression` — suppresses or resumes model-tree features by
  name or stable ID, skips features already in the requested state, refuses states a
  family table, simplified representation, or the model program owns, regenerates,
  and reads every status back. It requires `confirmation:
  "update_feature_suppression"` and never saves. Live Creo validation is still
  pending; see `creo_mcp/docs/LIVE_VALIDATION.zh-CN.md`.
- `creo_save_model_as` — creates a protected native part or assembly copy under
  a new name, refuses all existing Creo versions, and restores the original
  Creo working directory.
- `creo_export_model` — exports a loaded model to a new STEP, IGES, or Parasolid
  file, validates its extension and optional profile, and refuses overwrite.
- `creo_import_step` — imports a STEP file as a new **unsaved** Creo part or
  assembly, detects its model type, and measures the true Creo envelope. It is
  retained as a compatibility wrapper around the general CAD import path.
- `creo_create_packaging_box` — copies a qualified native Creo template to a
  new name, applies confirmed dimensions, regenerates, verifies the resulting
  envelope, and saves the new model. It refuses to overwrite any existing Creo
  version of the requested part name.
- `creo_create_product_clearance_tray` — creates the verified hard-edge tray
  as a new `CONCEPT_ONLY` imported BREP, records its geometry and validation
  metadata, saves it under a new name, and activates it in Creo.

The tools use explicit JSON schemas, structured output, standard MCP tool
annotations, isolated COM calls, and timeouts. Write operations are separate
from inspection and planning operations.

## Discovery and diagnostics

Two meta tools and two JSON resources make the surface inspectable without
loading every tool definition into context:

- `creo_tool_catalog` — every tool grouped as `meta` / `read` / `modify` /
  `write`, with title and parameter count; `include_schema=true` adds full JSON
  schemas.
- `creo_get_capabilities` — the hard capability boundaries of this bridge: which
  general feature paths the Creo 13.4 VB API does not expose, which CAD inputs
  are ambiguous (`.prt`), how units are normalized, and what must be verified
  after an edit.
- `creo://server/status` — server version, tool/resource counts, and the local
  preflight report.
- `creo://tools/catalog` — the catalog as a JSON resource.

The same information is available from the command line, without an MCP client:

```powershell
.\.venv\Scripts\creo-mcp.exe --list               # human-readable, grouped
.\.venv\Scripts\creo-mcp.exe --list-json          # machine-readable
.\.venv\Scripts\creo-mcp.exe --doctor             # preflight, no Creo mutation
.\.venv\Scripts\creo-mcp.exe --doctor --probe     # + live Creo connection check
```

`--doctor` checks the platform, Python, `pywin32`, the `mcp` version, the Creo
loadpoint from the registry, the `pfcls.pfcAsyncConnection` COM registration,
the running `xtop.exe` process, operation-log writability, and the broker. Every
actionable failure carries a Chinese remediation hint. Exit code is `1` only
when a check fails (`warn`/`skip` still exit `0`).

## Architecture boundary

The MCP is the general Creo capability layer. It owns file loading, geometry
measurement, native feature operations, regeneration, and guarded saving or
exporting. It must not assume that the product is a syringe or that the target
is blister packaging.

Product workflows belong in later skills. A syringe skill can compose generic
revolve, extrude, shell, pattern, and parameter operations. A blister skill can
measure any loaded reference product, apply clearance and manufacturing rules,
and compose generic cavity and tray features. This keeps the same MCP useful for
other medical devices and packaging tasks.

Native Creo `.prt` files and NX `.prt` files share an extension. Automatic CAD
import therefore rejects `.prt`: use the native part inspection/loading path for
Creo files, or pass `source_format: "nx"` explicitly for NX. Mesh sources such
as STL are accepted as reference geometry but are not treated as editable B-rep
solids.

`creo_create_packaging_box` requires both the matching `plan_id` from
`creo_plan_packaging_box` and `confirmation: "create_new_model"`. The plan ID
changes whenever the name, dimensions, wall thickness, or output directory
changes, so a stale approval cannot be reused for different geometry.

`creo_create_product_clearance_tray` is deliberately limited to concept work.
It derives its cavities from the supplied product STEP, and a dimensional change
must be planned and regenerated through MCP under a new revision. The result is
marked `CONCEPT_ONLY`, `imported_brep`, and `REGENERATE_WITH_MCP`; it is not a
native engineering or production-ready packaging model.

Generated concept STEP files carry a turquoise AP242 surface color (`#42DFD0`)
and the imported Creo model records `MCP_DISPLAY_COLOR_HEX`,
`MCP_DISPLAY_FINISH=MATTE_NON_METALLIC`, and
`MCP_DISPLAY_ROLE=VISUALIZATION_ONLY_NOT_MATERIAL`. The color is a visualization
aid only. It does not assign an engineering material or prove transparency,
roughness, gloss, or a manufacturing finish; those properties require separate
Creo and manufacturing validation.

Before creating a tray, use `creo_plan_product_clearance_tray` with the product
STEP in its intended packaged state. A file-level bounding box is only an early
screening measurement; the hard-edge plan verifies complete containment and a
straight insertion path, but not retention, forming, or manufacturing.

For an editable native rough blank instead of one imported solid, `creo_mcp.cavity_segments`
collapses the same conservative cavity prisms into a small stack of rectangular steps
(`live-validation/segment_probe.py` prints the table offline, no Creo required). See
`live-validation/TRAY_SEGMENTATION_SAMPLES.zh-CN.md` for measurements on three real
samples and the segmented native template those numbers imply.

Two behaviours worth knowing before you call `creo_create_product_clearance_tray`:

- `output_directory` must already exist; the planner reports it instead of creating
  directories on your behalf.
- A successful result reports `activated: true`, which means Creo's standard display
  path (`pfcModel.Display`) ran. It does not promise a foreground window: creating or
  activating a window deliberately is avoided because it corrupts Creo 13.4 graphics.
  `creo_get_status` may therefore show `active_model: null`. Read the model back by
  name instead — `model_name` and `model_kind` must be supplied together, and an
  unqualified request then fails with "not loaded in the session".

## Native packaging-box template

The first modelling workflow deliberately uses a native Creo template instead
of an imported STEP body or UI automation. Create one solid rectangular
extrusion in Creo, use a millimetre unit system, and rename its three driving
dimensions to:

```text
BOX_LENGTH
BOX_WIDTH
BOX_HEIGHT
```

Save that part as a dedicated template. Before using it, call
`creo_inspect_part_dimensions` and verify that the unit is `mm` and all three
symbols are present. The create tool copies this file, changes only the copied
model, checks its regenerated outline, and then saves the new model. The source
template is never modified.

The current creator produces a solid bounding envelope. `wall_thickness_mm`
must be null until the separate hollow-box workflow is implemented.

## Requirements

- Creo 13.4.1.0 is installed and running.
- `VB API for Creo Parametric` was installed and registered using
  `vb_api_register.bat` as Administrator.
- The MCP client and Creo are launched from the same Windows account.

## Standalone installation

Create a dedicated virtual environment in this repository. Do not reuse an
application repository's environment:

```powershell
cd <repo>
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m pip install -e ".[concept-geometry]"
.\.venv\Scripts\creo-mcp.exe --probe-status
```

The core install is enough for inspection, import, metadata, UDF, save, and
export tools. Install the `concept-geometry` extra on machines that generate
hard-edge product-clearance trays.

The editable install provides the `creo-mcp.exe` entry point while keeping the
server source and documentation in this repository. Client configurations may
use either that entry point or the explicit Python and `creo_mcp_server.py`
paths shown below.

## Run as an MCP server

Use the repository virtual environment:

```powershell
cd <repo>
.\.venv\Scripts\python.exe .\creo_mcp_server.py
```

This uses stdio, so it will appear idle in a terminal. nanobot launches it
automatically after the following connection is added to its config:

```json
{
  "tools": {
    "mcpServers": {
      "creo": {
        "command": "<repo>\\.venv\\Scripts\\python.exe",
        "args": [
          "<repo>\\creo_mcp_server.py"
        ],
        "cwd": "<repo>",
        "toolTimeout": 150,
        "enabledTools": [
          "creo_tool_catalog",
          "creo_get_capabilities",
          "creo_get_status",
          "creo_get_active_model",
          "creo_get_model_geometry",
          "creo_get_geometry_details",
          "creo_find_surfaces",
          "creo_get_model_structure",
          "creo_get_handoff_report",
          "creo_get_operation_log",
          "creo_validate_udf_manifest",
          "creo_run_udf_qualification",
          "creo_place_qualified_udf",
          "creo_plan_packaging_box",
          "creo_plan_product_clearance_tray",
          "creo_inspect_step_solids",
          "creo_inspect_part_dimensions",
          "creo_inspect_step_file",
          "creo_create_empty_part",
          "creo_update_model_metadata",
          "creo_update_feature_suppression",
          "creo_save_model_as",
          "creo_export_model",
          "creo_open_native_model",
          "creo_import_cad",
          "creo_import_step",
          "creo_create_packaging_box",
          "creo_create_product_clearance_tray"
        ]
      }
    }
  }
}
```

Do not merge the JSON by hand while the gateway is running. Add it through the
WebUI MCP settings, or stop the gateway first, update the existing config, and
then restart nanobot.

## Local verification

Run the package tests from the integration directory:

```powershell
cd <repo>
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
```

Use pytest, not `python -m unittest discover`: part of the suite (catalog,
diagnostics, and tool-convention tests) is written as pytest functions and is
silently skipped by unittest discovery.

Then check the surface and the machine without an MCP client:

```powershell
.\.venv\Scripts\creo-mcp.exe --list
.\.venv\Scripts\creo-mcp.exe --doctor
```

One-shot operations are available for local diagnosis without an MCP client.
While the broker is running, these requests are routed through it and the result
carries `"via": "broker"`; only when no broker is alive does the command open its
own VB API connection, because Creo allows just one:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation inspect_part `
  --payload '{"part_path":"D:\\path\\packaging_box_template.prt"}'
```

After obtaining stable IDs from `inspect_model_structure`, inspect selected
surfaces and edges in detail:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation inspect_geometry_details `
  --payload '{"surface_ids":[3669,3670],"edge_ids":[2843,2844]}'
```

Find large planar candidates at a known model coordinate:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation find_surfaces `
  --payload '{"surface_types":["plane"],"minimum_area_mm2":500,"constant_axis":"y","axis_coordinate_mm":0,"axis_tolerance_mm":0.01,"sort_by":"area_desc","max_results":10}'
```

STEP files can be inspected without a running Creo session:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation inspect_step `
  --payload '{"step_path":"C:\\path\\product.stp"}'
```

The first STEP import capability intentionally leaves the new model unsaved:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation import_step `
  --payload '{"step_path":"C:\\path\\product.stp","model_name":"product_reference","activate":true,"confirmation":"import_unsaved_model"}'
```

Use the general importer when the source format may vary:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation import_cad `
  --payload '{"source_path":"C:\\path\\product.x_t","source_format":"auto","model_name":"product_reference","activate":true,"confirmation":"import_unsaved_model"}'
```

Validate a candidate or qualified UDF manifest offline before any model mutation:

```powershell
<repo>\.venv\Scripts\python.exe .\creo_mcp_server.py `
  --operation validate_udf_manifest `
  --payload '{"manifest_path":"<UDF 目录>\\node.candidate.udf.json"}'
```

For a candidate whose `verified_non_interactive` flag is false, pass the returned
`validation_id`, complete stable-ID references, and all dimensions to the
`qualify_udf` one-shot operation or `creo_run_udf_qualification` MCP tool. After
a human confirms that Creo showed no prompts and the geometry is correct, set the
formal manifest flag to true, validate it again, and use the new validation ID
with `creo_place_qualified_udf`. Both write paths change only the loaded model
and never save it.

For engineering handoff, first run `handoff_report`, then make explicitly
confirmed semantic-name, dimension, and ownership-parameter changes with
`update_model_metadata`, and enable or disable template features that were preset
suppressed with `update_feature_suppression`. Inspect the report again before separately requesting
`save_model_as` or `export_model`. One-shot CLI responses include an
`operation_id` whether they run through a live broker (`"via": "broker"`) or open
their own connection; recent records are also available through the
`creo_get_operation_log` MCP tool. The default JSONL location is
`%LOCALAPPDATA%\CreoMCP\logs\operations.jsonl`, and `CREO_MCP_LOG_DIR` can
override its directory. Broker state and its own log live under
`%LOCALAPPDATA%\CreoMCP\`; set `CREO_MCP_RUNTIME_DIR` to relocate them, which is
what the test session does so test runs never append to the production log.