Creo MCP

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

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 or the Chinese architecture guide 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 for human handoff, naming, editability, observability, and acceptance rules. See 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. Client setup, protocol compatibility, distribution options, and the prioritized improvement backlog are documented in CLIENT_SETUP.zh-CN.md. Tool naming, descriptions, annotation and payload-budget rules live in 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.

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:

.\.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).

Related MCP server: dsh-nx

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:

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:

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:

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:

{
  "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:

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:

.\.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:

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

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

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

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

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

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

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