Skip to main content
Glama
nashirabbash

CoppeliaSim MCP Server

by nashirabbash
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

coppelia_step

Execute Python code in CoppeliaSim and capture dual snapshots for visual verification of physical simulation, preventing false success from code logs.

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": [{"name": "...", "is_model": bool, "pos": [x, y, z]}]. ALWAYS inspect scene_objects before creating/spawning:

  1. DO NOT spawn a robot if a model with the same alias/name already exists in 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')).

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 current active user models and shapes in the scene.

  • 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 = sim.checkDistance(entity1Handle, entity2Handle, threshold)

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

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

TableJSON Schema
NameRequiredDescriptionDefault
codeNo
resetNo
headlessNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and largely meets it: it discloses that the tool auto-launches a simulator, runs physics, writes two PNG files to /tmp, and returns scene_objects plus an execution result in one call. These are non-obvious side effects an agent must know. It does not discuss failure modes like timeouts, simulator crash behavior, or whether state persists across calls.

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 opens with an all-caps 'STRICT SUPREME DIRECTIVE' block of alarmist, repetitive prose before ever stating what the tool does, which inverts the front-loading principle. Much of the framing ('fatal protocol violation', restated warnings) is redundant, though the API cheat-sheet and example carry genuine value. Size is far beyond what the task requires.

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

Completeness4/5

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

For a tool that executes arbitrary code against a live simulator, the description covers a lot of the practical surface: environment modules, helper functions, API calls, and known pitfalls. An output schema exists, so return values need not be re-explained. The gaps are the unaddressed `reset` and `headless` flags and any note on state persistence between calls.

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

Parameters3/5

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

Schema coverage is 0%, so the description must compensate for all three parameters. It thoroughly explains the `code` parameter (injected modules, load_robot aliases, full API cheat-sheet, an example), but `reset` and `headless` are never mentioned anywhere in the text. Compensating for one of three parameters is partial, warranting a mid score.

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 states a specific verb and resource: 'Execute Python code directly inside CoppeliaSim simulator', plus a compact account of auto-launch, physics execution, and dual snapshot capture. The purpose is unambiguous once found, but it is buried under a long directive preamble rather than front-loaded. No siblings exist to differentiate from, which caps this below a 5.

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

Usage Guidelines4/5

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

It gives concrete when-to-do guidance: inspect scene_objects before spawning, reuse an existing model instead of duplicating, remove old objects, and always visually verify both screenshots before declaring success. What it lacks is any explicit statement of when NOT to use this tool or what alternatives exist (none are provided as siblings).

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