npm - lattice-mcp - Versions diffs - 1.1.0 → 1.1.1 - Mend

lattice-mcp 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/AGENTS.md CHANGED Viewed

@@ -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.
@@ -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,42 @@ 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);
+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 + 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.
 **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 +205,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 CHANGED Viewed

@@ -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,36 +140,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` | 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 |
-## 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 +174,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 +199,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 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
-⚠️ = 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 CHANGED Viewed

@@ -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.1",
 });
 // Overview
@@ -559,9 +574,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 +697,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 +989,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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lattice-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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"
   }
 }