@layers/amba-mcp 4.0.6 → 4.0.7

package/dist/auto/collection-tools.d.ts

@@ -2,27 +2,35 @@
  * `registerCollectionToolsFor` — project ONE collection into a set of
  * typed MCP tools and register them on a server.
  *
- * Phase 1 = admin scope. Each tool is a thin proxy over the EXISTING
- * authoritative admin collection routes (`/v1/admin/projects/:p/
- * collections/:name/...`) — we do NOT reimplement any query logic. The
- * tool's value is the *projection*: typed per-column input + an SDK-grade
- * description, generated from the live schema (`schema-to-zod.ts` +
- * `describe.ts`).
+ * Two scopes, two enforcement paths — both thin proxies over EXISTING
+ * authoritative routes (we do NOT reimplement any query logic):
  *
- * Tools generated (verbs that map to a real admin route):
- *   <ns>_<coll>_list      → GET    /collections/:name/rows?query=…
- *   <ns>_<coll>_get       → GET    /collections/:name/rows/:id
- *   <ns>_<coll>_find      → GET    /collections/:name/rows?query=… (typed where)
- *   <ns>_<coll>_insert    → POST   /collections/:name/rows
- *   <ns>_<coll>_update    → PATCH  /collections/:name/rows/:id
- *   <ns>_<coll>_delete    → DELETE /collections/:name/rows/:id
- *   <ns>_<coll>_aggregate → POST   /collections/:name/rows/aggregate
+ *   - `admin`  → `/v1/admin/projects/:p/collections/:name/rows*` with the
+ *     developer Bearer (pat-as-argument machinery). No per-user scoping —
+ *     the developer sees every row.
+ *   - `client` → `/v1/client/collections/:name*` with the project API key
+ *     + the end-user session Bearer. The client routes derive their SQL
+ *     predicate from the migration-053 access policies
+ *     (`_amba_collection_policies`) on every call, so the generated tools
+ *     inherit RLS enforcement byte-for-byte from the REST surface — the
+ *     MCP layer can't bypass a policy because it never compiles a query.
  *
- * `find_nearest` is intentionally Phase 2 (client scope + vector route).
+ * Tools generated (verbs that map to a real route):
+ *   <ns>_<coll>_list         → list rows (cursor pagination)
+ *   <ns>_<coll>_get          → one row by id
+ *   <ns>_<coll>_find         → typed per-column `where`
+ *   <ns>_<coll>_insert       → insert one row
+ *   <ns>_<coll>_update       → merge-patch one row
+ *   <ns>_<coll>_delete       → delete one row (hard-delete admin-only)
+ *   <ns>_<coll>_aggregate    → count/sum/avg/min/max
+ *   <ns>_<coll>_find_nearest → vector search (client scope, only when the
+ *                              collection has a vector column — the route
+ *                              lives on the client surface)
  *
- * Auth: every tool goes through `registerTool` (the pat-as-argument
- * helper), so the developer Bearer flows from the inbound request OR a
- * per-call `pat` arg, exactly like the platform collection tools.
+ * Pagination: list/find default to `created_at desc` ordering when the
+ * caller gives no `order` — a deterministic single-column order is what
+ * makes the route hand back a bootstrap `next_cursor` on the FIRST page,
+ * so an agent can paginate without ever reading docs.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ApiClient } from '../api-client.js';
@@ -33,6 +41,18 @@ export interface CollectionPolicy {
     read_policy: 'owner' | 'public';
     write_policy: 'owner' | 'authenticated';
 }
+/**
+ * Client-scope credentials + addressing. `baseUrl` points at the client
+ * API surface (e.g. `https://api.amba.dev/v1/client`); `sessionToken` is
+ * the END-USER session JWT — absent for key-only callers, in which case
+ * the routes reject user-scoped operations themselves (thin proxy, no
+ * local policy logic).
+ */
+export interface AppMcpClientAuth {
+    apiKey: string;
+    sessionToken?: string;
+    baseUrl: string;
+}
 export interface RegisterCollectionToolsOptions {
     /** Project the collection belongs to. */
     projectId: string;
@@ -44,8 +64,10 @@ export interface RegisterCollectionToolsOptions {
     schema: CollectionSchemaPayload;
     /** The collection's effective access policy. */
     policy: CollectionPolicy;
-    /** Scope to generate for. Phase 1 ships `admin`. */
+    /** Scope to generate for. */
     scope: ToolScope;
+    /** REQUIRED when `scope === 'client'` — the credentials to proxy with. */
+    clientAuth?: AppMcpClientAuth;
 }
 /**
  * Tool-name fragment regex. MCP + `tool-naming.test.ts` require lowercase
@@ -58,6 +80,6 @@ export declare function sanitizeNameFragment(raw: string): string;
 export declare function collectionToolName(namespace: string, collection: string, verb: string): string;
 /**
  * Register the typed CRUD tools for a single collection on `server`,
- * proxying to the existing admin routes via `apiClient`.
+ * proxying to the existing authoritative routes for the requested scope.
  */
 export declare function registerCollectionToolsFor(server: McpServer, apiClient: ApiClient, options: RegisterCollectionToolsOptions): void;

package/dist/auto/describe.d.ts

@@ -8,9 +8,10 @@
  * column names, types, nullability, the access policy in plain words, and
  * a worked example per verb.
  *
- * Pure string builders — snapshot-friendly, no I/O. NO provider leakage:
- * "collection", "row", "column", "function" only — never the underlying
- * storage engine.
+ * Pure string builders — snapshot-friendly, no I/O. Collections are named as
+ * what they are — relational Postgres tables. The hosting supplier (Neon) and
+ * the rest of the infra stack stay hidden: "collection", "row", "column",
+ * and "function" are the customer vocabulary, never a supplier name.
  */
 import { type MappedCollection } from './schema-to-zod.js';
 /** The verbs a collection projects into tools. */
@@ -35,5 +36,22 @@ export interface DescribeContext {
 export declare function describeCollectionTool(verb: CollectionVerb, ctx: DescribeContext): string;
 /** Description for the `<ns>_list_collections` meta tool. */
 export declare function describeListCollections(namespace: string): string;
+/** Context for a function tool description. */
+export interface DescribeFunctionContext {
+    /** Function name (customer-facing). */
+    fn: string;
+    /** Customer-declared tool description (deploy annotation), if any. */
+    declaredDescription: string | null;
+    /** Whether a declared input schema typed this tool. */
+    hasDeclaredSchema: boolean;
+    /** Whether the function was deployed `public: true`. */
+    isPublic: boolean;
+}
+/**
+ * Generate the description string for a function tool. Honest-confidence
+ * rule: a tool with a declared schema reads like a hand-built SDK call; a
+ * tool WITHOUT one says so plainly instead of over-claiming.
+ */
+export declare function describeFunctionTool(ctx: DescribeFunctionContext): string;
 /** Description for the `<ns>_whoami` meta tool. */
 export declare function describeWhoami(namespace: string): string;

package/dist/auto/function-tools.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `registerFunctionToolsFor` — project ONE deployed function into an MCP
+ * tool (auto-MCP Phase 2, slices C/I).
+ *
+ * Execution is the EXISTING function-execution path: the tool handler
+ * POSTs to the function's `invoke_url` (from the manifest — the same URL
+ * every other caller uses) with the connection's client credential
+ * (`X-Api-Key` + optional end-user session Bearer). The execution edge
+ * remains authoritative for auth, rate limits, and identity-header
+ * signing — the MCP layer adds nothing it would have to keep in sync.
+ *
+ * CLIENT SCOPE ONLY. The function-execution path authenticates callers
+ * with a project API key (+ optional session); a developer Bearer is not
+ * a credential it accepts, so an admin-scoped connection gets no function
+ * tools (the meta tools say so) rather than tools that can only fail.
+ *
+ * Input typing (honest-confidence tiers):
+ *   - declared `input_schema` (deploy annotation, validated subset) →
+ *     fully typed tool; args ARE the request body.
+ *   - no declared schema → generic `{ body?, query? }` wrapper with a
+ *     description that says exactly that.
+ *
+ * Tool name: `<ns>_fn_<name>`. The `fn` infix keeps the function
+ * namespace disjoint from `<ns>_<collection>_<verb>` — a function named
+ * `recipes_list` can never collide with the typed tools of a collection
+ * named `recipes`.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AppMcpClientAuth } from './collection-tools.js';
+/** One exposed function from the app-MCP manifest. */
+export interface AppMcpManifestFunction {
+    name: string;
+    description?: string | null;
+    input_schema?: Record<string, unknown> | null;
+    public?: boolean;
+    invoke_url: string;
+}
+export interface RegisterFunctionToolsOptions {
+    /** Tool-name namespace (sanitized app slug or project id). */
+    namespace: string;
+    /** Manifest entry for the function. */
+    fn: AppMcpManifestFunction;
+    /** Connection credentials proxied to the execution path. */
+    clientAuth: Pick<AppMcpClientAuth, 'apiKey' | 'sessionToken'>;
+}
+/** Build the `<ns>_fn_<name>` tool name. */
+export declare function functionToolName(namespace: string, fn: string): string;
+/**
+ * Register the tool for a single exposed function on `server`.
+ */
+export declare function registerFunctionToolsFor(server: McpServer, options: RegisterFunctionToolsOptions): void;

