智能家居控制MCP服务器

myIO MCP Server

Model Context Protocol (MCP) server for the myIO smart home controller (Arduino GIGA / Finder Opta 4.x and Arduino Due 3.12). It lets an AI assistant (Claude Desktop, Claude Code, any MCP client) read the state of the house and switch, dim and configure it through the controller's HTTP API.

Plan and log (Hungarian): ../MYIO_MCP_PLAN.md. The complete API the server is built on: API_REFERENCE.md (a copy of the firmware's own reference, Hungarian).

Status (1.6.0, 2026-10-26)

Rounds 0-5 of the plan: the February 2026 server fixed, put on tests, extended with the house entities, the configuration layer, automation (Flow rules, myIO Script programs), diagnostics / logs / files, every integration and RS485 expander - and in round 5 the MCP layer: resources, prompts, toolsets, consistent annotations and an optional Streamable HTTP transport.

• native node:http client (no more curl), one request at a time per controller, Connection: close
• correct value scales: temperature ×100, humidity ×10, SDM voltage/current ×10, SDM power in W, PCA/FET level raw 0..255
• every control tool reads the state back and reports what the controller actually did (a command the account has no permission for is silently dropped by the firmware)
• several controllers in one server (MYIO_SERVERS), every tool takes a server name
• version gate: V3 (Due 3.12) and V4 (GIGA/Opta 4.x) both supported, 4.x-only features answer with a clear error on a Due
• entities modelled like the myIO app / Homey / Home Assistant integration: thermostat zones, shutters (protection pairs), RGB groups, wall inputs, universal sensors
• configuration layer: globals, names, output/input configuration, protection pairs / joiners / groups, scenes, timers, users and permissions - toggle-type settings are read first and only sent when they must change
• automation: Flow rules described in plain words with element names, validated against the firmware's card rules BEFORE upload (the firmware silently disables a rule with a bad card), saved + reloaded + read back; scripts written, compiled on the controller, compile errors returned with the offending source line; the complete script language reference is a tool (myio_reference)
• diagnostics: health snapshot (resets, loop stalls, RAM, sockets, WiFi, NTP on a Due), Prometheus metrics, daily logs with level / text / time filters, file manager on internal flash and SD card (system files need MYIO_WRITE=admin)
• integrations: Shelly, myIO Link, MQTT, myIO Cloud, SG-Ready, alarm panel (SIA), MIA, LED strips, network, restart / web OTA; Opta expanders: failsafe / AUX / 1-Wire, KNX (table, names, ETS interface, device programming), DALI, DMX, Modbus RTU. Toggle-type settings are always given as desired values; passwords, keys and tokens are never returned; a value containing & is refused (the firmware cannot receive it)
• write level (MYIO_WRITE = state | config | admin) limits what the AI may change
• MCP layer: resources (myio://<controller>/state ...), four prompts in Hungarian and English that read the controller first, toolsets (MYIO_TOOLSETS) to save context, annotations that follow one rule set, Streamable HTTP for other LAN clients (bearer token)
• zod input schemas, mock controller + end-to-end tests (npm test, 72 tests), restoring live tests for a bench controller

Tools (102)

Element ids are shared by all tools and channels: relays 1..RQ, FET 101..116, groups 501.., PCA 2001..2000+PCAQ (see API_REFERENCE.md chapter 3).

Annotations follow one rule set: read tools are readOnlyHint; a desired-value setter (on / off / level / target / name / a setting) is idempotentHint - calling it twice changes nothing more (an identical protection pair, joiner or timer is reused, not duplicated); toggles, fire / run, button presses and add / new actions are not; tools that can overwrite or delete stored configuration are destructiveHint (switching an output is a reversible state change, not destructive); a tool with several actions is annotated for its most dangerous one. myio_webhook_test is openWorldHint (it calls an outside URL).

Toolsets

The 102 tool descriptions cost context. MYIO_TOOLSETS loads only some groups (the same field is in the Claude Desktop settings):

Examples: MYIO_TOOLSETS=house,automation (core + 20), MYIO_TOOLSETS=all,-legacy,-expanders (77). Empty or all = everything (default). Unknown names are reported on stderr; core cannot be switched off. The server instructions tell the model which groups are not loaded, and the prompts only mention tools that are. Resources and prompts do not depend on the toolsets.

Resources

Attachable context - the client reads them without a tool call. <controller> is the URI-safe form of the controller name (Földszint -> foldszint, Ground floor -> ground-floor; printed on stderr at start).

The templates offer completion (controller names, slot numbers, the last seven days).

Prompts

Each prompt reads the controller(s) when it is requested and embeds the data, so the conversation starts with full context (every data block fails on its own: "not available: ..."). Argument language: hu (default) or en; server limits it to one controller.

Streamable HTTP (optional)

stdio stays the default. With MYIO_HTTP_PORT the server also answers MCP over Streamable HTTP at /mcp, for other MCP clients on the LAN:

MYIO_HTTP_PORT=8765 MYIO_HTTP_HOST=0.0.0.0 MYIO_HTTP_TOKEN=$(openssl rand -base64 24) \
MYIO_BASE_URL=http://192.168.1.178 MYIO_USERNAME=admin MYIO_PASSWORD=... node dist/index.js
# client: URL http://<this-machine>:8765/mcp, header  Authorization: Bearer <token>

• binds to 127.0.0.1 by default; any other address needs MYIO_HTTP_TOKEN (min. 16 characters) or the server refuses to start. On loopback without a token a random one is generated and printed on stderr.
• every request needs Authorization: Bearer <token> (compared in constant time); sessions are kept in memory (max 16, idle 30 min).
• all sessions share the controller clients, so the per-controller request queue (and MYIO_MIN_GAP_MS) still protects the firmware.
• started from a terminal it serves only HTTP; under an MCP client (stdin is a pipe) stdio runs too. MYIO_STDIO=0|1 forces it.
• plain HTTP: use it inside the home network or behind a TLS reverse proxy / VPN, not on the open internet. On macOS the application firewall may ask to allow incoming connections for node.

Configuration

Environment variables (the Claude Desktop extension asks for them as user config):

Claude Desktop

Install myio-mcp.mcpb (Settings → Extensions) and fill in the URL, user and password. To rebuild the bundle:

npm install
npm run pack          # = sync-docs + tsc + mcpb pack . myio-mcp.mcpb

Claude Code / other MCP clients (stdio)

{
  "mcpServers": {
    "myio": {
      "command": "node",
      "args": ["/absolute/path/to/myio-mcp/dist/index.js"],
      "env": { "MYIO_BASE_URL": "http://192.168.1.178", "MYIO_USERNAME": "admin", "MYIO_PASSWORD": "..." }
    }
  }
}

Development

npm install
npm run build         # TypeScript -> dist/
npm test              # build + mock controller + end-to-end tests over stdio (node --test)
MYIO_BASE_URL=http://192.168.1.56 MYIO_USERNAME=admin MYIO_PASSWORD=... npm run smoke   # read-only check on a real controller
node test/mock_myio.mjs --serve 8111    # standalone mock controller (MOCK_VERSION=3.12.30 for a Due-like one)
npm run sync-docs     # copy ../SD_Files/js/lang/HU/API_REFERENCE.md (the canonical reference) into the package; --check only compares
LIVE_SERVERS='[{"name":"Opta","url":"http://192.168.1.60","username":"admin","password":"..."}]' node test/live_mcp5.mjs   # resources + prompts + HTTP, read-only

Layout: src/api.ts (HTTP client + command dispatch), src/model.ts (JSON → devices/sensors, scales, version gate), src/model_auto.ts (Flow validation / description, script state, traces), src/model_diag.ts (sysdiag, logs, files), src/servers.ts (several controllers, URI slugs), src/toolsets.ts (MYIO_TOOLSETS), src/resources.ts, src/prompts.ts, src/docs.ts (the bundled reference), src/http.ts (Streamable HTTP), src/tools/common.ts (read-back, desired-toggle and command helpers), src/tools/basic.ts + house.ts + config.ts + auto.ts + diag.ts + integr.ts + bus.ts (tool families on McpServer), src/index.ts (config + transports), test/mock_myio.mjs (controller mock built from the real d_sens_out.json sample, with an in-memory file system, Flow and Script engines), test/mcp.test.mjs, test/house.test.mjs, test/config.test.mjs, test/auto.test.mjs, test/integr.test.mjs, test/mcp5.test.mjs (resources, prompts, toolsets, annotations, HTTP); test/live_write.mjs, test/live_config.mjs, test/live_auto.mjs and test/live_integr.mjs are restoring live tests for a BENCH controller only; test/live_mcp5.mjs only reads. node test/call.mjs <tool> '<json>' ... calls tools by hand.

Rules the server follows (from the API reference, chapter 12)

1. One request at a time, Connection: close, no polling faster than 1 s - the controller has 3 listen sockets.
2. Commands go as POST /info.json body (the GET /command: path does not URL-decode), max 1024 bytes.
3. The command reply is an HTML/JSON acknowledgement, not the new state: read sens_out.json back.
4. JSON keys may be missing (permission filtering): never rely on a fixed key set.
5. Toggle-type config commands (relaysInvert=<id> ...) invert a flag - read first, send only on change.
6. Fixed point: temperature ×100, humidity/usens/SDM U,I ×10, thresholds ×10, PCA/FET level raw 0..255.

License

MIT