fieldpuppet
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server runs simulated Modbus TCP devices on this computer for testing SCADA, gateway and PLC-integration software. Nothing here talks to real equipment. Typical flow: list_templates, create_device (returns the host, port and unit id a Modbus client should connect to), then set_point / set_signal / apply_scenario / inject_fault to shape behaviour, and get_traffic_log to see what the software under test is asking for. Addresses are zero-based protocol addresses (holding register 40001 is address 0).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_templatesA | List the built-in device templates (generic, energy_meter, vfd, temperature_controller, pump, tank) with every point each one provides: name, table, address, data type and unit. Call this before create_device to choose a template or to learn point names. Changes nothing. |
| create_deviceA | Start one simulated Modbus TCP device that real client software can connect to. Use clone_device instead when you need many copies of a device that already exists, and load_project to bring back a saved set. Without a port the device gets the next free port; give a port already used by this simulator together with a different unit_id to put several devices behind one port. Fails if the id is taken, the port is used by another program, or the device limit is reached. Returns the device id plus the host, port and unit id to connect to. |
| clone_deviceA | Create several copies of a running device, each on its own port, for example 50 identical meters for a load test. Copies start with the source's points, current values, signals and settings; later changes to the source do not reach them. Use create_device for a single new device. If a copy cannot be created the call stops there and the error says how many were made; those copies keep running. Returns the id, port and unit id of every copy. |
| list_devicesA | List every running device with its id, host, port, unit id, active fault and scenario state, plus the dashboard address. Use it to find device ids or to check what is running; use get_device for one device's points and values. Changes nothing. |
| get_deviceA | Return everything about one device: connection details, settings, active fault, scenario progress and every point with its address, data type and current value. Use read_points instead when you only need values. Changes nothing. Fails if the id is unknown. |
| remove_deviceA | Stop one device and free its port. Its points, values, traffic log and running scenario are discarded and Modbus clients can no longer reach it. This cannot be undone unless the device was saved with save_project. Use remove_all_devices to clear everything. Fails if the id is unknown. |
| remove_all_devicesA | Stop every running device and free all their ports. All points, values, traffic logs and scenarios are discarded; saved project files are not touched. Use it to start from a clean state, and call save_project first if the current setup should be kept. Returns how many devices were removed (0 if none were running). |
| read_pointsA | Read the current engineering values (after scaling) of a device's points, with their units. Use this to check what a device is reporting right now; use read_registers when you need the raw 16-bit words a Modbus client would receive. Changes nothing. Fails if the device or a named point does not exist. |
| set_pointA | Set one point to a fixed engineering value (the simulator applies the point's scale and data type). Any signal running on that point is stopped, so the value stays until changed again. Use set_signal for a value that changes over time and write_registers to write raw words at an address. Returns the point with its new value. Fails if the device or point does not exist. |
| set_signalA | Attach a signal to one point so its value changes by itself: sine, ramp, random, random walk, counter, square or constant. It replaces any signal already on that point and runs until replaced, stopped, or overwritten by set_point. Pass signal null to stop the signal and keep the current value. Use set_point for a fixed value and apply_scenario to change several things on a timeline. Returns the point with its current value. |
| add_pointA | Add one new named point (a coil, discrete input or register value) to a device that is already running, without restarting it or disturbing connected clients. Use it to extend a template device; to define points when a device is first created, pass them to create_device instead. The point takes its initial value, or starts its signal, immediately. Returns the new point with its current value. Fails if the device does not exist, the name is already used on that device, or the definition is invalid (for example a 32-bit type in a bit table). |
| remove_pointA | Delete one named point from a running device, together with any signal on it. Only the definition is removed: the raw value last stored at its address stays readable by Modbus clients until overwritten (or is rejected if the device is strict and no other point covers the address). The device and its other points keep running. Use remove_device to remove the whole device. Fails if the device or point does not exist. |
| read_registersA | Read raw values straight from one Modbus table of a device, exactly as a client would receive them: 0 or 1 for coil and discrete, unscaled 16-bit words (0-65535) for holding and input. Use it to verify byte order, scaling or addresses; use read_points for engineering values by name. Addresses no point covers read 0, even on strict devices. Changes nothing and is not recorded in the traffic log. Returns the table, start address and list of values. |
| write_registersA | Write raw values into one Modbus table of a device, starting at an address: 0-65535 for holding and input registers, 0 or 1 for coils and discrete inputs. Unlike a Modbus client this can also write the read-only tables (discrete, input), which is how you fake sensor inputs at an address no point covers. Use set_point when the address belongs to a named point and you want scaling applied; a signal running on a point at that address will overwrite the value on its next update. Returns how many values were written. |
| apply_scenarioA | Play a timeline of timed steps on one device, starting now: set values, start or stop signals, inject or clear faults at given seconds. Use it to rehearse a sequence such as a pump trip followed by recovery; use set_point, set_signal or inject_fault for a single immediate change. Replaces any scenario already running on that device. Values, signals and faults set by steps stay in place after the scenario ends. Returns the scenario state. |
| stop_scenarioA | Stop the scenario running on one device so no further steps are played. Nothing is rolled back: values, signals and faults stay as the scenario left them (use clear_fault or set_point to reset them). Safe to call when no scenario is running. Fails if the device does not exist. |
| inject_faultA | Make one device misbehave on the wire so you can test how client software copes: slow answers, no answer (timeout), Modbus exception replies, or dropped connections. The fault applies to every request the device receives, replaces any fault already active on it, and lasts until clear_fault is called or its optional duration_s runs out. Point values keep updating in the background. Use apply_scenario to schedule faults at set times. |
| clear_faultA | Remove the active communication fault from one device so it answers Modbus requests normally again. Use it to end a fault started by inject_fault or by a scenario step before its duration runs out. It does not stop a running scenario, which may inject a fault again at a later step (use stop_scenario for that), and it does not change any values. Safe to call when no fault is active. Returns 'cleared': true if a fault was removed, false if there was none. Fails if the device does not exist. |
| get_traffic_logA | Show the most recent Modbus requests a device received from client software, oldest first: function code, address, quantity and how it was answered, plus the total number of requests served. Use it to see what the software under test is polling or to confirm a fault took effect. The log keeps the last 500 requests per device and is lost when the device is removed. Changes nothing. |
| save_projectA | Save every running device (points, current values, signals, ports, running scenarios) to a named project file on this machine so the same setup can be restored later with load_project. An existing project with the same name is overwritten without warning; call list_projects first to check. Running devices are not affected. Traffic logs and active faults are not saved. Fails if no devices are running. Returns the file path and device count. |
| load_projectA | Start the devices stored in a project saved earlier with save_project, on the ports recorded in it. By default they are added next to the devices already running, and the call fails part-way if an id or port is already in use (devices started before the failure keep running). With replace true, all running devices are removed first, which discards their unsaved state. Call list_projects to see the available names. Returns the devices that were started. |
| list_projectsA | List the names of the projects saved with save_project, sorted alphabetically, and the directory they are stored in. Use it to find a name for load_project or to check whether a name is taken before save_project overwrites it. Shows names only; load a project to see its devices. Changes nothing and returns an empty list when nothing has been saved. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 22 tools
Every tool targets a distinct resource+action, and the descriptions explicitly cross-reference the near neighbors (read_points vs read_registers vs get_device, set_point vs set_signal vs write_registers, remove_device vs remove_all_devices). Removal/stop variants (remove_device, remove_all_devices, remove_point, stop_scenario, clear_fault) each have clear, non-overlapping semantics. An agent can reliably pick the right tool.
All names are snake_case verb_noun (list_templates, create_device, read_points, set_signal, inject_fault, save_project, load_project). Verbs are used consistently per action (list_*, get_*, remove_*, read_*/write_*, set_*), with no camelCase or style mixing.
22 tools is on the heavy side, but the simulator genuinely spans devices, points, signals, raw registers, faults, scenarios, traffic logs and projects. Each tool maps to a needed operation rather than redundant variants. Slightly over the ideal range but well-justified.
Coverage is broad: full device lifecycle (create/clone/list/get/remove/save/load/list_projects), point add/remove/set/signal/read, raw register read/write, fault inject/clear, scenario apply/stop, and traffic log. Minor gap: no update_point to change a point's scale/unit/definition without removing and re-adding it. Core workflows are otherwise complete.