genieacs-mcp

Send a connection request to wake a CPE device without waiting for its periodic inform. Use this tool when you need the device to contact the ACS immediately, for example to execute pending tasks, apply preset changes, or force a parameter refresh. This sends an HTTP connection request to the CPE's management URL as configured in the TR-069 connection request mechanism. Returns 200 on success (the CPE acknowledged the request) or 504 if the CPE is unreachable (behind NAT, offline, or firewall blocking the connection request port). Example: connection_request(device_id="00236A-SmartRG585-SMRT00236a42"). Limitations: the CPE must be network-reachable from the ACS for connection requests to work. Devices behind NAT without STUN/NAT traversal configured will not respond. This does not queue a task — it only triggers the CPE to initiate a CWMP session.

Delete a pending task from the GenieACS task queue. Use this tool to cancel a task that was queued but has not yet been executed by the CPE, such as a mistakenly queued firmware download or an unwanted reboot. The task_id is the _id field from the task document, obtainable via the genieacs://tasks/{id} resource. Returns a 503 error if the device is currently in an active CWMP session (the task cannot be deleted while the device is communicating with the ACS). Example: delete_task(task_id="67abc123def456"). Limitations: only pending tasks can be deleted. Completed or in-progress tasks cannot be removed. Use retry_task instead if the task faulted and you want to re-run it.

Push a firmware image or configuration file to a CPE device via GenieACS TR-069 download mechanism. Use this tool to initiate an OTA firmware upgrade or to push any file (config backups, supplementary data) to a device. The file must already be uploaded to GenieACS — use genieacs://file/{name} to inspect available files. Returns the raw JSON response from the ACS confirming the download task was queued. Limitations: the download is asynchronous — the ACS queues the task and the CPE fetches the file on its next session (periodic inform or connection request). Large firmware files may take minutes to transfer. Verify success by checking genieacs://tasks/{device_id} after allowing time for the transfer. Example: download_firmware(device_id="00236A-SmartRG585-SMRT00236a42", file_id="firmware-v2.0.bin").

Read specific TR-069 parameter values from the GenieACS cache for a device without contacting the CPE. Use this tool to quickly retrieve known parameter values such as firmware version, serial number, uptime, WiFi SSID, or IP addresses. This reads the last-known values stored in the ACS database — the data may be stale if the device has not informed recently. Use refresh_parameter first if you need a guaranteed fresh value from the CPE. The parameter_path can be a single parameter (e.g. "Device.DeviceInfo.SoftwareVersion") or a comma-separated list for multiple parameters. Returns the matching device document fields as JSON. Limitations: only returns data that the ACS has previously collected. If a parameter has never been read from the CPE, it will not appear in the response.

Create, update, or delete a GenieACS preset. Presets define automatic configuration rules that are applied to CPE devices matching a precondition filter. Use action="put" to create or overwrite a preset, providing the full JSON body with weight, precondition, and configurations. Use action="delete" to remove a preset by name. A preset body should contain: weight (integer priority), precondition (a stringified MongoDB-style JSON query, e.g. "{\"_tags\":\"office\"}"), and configurations (array of objects with type "value", "provision", "add_object", or "delete_object"). Example body: {"weight":0,"precondition":"{\"_tags\":\"test\"}","configurations":[{"type":"provision","name":"myScript"}]}. Preset names cannot contain dots. Use genieacs://presets/list to view existing presets before making changes. Limitations: changes take effect on the next CPE inform, not immediately.

Create, update, or delete a GenieACS provision script. Provision scripts are JavaScript functions that run on the ACS during a device's inform session to dynamically configure CPEs. Use action="put" to upload a new provision script or overwrite an existing one. The script argument must be raw JavaScript source code (not JSON). Use action="delete" to remove a provision script by name. GenieACS validates the script syntax on upload — a 400 error means the JavaScript has a syntax error. Provision scripts are referenced by name in presets (via configurations of type "provision"). Use genieacs://provisions/list to view existing scripts before making changes. Example script: log("Device " + args[0] + " informed"); Limitations: provision scripts execute server-side in the GenieACS sandbox with a limited API (declare, commit, ext, log). They cannot make arbitrary HTTP calls or access the filesystem.

