lattice-mcp 1.0.1 → 1.1.1

package/AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md — lattice-mcp
+
+> `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,
+> containers, deployments, databases, registries, networks, volumes and instance config.
+> This file orients any agent/worker before touching code in this repo.
+>
+> **⚠️ Golden rule — keep this file current:** any change that adds, removes or retypes a
+> tool, changes the auth model, or drifts from `lattice-api`'s route surface MUST update this
+> AGENTS.md in the SAME change. Stale context here misleads every future agent. If you finish
+> work and haven't touched AGENTS.md, confirm that's actually correct.
+
+---
+
+## What this repo is
+
+A single-file Node ESM program (`index.js`, ~1,180 lines) that speaks MCP over stdio and
+translates tool calls into HTTP requests against `lattice-api`. It is published to npm as
+`lattice-mcp` and consumed via `npx -y lattice-mcp` from `~/.mcp.json`.
+
+It owns **only the translation layer**: tool names, argument schemas, descriptions, and URL
+construction. It holds no business logic, no caching, and no state. Every behaviour an agent
+observes — pagination limits, validation messages, side effects — comes from `lattice-api`.
+
+It does **not** own: the Lattice data model, deployment mechanics, or the worker protocol.
+Those live in [`lattice-api`](https://github.com/aidenappl/lattice-api) and
+[`lattice-runner`](https://github.com/aidenappl/lattice-runner).
+
+## Stack & dependencies
+
+- **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` ^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.
+
+## Project structure
+
+| Path | Role |
+|------|------|
+| `index.js` | Everything: `--setup` flow, config read, `api()` HTTP helper, `text()`/`body()` helpers, all 125 `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. |
+
+`index.js` is organised top-to-bottom as: setup block → config/guard → helpers → tools grouped
+by domain under `// ───` banner comments → transport. **Keep new tools inside the matching
+banner group**; do not append to the bottom.
+
+## Running, building & testing
+
+There is no `Devfile.yaml` and no `dev` CLI wiring here — it is a single script.
+
+```bash
+node --check index.js          # syntax gate — the only static check that exists
+npm install                    # needed before running locally (deps are not vendored)
+node index.js --setup          # interactive: writes the lattice block into ~/.mcp.json
+LATTICE_API_URL=... LATTICE_API_TOKEN=... node index.js   # run the server on stdio
+```
+
+**Smoke-testing without an MCP client.** The server speaks JSON-RPC over stdio, so you can
+drive it with a shell pipeline. This is the standard way to verify a change registers cleanly:
+
+```bash
+{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
+  sleep 2
+  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+  sleep 2; } | LATTICE_API_URL=x LATTICE_API_TOKEN=x node index.js
+```
+
+The `sleep`s matter — without them the requests race the handshake and you get nothing back.
+For a live call, swap `tools/list` for
+`{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"lattice_get_anomalies","arguments":{}}}`
+and supply the real token.
+
+## How code is written here
+
+- **Every tool follows one shape.** Deviating makes the file harder to scan:
+  ```js
+  server.tool("lattice_<verb>_<noun>", "<description>", { /* zod schema */ }, async (args) => {
+      const res = await api("<METHOD>", `/admin/<path>`, params, body);
+      return { content: text(res) };
+  });
+  ```
+- **Naming:** `lattice_` prefix on every tool, then `list|get|create|update|delete|<verb>` then
+  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. 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.
+- **Path params are template literals**, query params go through the `params` argument. Never
+  hand-concatenate a query string.
+- **Descriptions are the contract.** An agent picks tools from the description alone, so it
+  must state what the tool does, when to reach for it, and — for anything destructive — the
+  blast radius. Compare `lattice_stop_container` ("stops it") with `lattice_delete_container`
+  ("Destructive — lattice_stop_container only stops it").
+- **Read the handler before adding a tool.** Struct field names are not the request contract;
+  handlers frequently override or ignore them. Two live examples from `lattice-api`:
+  `HandleUpdateCompose` has a `containerConfigFingerprint` helper with short JSON keys
+  (`i`, `t`, `pm`) that is **not** the request body — the body is just `{compose_yaml}`; and
+  `HandleDatabaseAction` derives its action from the **last URL path segment**, not from a body
+  field.
+
+## Domain & architecture
+
+**Auth.** A single long-lived bearer token (`LATTICE_API_TOKEN`) from
+`lattice-api`'s `/admin/api-tokens`, sent on every request. There is no refresh, no expiry
+handling, and no login flow. A 401 means the token was revoked or expired — the fix is a new
+token via `--setup`, not a code change.
+
+**Config.** Read once at startup from `LATTICE_API_URL` and `LATTICE_API_TOKEN`; the process
+exits immediately if either is missing. In practice these come from the `env` block of the
+`lattice` entry in `~/.mcp.json`.
+
+**Tool groups**, in file order:
+
+The counts below sum to **125**, matching the header and `grep -c 'server.tool(' index.js`. The
+first six 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` |
+| Workers | 3 + 4 actions | list/get/metrics; reboot, upgrade, stop-all, start-all |
+| 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.
+
+**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
+predate this convention and remain separate tools.
+
+## Ecosystem & related repos
+
+| Repo | Relationship |
+|------|--------------|
+| [`lattice-api`](https://github.com/aidenappl/lattice-api) | The API this wraps. Its `main.go` route table is the source of truth for 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`](https://github.com/aidenappl/monitor-mcp) | Sibling MCP, same single-file structure — keep them stylistically aligned. |
+| `forta-mcp` / `keyring-mcp` / `openbucket-mcp` | Newer siblings; they carry a `body()` helper and destructive-blast-radius descriptions that originated here. |
+
+## Operations
+
+- **Published to npm** as `lattice-mcp` (public). Consumers run `npx -y lattice-mcp`, which
+  resolves the latest published version — so **publishing is deployment**. A bug shipped to npm
+  reaches every user on their next MCP server start.
+- **Publishing requires 2FA via passkey.** `npm publish` must run from an interactive terminal:
+  npm's web auth flow needs to open a browser, and from a non-TTY subprocess it degrades to
+  demanding an OTP that a passkey-only account cannot produce.
+- **In-session staleness:** a running MCP server process does not pick up a new npm version.
+  After publishing, the client must be restarted before the new tools/schemas appear.
+- **Common failure modes:**
+  - *All tools return `API request failed: fetch failed`* — `LATTICE_API_URL` is wrong or the
+    TLS proxy in front of Lattice has an expired cert.
+  - *All tools return 401* — token revoked or expired; re-run `--setup`.
+  - *One tool 404s while others work* — the MCP is ahead of the deployed `lattice-api`, or the
+    route moved.
+
+## Rules & guardrails
+
+- **Never hardcode a token, URL or hostname.** Everything comes from env.
+- **Never log request or response bodies.** Responses routinely contain env vars, registry
+  credentials and database passwords. `lattice_get_database_credentials` returns live secrets
+  by design — do not add convenience logging anywhere in `api()`.
+- **Never add a tool without reading its handler in `lattice-api`.** Inferring a request shape
+  from a struct has produced real, shipped bugs across this family of servers.
+- **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 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
+  72 hours) — do not publish without explicit instruction.
+
+## Verification — always before "done"
+
+```bash
+node --check index.js                      # must pass
+grep -c 'server.tool(' index.js            # tool count matches what you expect
+```
+
+Then the stdio handshake from *Running, building & testing* above, asserting:
+- the server registers **without stderr output**,
+- the tool count is what you expect,
+- **no duplicate tool names** (`server.tool` silently accepts a duplicate; the last registration
+  wins and the earlier tool disappears — this will not error).
+
+For any tool you added or changed, make **one real call against the live API** and confirm the
+response shape. Schema-only verification is not enough: it catches typos, not wrong units,
+wrong enum values, or parameters the handler ignores.
+
+**Never report work complete on the strength of `tools/list` alone.**
+
+## Keeping this file updated
+
+Update this AGENTS.md in the same change when you:
+- **Add/remove/rename a tool** → update the tool-group table and the count in the header.
+- **Change the auth model or config vars** → update *Domain & architecture*.
+- **Change the `api()`/`body()`/`text()` helpers** → update *How code is written here*.
+- **Bump the version or publish** → note behavioural changes under the relevant group.
+- **Notice `lattice-api` has gained routes** → either add the tools or record the gap here
+  explicitly, so the next agent knows it was a decision and not an oversight.
+- Also keep `README.md`'s tool tables in sync — it is the user-facing surface and drifts fastest.

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 **125 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,41 @@ 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 125) |
+| `npm publish` | Publish to npm — **this is deployment** (requires 2FA passkey from an interactive terminal) |
 
 ## Tools
 
