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:
1 parent
b9d7410716
commit
6f8341c66c
9 files changed
+521
-6
No files matched your search
@@ -0,0 +1,46 @@
|
|||||||
|
---
|
||||||
|
name: nextion-hmi
|
||||||
|
description: Create, inspect, edit and render Nextion display projects (.HMI files) without Nextion Editor, using the nxhmi tools in this repo. Use when the user wants to build or change a Nextion screen, page, button, text, slider, picture or font, look at how a page looks, or check an .HMI file.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Working on Nextion .HMI projects
|
||||||
|
|
||||||
|
Prefer the **`nxhmi` MCP tools** (configured in `.mcp.json`); fall back to the CLI
|
||||||
|
(`PYTHONPATH=src python -m nxhmi ...`) or the Python API (`src/nxhmi`) when they are not available.
|
||||||
|
|
||||||
|
## Loop
|
||||||
|
|
||||||
|
1. `info` -- model, display size, pages, components, pictures, fonts.
|
||||||
|
2. `get_page` -- the components of one page with readable values.
|
||||||
|
3. Change things: `set_attributes`, `set_event`, `add_component`, `remove_component`, `add_page`,
|
||||||
|
`add_picture`, `add_font`. Every call saves the file.
|
||||||
|
4. `verify` -- all checksums must be ok.
|
||||||
|
5. `render_page` -- **look at the result** (it matches Nextion Editor's canvas) before telling the
|
||||||
|
user it is done. Fix overlaps, clipped text and wrong colours you see.
|
||||||
|
|
||||||
|
Back up the user's file first (copy it) unless they said not to; edits write in place.
|
||||||
|
|
||||||
|
## Values
|
||||||
|
|
||||||
|
- Attributes accept readable values: `xcen`/`ycen` `left|center|right` / `up|center|down`,
|
||||||
|
`sta` `crop image|solid color|image` (page: `no background|solid color|image`), `style`
|
||||||
|
`flat|border|3D_Down|3D_Up` (+`3D_Auto` for buttons), colours as `#rrggbb` (stored as RGB565,
|
||||||
|
so they snap to the nearest 5/6/5-bit colour). Numbers always work too.
|
||||||
|
- `schema <kind>` lists every attribute of a component kind with defaults and allowed values;
|
||||||
|
`list_kinds` lists the kinds (`button`, `text`, `number`, `slider`, `progress_bar`, ...).
|
||||||
|
- Coordinates: `x`, `y`, `w`, `h` in pixels; `endx`/`endy` are updated automatically.
|
||||||
|
- Text needs a font: `font` is a font id. A new project has **no fonts** -- call `add_font`
|
||||||
|
first (height in px; no TrueType path = bundled CC0 font). `txt_maxl` must be >= the text length.
|
||||||
|
- Pictures: `add_picture` returns an id for `pic` / `picc` (crop) / `pic2` etc. Basic-series
|
||||||
|
displays only (Intelligent compressed pictures are not supported yet).
|
||||||
|
- Event code is Nextion script, one line per list item, e.g. `["page settings"]`,
|
||||||
|
`["n0.val++", "t0.txt=\"hi\""]`. Events: `codesdown` (press), `codesup` (release),
|
||||||
|
`codesload` / `codesloadend` (page pre/post-initialize), `codesunload`, `codestimer`, `codesslide`.
|
||||||
|
- `objname` must be unique per page; `add_component` picks `b0`, `t1`, ... if no name is given.
|
||||||
|
|
||||||
|
## Limits (see docs/COVERAGE.md)
|
||||||
|
|
||||||
|
- Writes projects for Nextion Editor 1.68.2; the user still compiles/uploads the `.tft` with the
|
||||||
|
Editor (or Nexus for uploading). nxhmi cannot compile `.tft` files yet.
|
||||||
|
- Rendering: radio buttons are ~95 % exact, QR codes are a placeholder, Intelligent-only
|
||||||
|
components are not drawn.
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"nxhmi": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["-m", "nxhmi.mcp_server"],
|
||||||
|
"env": {"PYTHONPATH": "src"}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -20,7 +20,10 @@ src/nxhmi/
|
|||||||
render.py page renderer matching the Editor canvas
|
render.py page renderer matching the Editor canvas
|
||||||
tft.py .tft research helpers (layout table, same-length trailer patch)
|
tft.py .tft research helpers (layout table, same-length trailer patch)
|
||||||
cli.py python -m nxhmi ...
|
cli.py python -m nxhmi ...
|
||||||
|
mcp_server.py MCP server (stdio JSON-RPC, no deps) -- tools for Claude incl. render_page images
|
||||||
examples/make_demo.py builds demo/ (demo.HMI, decoded/, render/)
|
examples/make_demo.py builds demo/ (demo.HMI, decoded/, render/)
|
||||||
|
.mcp.json registers the MCP server for Claude Code in this repo
|
||||||
|
.claude/skills/nextion-hmi/SKILL.md how to use the tools on a user's project (keep in sync with mcp_server.py)
|
||||||
tests/ unittest suite; fixtures/demo_editor_saved.HMI = the demo re-saved by the Editor
|
tests/ unittest suite; fixtures/demo_editor_saved.HMI = the demo re-saved by the Editor
|
||||||
tools/ template generator
|
tools/ template generator
|
||||||
docs/ FORMAT.md (spec), RENDER.md, COVERAGE.md, NOTES.md (open points, what was tried)
|
docs/ FORMAT.md (spec), RENDER.md, COVERAGE.md, NOTES.md (open points, what was tried)
|
||||||
@@ -56,5 +59,6 @@ new build writes different bytes, document the difference in docs/FORMAT.md per
|
|||||||
- Every format claim in `docs/FORMAT.md` needs evidence (byte-identical Editor output, or the
|
- Every format claim in `docs/FORMAT.md` needs evidence (byte-identical Editor output, or the
|
||||||
Editor accepting a file we wrote). Mark guesses as **OPEN**.
|
Editor accepting a file we wrote). Mark guesses as **OPEN**.
|
||||||
- Keep `docs/COVERAGE.md` and the README coverage table current when something is added.
|
- Keep `docs/COVERAGE.md` and the README coverage table current when something is added.
|
||||||
|
- New user-facing features get an MCP tool (with a test in `tests/test_mcp.py`) and a line in the skill.
|
||||||
- Writers must stay byte-identical to the Editor where we have samples; add a test when a new
|
- Writers must stay byte-identical to the Editor where we have samples; add a test when a new
|
||||||
rule is learned (see `tests/test_render.py` for the style: one rule, one measured expectation).
|
rule is learned (see `tests/test_render.py` for the style: one rule, one measured expectation).
|
||||||
@@ -73,6 +73,26 @@ python -m nxhmi render project.HMI pngs/ # one PNG per page
|
|||||||
python -m nxhmi kinds # component kinds for `add`
|
python -m nxhmi kinds # component kinds for `add`
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Use with Claude
|
||||||
|
|
||||||
|
The repo is set up for Claude (Claude Code, Claude Desktop or any MCP client):
|
||||||
|
|
||||||
|
- **MCP server** -- `python -m nxhmi.mcp_server` (stdio, no dependencies). Tools: `info`,
|
||||||
|
`get_page`, `set_attributes`, `set_event`, `add_component`, `remove_component`, `add_page`,
|
||||||
|
`new_project`, `add_picture`, `add_font`, `verify`, `list_kinds`, `schema`, and
|
||||||
|
**`render_page`, which returns the page as an image** so the model can see what it built.
|
||||||
|
Attribute values can be readable names (`"xcen": "center"`, `"bco": "#ff0000"`).
|
||||||
|
`.mcp.json` registers it automatically when Claude Code runs in this repo; elsewhere add:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"mcpServers": {"nxhmi": {"command": "python", "args": ["-m", "nxhmi.mcp_server"],
|
||||||
|
"env": {"PYTHONPATH": "/path/to/openhmi-nx/src"}}}}
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Skill** -- [.claude/skills/nextion-hmi/SKILL.md](.claude/skills/nextion-hmi/SKILL.md): the
|
||||||
|
edit -> verify -> render loop, value names, fonts/pictures, event code, limits.
|
||||||
|
- **Machine-readable CLI** -- `info --json`, `schema <kind>`, `dump --page`.
|
||||||
|
|
||||||
## Python
|
## Python
|
||||||
|
|
||||||
```python
|
```python
|
||||||
|
|||||||
+14
-1
@@ -11,6 +11,10 @@ from .page import Page
|
|||||||
|
|
||||||
|
|
||||||
def cmd_info(a):
|
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)
|
h = HMIFile.load(a.hmi)
|
||||||
t0, t1 = h.table_ok()
|
t0, t1 = h.table_ok()
|
||||||
print("file table: primary %s, backup %s" % ("ok" if t0 else "BAD", "ok" if t1 else "BAD"))
|
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)
|
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):
|
def cmd_kinds(a):
|
||||||
from . import components
|
from . import components
|
||||||
for k in components.kinds():
|
for k in components.kinds():
|
||||||
@@ -159,7 +168,11 @@ def cmd_dump(a):
|
|||||||
def main(argv=None):
|
def main(argv=None):
|
||||||
ap = argparse.ArgumentParser(prog="nxhmi", description="Read, verify and write Nextion Editor .HMI projects")
|
ap = argparse.ArgumentParser(prog="nxhmi", description="Read, verify and write Nextion Editor .HMI projects")
|
||||||
sub = ap.add_subparsers(dest="cmd", required=True)
|
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("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 = 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")
|
s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true", help="numbers instead of names/colours")
|
||||||
|
|||||||
@@ -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()
|
||||||
@@ -169,18 +169,18 @@ def main_add_resource(main: bytes, rtype: str, name: str) -> bytes:
|
|||||||
return bytes(b)
|
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."""
|
"""Add a new empty page to an opened project (next free N.pa) and register it in main.HMI."""
|
||||||
from .components import new_page
|
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:
|
if name in used:
|
||||||
raise ValueError("page %r exists" % name)
|
raise ValueError("page %r exists" % name)
|
||||||
n = 0
|
n = 0
|
||||||
while h.find("%d.pa" % n):
|
while hmi.find("%d.pa" % n):
|
||||||
n += 1
|
n += 1
|
||||||
p = new_page(name, **attrs)
|
p = new_page(name, **attrs)
|
||||||
h.write("%d.pa" % n, p.pack())
|
hmi.write("%d.pa" % n, p.pack())
|
||||||
h.write("main.HMI", main_add_resource(h.read("main.HMI"), "pa", "%d.pa" % n))
|
hmi.write("main.HMI", main_add_resource(hmi.read("main.HMI"), "pa", "%d.pa" % n))
|
||||||
return p
|
return p
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,105 @@
|
|||||||
|
"""MCP server: protocol round trip over stdio and every tool."""
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import shutil
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
import tempfile
|
||||||
|
import unittest
|
||||||
|
|
||||||
|
from helpers import FIXTURE, HAVE_PIL, ROOT
|
||||||
|
|
||||||
|
from nxhmi import mcp_server as M
|
||||||
|
|
||||||
|
|
||||||
|
class Protocol(unittest.TestCase):
|
||||||
|
def test_stdio_session(self):
|
||||||
|
env = dict(os.environ, PYTHONPATH=os.path.join(ROOT, "src"))
|
||||||
|
msgs = [{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}},
|
||||||
|
{"jsonrpc": "2.0", "method": "notifications/initialized"},
|
||||||
|
{"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
|
||||||
|
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "list_kinds", "arguments": {}}},
|
||||||
|
{"jsonrpc": "2.0", "id": 4, "method": "nope"}]
|
||||||
|
p = subprocess.run([sys.executable, "-m", "nxhmi.mcp_server"], input="\n".join(json.dumps(m) for m in msgs) + "\n",
|
||||||
|
capture_output=True, text=True, env=env, timeout=60)
|
||||||
|
replies = [json.loads(l) for l in p.stdout.splitlines()]
|
||||||
|
self.assertEqual([r["id"] for r in replies], [1, 2, 3, 4])
|
||||||
|
self.assertEqual(replies[0]["result"]["serverInfo"]["name"], "openhmi-nx")
|
||||||
|
self.assertIn("render_page", [t["name"] for t in replies[1]["result"]["tools"]])
|
||||||
|
self.assertIn("button", json.loads(replies[2]["result"]["content"][0]["text"])["kinds"])
|
||||||
|
self.assertEqual(replies[3]["error"]["code"], -32601)
|
||||||
|
|
||||||
|
|
||||||
|
class Tools(unittest.TestCase):
|
||||||
|
def setUp(self):
|
||||||
|
self.tmp = tempfile.mkdtemp()
|
||||||
|
self.hmi = os.path.join(self.tmp, "p.HMI")
|
||||||
|
shutil.copy(FIXTURE, self.hmi)
|
||||||
|
|
||||||
|
def tearDown(self):
|
||||||
|
shutil.rmtree(self.tmp)
|
||||||
|
|
||||||
|
def call(self, tool, **args):
|
||||||
|
r = M.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": tool, "arguments": args}})
|
||||||
|
res = r["result"]
|
||||||
|
if res.get("isError"):
|
||||||
|
raise AssertionError(res["content"][0]["text"])
|
||||||
|
return res["content"]
|
||||||
|
|
||||||
|
def j(self, tool, **args):
|
||||||
|
return json.loads(self.call(tool, **args)[0]["text"])
|
||||||
|
|
||||||
|
def test_info_and_page(self):
|
||||||
|
info = self.j("info", path=self.hmi)
|
||||||
|
self.assertEqual([p["page"] for p in info["pages"]], ["home", "controls", "gallery"])
|
||||||
|
page = self.j("get_page", path=self.hmi, page="home")
|
||||||
|
title = next(c for c in page["components"] if c["name"] == "title")
|
||||||
|
self.assertEqual(title["kind"], "text")
|
||||||
|
self.assertEqual(title["attributes"]["xcen"], "left")
|
||||||
|
|
||||||
|
def test_edit_cycle(self):
|
||||||
|
r = self.j("set_attributes", path=self.hmi, page="home", component="title",
|
||||||
|
attributes={"txt": "edited", "xcen": "center", "pco": "#ff0000", "x": 20})
|
||||||
|
self.assertEqual((r["attributes"]["txt"], r["attributes"]["xcen"], r["attributes"]["pco"]), ("edited", "center", "#ff0000"))
|
||||||
|
self.assertEqual(r["attributes"]["endx"], 20 + r["attributes"]["w"] - 1)
|
||||||
|
self.j("set_event", path=self.hmi, page="home", component="title", event="codesup", lines=["page 1"])
|
||||||
|
c = self.j("add_component", path=self.hmi, page="home", kind="button", name="bNew",
|
||||||
|
attributes={"x": 1, "y": 2, "w": 40, "h": 20, "txt": "go", "style": "3D_Auto"},
|
||||||
|
events={"codesup": ["page 0"]})
|
||||||
|
self.assertEqual(c["events"], {"codesup": ["page 0"]})
|
||||||
|
self.j("remove_component", path=self.hmi, page="home", component="bNew")
|
||||||
|
self.j("add_page", path=self.hmi, name="extra", attributes={"bco": "#000000"})
|
||||||
|
self.assertTrue(self.j("verify", path=self.hmi)["ok"])
|
||||||
|
|
||||||
|
def test_errors_are_tool_results(self):
|
||||||
|
r = M.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
|
||||||
|
"params": {"name": "get_page", "arguments": {"path": self.hmi, "page": "missing"}}})
|
||||||
|
self.assertTrue(r["result"]["isError"])
|
||||||
|
self.assertIn("pages: home", r["result"]["content"][0]["text"])
|
||||||
|
|
||||||
|
def test_schema(self):
|
||||||
|
s = self.j("schema", kind="text")
|
||||||
|
xcen = next(a for a in s["attributes"] if a["name"] == "xcen")
|
||||||
|
self.assertEqual(xcen["values"], ["left", "center", "right"])
|
||||||
|
|
||||||
|
def test_new_project_refuses_overwrite(self):
|
||||||
|
p = os.path.join(self.tmp, "new.HMI")
|
||||||
|
self.assertEqual(self.j("new_project", path=p)["pages"][0]["page"], "page0")
|
||||||
|
with self.assertRaises(AssertionError):
|
||||||
|
self.j("new_project", path=p)
|
||||||
|
|
||||||
|
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
|
||||||
|
def test_render_and_media(self):
|
||||||
|
content = self.call("render_page", path=self.hmi, page="home")
|
||||||
|
self.assertEqual(content[0]["type"], "image")
|
||||||
|
self.assertEqual(content[0]["mimeType"], "image/png")
|
||||||
|
from PIL import Image
|
||||||
|
png = os.path.join(self.tmp, "i.png")
|
||||||
|
Image.new("RGB", (4, 4), (9, 9, 9)).save(png)
|
||||||
|
self.assertEqual(self.j("add_picture", path=self.hmi, image_path=png)["picture_id"], 6)
|
||||||
|
self.assertEqual(self.j("add_font", path=self.hmi, height=12)["font_id"], 2)
|
||||||
|
self.assertTrue(self.j("verify", path=self.hmi)["ok"])
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
unittest.main()
|
||||||
@@ -60,6 +60,13 @@ class Cli(unittest.TestCase):
|
|||||||
self.assertEqual(self.run_cli("verify", self.hmi)[0], 0)
|
self.assertEqual(self.run_cli("verify", self.hmi)[0], 0)
|
||||||
self.assertIn('"title"', self.run_cli("dump", self.hmi, "--page", "home")[1])
|
self.assertIn('"title"', self.run_cli("dump", self.hmi, "--page", "home")[1])
|
||||||
|
|
||||||
|
def test_json_info_and_schema(self):
|
||||||
|
import json
|
||||||
|
info = json.loads(self.run_cli("info", self.hmi, "--json")[1])
|
||||||
|
self.assertEqual(info["size"], [480, 320])
|
||||||
|
sch = json.loads(self.run_cli("schema", "slider")[1])
|
||||||
|
self.assertIn("vertical", next(x for x in sch["attributes"] if x["name"] == "mode")["values"])
|
||||||
|
|
||||||
def test_decode_encode(self):
|
def test_decode_encode(self):
|
||||||
d = os.path.join(self.tmp, "dec")
|
d = os.path.join(self.tmp, "dec")
|
||||||
self.run_cli("decode", self.hmi, d)
|
self.run_cli("decode", self.hmi, d)
|
||||||
|
|||||||
Reference in new issue
Block a user