lattice-mcp 1.1.1 → 1.2.0

package/.github/workflows/verify.yml

@@ -0,0 +1,33 @@
+name: Verify
+
+# lattice-mcp is published to npm by hand, so there is no build-and-deploy
+# pipeline to hang this off. This workflow exists purely as a correctness gate on
+# push and pull request.
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4.2.2
+
+      - name: Set up Node
+        uses: actions/setup-node@v4.1.0
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Parses index.js, rejects duplicate tool names (server.tool silently
+      # lets the last registration win), and fails if README.md/AGENTS.md have
+      # drifted from the registered tool count.
+      - name: Verify
+        run: npm test

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 **133 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.
 >
@@ -42,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 133 `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. |
@@ -113,6 +113,40 @@ and supply the real token.
   `HandleDatabaseAction` derives its action from the **last URL path segment**, not from a body
   field.
 
+### Sensitive value masking
+
+`api()` passes every decoded JSON response through **`sanitise()`** before returning it. This is
+central, not per-tool, so a newly added tool is safe by default rather than by remembering.
+
+`mask()` keeps a value's **first two characters** and appends a **fixed-width tail** —
+`"supersecret"` → `"su**********"`. The prefix is what makes the mask useful rather than merely
+safe: you can still tell a `frt_` token from an `obk_` one, spot that two containers share a
+key, or confirm a rotation actually changed a value. The tail is fixed width so the mask does
+not disclose the real length. Values under three characters are masked whole.
+
+Four rules, in the order `sanitise()` applies them:
+
+| Field | Handling |
+|-------|----------|
+| `env_vars` | Parsed as JSON, then values whose **key** matches `isSecretName()` are masked. The blob is not masked wholesale — variable names are the useful half. An unparseable blob *is* masked wholesale rather than passed through. |
+| `compose_yaml` | Assignment lines (`- NAME=value` and `NAME: value`) whose name matches `isSecretName()` are masked, without tracking YAML block structure. |
+| `value` when the sibling `is_secret` is `true` | Masked. Global env vars are only secret when flagged, and masking the rest would hide image tags, ports and hostnames. |
+| anything in `SECRET_FIELDS` | Masked at any nesting depth, in objects and arrays alike. |
+
+`isSecretName()` matches password/secret/token/key/credential/dsn shapes but **excludes names
+ending in `_url`, `_uri`, `_endpoint`, `_host`, `_port`, `_issuer`** — `TOKEN_URL` and
+`AUTH_URL` are addresses, not credentials, and masking them makes an SSO misconfiguration much
+harder to diagnose.
+
+**Why this repo needs it more than the others:** this MCP authenticates as a Lattice **admin**,
+and `lattice-api` only masks global env vars server-side *for non-admin callers*
+(`HandleGlobalEnvVars.router.go`). Before masking, `lattice_list_env_vars` returned every
+`is_secret` value in plaintext despite its own description claiming otherwise.
+
+`LATTICE_ALLOW_SECRET_VALUES=1` disables masking entirely — for the cases where you genuinely
+need a working credential (`lattice_reveal_database_credentials`, the token-creation tools).
+It is off by default and should stay that way.
+
 ## Domain & architecture
 
 **Auth.** A single long-lived bearer token (`LATTICE_API_TOKEN`) from
@@ -126,20 +160,21 @@ exits immediately if either is missing. In practice these come from the `env` bl
 
 **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);
+The counts below sum to **133**, 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 + 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 |
+| **Database instances** | **19** | CRUD, `lattice_database_action` (start/stop/restart/remove enum), `lattice_get_database_connection`, `lattice_reveal_database_credentials`, `lattice_get_database_credentials` (deprecated), `lattice_get_database_events`, `lattice_get_database_logs`, `lattice_get_database_lifecycle_logs`, `lattice_open_database_console`, snapshot list/create/restore/delete |
+| **Worker port allocation** | **1** | `lattice_get_worker_port_availability` — claimed host ports on a worker plus a free suggestion |
 | **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` |
@@ -162,6 +197,36 @@ always 400'd); and `lattice_test_backup_destination` now marks `worker_id` as **
 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.
+
+**1.2.0** covers the managed-database overhaul in `lattice-api`. Tool count 126 → 133.
+
+New: `lattice_get_database_connection` (host/port/database/username, no secrets),
+`lattice_reveal_database_credentials` (`POST .../reveal` — audited, root only when `include_root`
+is set), `lattice_get_database_events` (**the first thing to reach for when a database is in an
+unexpected state** — the lifecycle history explains how it got there), `lattice_get_database_logs`,
+`lattice_get_database_lifecycle_logs`, `lattice_open_database_console`, and
+`lattice_get_worker_port_availability`.
+
+It also fixes two long-standing request-shape bugs verified against the handlers, both of the exact
+kind this repo's rules warn about:
+
+- `memory_limit` was documented as **bytes**. The API takes **megabytes** and multiplies before
+  sending to the worker, so any agent that followed the description passed a value roughly a
+  million times too small — and Docker rejects any limit under 6MB, so the create failed.
+- `status` was a free string whose description advertised `creating`, which is not a value the
+  platform has ever used. It is now an enum matching `structs.DatabaseStatus`
+  (`pending`/`provisioning`/`running`/`stopped`/`restarting`/`degraded`/`deleting`/`error`), as is
+  `health_status`. The API now rejects anything else with a 400.
+
+`lattice_create_database_instance`'s `port` is now documented as optional-and-preferably-omitted:
+the API allocates a free port from 20000-29999 and returns 409 naming the conflict if you pin one
+that is taken.
+
 **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
@@ -198,8 +263,11 @@ predate this convention and remain separate tools.
 
 - **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()`.
+  credentials and database passwords — do not add convenience logging anywhere in `api()`.
+- **Never weaken `sanitise()`.** It must stay recursive, applied centrally in `api()`, and on by
+  default. Masking is the only thing standing between an admin token's responses and a
+  permanent transcript. If a tool needs real values, the answer is
+  `LATTICE_ALLOW_SECRET_VALUES=1` in that server's env, not an exemption in the code.
 - **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
@@ -231,6 +299,12 @@ For any tool you added or changed, make **one real call against the live API** a
 response shape. Schema-only verification is not enough: it catches typos, not wrong units,
 wrong enum values, or parameters the handler ignores.
 
+**If you touched `api()`, `sanitise()`, `mask()` or the field lists**, re-verify masking: run a
+nested fixture (objects inside arrays inside objects, an `env_vars` blob, a `compose_yaml`
+string) through `sanitise()` and assert no live value survives at any depth. `npm test` checks
+statically that `api()` still calls `sanitise()`, but it cannot check that the field lists are
+still right.
+
 **Never report work complete on the strength of `tools/list` alone.**
 
 ## Keeping this file updated

package/README.md

@@ -8,7 +8,7 @@ Model Context Protocol server for [Lattice](https://github.com/aidenappl/lattice
 
 ## 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`.
+`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 **133 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:
 
@@ -74,6 +74,28 @@ Restart Claude Code after setup so the new server and tools are picked up.
 |----------|----------|-------------|
 | `LATTICE_API_URL` | Yes | Lattice API base URL |
 | `LATTICE_API_TOKEN` | Yes | Bearer token for authentication (sent on every request) |
+| `LATTICE_ALLOW_SECRET_VALUES` | No | Set to `1` to disable secret masking in responses |
+
+## Secret values are masked
+
+Every response is passed through a masking step before it reaches the model. Anything that looks
+like a credential keeps its **first two characters** and loses the rest to a fixed-width tail —
+`supersecret` becomes `su**********`.
+
+That is enough to tell two credentials apart, or to confirm a rotation actually changed
+something, and not enough to use. The tail is a fixed width so the mask does not reveal the real
+length.
+
+This covers container and stack `env_vars`, `compose_yaml` environment blocks, global env vars
+flagged `is_secret`, database passwords, and freshly minted deploy/worker/API tokens. Variable
+*names* are left readable — they are the useful half — as are addresses like `TOKEN_URL` and
+`AUTH_URL`.
+
+This server authenticates as a Lattice **admin**, and the API only masks global env vars
+server-side for *non-admin* callers. Without this step, `lattice_list_env_vars` returns every
+secret value in plaintext.
+
+Set `LATTICE_ALLOW_SECRET_VALUES=1` to turn masking off if you genuinely need a working value.
 
 ## Development
 
@@ -83,18 +105,19 @@ Restart Claude Code after setup so the new server and tools are picked up.
 | `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) |
