@layers/amba-mcp 4.0.10 → 4.0.12

package/README.md

@@ -33,7 +33,7 @@ registerAllTools(server, apiClient);
 
 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 — 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. While new accounts are invite-only, include `invite_code`; a missing or rejected code answers 403 `INVITE_REQUIRED` / `INVITE_INVALID` (and `SIGNUPS_CLOSED` when no accounts are being created), with `error.details.request_access_url` pointing at the request-access page.
 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"` before issuing client traffic.
 

package/dist/api-client.d.ts

@@ -20,9 +20,33 @@
 export declare class AmbaApiError extends Error {
     readonly status: number;
     readonly code: string | undefined;
-    constructor(status: number, code: string | undefined, message: string);
+    /** The API's own `error.message`, without the `API error <status>:` prefix. */
+    readonly apiMessage: string;
+    /**
+     * The API's `error.details`, when the response carried one: for example a
+     * 402 `FREE_TIER_LIMIT_REACHED` names the limit, the reset date, the
+     * billing URL and the one-call upgrade there. Tool results pass it to the
+     * agent (`lib/tool-result.ts` `apiErrorResult`).
+     */
+    readonly details: unknown;
+    constructor(status: number, code: string | undefined, message: string, details?: unknown);
 }
+/**
+ * Read a non-2xx response's `{ error: { code, message, details } }` envelope
+ * into an `AmbaApiError`. A body that is not that JSON envelope falls back to
+ * the status text.
+ */
+export declare function ambaApiErrorFromResponse(res: Response): Promise<AmbaApiError>;
 export interface ApiClientOptions {
+    /**
+     * Extra headers sent on the public developer-auth calls (signup, login,
+     * refresh and friends; see `tools/auth.ts`). The hosted MCP server uses
+     * this to attest the calling agent's IP to apps/api
+     * (`X-Amba-Client-IP` + `X-Amba-Proxy-Secret`), so per-IP signup and login
+     * limits key on the agent's IP and the MCP server's egress IP stays out of
+     * the bucket key. Local and CLI usage leaves it unset.
+     */
+    authProxyHeaders?: Record<string, string>;
     baseUrl?: string;
     /**
      * Optional override for token resolution. When provided, the client uses
@@ -34,11 +58,20 @@ export interface ApiClientOptions {
      * tokens transparently. Sync values should be wrapped in `() => Promise.resolve(token)`.
      */
     getToken?: () => Promise<string>;
+    /**
+     * Signup token forwarded on `/auth/developer/signup` as
+     * `X-Amba-Signup-Token`. The hosted MCP server copies it from the inbound
+     * request header of the same name so Amba's CI can sign up through MCP
+     * while public signup is closed. Unset for every other caller.
+     */
+    signupToken?: string;
 }
 export declare class ApiClient {
+    private authProxyHeaders;
     private baseUrl;
     private apiRoot;
     private tokenProvider?;
+    private signupToken?;
     constructor(options?: ApiClientOptions);
     /**
      * Return a sibling `ApiClient` bound to a different Bearer token.
@@ -54,6 +87,8 @@ export declare class ApiClient {
      * routing stays identical — only the token provider differs.
      */
     withToken(token: string): ApiClient;
+    /** The signup token to forward on `/auth/developer/signup`, if any. */
+    getSignupToken(): string | undefined;
     /**
      * Returns the configured admin-prefixed base URL (e.g.
      * `https://api.amba.dev/admin`). Auth tools (`amba_developer_signup`,
@@ -68,6 +103,13 @@ export declare class ApiClient {
      * normalisation. The constructor enforces the `/admin` suffix invariant.
      */
     getApiRoot(): string;
+    /**
+     * Headers to add to public developer-auth calls (see
+     * `ApiClientOptions.authProxyHeaders`). Those calls always run on the
+     * client the tools were registered with, so a `withToken` sibling does not
+     * need to carry them.
+     */
+    getAuthProxyHeaders(): Record<string, string>;
     /**
      * Resolve the current developer Bearer token, going through the configured
      * tokenProvider (or `~/.amba/credentials.json` for the CLI fallback).
@@ -79,6 +121,16 @@ export declare class ApiClient {
      */
     resolveTokenOrNull(): Promise<string | null>;
     private getToken;
+    /**
+     * Account notices (`X-Amba-Notice`, e.g. the unclaimed-sandbox claim
+     * instruction) seen on responses since the last `takeNotices()`. The
+     * `registerTool` wrapper drains them into the tool result so the agent
+     * reads them alongside the data it asked for.
+     */
+    private readonly notices;
+    /** Return and clear the notices collected since the last call. */
+    takeNotices(): string[];
+    private captureNotice;
     private request;
     get<T>(path: string, query?: Record<string, string>): Promise<T>;
     post<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;

package/dist/expo-build-prompt.js

@@ -94,6 +94,8 @@ Tell the user where their credentials live:
 - \`project_id\`, \`client_key\` — the values they paste into their app's \`.env.local\` / \`.env\`.
 - \`server_key\` — never ship to user devices; only into a server \`.env\` or a secret manager. The \`amb_dev_sk_\` / \`amb_live_sk_\` prefix is the marker.
 
+**Signup refused with 403 \`INVITE_REQUIRED\` or \`INVITE_INVALID\`?** New accounts need an invite code right now. Ask the developer for theirs (it starts with \`AMBA-\` and arrives in their invite email) and call \`amba_developer_signup\` again with the same arguments plus \`invite_code\`. If they have no code, or the answer is \`SIGNUPS_CLOSED\`, offer to request access for them: \`POST https://api.amba.dev/v1/auth/developer/waitlist\` with \`{ "email": "<their own email>", "note": "<optional>" }\`, or send them to the \`error.details.request_access_url\` page. Tell them the invite code arrives by email, then stop. Retry only with a code the developer hands you; never retry in a loop, invent codes, or try other email addresses. From a terminal, the code goes to \`npx @layers/amba init --invite <code>\` (or the \`AMBA_INVITE_CODE\` env var).
+
 **Already have a PAT?** Skip the signup. Call \`amba_developer_me({})\` to verify the Bearer; if it succeeds, either reuse the most recent project (\`amba_projects_list\`) or call \`amba_projects_create({ name: "<app-name>", platform: "all" })\` and then \`amba_api_keys_create\` twice to mint client + server keys for \`environment: "development"\`.
 
 **Can't reach \`amba_developer_signup\` — it's not in your tool list, or your harness blocks the call?** Do NOT try to work around it by adding the MCP server yourself, running an installer, or editing your own settings/permissions — refusing to self-modify or widen your own permissions is the correct call, and you should not circumvent it. Instead, hand the developer **one** command to run in **their own** terminal (which is not subject to your sandbox):
@@ -247,8 +249,8 @@ Be specific. List resources by key, not "some achievements". If something needs
 ## Get credentials (cheat sheet)
 
 - No terminal, in an MCP client: call \`amba_developer_signup\` (no Bearer required) — this guide's Step 0.
-- With a terminal: \`npx -y @layers/amba init\` signs up, mints a project + client/server keys, writes \`.env.local\` + \`AMBA.md\`, installs the \`/amba\` skill, and wires \`mcpServers.amba\` into every detected MCP-client config in one command. Auto-detects non-TTY invocations (the coding-agent bash-tool case) and runs headlessly.
-- Bind the sandbox account to a real email later: \`npx @layers/amba claim me@example.com\`. The backend emails a one-click magic link; clicking it lifts the sandbox cap to the Free tier.
+- With a terminal: \`npx -y @layers/amba init\` signs up, mints a project + client/server keys, writes \`.env.local\` + \`AMBA.md\`, installs the \`/amba\` skill, and wires \`mcpServers.amba\` into every detected MCP-client config in one command. Auto-detects non-TTY invocations (the coding-agent bash-tool case) and runs headlessly. While signups are invite-only, add \`--invite <code>\` (or set \`AMBA_INVITE_CODE\`).
+- Bind the sandbox account to its human owner as soon as you know who that is: \`amba_developer_claim\` with their email (or \`npx @layers/amba claim me@example.com\`). The backend emails a one-click magic link; clicking it lifts the sandbox cap to the Free tier. Each free project of an unclaimed sandbox runs its own clock from when it was created: a claim notice from day 7, a hold on day 14, and an archive on day 90 after a full hold (archiving deletes nothing); claiming lifts all of it.
 - Hosted MCP endpoint: \`https://mcp.amba.dev/mcp\` (Streamable HTTP, Bearer auth).
 
 ## SDKs

package/dist/index.d.ts

@@ -38,6 +38,9 @@ export declare function registerAllTools(server: McpServer, apiClient: ApiClient
 export declare function createApiClient(options: {
     baseUrl?: string;
     token?: string;
+    signupToken?: string;
+    /** See `ApiClientOptions.authProxyHeaders`. */
+    authProxyHeaders?: Record<string, string>;
 }): ApiClient;
 export { ApiClient } from './api-client.js';
 export type { ApiClientOptions } from './api-client.js';