ansys-agent-bridge: Ansys SpaceClaim Headless Driver and DSH Plugin

Introduction¶

When developing agents based on DeepSeek Harness (DSH), API calls to engineering software such as Ansys often have blind spots. The most typical pain point is “silent failure”: certain geometry operations (such as boolean operations or topology sharing) return a success status at the lower level, but the actual geometry has not changed, or only the body count has changed while the volume remains unchanged. If the agent relies only on the return value, it may incorrectly assume that the operation has succeeded, causing subsequent workflows to continue with incorrect data.

ansys-agent-bridge is an MCP server that runs Ansys SpaceClaim headlessly in the background through PyAnsys Geometry, along with a DSH plugin. Its core value is to measure geometry data (such as face count and volume) before and after operations so that these silent failures can be captured, rather than blindly trusting return values.

What is this¶

This is an open-source DSH plugin package (MIT license, maintained by 1622352030). It consists of two parts:
1. MCP server: Communicates with the SpaceClaim backend, performs geometry operations, and validates the results.
2. DSH plugin configuration: Provides a one-click installation command and a configuration patch to integrate the above MCP server into a DSH profile.

Core features¶

The plugin provides 15 MCP tools covering session management, file operations, geometry inspection, and modification.

Session and diagnostics¶

• ansys_bridge_doctor: Reports the detected Ansys version, SpaceClaim, Fluent, Python, and dependency package versions.
• scdm_session_start: Starts the hidden SpaceClaim modeler (version is auto-detected).
• scdm_session_status: Checks whether the session is active and its backend type/version.
• scdm_session_close: Releases the session and license.

Files and export¶

• scdm_open_file: Opens .scdoc/.scdocx/.dsco/.pmdb files and reports bodies, named selections, face count, and volume.
• scdm_insert_file: Merges another CAD file into the currently opened design.
• scdm_export: Exports .scdocx, STEP, IGES, Parasolid (text/binary), and .pmdb.

Geometry inspection¶

• scdm_list_bodies: Lists the body names, face count, and volume of the opened design.
• scdm_collisions: Detects the collision status of body pairs (TOUCH/NONE, etc.).
• scdm_min_distance: Calculates the minimum distance between two bodies (meters).
• scdm_inspect_geometry: Runs eight official geometry checks (duplicate faces, short edges, small faces, sewing, stitching, and so on).

Modification and scripting¶

• scdm_transform: Performs rotate/scale/mirror and verifies the result using before/after spatial fingerprints.
• scdm_boolean: Performs unite/subtract/intersect and is protected by before/after geometry checks.
• scdm_share_topology: Shares topology and runs the same protective checks.
• scdm_run_script: Runs headless IronPython scripts against the active session.

Installation and activation¶

Before installing, the following environment is required: a Windows operating system, an installed Ansys with SpaceClaim (tested on 2024 R2), and uv.

Method 1: Install from GitHub (recommended when network connectivity is good)¶

Install it directly using the DSH plugin management command.

dsh plugin --profile web add ansys-agent-bridge

After installation, restart the profile for the change to take effect.

Method 2: Install from a local checkout (when the network is unstable)¶

If the network cannot access GitHub, or if you are concerned that a failed git fetch might make the desktop application unresponsive, use the local checkout method.

1. Add the plugin package:

    dsh plugin --profile web add link:C:/path/to/ansys-agent-bridge

2. Configure the patch manually:
   Edit cordis.patch.yml (usually located at %APPDATA%\dsh-desktop\harness\profiles\web\). The command field must be uv; do not use an absolute path or a !!js expression.

    - id: mcp-ansys
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: ansys
        transport: stdio
        command: uv
        args:
          - 'tool'
          - 'run'
          - '--quiet'
          - '--from'
          - 'C:/path/to/ansys-agent-bridge/spaceclaim/python'
          - 'ansys-bridge-mcp'
        env:
          PYTHONIOENCODING: 'utf-8'
          ANSYS_BRIDGE_LOG_LEVEL: 'WARNING'
        toolCallTimeoutMs: 900000
        failOnStartupError: false

3. Register the skill:
   Due to limitations of the patching mechanism, spaceclaim/skills/ansys-spaceclaim/ is not registered automatically. Add that path manually in the profile’s cordis.patch.yml.

Typical usage¶

After installation and restarting the profile, operations can be performed by invoking the tools.

• Diagnose the environment:

    ansys_bridge_doctor

• Start a session:
  Invoke scdm_session_start.

• Open a file and inspect it:
  Invoke scdm_open_file to open the design, then invoke scdm_list_bodies to view body information.

Use cases and notes¶

• Platform limitation: Windows only. It must run under DSH process permissions.
• Network dependency: Method 1 depends on the network. If git fetch fails and failOnStartupError is false, the application may become unresponsive or the plugin may be locked and disabled.
• Manual configuration: Make sure the command in cordis.patch.yml is uv, and spaceclaim/skills/ansys-spaceclaim/ must be added manually.
• License management: After finishing with a session, always invoke scdm_session_close to release the license.

Conclusion¶

ansys-agent-bridge addresses the “untrusted return value” problem in interactions between agents and Ansys. By moving geometry validation logic down to the tool layer, it provides more reliable underlying support for CAD/CAE integration. See the plugin catalog page or the GitHub repository for more details.