+| `grep -c 'server.tool(' index.js` | Confirm the tool count (should be 133) |
 | `npm publish` | Publish to npm — **this is deployment** (requires 2FA passkey from an interactive terminal) |
 
 ## Tools
 
-All 125 tools, grouped as they appear in `index.js`. ⚠️ marks destructive tools; their descriptions state the blast radius.
+All 133 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/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 |
@@ -123,7 +146,7 @@ All 125 tools, grouped as they appear in `index.js`. ⚠️ marks destructive to
 |------|-------------|
 | `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 |
@@ -151,7 +174,7 @@ All 125 tools, grouped as they appear in `index.js`. ⚠️ marks destructive to
 ### Audit & API tokens
 | Tool | Description |
 |------|-------------|
-| `lattice_get_audit_log` | Recent audit log entries (who did what, when) |
+| `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 ⚠️ |
@@ -161,15 +184,26 @@ All 125 tools, grouped as they appear in `index.js`. ⚠️ marks destructive to
 |------|-------------|
 | `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_create_database_instance` | Provision mysql/mariadb/postgres on a worker (omit `port` to auto-allocate) |
 | `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_get_database_connection` | Host, port, database and username — no secrets |
+| `lattice_reveal_database_credentials` | Reveal live credentials (audited; root only on request) |
+| `lattice_get_database_credentials` | **Deprecated** — root credentials via GET; use the reveal tool |
+| `lattice_get_database_events` | Lifecycle history — start here when a database looks wrong |
+| `lattice_get_database_logs` | Container stdout/stderr |
+| `lattice_get_database_lifecycle_logs` | Worker lifecycle messages, incl. why a create failed |
+| `lattice_open_database_console` | Authorise an interactive SQL console session |
 | `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 ⚠️ |
+| `lattice_delete_database_snapshot` | Delete a snapshot and its remote file ⚠️ |
+
+### Worker port allocation
+| Tool | Description |
+|------|-------------|
+| `lattice_get_worker_port_availability` | Claimed host ports on a worker, plus a free suggestion |
 
 ### Backup destinations
 | Tool | Description |
@@ -285,7 +319,7 @@ 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. |
+| `index.js` | The whole server: `--setup` flow, config read, `api()` HTTP helper, `text()`/`body()` helpers, all 133 `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. |

package/index.js

@@ -57,6 +57,113 @@ if (!API_URL || !API_TOKEN) {
     process.exit(1);
 }
 
+// --- Sensitive value masking ---
+//
+// Lattice's admin API answers to an admin token, so it returns live
+// credentials in full: container and stack env vars, global env var values
+// (masking there is server-side and non-admin-only), database passwords,
+// freshly minted deploy/worker/API tokens. None of that is needed to answer
+// the questions these tools exist to answer, and anything that reaches a
+// model's context is in a transcript forever.
+//
+// Sensitive values are masked to their first two characters plus a
+// fixed-width tail: "supersecret" -> "su**********". The prefix keeps a value
+// identifiable and comparable — you can still tell a frt_ token from an obk_
+// one, or spot that two containers share the same key — while the fixed tail
+// avoids disclosing the length.
+//
+// Set LATTICE_ALLOW_SECRET_VALUES=1 to pass values through unmasked.
+
+const ALLOW_SECRETS = process.env.LATTICE_ALLOW_SECRET_VALUES === "1";
+
+function mask(value) {
+    if (typeof value !== "string" || value === "") return value;
+    // Under three characters there is no prefix worth keeping — a two-char
+    // secret would otherwise round-trip as itself.
+    if (value.length < 3) return "**********";
+    return value.slice(0, 2) + "**********";
+}
+
+// Response fields that are a credential wherever they appear.
+const SECRET_FIELDS = new Set([
+    "password", "root_password", "client_secret", "secret", "secret_key",
+    "secret_access_key", "access_key", "access_key_id", "token", "api_token",
+    "admin_token", "deploy_token", "worker_token", "plaintext", "private_key",
+    "encryption_key", "signing_key", "connection_string", "dsn",
+]);
+
+// Env-var and compose keys are free-form, so they are matched by shape rather
+// than by name. The `_url`/`_uri`/`_endpoint` exclusion keeps TOKEN_URL and
+// AUTH_URL readable — they are addresses, not credentials, and masking them
+// makes an SSO misconfiguration much harder to diagnose.
+const SECRET_NAME = /(pass(word|wd)?|secret|token|api[-_]?key|access[-_]?key|private[-_]?key|signing[-_]?key|encryption[-_]?key|credential|dsn|salt)/i;
+const ADDRESS_NAME = /_(url|uri|endpoint|host|port|issuer)$/i;
+
+function isSecretName(name) {
+    return SECRET_NAME.test(name) && !ADDRESS_NAME.test(name);
+}
+
+// Container and stack env vars arrive as a JSON object encoded in a string.
+// Masking the whole blob would hide the variable names too, which are the
+// useful half — so it is parsed, filtered by key, and re-encoded.
+function maskEnvBlob(raw) {
+    if (typeof raw !== "string" || raw === "") return raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        // Not the JSON object shape we expect — mask it wholesale rather than
+        // pass an unknown blob through.
+        return mask(raw);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return raw;
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        out[k] = isSecretName(k) && typeof v === "string" ? mask(v) : v;
+    }
+    return JSON.stringify(out);
+}
+
+// Compose YAML carries the same secrets in `environment:` blocks, in either
+// `- NAME=value` or `NAME: value` form. Matching the assignment line directly
+// avoids having to track YAML block structure.
+const COMPOSE_ENV_LINE = /^(\s*-?\s*)([A-Za-z_][A-Za-z0-9_]*)(\s*[:=]\s*)(.+)$/;
+
+function maskComposeYAML(raw) {
+    if (typeof raw !== "string" || raw === "") return raw;
+    return raw
+        .split("\n")
+        .map((line) => {
+            const m = line.match(COMPOSE_ENV_LINE);
+            if (!m || !isSecretName(m[2])) return line;
+            return m[1] + m[2] + m[3] + mask(m[4].trim());
+        })
+        .join("\n");
+}
+
+// Walks a decoded response and masks every sensitive value in place.
+function sanitise(node) {
+    if (ALLOW_SECRETS || node === null || typeof node !== "object") return node;
+    if (Array.isArray(node)) return node.map(sanitise);
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        if (k === "env_vars") {
+            out[k] = maskEnvBlob(v);
+        } else if (k === "compose_yaml") {
+            out[k] = maskComposeYAML(v);
+        } else if (k === "value" && node.is_secret === true) {
+            // Global env vars: the value is only a secret when flagged as one,
+            // and masking the rest would hide image tags, ports and hostnames.
+            out[k] = mask(v);
+        } else if (SECRET_FIELDS.has(k) && typeof v === "string") {
+            out[k] = mask(v);
+        } else {
+            out[k] = sanitise(v);
+        }
+    }
+    return out;
+}
+
 // --- HTTP helper ---
 
 async function api(method, path, params, body) {
@@ -90,7 +197,7 @@ async function api(method, path, params, body) {
     // Never log bodies anywhere; responses can carry secrets.
     const raw = await res.text();
     try {
-        return JSON.parse(raw);
+        return sanitise(JSON.parse(raw));
     } catch {
         return {
             success: false,
@@ -114,7 +221,7 @@ function body(obj) {
 
 const server = new McpServer({
     name: "lattice",
-    version: "1.1.1",
+    version: "1.2.0",
 });
 
 // Overview
@@ -129,6 +236,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"),
@@ -189,9 +302,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) };
 });
 
@@ -228,10 +343,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) };
 });
 
