类型 | 用途 | MCP URI / 工具 ID |
资源 | 只读获取 GenieACS 数据 |
|
工具 | 通过 GenieACS 在 CPE 上调用操作 |
|
所有内容均通过单个 JSON-RPC 端点 (/mcp) 公开。
LLM / 代理可以：initialize → readResource → listTools → callTool ……以此类推。
Related MCP server: mcp-fritzbox
请遵循 https://github.com/GeiserX/genieacs-container 中的说明，该项目已包含在其中的 docker compose 文件中。
npx genieacs-mcp或者全局安装：
npm install -g genieacs-mcp
genieacs-mcp这将为你的平台下载预构建的 Go 二进制文件，并以 stdio 传输方式运行它，兼容任何 MCP 客户端。
git clone https://github.com/GeiserX/genieacs-mcp
cd genieacs-mcp
# (optional) create .env from the sample
cp .env.example .env && $EDITOR .env
go run ./cmd/server变量 | 默认值 | 描述 |
| GenieACS NBI 端点（末尾不带 /） | |
| admin | GenieACS 用户名 |
| admin | GenieACS 密码 |
| (空 = HTTP) | 设置为 |
将它们放入 .env 文件（从 .env.example 复制）或在环境中设置它们。
已使用 Inspector 进行测试，目前完全可用。在提交 PR 之前，请确保此 MCP 服务器通过该媒介表现良好。
缺乏与实际 MCP 客户端（客户端 LLM）的测试，因此如果它未能充分匹配此 MCP 服务器提供的服务，请提交 PR 以改进描述。
{
"schema_version": "v1",
"name_for_human": "GenieACS-MCP",
"name_for_model": "genieacs_mcp",
"description_for_human": "Read data from GenieACS and run actions on CPEs (reboot, firmware update, parameter refresh).",
"description_for_model": "Interact with an Auto-Configuration-Server (ACS) that manages routers. First call initialize, then reuse the returned session id in header \"Mcp-Session-Id\" for every other call. Use readResource to fetch URIs that begin with genieacs://. Use listTools to discover available actions and callTool to execute them.",
"auth": { "type": "none" },
"api": {
"type": "jsonrpc-mcp",
"url": "http://localhost:8080/mcp",
"init_method": "initialize",
"session_header": "Mcp-Session-Id"
},
"logo_url": "https://raw.githubusercontent.com/GeiserX/genieacs-container/main/extra/logo.png",
"contact_email": "acsdesk@protonmail.com",
"legal_info_url": "https://github.com/GeiserX/genieacs-mcp/blob/main/LICENSE"
}GenieACS – 最好的开源 ACS
MCP-GO – 现代 MCP 实现
GoReleaser – 轻松实现多架构发布
欢迎加入！提交 issue 或提交 PR。
GenieACS-MCP 遵循 Contributor Covenant 行为准则。
该项目是用于处理 GenieACS 的更广泛工具集的一部分：
项目 | 类型 | 描述 |
Docker + Helm | 生产就绪的多架构 Docker 镜像和 Helm chart | |
Ansible Collection | 动态清单插件和设备管理模块 | |
HA 集成 | 用于 TR-069 监控的 Home Assistant 集成 | |
n8n 节点 | GenieACS 的工作流自动化 | |
服务定义 | Systemd/Supervisord 服务定义 | |
模拟器 | 用于测试的基于 Docker 的 GenieACS 模拟器 |
cashpilot-mcp — 被动收入监控
duplicacy-mcp — 备份健康状况监控
lynxprompt-mcp — AI 配置蓝图
pumperly-mcp — 燃油和电动汽车充电价格
telegram-archive-mcp — Telegram 消息存档
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.
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber (e.g. "00236A-SmartRG585-SMRT00236a42"). Obtain valid IDs from the genieacs://devices/list resource. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructive and non-idempotent behavior. Description adds detail on mechanism (HTTP connection request), return codes (200/504), and that it triggers a CWMP session without queuing. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is multi-sentence but well-structured: purpose, usage, mechanism, returns, example, limitations. Each sentence adds value, though slight verbosity could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return values and behavior. Covers example, limitations, and what the tool does not do (queuing). Adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage for device_id with format description. Description adds value by giving an explicit example and source for valid IDs, enhancing schema meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Send a connection request to wake a CPE device' and specifies context like executing pending tasks, applying presets, or forcing parameter refresh. Distinguishes from sibling tools like reboot_device or refresh_parameter by focusing on immediate contact trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (immediate contact needed). Mentions limitations (NAT, reachability) and that it does not queue a task. Could improve by explicitly stating when not to use and listing alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task identifier (_id field from the task document). Obtain task IDs from the genieacs://tasks/{deviceId} resource. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-idempotent behavior. Description adds specific error condition (503 during CWMP session) and limitation to pending tasks, providing valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise multi-sentence structure with front-loaded purpose, followed by usage, example, and limitations. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, usage, error handling, example, and limitations. Sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single 'task_id' parameter is fully described in both schema and description. Description adds example and source for obtaining task IDs, enhancing usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool deletes pending tasks from GenieACS queue, distinguishing it from siblings like retry_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (cancel queued tasks), when not (completed/in-progress), and alternatives (retry_task for faulted tasks).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber. Obtain valid IDs from the genieacs://devices/list resource. | |
| file_id | Yes | The GridFS _id (filename) of the file to push to the device. Must match an existing file in GenieACS — use genieacs://file/{name} to verify it exists. | |
| filename | No | Optional display name passed to the CPE during the download. If omitted, the CPE receives the file_id as the filename. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and no readOnly, but the description adds rich behavioral context: asynchronous download, queued task, CPE fetches on next session, large files take minutes, and return value is raw JSON confirmation. This far exceeds what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but front-loaded with purpose, then actionable steps, then limitations, and ends with an example. Every sentence is valuable, though it could be slightly tighter without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description explains the return value (raw JSON confirming task queued) and provides verification guidance. It covers async behavior, file prerequisites, and includes a concrete example. Completely adequate for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the input schema (100% coverage). The description adds extra meaning: device_id format and source, file_id verification via genieacs://file/, and default behavior for filename. This adds beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('push') and resource ('firmware image or configuration file to a CPE device'), and the mechanism ('GenieACS TR-069 download'). It clearly distinguishes from sibling tools like reboot_device or set_parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for OTA firmware upgrades or pushing any file) and prerequisites (file must already be uploaded to GenieACS). It also provides context on async behavior and verification. However, it does not explicitly list when NOT to use it, but that is minor given the clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber (e.g. "00236A-SmartRG585-SMRT00236a42"). Obtain valid IDs from the genieacs://devices/list resource. | |
| parameter_path | Yes | Comma-separated TR-069 parameter paths to retrieve from the ACS cache. Example: "Device.DeviceInfo.SoftwareVersion" or "Device.DeviceInfo.SoftwareVersion,Device.DeviceInfo.UpTime,Device.ManagementServer.PeriodicInformInterval" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is read-only ('without contacting the CPE', 'reads last-known values'), but the annotations set destructiveHint=true, which implies a destructive or modifying action. This is a direct contradiction between the description and the annotation, severely impacting transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is moderately concise and well-structured with clear sections. Some slight redundancy ('quickly retrieve') but overall efficient. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, limitations, return format, and edge case (unread parameters not appearing). No output schema, but description sufficiently explains return. Could mention error handling or missing device, but overall complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds extra value by explaining comma-separated lists for parameter_path, providing concrete examples, and detailing the device_id format. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read specific TR-069 parameter values from the GenieACS cache for a device without contacting the CPE.' The verb 'read' and resource 'TR-069 parameter values' are specific, and the mention of 'without contacting CPE' distinguishes it from refresh_parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (quickly retrieve known values) and when not (if fresh value needed, use refresh_parameter). Provides practical examples and limitations, guiding the agent on appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The operation to perform: "put" to create or update a preset, "delete" to remove it. | |
| body | No | The full JSON preset document (required for action="put", ignored for "delete"). Must contain weight, precondition, and configurations fields. | |
| name | Yes | The preset name (used as the identifier in the URL). Cannot contain dots. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, which the description confirms by stating it can delete presets. The description adds valuable context: changes take effect on next CPE inform, not immediately. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph, but it is well-organized and front-loads the purpose. Every sentence contributes useful information; however, it could be slightly more concise by removing some redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and three parameters (two required), the description covers usage, constraints (name cannot contain dots), example, and limitations (deferred effect). It is complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches parameter understanding by detailing the body structure (weight, precondition, configurations) and providing a concrete example. This adds meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create, update, or delete a GenieACS preset.' It explains what presets are and distinguishes itself from sibling tools (e.g., connection_request, delete_task). The verb 'manage' combined with resource 'preset' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines when to use action='put' vs 'delete', provides an example body, and recommends viewing existing presets via genieacs://presets/list. It does not explicitly state when not to use the tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The operation to perform: "put" to create or update a provision, "delete" to remove it. | |
| name | Yes | The provision script name (used as the identifier in the URL). | |
| script | No | The raw JavaScript source code of the provision script (required for action="put", ignored for "delete"). GenieACS validates syntax before saving. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: mentions syntax validation (400 error on syntax error), server-side execution sandbox with limited API, and limitations (no HTTP calls or filesystem access). This fully complements the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and an example, but slightly verbose. Every sentence is informative, but could be tightened without loss of meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description sufficiently covers return behavior (400 error for syntax issues), side effects (storing script), and prerequisites. Provides limitations and an example, making it complete for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by clarifying that script must be raw JavaScript (not JSON) and that validation occurs on upload. Action parameter meanings are also elaborated beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates, updates, or deletes a GenieACS provision script. The verb 'manage' is generic, but the description specifies the exact operations and resource, differentiating it from sibling tools like manage_preset which targets presets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use action='put' vs action='delete', and suggests viewing existing scripts via genieacs://provisions/list before changes. However, it does not explicitly state when not to use the tool or mention alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber (e.g. "00236A-SmartRG585-SMRT00236a42"). Obtain valid IDs from the genieacs://devices/list resource. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive intent. The description adds crucial behavioral details: the reboot is asynchronous, queued on ACS, no confirmation of actual reboot, and returns raw JSON. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured: purpose first, then usage, then limitations, then example. Every sentence is informative and necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (async reboot, no output schema), the description covers all essential aspects: purpose, prerequisites, return value, and limitations. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The one parameter (device_id) is fully described in the schema with format and examples. The description reinforces this with a concrete example and instructions to obtain valid IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reboot a CPE device') through a specific system (GenieACS TR-069 ACS). It distinguishes from sibling tools like connection_request or get_parameter by specifying the ACS context and the device scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage scenarios (after config change, firmware update, recovery) and instructs to discover valid IDs via another resource. However, it does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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").
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber. Obtain valid IDs from the genieacs://devices/list resource. | |
| parameter | Yes | Full TR-069 dotted parameter path to refresh. Examples: "Device.DeviceInfo.SoftwareVersion", "Device.DeviceInfo.SerialNumber", "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID". Must be a valid path in the device's CWMP data model. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses asynchronous behavior, queuing of task, and CPE contact dependency. Annotations indicate destructiveHint=true, but description does not elaborate on destruction; still, the mutation nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for purpose, usage, limitations, and example. Slightly verbose but every sentence adds value. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a tool with two simple parameters. Includes return value description (raw JSON), important limitations, and an example. No output schema needed; this covers the agent's needs fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds valuable context: device_id format (OUI-ProductClass-SerialNumber), where to obtain valid IDs, and multiple parameter path examples. Enhances understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool requests a CPE device to report a specific TR-069 parameter via GenieACS, distinguishing it from siblings like get_parameter, set_parameter, and reboot_device. The verb 'refresh' and target 'parameter' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (need up-to-date reading) and includes limitations (asynchronous, one parameter per call, full dotted path). Does not explicitly contrast with alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task identifier (_id field from the task document). Obtain task IDs from the genieacs://tasks/{deviceId} resource. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description reveals that retrying clears the fault and re-queues the task on next CPE inform, adding context beyond annotations (which indicate destructive and non-idempotent). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with clear sentences, includes an example and limitations, but could be slightly shorter by removing redundant phrases. Still well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given single parameter, no output schema, and annotations covering safety, the description fully covers purpose, usage, parameter semantics, and limitations. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema has 100% coverage, but description adds value by explaining task_id is the _id field, how to obtain it, and includes an example. Schema alone doesn't provide this context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retry a faulted task in GenieACS' with specific verb and resource, and distinguishes from sibling tools like delete_task and connection_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (after a faulted task), when not to (non-faulted tasks), and provides context to obtain task_id and check fault information via genieacs://faults/{id}.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of devices to return. Defaults to 50 if not specified. Use a higher value for bulk operations, but be mindful of response size. | |
| query | Yes | A MongoDB-style JSON query string to filter devices. Example: {"_tags":"office"} or {"_id":"00236A-SmartRG585-SMRT00236a42"} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, but description focuses on search and returns, not mentioning any destructive potential. It does not contradict annotations but fails to add context about why the tool is considered destructive. Adds useful behavioral details like query syntax and default limit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is reasonably concise given the complexity of MongoDB query syntax, with well-organized examples and limitations. Could tighten some phrases, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains return format ('JSON array of matching device documents'), covers query syntax, limit behavior, and limitations. For a search tool with 2 parameters, this is complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value beyond schema with query examples, explanation of ._value auto-append, default limit behavior, and limitations. This enriches understanding of both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb ('Search'), resource ('CPE devices'), and scope ('using MongoDB-style query filters'). It distinguishes from sibling tools like get_parameter or reboot_device by specifying the search functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use: 'find devices by tag, manufacturer, model, firmware version, last inform time, or any other TR-069 parameter.' Provides examples and mentions limitations (no complex aggregation). Does not explicitly exclude use cases, but implicitly guides via examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber (e.g. "00236A-SmartRG585-SMRT00236a42"). Obtain valid IDs from the genieacs://devices/list resource. | |
| parameter_values | Yes | A JSON array of parameter tuples to set. Each tuple is either [path, value] or [path, value, xsdType]. Example: [["Device.WiFi.SSID.1.SSID","NewName","xsd:string"],["Device.ManagementServer.PeriodicInformInterval",300,"xsd:unsignedInt"]] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack behavioral details, but the description fully explains: task queuing, immediate execution via connection request, queuing if unreachable, and fault behavior for read-only parameters. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of 8 sentences, each sentence adds unique value. It is front-loaded with the main purpose, followed by examples, types, limitations, and alternatives. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value ('raw ACS JSON response confirming the task'). It covers limitations, prerequisites, and error scenarios. Everything an agent needs is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds critical meaning: JSON array of tuples format, example, list of valid xsd types, and inference if type omitted. This goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set one or more TR-069 parameter values on a CPE device through GenieACS.' It specifies the verb (set), resource (parameter values on CPE), and distinguishes it from sibling tools like get_parameter or reboot_device.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (change device configuration like WiFi SSID) and provides warnings: CPE must be reachable, read-only parameters will fault. Suggests alternatives: 'Use refresh_parameter or genieacs://device/{id} first to discover valid parameter paths.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The operation to perform: "add" to tag the device, "remove" to untag it. | |
| device_id | Yes | The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber (e.g. "00236A-SmartRG585-SMRT00236a42"). Obtain valid IDs from the genieacs://devices/list resource. | |
| tag | Yes | The tag string to add or remove (e.g. "office", "floor-2", "firmware-pending"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations: it mentions the 404 error for invalid device, case-sensitivity of tags, and lack of built-in tag listing. Aligns with destructiveHint=true and readOnlyHint=false, but lacks details on idempotency or duplicate tag behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph. While not overly long, it could benefit from bullet points or clearer separation of sections to improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the tool's return value or success response. It only mentions a 404 error. For a mutating tool with no output schema, this is a notable gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches each parameter: explains action values ('add'/'remove'), gives device_id format and example, and provides tag string examples. Includes a full example call, adding substantial value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: add or remove a tag on a CPE device in GenieACS. It distinguishes between the two actions and explains tags are used for grouping devices, differentiating from sibling tools like search_devices and manage_preset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use action='add' and action='remove', provides an example, and suggests using search_devices for verification. It mentions the device must exist and limitations, but does not explicitly list when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.3connection_requestdelete_taskdownload_firmware3 fields changedInput schema / properties / device_id / descriptionPrevious value: -"Target device ID"New value: +"The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber. Obtain valid IDs from the genieacs://devices/list resource."Input schema / properties / file_id / descriptionPrevious value: -"GridFS _id of the file to download"New value: +"The GridFS _id (filename) of the file to push to the device. Must match an existing file in GenieACS — use genieacs://file/{name} to verify it exists."Input schema / properties / filename / descriptionPrevious value: -"(optional) file name to pass to the CPE"New value: +"Optional display name passed to the CPE during the download. If omitted, the CPE receives the file_id as the filename."get_parametermanage_presetmanage_provisionreboot_device1 field changedInput schema / properties / device_id / descriptionPrevious value: -"Exact device ID (_id) as known by GenieACS"New value: +"The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber (e.g. \"00236A-SmartRG585-SMRT00236a42\"). Obtain valid IDs from the genieacs://devices/list resource."refresh_parameter2 fields changedInput schema / properties / device_id / descriptionPrevious value: -"Target device ID"New value: +"The exact GenieACS device identifier (_id field). Typically in the format OUI-ProductClass-SerialNumber. Obtain valid IDs from the genieacs://devices/list resource."Input schema / properties / parameter / descriptionPrevious value: -"Full TR-069 path, e.g. Device.DeviceInfo.SerialNumber"New value: +"Full TR-069 dotted parameter path to refresh. Examples: \"Device.DeviceInfo.SoftwareVersion\", \"Device.DeviceInfo.SerialNumber\", \"InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID\". Must be a valid path in the device's CWMP data model."retry_tasksearch_devicesset_parametertag_devicev0.0.10download_firmwarereboot_devicerefresh_parameterScored across 12 tools
Each tool targets a distinct operation: device wake-up, reboot, firmware download, parameter set/refresh/read, device search/tag, preset/provision management, and task delete/retry. No overlapping purposes, clear differentiation.
All tools follow a consistent verb_noun pattern (e.g., delete_task, set_parameter, tag_device). No mixing of styles or ambiguous verbs.
12 tools cover the core operations for TR-069 device management: device interaction, parameter handling, task management, device discovery, and configuration management. Well-scoped without being excessive.
Covers essential CRUD and lifecycle operations for devices, parameters, tasks, presets, and provisions. Minor gap: no dedicated tool to list all queued tasks, but task management tools (delete, retry) and reference to task resources partially compensate.
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for InsForge BaaS — database, storage, edge functions, and deployments
