@layers/amba-mcp 1.0.1 → 4.0.3

package/dist/tools/auth.d.ts

@@ -16,18 +16,41 @@
  *      server's public-tools allowlist lets signup/login/refresh through
  *      unauthenticated.
  *   2. The signup response includes:
- *        - `pat`         — a long-lived Personal Access Token. Use the
- *                          PAT for agent flows: pass it as the inbound
- *                          Bearer for every subsequent MCP call. Survives
- *                          until rotated.
- *        - `project`     — a real isolated Neon-backed project provisioning
- *                          asynchronously. Includes project_id, client_key,
+ *        - `pat`         — a long-lived Personal Access Token.
+ *        - `project`     — a real isolated Amba project (provisioning
+ *                          asynchronously). Includes project_id, client_key,
  *                          server_key, provisioning_status, and verify_url.
- *                          Poll `amba_get_provisioning_status` until the
+ *                          Poll `amba_projects_get_provisioning_status` until the
  *                          workflow completes (~10s) before issuing
  *                          client-plane traffic.
- *   3. Re-issue subsequent MCP calls with `Authorization: Bearer <pat>`.
- *      All downstream tools (`amba_create_project`, etc.) now work.
+ *        - `mcp_config`  — ready-to-paste config snippets for Claude Code,
+ *                          Cursor, and Windsurf. Each entry carries a
+ *                          `path_hint` (where the file usually lives) and a
+ *                          `snippet` (the JSON to merge into that file under
+ *                          `mcpServers.amba`), with the PAT pre-baked into
+ *                          the Bearer header.
+ *        - `agent_instructions` — short prose telling the calling agent
+ *                          exactly what to do: keep calling tools in this
+ *                          same session with the freshly-minted `pat` arg,
+ *                          and write the snippet to the customer's MCP
+ *                          config for future sessions.
+ *   3. Same-session: the PAT is already in hand. Pass it as `pat` on every
+ *      subsequent `amba_*` tool call this session — `packages/mcp/src/lib/with-pat.ts`
+ *      injects a `pat` argument on every non-public tool that overrides
+ *      the inbound Bearer for that one call. No restart, no waiting.
+ *   4. Future sessions: the calling agent writes the matching snippet to
+ *      the customer's MCP client config file (Claude Code: `~/.claude.json`
+ *      or project-local `.mcp.json`; Cursor: `~/.cursor/mcp.json` or
+ *      `.cursor/mcp.json`; Windsurf: `~/.codeium/windsurf/mcp_config.json`).
+ *      Merge with any existing `mcpServers` block rather than overwriting.
+ *      The next time the MCP client starts, the static
+ *      `Authorization: Bearer <pat>` header takes over automatically — the
+ *      `pat` arg becomes optional. The customer does nothing.
+ *
+ * Browser-based MCP clients (Claude.ai web) cannot read a static config
+ * file — they discover the OAuth authorization server instead. For those
+ * clients the agent should direct the customer to https://mcp.amba.dev/authorize
+ * and complete the OAuth 2.1 + PKCE handshake.
  *
  * The PAT can be rotated via `amba_developer_rotate_pat`. The old PAT
  * stops working immediately on rotation (may take up to 30s to propagate).

