Skip to main content
Glama
nashirabbash

CoppeliaSim MCP Server

by nashirabbash
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

coppelia_step

Execute Python code in CoppeliaSim to create, inspect, and validate robotics scenes; each call auto-launches the simulator and returns dual visual snapshots plus execution results.

Instructions

🚨 STRICT SUPREME DIRECTIVE FOR AI AGENT (READ THIS FIRST): NEVER CONCLUDE OR REPORT SUCCESS BASED SOLELY ON CODE LOGS OR EXIT STATUS! You are interacting with a physical 3D simulation environment. Code that executes without error often produces physically broken scenes (e.g. walls collapsing under gravity, objects intersecting, robots falling through floors or flipped upside-down).

THEREFORE, YOU ARE STRICTLY REQUIRED TO USE YOUR EYES: Every call returns TWO visual snapshots:

  1. /tmp/coppelia_topdown.png (TOP-DOWN BIRD'S-EYE VIEW of entire board)

  2. /tmp/coppelia_snapshot.png (ISOMETRIC 3D PERSPECTIVE VIEW of structures)

MANDATORY PROTOCOL AFTER EVERY CALL:

  1. You MUST explicitly read and inspect BOTH image files using your image viewing / file inspection capabilities.

  2. Check /tmp/coppelia_topdown.png to verify: 2D room dimensions, obstacle spacing, robot heading, and boundary clearance.

  3. Check /tmp/coppelia_snapshot.png to verify: wall heights (e.g. 5m), roof alignment, upright robot stability, and no physical sagging or collision clipping.

  4. IF YOUR EYES SEE ANY VISUAL DEFECT (collapsed wall, misplaced robot, clipping mesh), YOU MUST NOT CLAIM COMPLETION. You must immediately self-correct your script coordinates and run again! Reporting "Task complete" without having visually verified both screenshots is a fatal protocol violation.

TOOL SUMMARY: Execute Python code directly inside CoppeliaSim simulator. Auto-launches simulator if closed, runs physics/scene code, auto-captures dual camera snapshots, and returns execution result in ONE single call.

SCENE HIERARCHY AWARENESS RULE (PREVENT DUPLICATE MODELS): Every call returns "scene_objects" as root nodes. Each node includes name, path, handle, type, is_model, pos, and recursive children; this covers every non-system object. ALWAYS inspect the full hierarchy before creating or spawning:

  1. DO NOT spawn a robot if a matching model already exists anywhere under scene_objects.

  2. To reuse existing robot: robot = sim.getObject('/PioneerP3DX') (or use existing handle).

  3. To remove duplicate/old objects: sim.removeObject(sim.getObject('/OldName')). If scene_hierarchy_error is present, scene inventory failed; do not treat an empty list as an empty scene.

WALLS & ENCLOSURE VISIBILITY RULE (PREVENT GREY VOID BLINDNESS): NEVER build solid block labyrinths or closed rooms that entomb the camera/robot in solid gray geometry!

  1. DO NOT spawn 50+ individual solid wall cuboids for mazes. Use thin perimeter borders instead (thickness 0.1m - 0.2m, NOT 0.8m thick blocks!).

  2. Color your walls and floor distinctly (e.g. walls = light blue [0.3, 0.6, 0.9], floor = dark grey [0.2, 0.2, 0.2]). NEVER leave all shapes default uncolored grey!

  3. If creating rooms or houses with roofs: DO NOT seal roofs with solid opaque material. Either leave roof off, or make it high and distinctly colored so internal contents remain visible.

INJECTED OBJECTS IN CODE:

  • sim: CoppeliaSim ZeroMQ API module.

  • simIK: CoppeliaSim Inverse/Forward Kinematics solver module.

  • simOMPL: Open Motion Planning Library module (RRT, RRT*, PRM path planners).

  • load_robot(alias, position=[x,y,z], orientation=[a,b,g]): Loads robot model. Valid aliases: ['pioneer', 'youbot', 'hexapod', 'ant_hexapod', 'omni', 'quadcopter', 'asti', 'panda', 'ur5', 'ur10', 'vacuum', 'epuck'].

  • get_scene_hierarchy(): Returns root objects with nested children for every non-system object type.

  • get_floor_info(): Returns default floor size, position, and bounding box.

  • client: RemoteAPIClient instance.

EXACT API CHEAT-SHEET (DO NOT SEARCH OR GUESS - USE THESE DIRECTLY):

  1. Shapes & Environment:

    • Create cuboid: h = sim.createPrimitiveShape(sim.primitiveshape_cuboid, [sizeX, sizeY, sizeZ], 0)

    • Create cylinder: h = sim.createPrimitiveShape(sim.primitiveshape_cylinder, [diameter, diameter, height], 0)

    • Create sphere: h = sim.createPrimitiveShape(sim.primitiveshape_sphere, [diameter, diameter, diameter], 0)

    • Make static (walls/floors/roofs): sim.setObjectInt32Param(h, sim.shapeintparam_static, 1)

    • Make respondable (solid collisions): sim.setObjectInt32Param(h, sim.shapeintparam_respondable, 1)

    • Color shape: sim.setShapeColor(h, None, sim.colorcomponent_ambient_diffuse, [R, G, B]) # values 0.0 - 1.0

  2. Positions & Hierarchy:

    • Set position: sim.setObjectPosition(handle, -1, [x, y, z]) # -1 = absolute world coords

    • Get position: pos = sim.getObjectPosition(handle, -1) # returns [x, y, z]

    • Set orientation: sim.setObjectOrientation(handle, -1, [alpha, beta, gamma])

    • Find object by name: h = sim.getObject('/ObjectName', {'noError': True})

    • Remove object: sim.removeObject(handle)

  3. Collision & Distance Detection:

    • Collision check: result, collPair = sim.checkCollision(entity1Handle, entity2Handle) # 1 = colliding, 0 = clear

    • Distance check: result, distData, pairHandles = sim.checkDistance(entity1Handle, entity2Handle) returns distance and closest points without a threshold.

Optional diagnostics request returns structured results in the JSON text content. Use {"kind":"distance","objects":["/A","/B"],"threshold":0.1} to receive distance, closest_points, threshold, and status; threshold only controls issue/clear classification. Scripts can also inspect and edit the full scene through sim.*.

  1. Path & Motion Planning (simOMPL & simIK):

    • simOMPL Task: task = simOMPL.createTask('task_name')

    • Set Algorithm: simOMPL.setAlgorithm(task, simOMPL.Algorithm.RRTConnect) # or RRTstar, PRM

    • Compute Path: solved, path = simOMPL.compute(task, maxTime=4.0)

    • simIK Solver: env = simIK.createEnvironment(); simIK.addElementFromScene(env, ikGroup, tip, target, base)

    • Native Path Interpolation: pathHandle = sim.createPath(ctrlPoints, options)

  2. Simulation & Motors:

    • Start simulation: sim.startSimulation()

    • Stop simulation: sim.stopSimulation()

    • Set motor velocity: sim.setJointTargetVelocity(jointHandle, float_val)

    • Read proximity sensor: detected, dist, pt, obj, normal = sim.readProximitySensor(sensorHandle)

sim.stopSimulation()
# House floor
floor = sim.createPrimitiveShape(sim.primitiveshape_cuboid, [10.0, 10.0, 0.2], 0)
sim.setObjectInt32Param(floor, sim.shapeintparam_static, 1)
sim.setObjectInt32Param(floor, sim.shapeintparam_respondable, 1)

# Spawn robot inside
robot = load_robot('pioneer', [0.0, 0.0, 0.3])
sim.startSimulation()

Input Schema

NameRequiredDescriptionDefault
codeNo
resetNo
timeoutNo
headlessNo
diagnosticsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.0.1
    • addedInput schema / properties / diagnostics
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Diagnostics"
+}
    • addedInput schema / properties / timeout
      Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "coppelia_stepOutput",