Reboot a CPE device through the GenieACS TR-069 ACS. Use this tool when a device needs to be restarted, for example after a configuration change, firmware update, or to recover from an unresponsive state. The device must exist in the GenieACS inventory — use genieacs://devices/list to discover valid IDs. Returns the raw JSON response from the ACS confirming the task was queued. Limitations: the reboot is asynchronous — the task is queued on the ACS and executed the next time the CPE contacts the ACS (via its periodic inform or a connection request). There is no confirmation that the device actually rebooted. Example: reboot_device(device_id="00236A-SmartRG585-SMRT00236a42").

Request a CPE device to report the current value of a specific TR-069 parameter via GenieACS. Use this tool when you need an up-to-date reading of a device parameter — for example, checking the current firmware version, uptime, WiFi SSID, or any CWMP data model path. The refreshed value is stored in the GenieACS device document and can be read afterwards via genieacs://device/{id}. Returns the raw JSON response from the ACS confirming the refresh task was queued. Limitations: the refresh is asynchronous — the value is updated when the CPE next contacts the ACS. Only one parameter path can be refreshed per call; use the full dotted TR-069 object path. Example: refresh_parameter(device_id="00236A-SmartRG585-SMRT00236a42", parameter="Device.DeviceInfo.SoftwareVersion").

Retry a faulted task in GenieACS. Use this tool when a previously queued task (reboot, firmware download, parameter set, etc.) has failed and you want to re-attempt it. The task_id is the _id field from the task document, obtainable via the genieacs://tasks/{id} resource — look for tasks with fault information. This clears the fault and re-queues the task for execution on the next CPE inform. Example: retry_task(task_id="67abc123def456"). Use genieacs://faults/{id} to understand why the task originally failed before retrying. Limitations: only faulted tasks can be retried. Retrying a non-faulted task has no effect.

Search for CPE devices in GenieACS using MongoDB-style query filters. Use this tool to find devices by tag, manufacturer, model, firmware version, last inform time, or any other TR-069 parameter stored in the ACS. The query argument is a JSON string using MongoDB query syntax. Examples: {"_tags":"office"} to find devices tagged "office", {"InternetGatewayDevice.DeviceInfo.Manufacturer._value":"Huawei"} to find Huawei devices, {"_lastInform":{"$lt":"2024-01-01T00:00:00Z"}} to find devices that haven't informed since 2024. For non-underscore-prefixed parameter paths, GenieACS automatically appends "._value" to the query, so you can also query as {"InternetGatewayDevice.DeviceInfo.Manufacturer":"Huawei"}. Returns a JSON array of matching device documents. Use the limit argument to control the maximum number of results (default 50). Limitations: complex aggregation queries are not supported — only standard MongoDB comparison operators ($eq, $ne, $gt, $lt, $gte, $lte, $regex, $in, $nin, $exists).

Set one or more TR-069 parameter values on a CPE device through GenieACS. Use this tool to change device configuration such as WiFi SSID, management server URL, periodic inform interval, or any writable TR-069 parameter. The parameter_values argument must be a JSON array of tuples, where each tuple is [parameterPath, value] or [parameterPath, value, xsdType]. Example: [["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID","MySSID","xsd:string"]]. Valid xsd types include xsd:string, xsd:boolean, xsd:unsignedInt, xsd:int, xsd:dateTime. If the type is omitted, GenieACS infers it from the value. The task is queued and a connection request is sent to the CPE for immediate execution. Returns the raw ACS JSON response confirming the task. Limitations: the CPE must be reachable for immediate execution; otherwise the task remains queued until the next periodic inform. Not all parameters are writable — the CPE will fault if you attempt to set a read-only parameter. Use refresh_parameter or genieacs://device/{id} first to discover valid parameter paths.

Add or remove a tag on a CPE device in GenieACS. Tags are labels used to group devices for preset matching, bulk operations, and organizational purposes. Use action="add" to tag a device and action="remove" to untag it. Tags are referenced in preset preconditions (e.g. {"_tags":"office"}) to target specific device groups for automatic configuration. The device must exist in GenieACS — returns a 404 error if the device ID is invalid. Example: tag_device(device_id="00236A-SmartRG585-SMRT00236a42", tag="office", action="add"). Use search_devices with a _tags filter to verify tag assignment after modification. Limitations: tag names are case-sensitive strings. There is no built-in tag listing — use search_devices or genieacs://devices/list to discover existing tags on devices.