package/dist/tools/billing.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Per-project billing tools — the "pricing-as-API" unlock for agentic
+ * onboarding. An AI agent provisioning new features should be able to ask
+ * the platform what tier the project is on, how much headroom is left on
+ * each metered axis, and what (if anything) needs a human in the loop
+ * before the next step.
+ *
+ * Three tools land here:
+ *
+ *   - `amba_billing_status`   — live per-project state (call before
+ *                                 provisioning data-heavy workloads).
+ *   - `amba_billing_tiers`    — static catalog of tiers + overage rates
+ *                                 (hardcoded so reasoning works offline
+ *                                 and stays stable when the API is down).
+ *   - `amba_billing_set_ceiling` — write-side: cap the monthly bill or
+ *                                 remove the cap. Surface to the human
+ *                                 before calling.
+ *
+ * The status + set-ceiling tools call REST endpoints that W2-B is
+ * shipping in parallel (`GET/PUT /v1/admin/projects/:id/billing/...`).
+ * If those endpoints aren't live yet the calls will surface as 404s
+ * via the standard `AmbaApiError` path — no special-casing here.
+ *
+ * No vendor leakage: field names + descriptions stay in Amba's
+ * customer-facing vocabulary (tier, headroom, paused_at, spend_ceiling).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/collections.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Collection MCP tools — admin (schema + admin-side row CRUD) and
+ * client (end-user row CRUD with auto-RLS) surfaces wrapped 1:1 from
+ * `apps/api/src/routes/admin/collections.ts`,
+ * `apps/api/src/routes/admin/collection-rows.ts`, and
+ * `apps/api/src/routes/client/collections.ts`.
+ *
+ * Two distinct authentication models split the toolset:
+ *
+ *   - **Admin tools** (`amba_collections_create`, `amba_collections_alter`,
+ *     `amba_admin_insert_row`, etc.) authenticate the **developer/agent**
+ *     and accept an optional `pat` argument. When omitted, the handler
+ *     falls back to the inbound Bearer the hosted MCP server forwards
+ *     into `ApiClient` (or the CLI's `~/.amba/credentials.json`). Admin
+ *     operations bypass auto-RLS — the developer sees / mutates every
+ *     row regardless of `user_id`.
+ *
+ *   - **Client tools** (`amba_client_*`) authenticate the **end-user**
+ *     and require `api_key` (the project's client X-Api-Key) plus an
+ *     optional `session_token` (the end-user's session Bearer). The
+ *     server enforces auto-RLS — every read/write is scoped to the
+ *     signed-in app_user, no opt-out. Most client tools require a
+ *     `session_token` because the route's `clientSessionAuth` middleware
+ *     demands one.
+ *
+ * Wire shape mirrors the route handlers exactly. See the route source
+ * for the authoritative contract — these tools are a thin pass-through
+ * so future route changes don't force an MCP rewrite.
+ *
+ * Pat-arg pattern: this file inlines the `pat ?? apiClient.resolveTokenOrNull()`
+ * dance described in `packages/mcp/src/lib/with-pat.ts` (task #36's
+ * central helper). When that helper lands, this file should migrate to
+ * `registerTool(...)` without changing tool semantics.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/domains.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Domain purchase MCP tools (T-Registrar / task #25).
+ *
+ * Lets an agent search for an available domain, see its price, and buy it
+ * through Amba — Amba registers the domain and connects it to one of the
+ * project's sites as a live custom domain with no DNS setup by the customer.
+ *
+ * Tools:
+ *   - `amba_domains_search`   — find available domains for a query (free).
+ *   - `amba_domains_check`    — authoritative availability + price for
+ *                               specific domains (free).
+ *   - `amba_domains_purchase` — buy + connect a domain to a site. Returns a
+ *                               QUOTE you must confirm before money moves;
+ *                               re-call with `confirm: true` + the quoted
+ *                               `accept_price_usd` to execute.
+ *   - `amba_domains_list`     — list domains this project has purchased.
+ *
+ * Money safety: `amba_domains_purchase` never charges on the first call. It
+ * returns the price and `confirmation_required: true`; the agent must
+ * surface the cost to the user and re-call with `confirm: true` and
+ * `accept_price_usd` matching the quote. Even then, the platform only
+ * executes a real registration when purchasing is enabled — otherwise it
+ * returns the quote with `gated: true`.
+ *
+ * Provider neutrality: this is "buy a domain through Amba" — the upstream
+ * registrar is never named in tool descriptions or output.
+ *
+ * Authentication: every tool accepts an optional inline `pat` via the
+ * `registerTool` helper (see `../lib/with-pat.ts`).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/email.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Transactional email tools — agentic configuration of templates,
+ * suppressions, sending, and delivery inspection.
+ *
+ * Mirrors the REST surface in `apps/api/src/routes/admin/email.ts` 1:1 so
+ * an agent setting up a project can wire transactional email end-to-end
+ * without leaving the agentic context:
+ *
+ *   amba_email_templates_create     POST   /email/templates   (upsert by name)
+ *   amba_email_templates_list       GET    /email/templates
+ *   amba_email_templates_get        GET    /email/templates/:name
+ *   amba_email_templates_update     PATCH  /email/templates/:name
+ *   amba_email_templates_delete     DELETE /email/templates/:name
+ *   amba_email_suppressions_create  POST   /email/suppressions
+ *   amba_email_suppressions_list    GET    /email/suppressions
+ *   amba_email_suppressions_delete  DELETE /email/suppressions/:email
+ *   amba_email_send                 POST   /email/send
+ *   amba_email_deliveries_list      GET    /email/deliveries
+ *   amba_email_deliveries_get       GET    /email/deliveries/:id
+ *
+ * Descriptions stay provider-neutral — the underlying email delivery
+ * provider is never named.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/functions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Function-deployment MCP tools (#38).
+ *
+ * Surfaces every operation `amba functions ...` exposes through the CLI:
+ * deploy a bundled script, list deployments, describe one, delete a
+ * function (cascade), and full schedule lifecycle (create, pause,
+ * resume, trigger now). Logs read is the last operation in the set —
+ * Workers Logpush events for a single function over a bounded time
+ * range.
+ *
+ * Wire details:
+ *   - All routes mount under `/projects/:projectId/functions/*` on the
+ *     admin API. The `ApiClient` base already includes `/admin`. Every
+ *     interpolation goes through `encodeURIComponent` so a malformed
+ *     `project_id`, function `name`, etc. cannot escape the path
+ *     segment.
+ *   - `amba_functions_deploy` hits the server-side dispatch upload
+ *     route (`POST /functions/deploy`, multipart). The CLI used to
+ *     POST direct to the CDN with the customer's API token; the
+ *     server-side route landed in UNBURY-10 / S-301 so amba owns the
+ *     upstream credential. Same upload here from MCP. Client-side
+ *     bundle size guard mirrors the API's 10 MiB cap to fail fast
+ *     instead of wasting an upload.
+ *   - `amba_functions_delete` requires `?confirm=<name>` per the API's
+ *     guard against typo'd deletes. The tool sets it automatically
+ *     from the validated input.
+ *
+ * Authentication: every tool accepts an optional inline `pat` arg.
+ * Resolution order is `args.pat ?? inbound-Authorization-Bearer`
+ * (see `_pat.ts`).
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/funnels.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/invites.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project membership + invite tools — agentic collaboration.
+ *
+ * Per the wave-2 schema (`infra/neon/control/027_project_billing.sql`),
+ * a project is owned by one developer (the existing `projects.developer_id`
+ * column) but can have additional members invited by email. Roles:
+ *
+ *   - admin: manage members + integrations
+ *   - member: write data
+ *   - viewer: read-only
+ *
+ * Owners cannot be removed; transfer ownership first via
+ * `amba_projects_transfer_owner`. Members can remove themselves.
+ *
+ * The REST endpoints these tools call are shipped by W2-C in parallel
+ * (`/v1/admin/projects/:id/invites`, `.../members`, `.../members/:dev_id`,
+ * `.../transfer-ownership`). If those aren't live yet, calls surface as
+ * 404 via `AmbaApiError`.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/secrets.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Secret MCP tools (#38).
+ *
+ * Wraps the customer secrets proxy (UNBURY-10 / S-401). A secret is either
+ * FUNCTION-SCOPED (`function` set) or PROJECT-WIDE (`function` omitted —
+ * one value visible to every function in the project, including ones
+ * deployed later). The API carries this via the optional `function` field
+ * on POST and the optional `?function=` query param on DELETE. Secrets may
+ * be set BEFORE the function is deployed — the sync drains once a
+ * deployment lands.
+ *
+ * Naming:
+ *   - Secret name: /^[A-Z][A-Z0-9_]{0,62}$/ (uppercase env-var shape).
+ *   - Function name: /^[a-z][a-z0-9_-]{0,57}$/ (matches the function
+ *     deploy validator one-for-one).
+ *
+ * Reserved binding names (AMBA_INTERNAL_TOKEN, EDGE_HEADER_SIGNING_SECRET,
+ * STORAGE, EDGE_DB_PROXY, AMBA_API_URL, AMBA_AI_GATEWAY_URL,
+ * AMBA_PROJECT_ID) are blocked at the API layer — the proxy returns
+ * 400 RESERVED_BINDING. Don't try to shadow them.
+ *
+ * Plaintext values are NEVER returned. `amba_secrets_list` returns
+ * name + version + sync_status (pending/syncing/synced/failed) only.
+ *
+ * Authentication: every tool accepts an optional inline `pat` arg via the
+ * `registerTool` helper in `../lib/with-pat.ts`. Resolution: `args.pat ??
+ * inbound-Authorization-Bearer`, with `MISSING_PAT` short-circuit if neither.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/setup.d.ts

@@ -1,3 +1,3 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ApiClient } from '../api-client.js';
-export declare function registerTools(server: McpServer, _apiClient: ApiClient): void;
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/sites.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Static-site MCP tools (#38).
+ *
+ * Mirrors the CLI's `amba sites ...` surface so an agent can register a
+ * static site, deploy files, attach custom domains, and tear everything
+ * down — all through MCP, no human-in-loop.
+ *
+ * Wire details:
+ *   - `amba_sites_deploy` is create-or-deploy in one shot: it POSTs `/sites`
+ *     to mint the row (tolerating `ALREADY_EXISTS`), then POSTs the
+ *     per-file multipart bundle to `/sites/:name/deployments`. The two-call
+ *     pattern matches the CLI's flow exactly, just collapsed for agent
+ *     ergonomics — one tool call, one canonical public URL out. The
+ *     409-tolerance branch is now driven by the upstream `error.code`
+ *     (via `AmbaApiError`), not regex over the prose, so an unrelated
+ *     409 (e.g. quota) is NOT silently swallowed.
+ *   - `amba_sites_add_domain` runs the upstream custom hostname
+ *     registration server-side (Wave-3 / #100); customers no longer
+ *     need a direct upstream API token client-side.
+ *   - `amba_sites_remove_domain` is idempotent — a 404 from the API is
+ *     treated as success (the row was already gone).
+ *
+ * Files: pass an object keyed by repo-relative path
+ * (e.g. {"index.html": "<!doctype html>...", "assets/main.css": "..."}).
+ * Each value is the file content as a string. Per-file cap is 25 MiB.
+ *
+ * Hostname inputs are lowercased at the tool boundary (HTTP semantics
+ * + matches the API's storage normalisation) so a customer typing
+ * "App.Example.com" doesn't end up with an unfindable binding.
+ *
+ * Authentication: every tool accepts an optional inline `pat` arg via the
+ * `registerTool` helper in `../lib/with-pat.ts`. Resolution: `args.pat ??
+ * inbound-Authorization-Bearer`, with `MISSING_PAT` short-circuit if neither.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/dist/tools/webhooks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Outbound webhook subscription tools — agentic configuration of
+ * server-to-server event delivery.
+ *
+ * A webhook subscription registers an HTTPS endpoint that Amba POSTs to
+ * (HMAC-signed) whenever a matching engagement event fires. These tools
+ * mirror the REST surface 1:1 so an agent can stand up, inspect, test, and
+ * troubleshoot subscriptions without leaving the agentic context:
+ *
+ *   amba_webhooks_create            POST   /webhooks/subscriptions
+ *   amba_webhooks_list              GET    /webhooks/subscriptions
+ *   amba_webhooks_get               GET    /webhooks/subscriptions/:id
+ *   amba_webhooks_update            PATCH  /webhooks/subscriptions/:id
+ *   amba_webhooks_delete            DELETE /webhooks/subscriptions/:id
+ *   amba_webhooks_rotate_secret     POST   /webhooks/subscriptions/:id/rotate-secret
+ *   amba_webhooks_test              POST   /webhooks/subscriptions/:id/test
+ *   amba_webhooks_deliveries_list   GET    /webhooks/deliveries
+ *   amba_webhooks_deliveries_get    GET    /webhooks/deliveries/:id
+ *   amba_webhooks_deliveries_replay POST   /webhooks/deliveries/:id/replay
+ *
+ * Param schemas are derived from the REST request shapes in
+ * `apps/api/src/routes/admin/webhooks.ts`. Descriptions stay
+ * provider-neutral — the underlying delivery infrastructure is never named.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+export declare function registerTools(server: McpServer, apiClient: ApiClient): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba-mcp",
-  "version": "1.0.1",
+  "version": "4.0.3",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -12,6 +12,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./prompts": {
+      "types": "./dist/resources/prompts.d.ts",
+      "import": "./dist/resources/prompts.js"
     }
   },
   "files": [
@@ -22,12 +26,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^3.25.0",
-    "@layers/amba-shared": "1.0.0"
+    "@layers/amba-shared": "4.0.3"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "tsdown": "^0.12.5",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
   },
   "repository": {
     "type": "git",
@@ -43,9 +48,10 @@
   },
   "description": "MCP server tools for amba — agentic developer onboarding, project provisioning, and SDK introspection over the Model Context Protocol.",
   "scripts": {
-    "build": "tsdown && tsc --emitDeclarationOnly",
+    "build": "tsdown && tsc --emitDeclarationOnly --project tsconfig.build.json",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "clean": "rm -rf dist"
   }
 }