-  "type": "object"
-}New value: +null
  2. First observedv0.1.0

TDQS

B3.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations to lean on, the description carries the full burden and does so thoroughly: it discloses auto-launch behavior, the exact snapshot paths written, the shape of the `scene_objects` return, the `scene_hierarchy_error` failure signal, and mutation side effects (spawning/removing objects). An agent knows the observable behavior and side effects before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is bloated with repeated all-caps directives and duplicated warnings, and it front-loads a shouting protocol notice ahead of the actual tool summary. The genuinely useful material (return format, API cheat-sheet) is buried under rhetorical repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a code-execution tool with no output schema, the return behavior is described well (two PNG paths, scene hierarchy, diagnostics results). However, the three undocumented parameters and the absence of any note on what `reset`/`timeout` do leave real gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must document all five parameters, yet it only explains `diagnostics` (with a concrete example payload) and implicitly `code`. `reset`, `timeout`, and `headless` are never defined, so an agent must guess their semantics and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The 'TOOL SUMMARY' block states a specific verb and resource: execute Python code inside CoppeliaSim, auto-launch the simulator, capture dual snapshots, and return results in one call. It is concrete and distinguishable, but it never explicitly contrasts itself with siblings like coppelia_simulate or coppelia_scene, leaving the differentiation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong procedural guidance for *how* to use the output (inspect both PNGs, check hierarchy before spawning), but no guidance on *when* this tool should be chosen over coppelia_simulate, coppelia_scene, or coppelia_motion. Usage context is implied rather than stated against alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools