Claude integration: MCP server with render_page images, skill, JSON CLI

- nxhmi.mcp_server: dependency-free stdio MCP server, 14 tools; readable
  values in and out; render_page returns a PNG image
- .mcp.json for Claude Code, .claude/skills/nextion-hmi/SKILL.md
- CLI: info --json, schema <kind>
- fix: project.add_page(h=...) clashed with the page height keyword
- 75 tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-15 15:27:01 +01:00
1 parent b9d7410716
commit 6f8341c66c
9 files changed
+521 -6

No files matched your search

+14 -1
View File
@@ -11,6 +11,10 @@ from .page import Page
def cmd_info(a):
if a.json:
from .mcp_server import t_info
print(json.dumps(t_info(a.hmi), indent=1, ensure_ascii=False))
return
h = HMIFile.load(a.hmi)
t0, t1 = h.table_ok()
print("file table: primary %s, backup %s" % ("ok" if t0 else "BAD", "ok" if t1 else "BAD"))
@@ -140,6 +144,11 @@ def cmd_render(a):
print("wrote", path)
def cmd_schema(a):
from .mcp_server import t_schema
print(json.dumps(t_schema(a.kind), indent=1, ensure_ascii=False))
def cmd_kinds(a):
from . import components
for k in components.kinds():
@@ -159,7 +168,11 @@ def cmd_dump(a):
def main(argv=None):
ap = argparse.ArgumentParser(prog="nxhmi", description="Read, verify and write Nextion Editor .HMI projects")
sub = ap.add_subparsers(dest="cmd", required=True)
s = sub.add_parser("info", help="list entries, pages and checksum status"); s.add_argument("hmi"); s.set_defaults(f=cmd_info)
s = sub.add_parser("info", help="list entries, pages and checksum status"); s.add_argument("hmi")
s.add_argument("--json", action="store_true", help="machine-readable overview (pages, components, fonts, ...)")
s.set_defaults(f=cmd_info)
s = sub.add_parser("schema", help="attributes of a component kind (types, defaults, allowed values)")
s.add_argument("kind"); s.set_defaults(f=cmd_schema)
s = sub.add_parser("verify", help="check every checksum"); s.add_argument("hmi", nargs="+"); s.set_defaults(f=cmd_verify)
s = sub.add_parser("decode", help="HMI -> folder of JSON/text"); s.add_argument("hmi"); s.add_argument("out")
s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true", help="numbers instead of names/colours")
+311
View File
@@ -0,0 +1,311 @@
"""MCP server for Claude (and other MCP clients): work on Nextion .HMI projects through tool calls.
python -m nxhmi.mcp_server # stdio, newline-delimited JSON-RPC 2.0 (Model Context Protocol)
No dependencies (Pillow is only needed for render_page / add_picture / add_font). Every tool takes
the project path and reads/writes the file itself, so calls are independent. ``render_page``
returns a PNG image so the model can look at the result.
"""
from __future__ import annotations
import base64
import io
import json
import os
import sys
import traceback
from . import __version__, components as C, enums, project
from .container import HMIFile
from .page import Page
PROTOCOL = "2025-06-18"
# ----------------------------------------------------------------------------- helpers
def _load(path):
return HMIFile.load(path)
def _pages(h):
out = {}
for e in h.live():
if e.name.endswith(".pa"):
out[Page.parse(h.read(e.name)).name] = e.name
return out
def _page(h, name):
pages = _pages(h)
if name not in pages:
raise ValueError("no page %r; pages: %s" % (name, ", ".join(pages)))
return pages[name], Page.parse(h.read(pages[name]))
def _component_json(c):
ctype = c.get("type")
att = {}
for a in c.attrs():
kind, value = a.decoded()
att[a.name] = enums.to_label(ctype, a.name, kind, value)
ev = {g.name: [r.decode("latin-1") for r in g.records] for g in c.groups if g.name != "att" and g.records}
kind = C.TYPES.get(ctype, {}).get("kind", "type%d" % ctype)
return {"name": c.name, "kind": kind, "attributes": att, "events": ev}
def _coerce(c, name, value):
a = c.attr(name)
if a is None:
raise ValueError("component %r has no attribute %r" % (c.name, name))
kind, _ = a.decoded()
if kind in ("u8", "u16", "u32"):
value = enums.from_label(c.get("type"), name, kind, value)
return value
# ----------------------------------------------------------------------------- tools
def t_info(path):
h = _load(path)
main = project.parse_main(h.read("main.HMI"))
pages = []
for name, entry in _pages(h).items():
p = Page.parse(h.read(entry))
pages.append({"page": name, "entry": entry, "components": [c.name for c in p.components[1:]]})
return {"model": main.get("model", main["model_id"]), "size": project.project_size(h), "pages": pages,
"pictures": sorted(n for n in h.names() if n.endswith(".i")),
"fonts": sorted(n for n in h.names() if n.endswith(".zi")),
"program_s": h.read("Program.s").decode("latin-1")}
def t_get_page(path, page):
_, p = _page(_load(path), page)
return {"page": page, "components": [_component_json(c) for c in p.components]}
def t_set_attributes(path, page, component, attributes):
h = _load(path)
entry, p = _page(h, page)
c = p.component(component)
if c is None:
raise ValueError("no component %r on page %r" % (component, page))
for k, v in attributes.items():
c.set(k, _coerce(c, k, v))
C._fix_ends(c)
h.write(entry, p.pack())
h.save(path)
return _component_json(c)
def t_set_event(path, page, component, event, lines):
h = _load(path)
entry, p = _page(h, page)
c = p.component(component)
if c is None:
raise ValueError("no component %r on page %r" % (component, page))
c.set_event(event, lines)
h.write(entry, p.pack())
h.save(path)
return _component_json(c)
def t_add_component(path, page, kind, name=None, attributes=None, events=None):
h = _load(path)
entry, p = _page(h, page)
tmp = C.make(kind, "tmp", 0)
kw = {k: _coerce(tmp, k, v) for k, v in (attributes or {}).items()}
c = C.add(p, kind, name, events=events or {}, **kw)
h.write(entry, p.pack())
h.save(path)
return _component_json(c)
def t_remove_component(path, page, component):
h = _load(path)
entry, p = _page(h, page)
before = len(p.components)
p.components = [c for c in p.components if c.name != component or c is p.components[0]]
if len(p.components) == before:
raise ValueError("no component %r on page %r" % (component, page))
h.write(entry, p.pack())
h.save(path)
return {"removed": component}
def t_add_page(path, name, attributes=None):
h = _load(path)
w, hh = project.project_size(h)
p = project.add_page(h, name, w=w, h=hh)
for k, v in (attributes or {}).items():
p.components[0].set(k, _coerce(p.components[0], k, v))
entry = _pages(h)[name]
h.write(entry, p.pack())
h.save(path)
return {"page": name, "entry": entry}
def t_new_project(path, model="NX4832T035_011", first_page="page0"):
if os.path.exists(path):
raise ValueError("%s exists; refusing to overwrite" % path)
project.new_project(model, first_page).save(path)
return t_info(path)
def t_add_picture(path, image_path):
h = _load(path)
with open(image_path, "rb") as f:
pid = project.add_picture(h, f.read())
h.save(path)
return {"picture_id": pid}
def t_add_font(path, height, ttf_path=None, encoding="ascii"):
from . import fonts
h = _load(path)
f = fonts.from_ttf(ttf_path, int(height), encoding)
fid = project.add_font(h, f)
h.save(path)
return {"font_id": fid, "name": f.name, "height": f.height}
def t_verify(path):
from . import checksum
import struct
h = _load(path)
problems = []
t0, t1 = h.table_ok()
if not (t0 and t1):
problems.append("file table checksum (primary %s, backup %s)" % (t0, t1))
for e in h.live():
blob = h.read(e.name)
stored = struct.unpack_from("<I", blob, 0)[0]
if e.name.endswith(".pa") and checksum.page_crc(blob) != stored:
problems.append(e.name + " page checksum")
if e.name == "main.HMI" and checksum.main_crc(blob) != stored:
problems.append("main.HMI checksum")
return {"ok": not problems, "problems": problems}
def t_schema(kind):
tpl = C.TYPES[C.KINDS[kind]]
ctype = C.KINDS[kind]
out = []
for name, k, default in tpl["att"]:
item = {"name": name, "type": k, "default": enums.to_label(ctype, name, k, default)}
t = enums.table(ctype, name)
if t:
item["values"] = list(t.values())
if name in enums.COLOR_ATTRS:
item["values"] = "#rrggbb"
out.append(item)
return {"kind": kind, "type": ctype, "events": tpl["events"], "attributes": out,
"intelligent_only": kind in C.INTELLIGENT_ONLY}
def t_kinds():
return {"kinds": C.kinds(), "intelligent_only": C.INTELLIGENT_ONLY}
def t_render_page(path, page):
from .render import Renderer
img = Renderer(_load(path)).render(page)
b = io.BytesIO()
img.save(b, "PNG")
return {"__image__": base64.b64encode(b.getvalue()).decode("ascii"),
"text": "page %r rendered (%dx%d), as Nextion Editor shows it" % (page, img.width, img.height)}
S = {"type": "string"}
OBJ = {"type": "object"}
TOOLS = {
"info": (t_info, "Overview of a project: model, size, pages with their components, pictures, fonts, Program.s.",
{"path": S}, ["path"]),
"get_page": (t_get_page, "All components of a page with readable attribute values and event code.",
{"path": S, "page": S}, ["path", "page"]),
"set_attributes": (t_set_attributes, "Change attributes of one component. Values may be names (e.g. xcen: 'center'), "
"'#rrggbb' colours or numbers. Saves the file.",
{"path": S, "page": S, "component": S, "attributes": OBJ}, ["path", "page", "component", "attributes"]),
"set_event": (t_set_event, "Replace the event code of a component, e.g. event 'codesup' (touch release), "
"'codesdown' (press), 'codesload' / 'codesloadend' (page pre/post-initialize), 'codestimer'.",
{"path": S, "page": S, "component": S, "event": S, "lines": {"type": "array", "items": S}},
["path", "page", "component", "event", "lines"]),
"add_component": (t_add_component, "Add a component of a kind (see list_kinds/schema) with attributes and events.",
{"path": S, "page": S, "kind": S, "name": S, "attributes": OBJ, "events": OBJ},
["path", "page", "kind"]),
"remove_component": (t_remove_component, "Remove a component from a page.",
{"path": S, "page": S, "component": S}, ["path", "page", "component"]),
"add_page": (t_add_page, "Add an empty page (display size of the project).",
{"path": S, "name": S, "attributes": OBJ}, ["path", "name"]),
"new_project": (t_new_project, "Create a new project file (refuses to overwrite). Models: see nxhmi.models.",
{"path": S, "model": S, "first_page": S}, ["path"]),
"add_picture": (t_add_picture, "Add a picture from an image file (png/jpg/bmp); returns its picture id.",
{"path": S, "image_path": S}, ["path", "image_path"]),
"add_font": (t_add_font, "Add a font rasterized from a TrueType file (omit ttf_path for the bundled CC0 font).",
{"path": S, "height": {"type": "integer"}, "ttf_path": S, "encoding": S}, ["path", "height"]),
"verify": (t_verify, "Check every checksum in the project.", {"path": S}, ["path"]),
"list_kinds": (t_kinds, "Component kinds that can be added.", {}, []),
"schema": (t_schema, "Attributes of a component kind: names, types, defaults, allowed values.", {"kind": S}, ["kind"]),
"render_page": (t_render_page, "Render a page to an image exactly as Nextion Editor's canvas shows it -- use it to "
"check your changes visually.", {"path": S, "page": S}, ["path", "page"]),
}
def tool_list():
return [{"name": n, "description": d,
"inputSchema": {"type": "object", "properties": props, "required": req}}
for n, (_, d, props, req) in TOOLS.items()]
def call(name, args):
if name not in TOOLS:
raise ValueError("unknown tool %r" % name)
result = TOOLS[name][0](**(args or {}))
if isinstance(result, dict) and "__image__" in result:
return [{"type": "image", "data": result["__image__"], "mimeType": "image/png"},
{"type": "text", "text": result["text"]}]
return [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}]
def handle(msg):
method, mid = msg.get("method"), msg.get("id")
if mid is None: # notification
return None
try:
if method == "initialize":
res = {"protocolVersion": msg.get("params", {}).get("protocolVersion", PROTOCOL),
"capabilities": {"tools": {}},
"serverInfo": {"name": "openhmi-nx", "version": __version__}}
elif method == "tools/list":
res = {"tools": tool_list()}
elif method == "tools/call":
p = msg.get("params", {})
try:
res = {"content": call(p.get("name"), p.get("arguments"))}
except Exception as e: # tool errors are results, not protocol errors
res = {"content": [{"type": "text", "text": "error: %s" % e}], "isError": True}
elif method == "ping":
res = {}
else:
return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": "method not found"}}
return {"jsonrpc": "2.0", "id": mid, "result": res}
except Exception as e:
return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32603, "message": str(e),
"data": traceback.format_exc()}}
def main():
for line in sys.stdin:
line = line.strip()
if not line:
continue
try:
msg = json.loads(line)
except json.JSONDecodeError:
continue
out = handle(msg)
if out is not None:
sys.stdout.write(json.dumps(out) + "\n")
sys.stdout.flush()
if __name__ == "__main__":
main()
+5 -5
View File
@@ -169,18 +169,18 @@ def main_add_resource(main: bytes, rtype: str, name: str) -> bytes:
return bytes(b)
def add_page(h: HMIFile, name: str, **attrs) -> Page:
def add_page(hmi: HMIFile, name: str, **attrs) -> Page:
"""Add a new empty page to an opened project (next free N.pa) and register it in main.HMI."""
from .components import new_page
used = {Page.parse(h.read(e.name)).name for e in h.live() if e.name.endswith(".pa")}
used = {Page.parse(hmi.read(e.name)).name for e in hmi.live() if e.name.endswith(".pa")}
if name in used:
raise ValueError("page %r exists" % name)
n = 0
while h.find("%d.pa" % n):
while hmi.find("%d.pa" % n):
n += 1
p = new_page(name, **attrs)
h.write("%d.pa" % n, p.pack())
h.write("main.HMI", main_add_resource(h.read("main.HMI"), "pa", "%d.pa" % n))
hmi.write("%d.pa" % n, p.pack())
hmi.write("main.HMI", main_add_resource(hmi.read("main.HMI"), "pa", "%d.pa" % n))
return p