@@ -426,7 +545,7 @@ server.tool("lattice_delete_api_token", "Delete an API token", {
 server.tool("lattice_list_database_instances", "List managed database instances with engine, version, status, worker and health. Filter by worker, engine or status", {
     worker_id: z.number().optional().describe("Filter by worker ID"),
     engine: z.enum(["mysql", "mariadb", "postgres"]).optional().describe("Filter by engine"),
-    status: z.string().optional().describe("Filter by status (running, stopped, creating, error)"),
+    status: z.enum(["pending", "provisioning", "running", "stopped", "restarting", "degraded", "deleting", "error"]).optional().describe("Filter by lifecycle status"),
     limit: z.number().optional().describe("Max instances to return"),
     offset: z.number().optional().describe("Pagination offset"),
 }, async (args) => {
@@ -441,18 +560,18 @@ server.tool("lattice_get_database_instance", "Get one database instance: engine,
     return { content: text(res) };
 });
 
-server.tool("lattice_create_database_instance", "Provision a database instance on a worker. Creates a real container — pick a port that is free on that worker", {
+server.tool("lattice_create_database_instance", "Provision a database instance on a worker. Creates a real container. Omit `port` to have a free one allocated automatically — that is the recommended path; a port already in use returns 409 naming the conflict", {
     name: z.string().describe("Instance name (must be unique)"),
     engine: z.enum(["mysql", "mariadb", "postgres"]).describe("Database engine"),
     worker_id: z.number().describe("Worker to provision on"),
     engine_version: z.string().optional().describe("Engine version tag; the API picks a default when omitted"),
-    port: z.number().optional().describe("Host port to expose"),
+    port: z.number().optional().describe("Host port to expose. Omit to auto-allocate a free port from the managed range (20000-29999)"),
     root_password: z.string().optional().describe("Root/superuser password"),
     database_name: z.string().optional().describe("Initial database to create"),
     username: z.string().optional().describe("Application user to create"),
     password: z.string().optional().describe("Application user's password"),
     cpu_limit: z.number().optional().describe("CPU limit in cores"),
-    memory_limit: z.number().optional().describe("Memory limit in bytes"),
+    memory_limit: z.number().optional().describe("Memory limit in MEGABYTES (the API converts to bytes; values under 6MB are rejected by Docker)"),
     snapshot_schedule: z.string().optional().describe("Cron expression for automatic snapshots"),
     retention_count: z.number().optional().describe("How many automatic snapshots to keep"),
     backup_destination_id: z.number().optional().describe("Backup destination for snapshots"),
@@ -464,13 +583,13 @@ server.tool("lattice_create_database_instance", "Provision a database instance o
 server.tool("lattice_update_database_instance", "Update a database instance's configuration. Only the fields you pass are changed", {
     id: z.number().describe("Database instance ID"),
     name: z.string().optional(),
-    status: z.string().optional(),
-    port: z.number().optional(),
+    status: z.enum(["pending", "provisioning", "running", "stopped", "restarting", "degraded", "deleting", "error"]).optional().describe("Lifecycle status — normally managed by the reconciler; set manually only to correct drift"),
+    port: z.number().optional().describe("New host port; rejected with 409 if already claimed on the worker"),
     root_password: z.string().optional().describe("New root password"),
     password: z.string().optional().describe("New application user password"),
     cpu_limit: z.number().optional(),
-    memory_limit: z.number().optional(),
-    health_status: z.string().optional(),
+    memory_limit: z.number().optional().describe("Memory limit in MEGABYTES"),
+    health_status: z.enum(["none", "starting", "healthy", "unhealthy"]).optional(),
     snapshot_schedule: z.string().optional().describe("Cron expression for automatic snapshots"),
     retention_count: z.number().optional(),
     backup_destination_id: z.number().optional(),
@@ -495,13 +614,69 @@ server.tool("lattice_database_action", "Start, stop, restart or remove a databas
     return { content: text(res) };
 });
 
-server.tool("lattice_get_database_credentials", "Get a database instance's connection credentials. Returns secret values — avoid unless the credentials are actually needed", {
+server.tool("lattice_get_database_connection", "Get a database instance's host, port, database and username. Contains no secrets — prefer this over the credential tools when you only need to know where a database lives", {
+    id: z.number().describe("Database instance ID"),
+}, async ({ id }) => {
+    const res = await api("GET", `/admin/database-instances/${id}/connection`);
+    return { content: text(res) };
+});
+
+server.tool("lattice_reveal_database_credentials", "Reveal a database instance's live credentials. Every call is audited and recorded against the instance. Returns the application user by default; set include_root only when root access is genuinely required. Passwords come back masked to their first two characters — enough to confirm which credential is deployed, not enough to use. Set LATTICE_ALLOW_SECRET_VALUES=1 in the MCP server env to get the real values, or read them from the Lattice UI", {
+    id: z.number().describe("Database instance ID"),
+    include_root: z.boolean().optional().describe("Also return the root/superuser password (default false)"),
+}, async ({ id, include_root }) => {
+    const res = await api("POST", `/admin/database-instances/${id}/reveal`, null, body({ include_root }));
+    return { content: text(res) };
+});
+
+server.tool("lattice_get_database_credentials", "DEPRECATED — returns root credentials from a plain GET. Use lattice_reveal_database_credentials instead, which is audited and scoped", {
     id: z.number().describe("Database instance ID"),
 }, async ({ id }) => {
     const res = await api("GET", `/admin/database-instances/${id}/credentials`);
     return { content: text(res) };
 });
 
+server.tool("lattice_get_database_events", "Get a database instance's lifecycle history — every status transition, failure, reconciliation, console open and credential reveal. START HERE when a database is in an unexpected state: this is what explains how it got there", {
+    id: z.number().describe("Database instance ID"),
+    kind: z.enum(["requested", "accepted", "transition", "health", "failed", "reconciled", "console_open", "reveal"]).optional().describe("Filter by event kind"),
+    limit: z.number().optional().describe("Max events to return"),
+}, async ({ id, ...params }) => {
+    const res = await api("GET", `/admin/database-instances/${id}/events`, params);
+    return { content: text(res) };
+});
+
+server.tool("lattice_get_database_logs", "Get a database container's stdout/stderr. Use together with lattice_get_database_events when diagnosing a failed or degraded instance — the events say what happened, the logs say why", {
+    id: z.number().describe("Database instance ID"),
+    stream: z.enum(["stdout", "stderr"]).optional().describe("Filter by stream"),
+    limit: z.number().optional().describe("Max log lines to return"),
+}, async ({ id, ...params }) => {
+    const res = await api("GET", `/admin/database-instances/${id}/logs`, params);
+    return { content: text(res) };
+});
+
+server.tool("lattice_get_database_lifecycle_logs", "Get worker-emitted lifecycle messages for a database container, including provisioning progress and the reason a create failed", {
+    id: z.number().describe("Database instance ID"),
+    limit: z.number().optional().describe("Max entries to return"),
+}, async ({ id, ...params }) => {
+    const res = await api("GET", `/admin/database-instances/${id}/lifecycle`, params);
+    return { content: text(res) };
+});
+
+server.tool("lattice_open_database_console", "Authorise an interactive console session against a running database and return the worker, container and SQL client command to run. The session itself runs over the admin WebSocket, so this returns the authorisation, not a live shell", {
+    id: z.number().describe("Database instance ID"),
+}, async ({ id }) => {
+    const res = await api("POST", `/admin/database-instances/${id}/console`);
+    return { content: text(res) };
+});
+
+server.tool("lattice_get_worker_port_availability", "List host ports already claimed on a worker (by databases and by stack containers) and get a free suggestion. Check this before pinning a database to a specific port", {
+    id: z.number().describe("Worker ID"),
+    port: z.number().optional().describe("Check one specific port instead of listing all claims"),
+}, async ({ id, ...params }) => {
+    const res = await api("GET", `/admin/workers/${id}/port-availability`, params);
+    return { content: text(res) };
+});
+
 server.tool("lattice_list_database_snapshots", "List snapshots for a database instance, with size and creation time. Check this before deleting or restoring an instance", {
     id: z.number().describe("Database instance ID"),
 }, async ({ id }) => {
@@ -789,7 +964,7 @@ server.tool("lattice_list_deploy_tokens", "List a stack's deploy tokens — the
     return { content: text(res) };
 });
 
-server.tool("lattice_create_deploy_token", "Create a deploy token for a stack. The plaintext is returned once; use it as https://<lattice>/api/deploy/<token>?container=<name>", {
+server.tool("lattice_create_deploy_token", "Create a deploy token for a stack. The plaintext is returned once and this server masks it to its first two characters, so the usable value never enters a transcript — read it from the Lattice UI, or set LATTICE_ALLOW_SECRET_VALUES=1. Used as https://<lattice>/api/deploy/<token>?container=<name>", {
     id: z.number().describe("Stack ID"),
     name: z.string().describe("Token name, e.g. 'github-actions'"),
 }, async ({ id, name }) => {
@@ -910,7 +1085,7 @@ server.tool("lattice_list_worker_tokens", "List a worker's registration tokens.
     return { content: text(res) };
 });
 
-server.tool("lattice_create_worker_token", "Create a registration token for a worker, used by the runner to connect. Plaintext is returned once", {
+server.tool("lattice_create_worker_token", "Create a registration token for a worker, used by the runner to connect. Plaintext is returned once and this server masks it to its first two characters — read the usable value from the Lattice UI, or set LATTICE_ALLOW_SECRET_VALUES=1", {
     id: z.number().describe("Worker ID"),
     name: z.string().describe("Token name"),
 }, async ({ id, name }) => {
@@ -997,7 +1172,7 @@ server.tool("lattice_force_remove_container", "Force-remove a container on a wor
 // Global env vars, templates, webhooks
 // ─────────────────────────────────────────────────────────────────────────────
 
-server.tool("lattice_list_env_vars", "List global environment variables available for interpolation into stack and container configs as ${NAME}. Values marked is_secret are masked", {}, async () => {
+server.tool("lattice_list_env_vars", "List global environment variables available for interpolation into stack and container configs as ${NAME}. Values marked is_secret are masked to their first two characters by this server — the API itself only masks them for non-admin callers, and this MCP authenticates as an admin", {}, async () => {
     const res = await api("GET", "/admin/env-vars");
     return { content: text(res) };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lattice-mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server for Lattice container orchestration platform",
   "type": "module",
   "main": "index.js",
@@ -8,7 +8,8 @@
     "lattice-mcp": "index.js"
   },
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "test": "node verify.mjs"
   },
   "keywords": [
     "mcp",

package/verify.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Static verification for lattice-mcp.
+ *
+ * index.js cannot simply be imported to check it: it ends in a top-level await
+ * that connects the stdio transport, so importing would hang waiting for a
+ * client. Everything here is therefore checked by parsing the source.
+ *
+ * What this catches:
+ *
+ *  - Duplicate tool names. `server.tool()` silently accepts a duplicate — the
+ *    last registration wins and the earlier tool disappears with no error. That
+ *    is invisible until an agent calls the vanished tool.
+ *  - Tool counts in README.md and AGENTS.md drifting from the code. This repo
+ *    already shipped a release where the MCP lagged the API by two months; the
+ *    documented count is the cheapest tripwire for that.
+ *  - Tools not following the lattice_ prefix, which the client relies on.
+ *  - sanitise() being unwired from api(). Masking is applied in exactly one
+ *    place; removing that call leaves every tool working and every response
+ *    leaking, which no other check would notice.
+ */
+
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const failures = [];
+const fail = (msg) => failures.push(msg);
+
+const source = readFileSync("index.js", "utf8");
+
+// ── Syntax ───────────────────────────────────────────────────────────────────
+try {
+    execFileSync(process.execPath, ["--check", "index.js"], { stdio: "pipe" });
+} catch (err) {
+    fail(`index.js failed to parse:\n${err.stderr?.toString() ?? err.message}`);
+}
+
+// ── Tool registrations ───────────────────────────────────────────────────────
+const names = [...source.matchAll(/server\.tool\(\s*"([^"]+)"/g)].map((m) => m[1]);
+
+if (names.length === 0) {
+    fail("no server.tool() registrations found — did the call shape change?");
+}
+
+const seen = new Set();
+const duplicates = new Set();
+for (const name of names) {
+    if (seen.has(name)) duplicates.add(name);
+    seen.add(name);
+}
+if (duplicates.size > 0) {
+    fail(
+        `duplicate tool names (the later registration silently replaces the earlier): ${[...duplicates].join(", ")}`,
+    );
+}
+
+const misnamed = names.filter((n) => !n.startsWith("lattice_"));
+if (misnamed.length > 0) {
+    fail(`tools not prefixed with lattice_: ${misnamed.join(", ")}`);
+}
+
+// ── Documented counts must match the code ────────────────────────────────────
+const toolCount = names.length;
+
+for (const file of ["README.md", "AGENTS.md"]) {
+    const doc = readFileSync(file, "utf8");
+    const match = doc.match(/\*\*(\d+) typed tools\*\*/);
+    if (!match) {
+        fail(`${file}: could not find a "**N typed tools**" figure to check against`);
+        continue;
+    }
+    const documented = Number(match[1]);
+    if (documented !== toolCount) {
+        fail(
+            `${file} documents ${documented} tools but index.js registers ${toolCount} — ` +
+                `update the docs in the same change (see "Keeping this file updated")`,
+        );
+    }
+}
+
+// README lists every tool in a table; make sure the listing is complete too.
+const readme = readFileSync("README.md", "utf8");
+const undocumented = names.filter((n) => !readme.includes(`\`${n}\``));
+if (undocumented.length > 0) {
+    fail(`tools missing from the README tool tables: ${undocumented.join(", ")}`);
+}
+
+// ── Version consistency ──────────────────────────────────────────────────────
+// The version lives in two places: package.json and the McpServer declaration.
+// They drift silently — nothing reads both — and the failure surfaces only at
+// `npm publish`, as "cannot publish over the previously published versions",
+// after the release has already been tagged and pushed.
+const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+const serverVersion = source.match(/new McpServer\(\{[^}]*version:\s*"([^"]+)"/s)?.[1];
+
+if (!serverVersion) {
+    fail("could not find the McpServer version declaration in index.js");
+} else if (serverVersion !== pkg.version) {
+    fail(
+        `version mismatch: package.json is ${pkg.version} but index.js declares ${serverVersion} — ` +
+            `bump both`,
+    );
+}
+
+// AGENTS.md documents each release; a bump with no matching entry means the
+// release notes are already behind.
+const agents = readFileSync("AGENTS.md", "utf8");
+if (pkg.version && !agents.includes(`**${pkg.version}**`)) {
+    fail(`AGENTS.md has no "**${pkg.version}**" release entry — document the release in the same change`);
+}
+
+// ── Secret masking ───────────────────────────────────────────────────────────
+// sanitise() is the only thing keeping env vars, database passwords and freshly
+// minted tokens out of a transcript, and it works by being applied centrally in
+// api(). Unwiring that one call is a silent, total regression — every tool keeps
+// working and every response starts leaking. This is the tripwire for it.
+if (!/return sanitise\(JSON\.parse\(raw\)\)/.test(source)) {
+    fail("api() no longer passes its parsed response through sanitise() — every tool now leaks secrets");
+}
+if (!/function sanitise\(/.test(source) || !/function mask\(/.test(source)) {
+    fail("sanitise()/mask() are missing from index.js");
+}
+// The masking must default to on; only an explicit opt-in env var disables it.
+if (!/const ALLOW_SECRETS = process\.env\.LATTICE_ALLOW_SECRET_VALUES === "1"/.test(source)) {
+    fail("the masking opt-out is not the expected LATTICE_ALLOW_SECRET_VALUES === \"1\" check — masking may no longer default to on");
+}
+
+// ── Report ───────────────────────────────────────────────────────────────────
+if (failures.length > 0) {
+    console.error("verification failed:\n");
+    for (const f of failures) console.error(`  ✗ ${f}`);
+    process.exit(1);
+}
+
+console.log(`✓ index.js parses`);
+console.log(`✓ version ${pkg.version} consistent across package.json, index.js and AGENTS.md`);
+console.log(`✓ ${toolCount} tools registered, no duplicates, all lattice_-prefixed`);
+console.log(`✓ README.md and AGENTS.md agree on the tool count`);
+console.log(`✓ every tool appears in the README tool tables`);
+console.log(`✓ sanitise() is wired into api() and masking defaults to on`);