Hubitat-local-MCP-server: Instructions file for Codex

AGENTS.md

Conventions for AI coding agents working on this repo (OpenAI Codex, Cursor, Aider, Windsurf, Zed, etc.). Claude Code reads CLAUDE.md, which is kept byte-identical to this file — the PR Guard CI workflow flags drift. AGENTS.md is the source of truth. Edit it, then cp AGENTS.md CLAUDE.md before committing. (GitHub Copilot uses .github/copilot-instructions.md; .gemini/styleguide.md drove Gemini Code Assist's reviews — that bot is sunset and disabled, its replacement TBD.)

This file is for AI agents. Human contributors follow .github/pull_request_template.md and .gemini/styleguide.md.

Commands

./gradlew test                     # full Spock suite (~1 min)
./gradlew test --tests "<spec>"    # single spec
python tests/sandbox_lint.py       # Groovy sandbox lint

Run both before pushing. CI runs the same.

Code style

Hubitat Groovy sandbox (hubitat-mcp-server.groovy, hubitat-mcp-rule.groovy) blocks several JVM features the runtime would otherwise expose. Highlights — see tests/sandbox_lint.py for the full set:

• Eval.*, GroovyShell, Class.forName, Runtime.exec, new Thread, new File / java.io.File — not allowed
• getClass() — reflection blocked
• log.isDebugEnabled() — not exposed
• Date.format(String, Locale) — only the no-Locale overload works
• Filesystem only via the hub File Manager API (/hub/fileManager); MCP-tool surface is list_files / read_file / write_file / delete_file

Use atomicState for thread-safe persistence, state for UI/counters. Compare device IDs as strings (.toString()).

Comments: only when the WHY is non-obvious. No multi-paragraph docblocks. Don't reference the current PR/issue/caller.

Tool design rules

These rules apply to every MCP tool added or renamed. Cached MCP clients refresh their tool list on update — no deprecation aliases are shipped.

Tool naming

• Universal service prefix. Every MCP tool name begins with hub_. Anthropic's verified guidance: prefix-namespacing tools by service has "non-trivial effects on our tool-use evaluations" — writing-tools-for-agents (2025-09-11). Example: hub_list_devices, hub_create_room, hub_call_device_command.
• Verb-noun order. After the hub_ prefix, the name reads verb-noun. Verbs are drawn from the strict vocabulary table below. Nouns are the most natural English for the entity in context (drop redundant qualifiers — e.g., rule is preferred over rm_rule where context disambiguates).
• Gateway verbs — manage_ (write-bearing) and read_ (pure-read). A gateway's verb encodes whether it can mutate. manage_ names any gateway that contains at least one write tool, whether mixed read+write or write-only (e.g., hub_manage_rooms, hub_manage_code, hub_manage_destructive_ops). read_ names a gateway whose every sub-tool is read-only (e.g., hub_read_apps_code, hub_read_diagnostics). This lets an AI consumer enable the hub_read_* gateways for safe read-only access while gating every write-bearing hub_manage_* gateway behind a write permission. manage_ MAY also be used by a flat-only tool — one that never sits behind any gateway and is always kept top-level on tools/list — even though it is not itself a gateway. The canonical case is a flat tool that action-dispatches a small set (≤4) of verbs on a single noun (current example: hub_manage_virtual_device with action: "create"/"delete"). Don't introduce more flat manage_ tools without explicit maintainer sign-off. A gateway read_ prefix is distinct from the file-manager leaf tools hub_read_file/hub_write_file (see the verb table) — those keep their own read/write verbs; the noun (file vs a gateway domain) disambiguates.
• Multi-gateway membership. A tool MAY appear under more than one gateway when both gateway domains apply.
• Gateway read/write split. A read-only tool MUST be reachable from a hub_read_* gateway (or be a flat top-level tool) — it may never be unique to a hub_manage_* gateway. A hub_manage_* gateway MAY be mixed (carry its read tools too, for workflow cohesion) as long as those reads are also surfaced in a hub_read_* gateway via multi-gateway membership (same tool listed in both; no code duplication). This guarantees an AI consumer can reach every read through a pure-read surface while disabling every write-bearing manage_ gateway. Pure-read gateways enable cleaner per-gateway disable in LLM client settings and clearer mental models for AI consumers.
• Hard rename, no aliases. Non-conforming tools are renamed in lockstep when the convention requires it. The expectation: MCP clients refresh their cached tool list on server update. No deprecation aliases are shipped.