lattice-mcp 1.1.0 → 1.1.2

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 > `lattice-mcp` is the **Model Context Protocol server for Lattice**, the container
 > orchestration platform that runs every `appleby.cloud` service. It exposes the
-> `lattice-api` admin surface to Claude Code as **125 typed tools** — workers, stacks,
+> `lattice-api` admin surface to Claude Code as **126 typed tools** — workers, stacks,
 > containers, deployments, databases, registries, networks, volumes and instance config.
 > This file orients any agent/worker before touching code in this repo.
 >
@@ -32,8 +32,9 @@ Those live in [`lattice-api`](https://github.com/aidenappl/lattice-api) and
 - **Runtime:** Node ≥18 (needs global `fetch` and `AbortSignal.timeout`). `"type": "module"` —
   ESM only, top-level `await` is used at the bottom of `index.js`.
 - **`@modelcontextprotocol/sdk` ^1.29.0** — `McpServer` + `StdioServerTransport`.
-- **`zod`** — argument schemas. Supplied transitively by the MCP SDK; it is *not* a declared
-  dependency, which is a latent fragility (see Rules & guardrails).
+- **`zod` ^4.4.3** — argument schemas. Declared explicitly as of **1.1.1** (it was previously
+  only resolved transitively through the MCP SDK, a latent fragility); the range matches the
+  version the SDK resolves.
 - No build step, no bundler, no tests, no lint config. `node --check index.js` is the only
   static gate.
 
@@ -41,7 +42,7 @@ Those live in [`lattice-api`](https://github.com/aidenappl/lattice-api) and
 
 | Path | Role |
 |------|------|
-| `index.js` | Everything: `--setup` flow, config read, `api()` HTTP helper, `text()`/`body()` helpers, all 125 `server.tool(...)` registrations, transport connect. |
+| `index.js` | Everything: `--setup` flow, config read, `api()` HTTP helper, `text()`/`body()` helpers, all 126 `server.tool(...)` registrations, transport connect. |
 | `package.json` | npm metadata. `bin.lattice-mcp` → `index.js`, so `npx lattice-mcp` works. |
 | `README.md` | User-facing setup + full tool table. |
 | `AGENTS.md` | This file. |
@@ -90,9 +91,12 @@ and supply the real token.
   the noun (`lattice_list_database_instances`). The prefix is what disambiguates these from
   `monitor_*` and `forta_*` tools in a shared client.
 - **`api(method, path, params, body)`** — `params` become query string entries (undefined/null
-  are dropped), `body` is JSON-encoded. Errors are swallowed and returned as
-  `{success:false, error_message}` so a network failure surfaces as tool output rather than a
-  transport crash.
+  are dropped), `body` is JSON-encoded. Failures are returned as tool output, never thrown, so
+  they surface to the agent rather than crashing the transport. A network-level failure returns
+  `{success:false, error_message: "API request failed: …"}`; a response that arrives but is not
+  JSON (e.g. a 502/504 HTML page from the TLS proxy) returns
+  `{success:false, error_code: <http status>, error_message: "API returned a non-JSON response …"}`
+  with a truncated body — bodies are never logged, only returned, since they can carry secrets.
 - **`body(obj)`** strips `undefined` keys. **Always use it on PUT/PATCH tools.** The API treats
   a present-but-null field as an explicit clear, so forwarding raw `{...fields}` on an update
   would wipe every field the caller didn't pass.
@@ -122,28 +126,48 @@ exits immediately if either is missing. In practice these come from the `env` bl
 
 **Tool groups**, in file order:
 
+The counts below sum to **126**, matching the header and `grep -c 'server.tool(' index.js`. The
+first rows are the original, pre-`1.1.0` tools (registered top-of-file with no banner comment);
+every bolded row corresponds to a `// ───` banner group and matches its exact in-file name.
+
 | Group | Tools | Notes |
 |-------|-------|-------|
-| Overview & health | 2 | `lattice_overview`, `lattice_health` |
+| Overview & health | 3 | `lattice_overview`, `lattice_health`, `lattice_get_version` |
 | Workers | 3 + 4 actions | list/get/metrics; reboot, upgrade, stop-all, start-all |
-| Stacks | 2 + 4 actions | list/get; deploy, restart, stop, start, update |
-| Containers | 5 + 8 actions | get/list/logs/lifecycle/metrics; start, stop, restart, kill, pause, unpause, remove, recreate |
-| Deployments | 4 | list/get/logs, rollback, approve |
-| Audit & API tokens | 4 | audit log; token list/create/delete |
-| **Database instances** | **11** | CRUD, `lattice_database_action`, credentials, snapshots, restore |
-| **Backup destinations** | **6** | CRUD + test |
-| **Registries** | **8** | CRUD, test, test-inline, repositories, tags |
-| **Discovery & diagnostics** | **7** | search, anomalies, fleet-metrics, versions, refresh-versions, container metrics, self |
-| **Stacks — compose & tokens** | **13** | create/delete, compose update/sync/import, export/import, save-template, deploy tokens |
-| **Containers — definition CRUD** | **3** | create/update/delete definitions |
-| **Workers — resources** | **16** | worker CRUD, tokens, volumes, networks, force-remove |
-| **Global env vars / templates / webhooks** | **12** | |
-| **Users & instance config** | **12** | users, SSO, SMTP, notification prefs |
+| Stacks | 2 + 5 actions | list/get; deploy, restart, stop, start, update |
+| Containers | 4 + 8 actions | list/get/logs/lifecycle; start, stop, restart, kill, pause, unpause, remove, recreate. (`lattice_get_container_metrics` is *not* here — it lives under **Discovery & diagnostics**.) |
+| Deployments | 4 | list/get/logs, rollback. (`lattice_approve_deployment` is *not* here — it lives under **Stacks — lifecycle, compose & deploy tokens**.) |
+| Instance self-update | 2 | `lattice_update_api`, `lattice_update_web` — tell the API/web container to pull its latest image and redeploy itself |
+| Audit & API tokens | 4 | `lattice_get_audit_log`; API token list/create/delete |
+| **Database instances** | **11** | CRUD, `lattice_database_action` (start/stop/restart/remove enum), `lattice_get_database_credentials`, snapshot list/create/restore/delete |
+| **Backup destinations** | **6** | list/get/create/update/delete + `lattice_test_backup_destination` |
+| **Registries** | **8** | list/create/update/delete, `lattice_test_registry`, `lattice_test_registry_inline`, `lattice_list_registry_repositories`, `lattice_list_registry_tags` |
+| **Discovery & diagnostics** | **7** | `lattice_search`, `lattice_get_anomalies`, `lattice_get_fleet_metrics`, `lattice_get_versions`, `lattice_refresh_versions`, `lattice_get_container_metrics`, `lattice_get_self` |
+| **Stacks — lifecycle, compose & deploy tokens** | **13** | create/delete, `lattice_get_stack_containers`, compose update/sync/import, export/import, `lattice_save_stack_as_template`, deploy-token list/create/delete, `lattice_approve_deployment` |
+| **Containers — definition CRUD** | **3** | `lattice_create_container`, `lattice_update_container`, `lattice_delete_container` |
+| **Workers — registration, tokens, volumes, networks** | **16** | worker create/update/delete, `lattice_get_worker_container_stats`, worker-token ×3, volume ×3, worker-network ×3, `lattice_list_all_networks`, `lattice_delete_network`, `lattice_force_remove_container` |
+| **Global env vars, templates, webhooks** | **12** | env-var CRUD (4), template list/create/delete (3), webhook list/create/update/delete/test (5) |
+| **Users & instance configuration** | **11** | user CRUD (4); SSO get/update (2); SMTP get/update/test (3); notification-prefs get/update (2) |
 
 Bolded groups were added in **1.1.0**, closing a gap where the MCP had drifted roughly two
 months behind `lattice-api` — database instances shipped in the API in May 2026 and were
 entirely unreachable from the MCP until then.
 
+**1.1.1** is a bug-fix release (no tool count change). It corrects three request-shape/route bugs
+verified against `lattice-api` handlers: `lattice_get_self` now calls `GET /auth/self` (the old
+`GET /admin/self` route never existed and always 404'd — the endpoint is `HandleAuthSelf` on the
+bearer-authed `/auth` subrouter); `lattice_force_remove_container` now sends `{container_name}` in
+the JSON body (`HandleForceRemoveContainer` reads it there, not from query params, so the old call
+always 400'd); and `lattice_test_backup_destination` now marks `worker_id` as **required** (a query
+param the handler 400s without — the test dispatches over the worker's WebSocket). It also hardens
+`api()` against non-JSON responses (see *How code is written here*) and declares `zod` explicitly.
+
+**1.1.2** adds `lattice_get_version` (`GET /version`, so agents can read the deployed API version
+for deploy-drift checks without shelling out to `curl`), and widens two read tools to pass filter
+params the handlers already accept but the tools were dropping: `lattice_get_audit_log` gains
+`user_id` / `action` / `resource_type` / `offset` (answer "who deleted stack X" server-side instead
+of scanning 50 rows), and `lattice_get_container_logs` gains `offset` / `worker_id`. Tool count 125 → 126.
+
 **Consolidations.** Where `lattice-api` exposes several paths served by one handler, this repo
 exposes one tool with an enum rather than N tools. `lattice_database_action` covers
 `/start`, `/stop`, `/restart` and `/remove`. Worker actions are the historical exception — they
@@ -187,9 +211,10 @@ predate this convention and remain separate tools.
 - **Do not break tool names.** They are a public contract: renaming one silently breaks any
   saved workflow or prompt that referenced it. Add a new tool and deprecate in the description
   instead.
-- **`zod` is used but not declared** in `package.json` — it resolves transitively through the
-  MCP SDK. If the SDK ever drops or hoists it differently, every tool schema breaks at startup.
-  Adding it as an explicit dependency is the correct fix; do it in a standalone change.
+- **`zod` is declared explicitly** in `package.json` (`^4.4.3`) as of **1.1.1**. It used to
+  resolve only transitively through the MCP SDK, which meant a SDK change that dropped or hoisted
+  it differently would break every tool schema at startup. Keep the declared range aligned with
+  the version the SDK actually resolves (check `package-lock.json`).
 - **Keep destructive descriptions honest.** If a tool destroys data, the description must say so
   and name the safer alternative.
 - Publishing is outward-facing and effectively irreversible (npm unpublish is restricted after

package/README.md

@@ -1,18 +1,55 @@
 # lattice-mcp
 
-MCP server for the [Lattice](https://github.com/aidenappl/lattice-api) container orchestration platform. Gives Claude Code direct access to manage workers, stacks, containers, and deployments.
+Model Context Protocol server for [Lattice](https://github.com/aidenappl/lattice-api), the container orchestration platform that runs every `appleby.cloud` service. Gives Claude Code direct, typed access to workers, stacks, containers, deployments, databases, registries, networks, volumes and instance configuration.
 
-## Quick Start
+> **appleby.cloud platform** · MCP server · published to npm as `lattice-mcp` · consumed via `npx -y lattice-mcp`
+
+---
+
+## Overview
+
+`lattice-mcp` is a single-file Node ESM program (`index.js`) that speaks MCP over stdio and translates tool calls into HTTP requests against the `lattice-api` admin surface. It exposes **126 typed tools** and holds no business logic, caching or state of its own — every behaviour (pagination, validation, side effects) comes from `lattice-api`.
+
+Once configured, ask Claude Code things like:
+
+- "What's the status of all stacks?"
+- "Show me logs for the forta-api container"
+- "Which containers are unhealthy?" (`lattice_get_anomalies` is the best first call)
+- "Deploy stack 5" / "Rollback the last deployment on stack 12"
+- "What image tags can I deploy from the registry?"
+
+## Role in the appleby.cloud ecosystem
+
+| Repo | Relationship |
+|------|--------------|
+| [`lattice-api`](https://github.com/aidenappl/lattice-api) | The API this wraps — its route table is the source of truth for tool coverage. |
+| [`lattice-web`](https://github.com/aidenappl/lattice-web) | Next.js dashboard over the same API. |
+| [`lattice-runner`](https://github.com/aidenappl/lattice-runner) | Agent on each worker VM; WebSocket back to `lattice-api`. |
+| `monitor-mcp` / `forta-mcp` / `keyring-mcp` / `openbucket-mcp` | Sibling MCP servers, same single-file structure. |
+
+## Tech stack
+
+- **Node ≥18** (needs global `fetch` and `AbortSignal.timeout`), ESM (`"type": "module"`).
+- **`@modelcontextprotocol/sdk` ^1.29.0** — `McpServer` + `StdioServerTransport`.
+- **`zod` ^4.4.3** for argument schemas (a declared dependency as of 1.1.1).
+- No build step, no bundler. `node --check index.js` is the only static gate.
+
+## Getting started
+
+### Prerequisites
+
+- Node ≥18.
+- A Lattice API URL and API token. Generate a token from the Lattice web dashboard under **Settings > API Tokens**.
+
+### Setup
+
+Quickest — interactive setup writes the `lattice` block into `~/.mcp.json`:
 
 ```bash
 npx lattice-mcp --setup
 ```
 
-This prompts for your Lattice API URL and API token, writes the config to `~/.mcp.json`, and you're ready to go. Restart Claude Code after setup.
-
-## Manual Setup
-
-Add to `~/.mcp.json`:
+Or configure it manually in `~/.mcp.json`:
 
 ```json
 {
@@ -29,21 +66,42 @@ Add to `~/.mcp.json`:
 }
 ```
 
-Generate an API token from the Lattice web dashboard under **Settings > API Tokens**.
+Restart Claude Code after setup so the new server and tools are picked up.
+
+### Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `LATTICE_API_URL` | Yes | Lattice API base URL |
+| `LATTICE_API_TOKEN` | Yes | Bearer token for authentication (sent on every request) |
+
+## Development
+
+| Command | What it does |
+|---------|--------------|
+| `node index.js --setup` | Interactive setup — writes the `lattice` block into `~/.mcp.json` |
+| `npm install` | Install dependencies (not vendored) |
+| `node --check index.js` | Syntax gate — the only static check that exists |
+| `LATTICE_API_URL=… LATTICE_API_TOKEN=… node index.js` | Run the server on stdio |
+| `grep -c 'server.tool(' index.js` | Confirm the tool count (should be 126) |
+| `npm publish` | Publish to npm — **this is deployment** (requires 2FA passkey from an interactive terminal) |
 
 ## Tools
 
-### Overview & Health
+All 126 tools, grouped as they appear in `index.js`. ⚠️ marks destructive tools; their descriptions state the blast radius.
+
+### Overview & health
 | Tool | Description |
 |------|-------------|
-| `lattice_overview` | Fleet overview — worker counts, stack counts, failed stacks, CPU/memory |
+| `lattice_overview` | Fleet overview — worker/stack/container counts, failed stacks, CPU/memory |
 | `lattice_health` | API health and database connectivity |
+| `lattice_get_version` | Deployed lattice-api version string — check deploy drift against GitHub tags |
 
 ### Workers
 | Tool | Description |
 |------|-------------|
-| `lattice_list_workers` | List workers with status, IP, versions |
-| `lattice_get_worker` | Detailed worker info |
+| `lattice_list_workers` | List workers with status, IP, versions, heartbeat |
+| `lattice_get_worker` | Detailed worker info including metrics |
 | `lattice_get_worker_metrics` | CPU, memory, disk, network metrics |
 | `lattice_reboot_worker` | Reboot a worker machine |
 | `lattice_upgrade_worker` | Upgrade worker runner to latest |
@@ -55,18 +113,18 @@ Generate an API token from the Lattice web dashboard under **Settings > API Toke
 |------|-------------|
 | `lattice_list_stacks` | List stacks with status and worker assignment |
 | `lattice_get_stack` | Full stack details including compose YAML |
-| `lattice_update_stack` | Update stack configuration |
 | `lattice_deploy_stack` | Deploy a stack (all or specific containers) |
 | `lattice_restart_stack` | Restart all containers in a stack |
 | `lattice_stop_stack` | Stop all containers in a stack |
 | `lattice_start_stack` | Start all containers in a stack |
+| `lattice_update_stack` | Update stack configuration |
 
 ### Containers
 | Tool | Description |
 |------|-------------|
 | `lattice_list_containers` | List containers with status, image, ports, health |
 | `lattice_get_container` | Full container details |
-| `lattice_get_container_logs` | Recent container logs (stdout/stderr) |
+| `lattice_get_container_logs` | Recent container logs (stdout/stderr); `offset` paginates into older logs, filter by `stream`/`worker_id` |
 | `lattice_get_container_lifecycle` | Lifecycle events (start, stop, health changes) |
 | `lattice_start_container` | Start a stopped container |
 | `lattice_stop_container` | Stop a running container |
@@ -74,8 +132,8 @@ Generate an API token from the Lattice web dashboard under **Settings > API Toke
 | `lattice_kill_container` | Force kill a container |
 | `lattice_pause_container` | Pause a running container |
 | `lattice_unpause_container` | Unpause a paused container |
-| `lattice_remove_container` | Remove a container |
-| `lattice_recreate_container` | Remove and recreate a container |
+| `lattice_remove_container` | Remove a container ⚠️ |
+| `lattice_recreate_container` | Remove and recreate a container ⚠️ |
 
 ### Deployments
 | Tool | Description |
@@ -83,36 +141,21 @@ Generate an API token from the Lattice web dashboard under **Settings > API Toke
 | `lattice_list_deployments` | List deployments with status and timing |
 | `lattice_get_deployment` | Deployment details with container-level status |
 | `lattice_get_deployment_logs` | Pull, create, start, swap events with timing |
-| `lattice_rollback_deployment` | Rollback to previous state |
+| `lattice_rollback_deployment` | Rollback to previous state ⚠️ |
+
+### Instance self-update
+| Tool | Description |
+|------|-------------|
+| `lattice_update_api` | Trigger the Lattice API container to self-update |
+| `lattice_update_web` | Trigger the Lattice web container to update |
 
-### System
+### Audit & API tokens
 | Tool | Description |
 |------|-------------|
-| `lattice_get_audit_log` | Recent audit log entries |
-| `lattice_update_api` | Trigger API self-update |
-| `lattice_update_web` | Trigger web container update |
+| `lattice_get_audit_log` | Audit log entries (who did what, when); filter by `user_id`/`action`/`resource_type`, `offset` paginates |
 | `lattice_list_api_tokens` | List API tokens |
 | `lattice_create_api_token` | Create a new API token |
-| `lattice_delete_api_token` | Delete an API token |
-
-## Example Prompts
-
-- "What's the status of all stacks?"
-- "Show me logs for the forta-api container"
-- "Deploy stack 5"
-- "Which containers are unhealthy?"
-- "Rollback the last deployment on stack 12"
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `LATTICE_API_URL` | Yes | Lattice API base URL |
-| `LATTICE_API_TOKEN` | Yes | API token for authentication |
-
-## License
-
-MIT
+| `lattice_delete_api_token` | Delete an API token ⚠️ |
 
 ### Database instances
 | Tool | Description |
@@ -132,18 +175,22 @@ MIT
 ### Backup destinations
 | Tool | Description |
 |------|-------------|
-| `lattice_list_backup_destinations` / `lattice_get_backup_destination` | Inventory |
-| `lattice_create_backup_destination` / `lattice_update_backup_destination` | Manage destinations |
-| `lattice_delete_backup_destination` | Delete ⚠️ |
-| `lattice_test_backup_destination` | Test connectivity without writing a backup |
+| `lattice_list_backup_destinations` | List backup destinations |
+| `lattice_get_backup_destination` | One destination's configuration |
+| `lattice_create_backup_destination` | Create a destination |
+| `lattice_update_backup_destination` | Update a destination |
+| `lattice_delete_backup_destination` | Delete a destination ⚠️ |
+| `lattice_test_backup_destination` | Test connectivity without writing a backup (requires a connected `worker_id`) |
 
 ### Registries
 | Tool | Description |
 |------|-------------|
-| `lattice_list_registries` | Configured registries |
-| `lattice_create_registry` / `lattice_update_registry` | Manage registries |
-| `lattice_delete_registry` | Delete ⚠️ |
-| `lattice_test_registry` / `lattice_test_registry_inline` | Test stored or unsaved credentials |
+| `lattice_list_registries` | Configured container registries |
+| `lattice_create_registry` | Add a registry |
+| `lattice_update_registry` | Update a registry |
+| `lattice_delete_registry` | Delete a registry ⚠️ |
+| `lattice_test_registry` | Test a saved registry's stored credentials |
+| `lattice_test_registry_inline` | Test registry credentials before saving |
 | `lattice_list_registry_repositories` | What images exist |
 | `lattice_list_registry_tags` | **What versions are deployable** |
 
@@ -153,53 +200,105 @@ MIT
 | `lattice_search` | Search workers, stacks and containers in one call |
 | `lattice_get_anomalies` | **Restart loops, unhealthy containers, offline workers — best first call** |
 | `lattice_get_fleet_metrics` | Aggregated fleet CPU/memory/disk/network |
-| `lattice_get_versions` / `lattice_refresh_versions` | Runner versions and what's outdated |
+| `lattice_get_versions` | Runner versions and what's outdated |
+| `lattice_refresh_versions` | Re-poll every worker for its current runner version |
 | `lattice_get_container_metrics` | Per-container metrics over time |
 | `lattice_get_self` | Which user the token authenticates as |
 
-### Stacks — compose, export & deploy tokens
+### Stacks — lifecycle, compose & deploy tokens
 | Tool | Description |
 |------|-------------|
-| `lattice_create_stack` / `lattice_delete_stack` | Stack lifecycle ⚠️ |
+| `lattice_create_stack` | Create an empty stack |
+| `lattice_delete_stack` | Delete a stack and all its containers ⚠️ |
 | `lattice_get_stack_containers` | Containers in a stack |
-| `lattice_update_stack_compose` / `lattice_sync_stack_compose` | Compose YAML management |
+| `lattice_update_stack_compose` | Replace a stack's compose YAML |
+| `lattice_sync_stack_compose` | Reconcile container records against stored compose YAML |
 | `lattice_import_compose` | Create a stack from compose YAML |
-| `lattice_export_stack` / `lattice_import_stack_export` | Portable stack backup/restore |
+| `lattice_export_stack` | Export a stack's full definition as portable JSON |
+| `lattice_import_stack_export` | Recreate a stack from an export document |
 | `lattice_save_stack_as_template` | Save a stack as a reusable template |
 | `lattice_list_deploy_tokens` | CI deploy tokens — `last_used_at` shows whether CI reaches Lattice |
-| `lattice_create_deploy_token` / `lattice_delete_deploy_token` | Manage CI deploy tokens ⚠️ |
+| `lattice_create_deploy_token` | Create a CI deploy token |
+| `lattice_delete_deploy_token` | Delete a CI deploy token ⚠️ |
 | `lattice_approve_deployment` | Approve a deployment awaiting approval |
 
 ### Container definitions
 | Tool | Description |
 |------|-------------|
-| `lattice_create_container` / `lattice_update_container` | Manage container definitions |
-| `lattice_delete_container` | Delete definition and container ⚠️ |
+| `lattice_create_container` | Add a container definition to a stack |
+| `lattice_update_container` | Update a container definition |
+| `lattice_delete_container` | Delete definition and its running container ⚠️ |
 
-### Workers — resources
+### Workers — registration, tokens, volumes, networks
 | Tool | Description |
 |------|-------------|
-| `lattice_create_worker` / `lattice_update_worker` / `lattice_delete_worker` | Worker registration ⚠️ |
-| `lattice_get_worker_container_stats` | Live per-container stats |
-| `lattice_list_worker_tokens` / `lattice_create_worker_token` / `lattice_delete_worker_token` | Runner registration tokens ⚠️ |
-| `lattice_list_worker_volumes` / `lattice_create_worker_volume` / `lattice_delete_worker_volume` | Docker volumes ⚠️ |
-| `lattice_list_worker_networks` / `lattice_create_worker_network` / `lattice_delete_worker_network` | Docker networks ⚠️ |
-| `lattice_list_all_networks` / `lattice_delete_network` | Fleet-wide networks ⚠️ |
+| `lattice_create_worker` | Register a worker |
+| `lattice_update_worker` | Update a worker's name, hostname, IP, status, labels |
+| `lattice_delete_worker` | Delete a worker ⚠️ |
+| `lattice_get_worker_container_stats` | Live per-container stats from one worker |
+| `lattice_list_worker_tokens` | Worker registration tokens |
+| `lattice_create_worker_token` | Create a registration token for a worker |
+| `lattice_delete_worker_token` | Delete a worker token ⚠️ |
+| `lattice_list_worker_volumes` | Docker volumes on a worker |
+| `lattice_create_worker_volume` | Create a Docker volume on a worker |
+| `lattice_delete_worker_volume` | Delete a Docker volume ⚠️ |
+| `lattice_list_worker_networks` | Docker networks on a worker |
+| `lattice_create_worker_network` | Create a Docker network on a worker |
+| `lattice_delete_worker_network` | Delete a Docker network ⚠️ |
+| `lattice_list_all_networks` | Every tracked network across the fleet |
+| `lattice_delete_network` | Delete a tracked network by Lattice ID ⚠️ |
 | `lattice_force_remove_container` | Force-remove a wedged container ⚠️ |
 
 ### Env vars, templates & webhooks
 | Tool | Description |
 |------|-------------|
-| `lattice_list_env_vars` / `lattice_create_env_var` / `lattice_update_env_var` / `lattice_delete_env_var` | Global `${VAR}` interpolation values ⚠️ |
-| `lattice_list_templates` / `lattice_create_template` / `lattice_delete_template` | Stack templates ⚠️ |
-| `lattice_list_webhooks` / `lattice_create_webhook` / `lattice_update_webhook` / `lattice_delete_webhook` / `lattice_test_webhook` | Outbound event webhooks ⚠️ |
+| `lattice_list_env_vars` | Global `${VAR}` interpolation values (secrets masked) |
+| `lattice_create_env_var` | Create a global environment variable |
+| `lattice_update_env_var` | Update a global environment variable |
+| `lattice_delete_env_var` | Delete a global environment variable ⚠️ |
+| `lattice_list_templates` | Saved stack templates |
+| `lattice_create_template` | Create a stack template |
+| `lattice_delete_template` | Delete a stack template ⚠️ |
+| `lattice_list_webhooks` | Outbound event webhooks |
+| `lattice_create_webhook` | Create an outbound webhook |
+| `lattice_update_webhook` | Update a webhook |
+| `lattice_delete_webhook` | Delete a webhook ⚠️ |
+| `lattice_test_webhook` | Send a test payload to a webhook |
 
 ### Users & instance configuration
 | Tool | Description |
 |------|-------------|
-| `lattice_list_users` / `lattice_create_user` / `lattice_update_user` / `lattice_delete_user` | User management ⚠️ |
-| `lattice_get_sso_config` / `lattice_update_sso_config` | Forta SSO ⚠️ |
-| `lattice_get_smtp_config` / `lattice_update_smtp_config` / `lattice_test_smtp` | Alert email |
-| `lattice_get_notification_prefs` / `lattice_update_notification_prefs` | Per-event notification prefs |
+| `lattice_list_users` | List Lattice users with roles and status |
+| `lattice_create_user` | Create a local Lattice user |
+| `lattice_update_user` | Update a user's name, role or active flag ⚠️ |
+| `lattice_delete_user` | Delete a Lattice user ⚠️ |
+| `lattice_get_sso_config` | Get the Forta SSO configuration |
+| `lattice_update_sso_config` | Update SSO config ⚠️ (can lock out SSO users) |
+| `lattice_get_smtp_config` | Get the SMTP configuration |
+| `lattice_update_smtp_config` | Update the SMTP configuration |
+| `lattice_test_smtp` | Send a test email with the saved SMTP config |
+| `lattice_get_notification_prefs` | Per-event notification preferences |
+| `lattice_update_notification_prefs` | Update notification preferences |
+
+## Project structure
+
+Everything lives in one file:
+
+| Path | Role |
+|------|------|
+| `index.js` | The whole server: `--setup` flow, config read, `api()` HTTP helper, `text()`/`body()` helpers, all 126 `server.tool(...)` registrations, transport connect. |
+| `package.json` | npm metadata; `bin.lattice-mcp` → `index.js`. |
+| `AGENTS.md` | Contributor/agent guide — conventions, handler contracts, verification. |
+| `README.md` | This file. |
+
+## Deployment
 
-⚠️ = destructive. Tool descriptions state the blast radius.
+Published to npm as `lattice-mcp` (public). Consumers run `npx -y lattice-mcp`, which resolves the latest published version — so **publishing is deployment**, and a running MCP server must be restarted to pick up a new version. `npm publish` requires 2FA via passkey from an interactive terminal.
+
+## Contributing & further reading
+
+Read [`AGENTS.md`](./AGENTS.md) before changing code — it documents the one-shape tool pattern, the `body()`/`api()` helpers, the "read the handler before adding a tool" rule, and the verification steps. Related repos: [`lattice-api`](https://github.com/aidenappl/lattice-api), [`lattice-web`](https://github.com/aidenappl/lattice-web), [`lattice-runner`](https://github.com/aidenappl/lattice-runner).
+
+## License
+
+MIT

package/index.js

@@ -77,12 +77,27 @@ async function api(method, path, params, body) {
         opts.headers["Content-Type"] = "application/json";
         opts.body = JSON.stringify(body);
     }
+    let res;
     try {
-        const res = await fetch(url.toString(), opts);
-        return await res.json();
+        res = await fetch(url.toString(), opts);
     } catch (err) {
+        // Network-level failure (DNS, connection refused, timeout) — no response at all.
         return { success: false, error: err.message, error_message: `API request failed: ${err.message}` };
     }
+    // Response arrived. Read the body once as text, then try to parse it as JSON.
+    // On parse failure surface the HTTP status and a truncated text body rather than
+    // an opaque parse error — a 502/504 HTML page from the TLS proxy lands here.
+    // Never log bodies anywhere; responses can carry secrets.
+    const raw = await res.text();
+    try {
+        return JSON.parse(raw);
+    } catch {
+        return {
+            success: false,
+            error_code: res.status,
+            error_message: `API returned a non-JSON response (HTTP ${res.status})${raw ? `: ${raw.slice(0, 500)}` : ""}`,
+        };
+    }
 }
 
 function text(data) {
@@ -99,7 +114,7 @@ function body(obj) {
 
 const server = new McpServer({
     name: "lattice",
-    version: "1.0.0",
+    version: "1.1.2",
 });
 
 // Overview
@@ -114,6 +129,12 @@ server.tool("lattice_health", "Check API health and database connectivity", {},
     return { content: text(res) };
 });
 
+// Version
+server.tool("lattice_get_version", "Get the deployed lattice-api version string. Use to check deploy drift against GitHub tags/commits (e.g. for /howfarbehind).", {}, async () => {
+    const res = await api("GET", "/version");
+    return { content: text(res) };
+});
+
 // Workers
 server.tool("lattice_list_workers", "List all workers with status, IP, Docker version, runner version, last heartbeat", {
     status: z.enum(["online", "offline", "disconnected"]).optional().describe("Filter by worker status"),
@@ -174,9 +195,11 @@ server.tool("lattice_get_container", "Get full container details including confi
 server.tool("lattice_get_container_logs", "Get recent container logs (stdout/stderr)", {
     id: z.number().describe("Container ID"),
     limit: z.number().optional().describe("Number of log lines (default 50)"),
+    offset: z.number().optional().describe("Skip this many lines — paginate past the tail into older logs"),
     stream: z.enum(["stdout", "stderr"]).optional().describe("Filter by stream"),
-}, async ({ id, limit, stream }) => {
-    const res = await api("GET", `/admin/containers/${id}/logs`, { limit, stream });
+    worker_id: z.number().optional().describe("Filter by worker ID"),
+}, async ({ id, limit, offset, stream, worker_id }) => {
+    const res = await api("GET", `/admin/containers/${id}/logs`, { limit, offset, stream, worker_id });
     return { content: text(res) };
 });
 
@@ -213,10 +236,14 @@ server.tool("lattice_get_deployment_logs", "Get deployment logs: pull, create, s
 });
 
 // Audit log
-server.tool("lattice_get_audit_log", "Get recent audit log entries (who did what, when)", {
+server.tool("lattice_get_audit_log", "Get recent audit log entries (who did what, when). Filter by user, action, or resource type to answer 'who deleted X' without scanning.", {
     limit: z.number().optional().describe("Number of entries (default 50)"),
-}, async ({ limit }) => {
-    const res = await api("GET", "/admin/audit-log", { limit });
+    offset: z.number().optional().describe("Skip this many entries for pagination"),
+    user_id: z.number().optional().describe("Filter by the user who performed the action"),
+    action: z.string().optional().describe("Filter by action (e.g. create, update, delete, deploy)"),
+    resource_type: z.string().optional().describe("Filter by resource type (e.g. stack, container, worker, registry)"),
+}, async ({ limit, offset, user_id, action, resource_type }) => {
+    const res = await api("GET", "/admin/audit-log", { limit, offset, user_id, action, resource_type });
     return { content: text(res) };
 });
 
@@ -559,9 +586,9 @@ server.tool("lattice_delete_backup_destination", "Delete a backup destination. I
     return { content: text(res) };
 });
 
-server.tool("lattice_test_backup_destination", "Test connectivity and credentials for a backup destination without writing a real backup", {
+server.tool("lattice_test_backup_destination", "Test connectivity and credentials for a backup destination without writing a real backup. The test is dispatched over the worker's WebSocket, so worker_id is required and that worker must be connected", {
     id: z.number().describe("Backup destination ID"),
-    worker_id: z.number().optional().describe("Worker to run the test from"),
+    worker_id: z.number().describe("Worker to run the test from — required; the test runs on this worker over its WebSocket, so it must be connected"),
 }, async ({ id, worker_id }) => {
     const res = await api("POST", `/admin/backup-destinations/${id}/test`, { worker_id });
     return { content: text(res) };
@@ -682,7 +709,7 @@ server.tool("lattice_get_container_metrics", "Get a single container's CPU, memo
 });
 
 server.tool("lattice_get_self", "Get the user this API token authenticates as, including role", {}, async () => {
-    const res = await api("GET", "/admin/self");
+    const res = await api("GET", "/auth/self");
     return { content: text(res) };
 });
 
@@ -974,7 +1001,7 @@ server.tool("lattice_force_remove_container", "Force-remove a container on a wor
     id: z.number().describe("Worker ID"),
     name: z.string().describe("Container name to force-remove"),
 }, async ({ id, name }) => {
-    const res = await api("POST", `/admin/workers/${id}/force-remove`, { name });
+    const res = await api("POST", `/admin/workers/${id}/force-remove`, null, { container_name: name });
     return { content: text(res) };
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lattice-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP server for Lattice container orchestration platform",
   "type": "module",
   "main": "index.js",
@@ -24,6 +24,7 @@
     "url": "git+https://github.com/aidenappl/lattice-mcp.git"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   }
 }