@layers/amba-mcp 1.0.0 → 4.0.2

package/README.md

@@ -1,29 +1,24 @@
 # @layers/amba-mcp
 
-Reusable Model Context Protocol (MCP) tool registry for [Amba](https://amba.dev) — the agent-native backend-as-a-service for mobile apps.
+Amba is the agent-native backend-as-a-service for mobile and web apps. This package is the Model Context Protocol (MCP) tool registry that lets an AI agent drive the Amba admin API directly.
 
-This package exposes ~178 MCP tools across ~17 groups (projects, push, segments, config, content, users, achievements, challenges, economy, leaderboards, platform, social, xp, events, auth, and more) that an AI agent can call against the Amba admin API.
-
-It is the same registry consumed by the hosted MCP server at `mcp.amba.dev`.
+It exposes ~178 tools across ~17 groups (projects, push, segments, config, content, users, achievements, challenges, economy, leaderboards, platform, social, xp, events, auth, …) and is the same registry that powers the hosted MCP server at `mcp.amba.dev`.
 
 ## Install
 
 ```bash
-npm install @layers/amba-mcp
+npm install @layers/amba-mcp@1.0.1
 ```
 
-## Usage
+## Configure + first call
 
-`@layers/amba-mcp` is a tool registry. It registers tools against an injected `McpServer` and `ApiClient`. It does NOT bootstrap a transport — your code does.
+This package is a tool registry, not a transport. You mount it into your own MCP server:
 
 ```ts
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerAllTools, createApiClient } from '@layers/amba-mcp';
 
-const server = new McpServer({
-  name: 'amba-mcp',
-  version: '0.1.0',
-});
+const server = new McpServer({ name: 'amba-mcp', version: '1.0.0' });
 
 const apiClient = createApiClient({
   baseUrl: 'https://api.amba.dev/v1/admin',
@@ -31,19 +26,22 @@ const apiClient = createApiClient({
 });
 
 registerAllTools(server, apiClient);
-
-// Mount `server` behind any MCP transport (stdio, Streamable HTTP, SSE, ...).
+// Then mount `server` behind any MCP transport (stdio, Streamable HTTP, SSE).
 ```
 
-### Authenticating
-
-Every tool except the public auth tools (`amba_developer_signup`, `_login`, `_refresh`) requires a developer Bearer token. Pass it explicitly via `createApiClient({ token })`, or omit `token` to fall back to the CLI credential file at `~/.amba/credentials.json`.
+### Bootstrap with no browser
 
-For agent flows the recommended bootstrap is:
+Every tool except the public auth tools (`amba_developer_signup`, `amba_developer_login`, `amba_developer_refresh`) requires a developer Bearer token.
 
-1. Call `amba_developer_signup` with no Authorization header to create an account. The response includes a long-lived Personal Access Token (`pat`) and a freshly provisioned project.
+1. Call `amba_developer_signup` with no Authorization header — the response includes a long-lived Personal Access Token (`pat`) and a freshly provisioned project.
 2. Pass the `pat` as the inbound Bearer on every subsequent MCP call.
-3. Poll `amba_get_provisioning_status` until the project flips to `status='active'` (~10s) before issuing client-plane traffic.
+3. Poll `amba_get_provisioning_status` until the project flips to `status: "active"` before issuing client traffic.
+
+Omit `token` on `createApiClient` to fall back to the CLI credential file at `~/.amba/credentials.json`.
+
+## Docs
+
+Tool reference: <https://docs.amba.dev/mcp>.
 
 ## License
 

package/dist/api-client.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Structured error thrown by `ApiClient.request` (and by the dev-tooling
+ * `callWithPat` rawFetch path) on any non-2xx response. Preserves the
+ * upstream `error.code` + HTTP `status` so callers can do code-based
+ * branching (e.g. `if (err.code === 'ALREADY_EXISTS')`) instead of
+ * regex-matching the prose of the thrown message.
+ *
+ * Backward-compat: the `message` string still follows the same
+ * `API error ${status}: ${message}` shape that the prior plain-Error
+ * throw used, so any caller that grepped the message keeps working.
+ *
+ * Lives in api-client.ts (not tools/_pat.ts) so both the bound-ApiClient
+ * delegate path AND the rawFetch path throw the same instanceof-able
+ * type — without this, BugBot 2026-05-16 caught that my catch blocks
+ * (`err instanceof AmbaApiError`) on `amba_sites_deploy`,
+ * `amba_sites_remove_domain`, and `amba_functions_delete` were silently
+ * skipped on the no-pat (hosted-MCP-primary) path because that path
+ * threw plain Error.
+ */
+export declare class AmbaApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(status: number, code: string | undefined, message: string);
+}
 export interface ApiClientOptions {
     baseUrl?: string;
     /**
@@ -16,6 +40,20 @@ export declare class ApiClient {
     private apiRoot;
     private tokenProvider?;
     constructor(options?: ApiClientOptions);
+    /**
+     * Return a sibling `ApiClient` bound to a different Bearer token.
+     *
+     * Used by the `pat`-as-tool-argument pattern (`packages/mcp/src/lib/with-pat.ts`):
+     * an agent that just minted a PAT via `amba_developer_signup` cannot
+     * mutate the static HTTP `Authorization` header its MCP client sends
+     * with each request, so every tool accepts a `pat` argument and the
+     * `registerTool` helper calls `withToken(pat)` to override the inbound
+     * Bearer for that one tool invocation.
+     *
+     * The new client shares the same `baseUrl` / `apiRoot` so downstream
+     * routing stays identical — only the token provider differs.
+     */
+    withToken(token: string): ApiClient;
     /**
      * Returns the configured admin-prefixed base URL (e.g.
      * `https://api.amba.dev/admin`). Auth tools (`amba_developer_signup`,
@@ -43,10 +81,10 @@ export declare class ApiClient {
     private getToken;
     private request;
     get<T>(path: string, query?: Record<string, string>): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
-    put<T>(path: string, body?: unknown): Promise<T>;
-    patch<T>(path: string, body?: unknown): Promise<T>;
-    delete<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
+    patch<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
+    delete<T>(path: string, query?: Record<string, string>): Promise<T>;
     /**
      * GET that returns the raw response body as a string and only reads up to
      * `maxBytes` bytes. Used by export tools that hit CSV/NDJSON streaming

package/dist/categories.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical 7-category taxonomy for Amba MCP tools.
+ *
+ * Mirrors the marketing-site taxonomy
+ * (`apps/marketing-site/app/components/feature-grid.tsx`) and the docs IA
+ * (`apps/docs/content/docs/meta.json`). Keep them in lock-step; the
+ * council audit at `.council-reports/skill-06-positioning.md` is the
+ * canonical reference and documents why the count is 7, not 9 or 19.
+ *
+ * The MCP protocol itself has no native "category" field — `ToolAnnotations`
+ * is a closed set (title, readOnlyHint, destructiveHint, idempotentHint,
+ * openWorldHint). So this module exposes the category metadata as a
+ * separate, type-safe API for surfaces that consume the registry
+ * (mcp-server resource pages, console tool browsers, MCP-tools docs).
+ *
+ * Lookup is by tool name. Both the canonical name and any legacy alias
+ * registered in `tools/__test-fixtures__/rename-map.ts` resolve to the
+ * same category so callers don't need to canonicalize first.
+ */
+/** The 7 canonical Amba categories. */
+export type AmbaCategory = 'identity' | 'engagement' | 'gamification' | 'economy' | 'social' | 'analytics' | 'infrastructure';
+/** Display-friendly metadata for each category. */
+export declare const CATEGORY_META: Record<AmbaCategory, {
+    readonly title: string;
+    readonly blurb: string;
+    readonly order: number;
+}>;
+/** Display order for callers that need it. */
+export declare const CATEGORY_ORDER: ReadonlyArray<AmbaCategory>;
+/**
+ * Exhaustive tool-name → category map. Includes BOTH the canonical
+ * `amba_<resource>_<verb>` names AND the legacy aliases listed in
+ * `tools/__test-fixtures__/rename-map.ts`. Lookup via `getToolCategory`
+ * is therefore alias-agnostic.
+ *
+ * Edits land here when a new MCP tool is registered. The
+ * `categories.test.ts` companion asserts every registered tool name has
+ * a mapping — drift surfaces at test time, not in production.
+ */
+export declare const TOOL_CATEGORY: Readonly<Record<string, AmbaCategory>>;
+/**
+ * Look up the canonical category for an MCP tool name. Accepts both
+ * canonical names and legacy aliases. Returns `null` for unknown names —
+ * the test suite asserts every registered tool has a mapping, so a
+ * `null` at runtime indicates a registration that drifted ahead of
+ * the taxonomy.
+ */
+export declare function getToolCategory(toolName: string): AmbaCategory | null;