-### Overview & Health
+All 125 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 |
 
 ### 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,11 +112,11 @@ 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 |
@@ -74,8 +131,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,32 +140,163 @@ 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` | Recent audit log entries (who did what, when) |
 | `lattice_list_api_tokens` | List API tokens |
 | `lattice_create_api_token` | Create a new API token |
-| `lattice_delete_api_token` | Delete an API token |
+| `lattice_delete_api_token` | Delete an API token ⚠️ |
+
+### Database instances
+| Tool | Description |
+|------|-------------|
+| `lattice_list_database_instances` | List managed databases (filter by worker, engine, status) |
+| `lattice_get_database_instance` | Full instance config |
+| `lattice_create_database_instance` | Provision mysql/mariadb/postgres on a worker |
+| `lattice_update_database_instance` | Update config, limits, snapshot schedule |
+| `lattice_delete_database_instance` | Delete an instance ⚠️ |
+| `lattice_database_action` | start / stop / restart / remove ⚠️ |
+| `lattice_get_database_credentials` | Connection credentials (returns secrets) |
+| `lattice_list_database_snapshots` | Snapshots for an instance |
+| `lattice_create_database_snapshot` | Take a snapshot now |
+| `lattice_restore_database_snapshot` | Restore from a snapshot ⚠️ |
+| `lattice_delete_database_snapshot` | Delete a snapshot ⚠️ |
 
-## Example Prompts
+### Backup destinations
+| Tool | Description |
+|------|-------------|
+| `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`) |
 
-- "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"
+### Registries
+| Tool | Description |
+|------|-------------|
+| `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** |
 
-## Environment Variables
+### Discovery & diagnostics
+| Tool | Description |
+|------|-------------|
+| `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` | 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 |
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `LATTICE_API_URL` | Yes | Lattice API base URL |
-| `LATTICE_API_TOKEN` | Yes | API token for authentication |
+### Stacks — lifecycle, compose & deploy tokens
+| Tool | Description |
+|------|-------------|
+| `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` | 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` | 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` | 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` | Add a container definition to a stack |
+| `lattice_update_container` | Update a container definition |
+| `lattice_delete_container` | Delete definition and its running container ⚠️ |
+
+### Workers — registration, tokens, volumes, networks
+| Tool | Description |
+|------|-------------|
+| `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` | 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` | 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 125 `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
+
+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