Skip to main content
Glama
acommand-edge

acommand-edge

Official

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 50

On 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

demo --scenario factory

factory-demo

motor-01

bearing_temperature in C

Port

demo --scenario port

port-demo

crane-01

vibration_rms in mm/s

Warehouse

demo --scenario warehouse

warehouse-demo

cold-room-01

temperature in C

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

Import 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.json

Publish 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.json

Set 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.json

Each 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_devices

List up to 200 site/device pairs and last observed times

get_latest_telemetry

Read the latest recorded value for up to 200 metrics on one device

get_telemetry_history

Read one device/metric history, with a 1–200 result limit

get_recent_alerts

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 build

Tests 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      This 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      18
      339 PyPI
      3
      MIT