package/dist/auto/index.d.ts

@@ -2,46 +2,87 @@
  * Auto-MCP wedge entry — `registerAutoMcpTools`.
  *
  * The per-tenant MCP surface: instead of Amba's own platform tools, this
- * registers tools that ARE the customer's own collections, projected into
- * typed per-collection tools (`<ns>_<coll>_list/get/find/insert/update/
- * delete/aggregate`) plus two meta tools:
+ * registers tools that ARE the customer's own collections and deployed
+ * functions, projected into typed tools (`<ns>_<coll>_list/get/find/
+ * insert/update/delete/aggregate[/find_nearest]`, `<ns>_fn_<name>`) plus
+ * two meta tools:
  *
- *   - `<ns>_list_collections` — the index of exposed collections.
+ *   - `<ns>_list_collections` — the index of exposed collections/functions.
  *   - `<ns>_whoami`           — which project + scope this surface serves.
  *
- * Generation is LIVE (design doc §2.3): on registration we list the
- * project's collections and introspect each via the existing admin
- * routes, then project them. Stateless-per-request (the handler builds a
- * fresh server per HTTP request) makes this clean — no cache in Phase 1.
+ * GENERATION IS MANIFEST-ONLY (Phase 2). The `/app-mcp/manifest` payload
+ * is the single source of truth for what this surface exposes: it is
+ * built server-side from the project's EXPLICIT exposure allowlist
+ * (default-deny — slice H), so the tool layer can never register
+ * something the allowlist didn't opt in. The Phase-1 live-introspection
+ * fallback is gone for exactly that reason: a fallback that enumerates
+ * every collection would silently bypass the allowlist whenever the
+ * manifest endpoint hiccuped. Without a manifest, the meta tools register
+ * a clear diagnostic instead.
  *
- * Phase 1 = admin scope, collections only. Function tools, client scope,
- * and the manifest cache are later phases.
+ * Scopes:
+ *   - `admin`  — developer Bearer; collection tools proxy
+ *     `/v1/admin/.../rows*`. Function tools do NOT register (the
+ *     function-execution path authenticates with client keys, not
+ *     developer Bearers).
+ *   - `client` — project API key + optional end-user session
+ *     (`options.clientAuth`); collection tools proxy
+ *     `/v1/client/collections/*` (migration-053 policy enforcement on
+ *     every call), function tools invoke through the function-execution
+ *     path with the same credential.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ApiClient } from '../api-client.js';
+import { type AppMcpClientAuth } from './collection-tools.js';
+import { type AppMcpManifestFunction } from './function-tools.js';
 import { type ToolScope } from './describe.js';
 import { mapCollectionSchema, type CollectionSchemaPayload } from './schema-to-zod.js';
