adguardctrl AGENTS.md

Repository Guidance

Definition of Done

Before reporting any code change as complete, run:

./scripts/verify

It runs npm run typecheck, npm test, and npm run build. Report the actual results, paste failures verbatim, and never claim success you did not observe.

Project Shape

• TypeScript MCP server for AdGuard Home and AdGuardHome Sync. It exposes 33 tools across read, safe-write, and destructive tiers.
• mcp-server.ts is the stdio MCP entry point. index.ts is the OpenClaw plugin entry point. Both must register tools through buildAllTools() in src/tools/index.ts.
• Tool implementations live one per file under src/tools/. When adding or removing a tool, update the explicit import/export list in src/tools/index.ts; it is the canonical registration list.

Hard Prohibitions

• A pre-push hook exists (hooks/pre-push, wired via core.hooksPath). Never push with --no-verify. If the hook blocks, fix the flagged content or add the documented inline allow tag, then push normally.
• Never weaken, skip, or delete failing tests, and never weaken or remove the tier gates (assertConfirmedWrite, assertDestructive) to make something pass. Fix the code instead.
• Never invent npm scripts, tool names, endpoints, or API facts. Verify against package.json, src/tools/index.ts, and the code before citing them.
• When blocked, report the exact blocker (command, full error output) and stop. Do not work around it silently.

Safety Rules: Tier Gates

• Adding or editing a Tier-2 write tool: it must call assertConfirmedWrite(raw, NAME) before any network request. Tier-3 destructive tools must call assertDestructive(raw, NAME) before any network request. Reads need no gate.
• Building a request body: never forward instance, confirm, destructive, or future gate-only fields to AdGuard Home request bodies. Strip them first.
• Touching credentials: keep credential handling in src/security.ts and register any derived secret forms, especially Basic auth header values, before serving tools.