acommand-edge
OfficialSubscribes to MQTT telemetry topics (acommand/{site_id}/{device_id}/telemetry), validating incoming JSON payloads against the required schema and storing readings in the local telemetry store, with optional threshold-rule evaluation, QoS 1 subscription, 64 KiB payload limits, and TLS with CA certificate support for remote/authenticated brokers. Read-only — it never publishes control commands.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Acommand Edge Gateway
Read device telemetry. Give AI agents useful, bounded context.
中文说明 · Acommand AI · Research and sources · Third-party notices
Acommand Edge Gateway is an MIT-licensed Python integration starter connecting MQTT messages and Modbus TCP readings to a local telemetry store and a read-only Model Context Protocol (MCP) interface. It includes synthetic factory, port, and warehouse examples for learning and prototyping.
Version 0.1.0 is a development starter, not a production industrial control system. It does not operate equipment, include a language model, or call a paid AI API. The demo needs no hardware, credentials, or runtime dependencies beyond Python 3.11+.
What is included
Validated numeric telemetry with explicit site, device, metric, unit, and time.
SQLite storage; exact event replays are ignored, while changed data using an existing event ID for the same site/device is rejected.
Unit-aware threshold rules and stored alerts.
Optional MQTT subscriber and single-register, read-only Modbus TCP adapter.
Four read-only MCP tools over local stdio, using an existing database.
Synthetic examples and tests for the core, connectors, and MCP interface.
flowchart TD
MQTT["MQTT messages"] --> Validate["Validate telemetry"]
Modbus["Modbus register"] --> Validate
Demo["Synthetic examples"] --> Validate
Validate --> Store["SQLite telemetry"]
Validate --> Rules["Threshold rules"]
Rules --> Store
Store --> CLI["CLI queries"]
Store --> MCP["Read-only MCP tools"]
MCP --> Host["AI client"]Related MCP server: telemetry-mcp
Quick start
git clone https://github.com/AcommandAIGroup/acommand-edge-gateway.git
cd acommand-edge-gateway
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
acommand-edge --db ./data/demo.db demo --scenario factory
acommand-edge --db ./data/demo.db devices
acommand-edge --db ./data/demo.db latest factory-demo motor-01
acommand-edge --db ./data/demo.db history factory-demo motor-01 bearing_temperature --limit 50
acommand-edge --db ./data/demo.db alerts --site factory-demo --device motor-01 --limit 50On Windows, activate the environment with .venv\Scripts\Activate.ps1 in
PowerShell. The --db option goes before the subcommand. The demo creates
the database and adds new synthetic events each time it runs; it is not a live
device feed.
Scenario | Command suffix | Site | Device | Example metric |
Factory |
|
|
|
|
Port |
|
|
|
|
Warehouse |
|
|
|
|
Thresholds and measurements are illustrative, not manufacturer limits or evidence of predictive maintenance performance.
Telemetry format and JSONL ingestion
Each event requires exactly these seven fields:
{
"event_id": "sample-001",
"site_id": "factory-demo",
"device_id": "motor-01",
"metric": "bearing_temperature",
"value": 78.0,
"unit": "C",
"timestamp": "2026-11-13T08:00:00Z"
}Save one complete JSON object per line in a .jsonl file; the multi-line JSON
above is formatted only for readability. IDs and metric names are 1–64 ASCII
characters, start with a letter or digit, and may include ., _, or -.
Values must be finite numbers, not strings or booleans. Timestamps must contain
a timezone and are normalized to UTC. Units are short measurement labels; no
automatic unit conversion is performed.
acommand-edge --db ./data/demo.db ingest examples/telemetry.jsonl --rules examples/rules.jsonImport stops at the first invalid line; earlier accepted lines remain stored. It is not an all-or-nothing file transaction. Each nonblank line is limited to 64 KiB.
Rules are a JSON array. For example:
[
{
"rule_id": "bearing-high",
"site_id": "factory-demo",
"device_id": "motor-01",
"metric": "bearing_temperature",
"unit": "C",
"operator": "gt",
"threshold": 75,
"severity": "warning"
}
]Supported operators: gt, gte, lt, lte. Severity: info, warning, or
critical. site_id and device_id filters are optional; the metric and unit
must match exactly. Rules evaluate new events at ingestion, not historical rows
after a rule file changes. Alerts are observations, not equipment commands.
Connect MQTT or Modbus
Install all optional adapters and the MCP SDK:
python -m pip install -e '.[all]'Individual extras are .[mqtt], .[modbus], and .[mcp]. Optional direct
dependencies are pinned to Paho MQTT 2.1.0, PyModbus 3.11.3, and MCP
Python SDK 1.30.0. These pins are not a complete transitive dependency lock.
MQTT
Start your local broker, then run the subscriber:
acommand-edge --db ./data/demo.db mqtt --host localhost --port 1883 \
--topic 'acommand/+/+/telemetry' --rules examples/rules.jsonPublish the telemetry schema to acommand/{site_id}/{device_id}/telemetry from
your device or simulator. For the JSON example above, the topic is
acommand/factory-demo/motor-01/telemetry. Topic and payload identities must
match. The adapter accepts at most 64 KiB per payload and only subscribes; it
does not publish control commands.
Remote hosts and any connection carrying credentials require verified TLS:
acommand-edge --db ./data/demo.db mqtt --host mqtt.example.com --port 8883 \
--tls --ca-cert /absolute/path/to/ca.pem \
--topic 'acommand/factory-demo/+/telemetry' --rules examples/rules.jsonSet ACOMMAND_MQTT_USERNAME and ACOMMAND_MQTT_PASSWORD in your environment or
secret manager when required by the broker. Do not put secrets in tracked files.
Omit --ca-cert to use the default certificate trust store. Select the correct
TLS port explicitly; --tls does not change the port.
The subscription requests QoS 1. This starter does not guarantee durable replay, exactly-once delivery, or lossless recovery after storage failure or a process restart. Use broker access rules to constrain which sites each client may publish or read.
Modbus TCP
Edit examples/modbus.json to match a device you are authorized to query:
{
"host": "127.0.0.1",
"port": 5020,
"site_id": "factory-demo",
"asset_id": "motor-01",
"device_id": 1,
"address": 0,
"count": 1,
"register_type": "holding",
"metric": "bearing_temperature",
"unit": "C",
"scale": 0.1,
"offset": 0,
"timeout": 3
}acommand-edge --db ./data/demo.db modbus examples/modbus.json --rules examples/rules.jsonEach invocation reads one unsigned 16-bit register once and closes the
connection. address is zero-based; device_id is the Modbus unit identifier;
asset_id becomes the telemetry device ID. The value is register * scale + offset. register_type accepts holding or input. Signed, multi-register,
floating-point, serial RTU, and continuous polling are not implemented.
This adapter uses plain Modbus TCP. Keep it on an approved, isolated device network; check the manufacturer's register map before connecting. A local read timestamp is not the device's measurement timestamp.
Give an AI client read-only access
Seed the database first using the demo or a collector. Then configure an MCP client that supports launching stdio servers. Use absolute paths for both the virtual-environment executable and database:
{
"mcpServers": {
"acommand-edge": {
"command": "/absolute/path/to/acommand-edge-gateway/.venv/bin/acommand-edge",
"args": ["--db", "/absolute/path/to/data/demo.db", "mcp"]
}
}
}This is a common configuration shape; use your client's configuration location
and syntax. On Windows, the executable is under .venv/Scripts/acommand-edge.exe.
Running acommand-edge --db /absolute/path/to/data/demo.db mcp directly waits
for MCP protocol messages; it is not an interactive chat prompt.
Tool | Purpose |
| List up to 200 site/device pairs and last observed times |
| Read the latest recorded value for up to 200 metrics on one device |
| Read one device/metric history, with a 1–200 result limit |
| Read threshold alerts, with optional filters and a 1–200 result limit |
The MCP server opens SQLite read-only and exposes no network listener or device write tools. Results include a retrieval time and freshness note: a recent query does not mean the measurement is recent. The AI client decides whether to send returned telemetry to its model provider; configure that client for your data requirements. The gateway itself makes no external model call.
Try asking your client: “Show the latest measurements for factory-demo/motor-01 and explain which configured thresholds were exceeded. Separate observations from hypotheses and include measurement times.”
Development and limitations
python -m pip install -e '.[all,dev]'
python -m unittest discover -s tests -v
ruff check .
python -m buildTests are included; their presence is not a hardware certification. Real MQTT brokers, Modbus devices, and AI clients need environment-specific validation. This release has no multi-user authorization, high-availability deployment, retention scheduler, equipment actuation, or production service guarantees. SQLite files contain operational data and require appropriate filesystem permissions and lifecycle management.
See CONTRIBUTING.md, SECURITY.md, and research notes.
About Acommand AI
Acommand AI is a global AI agent platform and solutions provider, connecting devices, business systems, and people across factories, ports, warehouses, and other operational environments.
acommandai.com · Business enquiries: Service@Acommandai.com
Original integration code: MIT. Dependencies retain their own licenses; see THIRD_PARTY_NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Local shadow MCP for HVAC, plumbing, electrical, and sewer. Read-only. Not a hosted OS.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceThis MCP server enables AI agents to read MQTT and Sparkplug B data via tools like list_topics, get_latest, and read_all, providing read-only access to latest sensor values.1MIT
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server for querying telemetry data from configurable backends. Provides tools to list sources, describe schemas, run bounded queries, and compute aggregates.MIT
- AlicenseNot gradedqualityBmaintenanceProvides read-only MCP access to Signal K vessel data for diagnostics, letting clients retrieve allowed self values, discover paths, list plugins, and report capability/security policy without write or control commands.55 npmMIT
- AlicenseAqualityBmaintenanceA read-only MCP server that lets an AI agent inspect a ROS2 graph, its underlying DDS participants, readers, writers and QoS mismatches, and recorded bag files, with twelve typed tools that behave the same against a live robot or built-in mock fixtures. It has no write path at all, so it can never publish to the bus or command a robot.18339 PyPI3MIT