+/**
+ * One collection entry in the app-MCP manifest (the
+ * `GET /app-mcp/manifest` payload — see apps/api/src/lib/app-mcp-manifest.ts).
+ */
+export interface AppMcpManifestCollection extends CollectionSchemaPayload {
+    read_policy?: 'owner' | 'public';
+    write_policy?: 'owner' | 'authenticated';
+}
+/** The app-MCP manifest payload. */
+export interface AppMcpManifestPayload {
+    project_id: string;
+    version: number;
+    collections: AppMcpManifestCollection[];
+    /** Exposed deployed functions (Phase 2; older APIs omit the field). */
+    functions?: AppMcpManifestFunction[];
+    /** Surface config echo (Phase 2; older APIs omit these). */
+    enabled?: boolean;
+    auth_mode?: 'all' | 'client_only' | 'developer_only';
+    slug?: string | null;
+}
 export interface RegisterAutoMcpOptions {
     /** Project whose collections become the tool surface. */
     projectId: string;
-    /** Scope to generate. Phase 1 ships `admin`. */
+    /** Scope to generate. */
     scope: ToolScope;
     /**
-     * Tool-name namespace. Defaults to a sanitized project id. A future
-     * phase passes the project slug here so multiple connected apps don't
-     * collide.
+     * The manifest (slice F cache). REQUIRED for any data tool to register
+     * — the manifest carries the server-enforced exposure allowlist, and
+     * registering anything without it would bypass that allowlist. Absent
+     * manifest → meta tools only, with a clear diagnostic.
+     */
+    manifest?: AppMcpManifestPayload;
+    /** Client-scope credentials + client API base URL. */
+    clientAuth?: AppMcpClientAuth;
+    /**
+     * Tool-name namespace. Defaults to the manifest's slug when set,
+     * otherwise a sanitized project id.
      */
     namespace?: string;
 }
 /**
  * Register the auto-MCP tool surface for one project on `server`.
  *
- * Lists + introspects the project's collections (admin routes) and
- * registers a typed tool set per collection, plus the two meta tools.
  * Returns the names of the collections that were exposed plus `listOk`
- * (false when the collection listing was incomplete — a paginated page
- * failed — in which case typed tools are deliberately NOT registered so a
- * truncated set never masquerades as the whole project).
+ * (false when no manifest was available — in which case NO data tools
+ * register and the meta tools carry the diagnostic).
  */
 export declare function registerAutoMcpTools(server: McpServer, apiClient: ApiClient, options: RegisterAutoMcpOptions): Promise<{
     namespace: string;
@@ -49,8 +90,11 @@ export declare function registerAutoMcpTools(server: McpServer, apiClient: ApiCl
     listOk: boolean;
 }>;
 export { registerCollectionToolsFor, collectionToolName, sanitizeNameFragment, } from './collection-tools.js';
-export type { CollectionPolicy, RegisterCollectionToolsOptions } from './collection-tools.js';
+export type { AppMcpClientAuth, CollectionPolicy, RegisterCollectionToolsOptions, } from './collection-tools.js';
+export { registerFunctionToolsFor, functionToolName } from './function-tools.js';
+export type { AppMcpManifestFunction, RegisterFunctionToolsOptions } from './function-tools.js';
+export { jsonSchemaPropertyToZod, jsonSchemaToZodShape } from './json-schema-to-zod.js';
 export { mapCollectionSchema };
 export type { CollectionSchemaPayload };
 export { classifyColumn, SERVER_MANAGED_COLUMNS, type CollectionColumn, type ColumnKind, type MappedCollection, } from './schema-to-zod.js';
-export { describeCollectionTool, describeListCollections, describeWhoami, type CollectionVerb, type DescribeContext, type ToolScope, } from './describe.js';
+export { describeCollectionTool, describeFunctionTool, describeListCollections, describeWhoami, type CollectionVerb, type DescribeContext, type DescribeFunctionContext, type ToolScope, } from './describe.js';

package/dist/auto/json-schema-to-zod.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Declared-function-input-schema → zod shape mapper (auto-MCP Phase 2,
+ * slices C/I).
+ *
+ * A deployed function may DECLARE its input schema in the deploy
+ * annotation (`mcp.input_schema`). The API validates the annotation down
+ * to a SUPPORTED SUBSET of JSON Schema at deploy time (see
+ * `apps/api/src/lib/function-mcp-schema.ts`); this module converts that
+ * subset into the `ZodRawShape` the MCP tool registration consumes, so a
+ * declared schema becomes a genuinely typed tool — the agent sees the
+ * function's real parameters, not a `body: object` blob.
+ *
+ * Supported subset (deliberately mirrored with the deploy-time
+ * validator — change both together):
+ *
+ *   - top level: { type: "object", properties, required? }
+ *   - property types: string | number | integer | boolean | object | array
+ *   - per property: description?, enum? (strings/numbers), items?
+ *   - nesting: objects/arrays up to the validator's depth cap
+ *
+ * Fail-safe posture: this runs against schemas the API already validated,
+ * but a manifest could carry an annotation written by an older/newer API.
+ * Any construct we can't map cleanly degrades to `z.unknown()` for that
+ * property (the tool still works; the typing is just looser) — never a
+ * throw, because a registration-time throw would take down the whole
+ * tool surface for one bad annotation.
+ */
+import { z } from 'zod';
+/** Convert one property schema to a zod type. Never throws. */
+export declare function jsonSchemaPropertyToZod(schema: unknown): z.ZodTypeAny;
+/**
+ * Convert a declared top-level input schema to a `ZodRawShape` (the MCP
+ * tool registration input). Returns `null` when the schema is not the
+ * supported `type: "object"` shape — the caller falls back to the
+ * generic `{ body?, query? }` tool input.
+ */
+export declare function jsonSchemaToZodShape(schema: unknown): z.ZodRawShape | null;

package/dist/expo-build-prompt.js

@@ -305,7 +305,7 @@ All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, the
 - **analytics** — funnels + retention. Query via \`amba_analytics_get\`.
 
 ### Infrastructure
-- **collections** — your own typed key-value tables. Define with \`amba_collections_create\`; read/write from SDK \`Amba.client.*\`.
+- **collections** — your own relational Postgres tables (typed columns, foreign keys, transactions, unique indexes, vector search). Define with \`amba_collections_create\`; read/write from SDK \`Amba.client.*\`.
 - **functions** — serverless TypeScript handlers. Deploy with \`amba_functions_deploy\`; schedule with \`amba_functions_schedule\`.
 - **sites** — static site hosting at \`*.app.amba.host\`. Deploy with \`amba_sites_deploy\`.
 - **media** — file storage + CDN. Upload via \`amba_media_upload\`.
@@ -391,7 +391,7 @@ That's the entire setup. The CLI:
    detects on disk — Claude Code, Cursor, Windsurf.
 6. Verifies the PAT against the API and confirms it's good.
 
-The Amba MCP toolset (\`amba_*\` tools — ~130 of them) is available to
+The Amba MCP toolset (\`amba_*\` tools — 500+ of them) is available to
 the agent immediately: pass the freshly-minted \`pat\` as an inline
 argument on every \`amba_*\` call in the current session. The next time
 your MCP client starts it picks the PAT up from the config as the

package/dist/index.d.ts

@@ -41,5 +41,5 @@ export declare function createApiClient(options: {
 }): ApiClient;
 export { ApiClient } from './api-client.js';
 export type { ApiClientOptions } from './api-client.js';
-export { registerAutoMcpTools, registerCollectionToolsFor, collectionToolName, sanitizeNameFragment, mapCollectionSchema, classifyColumn, describeCollectionTool, describeListCollections, describeWhoami, SERVER_MANAGED_COLUMNS, } from './auto/index.js';
-export type { RegisterAutoMcpOptions, CollectionPolicy, RegisterCollectionToolsOptions, CollectionSchemaPayload, CollectionColumn, ColumnKind, MappedCollection, CollectionVerb, DescribeContext, ToolScope, } from './auto/index.js';
+export { registerAutoMcpTools, registerCollectionToolsFor, registerFunctionToolsFor, collectionToolName, functionToolName, sanitizeNameFragment, mapCollectionSchema, classifyColumn, describeCollectionTool, describeFunctionTool, describeListCollections, describeWhoami, jsonSchemaToZodShape, SERVER_MANAGED_COLUMNS, } from './auto/index.js';
+export type { RegisterAutoMcpOptions, AppMcpClientAuth, AppMcpManifestPayload, AppMcpManifestCollection, AppMcpManifestFunction, CollectionPolicy, RegisterCollectionToolsOptions, RegisterFunctionToolsOptions, CollectionSchemaPayload, CollectionColumn, ColumnKind, MappedCollection, CollectionVerb, DescribeContext, DescribeFunctionContext, ToolScope, } from './auto/index.js';