@layers/amba-mcp 4.0.5 → 4.0.7

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

@@ -0,0 +1,85 @@
+/**
+ * `registerCollectionToolsFor` — project ONE collection into a set of
+ * typed MCP tools and register them on a server.
+ *
+ * Two scopes, two enforcement paths — both thin proxies over EXISTING
+ * authoritative routes (we do NOT reimplement any query logic):
+ *
+ *   - `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.
+ *
+ * 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)
+ *
+ * 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';
+import { type ToolScope } from './describe.js';
+import { type CollectionSchemaPayload } from './schema-to-zod.js';
+/** Effective access policy resolved from the describe endpoint. */
+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;
+    /** Tool-name namespace (sanitized app slug or project id). */
+    namespace: string;
+    /** Collection name (customer-facing, no `coll_` prefix). */
+    collection: string;
+    /** The describe-endpoint schema payload. */
+    schema: CollectionSchemaPayload;
+    /** The collection's effective access policy. */
+    policy: CollectionPolicy;
+    /** 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
+ * `_`-separated names. The namespace + collection are sanitized to that
+ * shape so a slug like "My App" or a collection like "MyRecipes" never
+ * produces an invalid tool name.
+ */
+export declare function sanitizeNameFragment(raw: string): string;
+/** Build the `<ns>_<coll>_<verb>` tool name. */
+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 authoritative routes for the requested scope.
+ */
+export declare function registerCollectionToolsFor(server: McpServer, apiClient: ApiClient, options: RegisterCollectionToolsOptions): void;

package/dist/auto/describe.d.ts

@@ -0,0 +1,57 @@
+/**
+ * SDK-grade per-tool description generator for the auto-MCP wedge.
+ *
+ * The wedge is only worth shipping if the generated tools read like a
+ * hand-built typed client, not a thin `find_rows({collection, where})`
+ * wrapper (design doc §7). These descriptions are generated from the live
+ * column list + access policy so an agent never needs external docs:
+ * column names, types, nullability, the access policy in plain words, and
+ * a worked example per verb.
+ *
+ * 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. */
+export type CollectionVerb = 'list' | 'get' | 'find' | 'insert' | 'update' | 'delete' | 'aggregate' | 'find_nearest';
+/** Access scope the tools were generated for. Phase 1 ships `admin`. */
+export type ToolScope = 'admin' | 'client';
+export interface DescribeContext {
+    /** Collection name (customer-facing, no `coll_` prefix). */
+    collection: string;
+    /** The mapped schema (column kinds, vector columns). */
+    mapped: MappedCollection;
+    /** Effective read policy from the collection's access policy. */
+    readPolicy: 'owner' | 'public';
+    /** Effective write policy from the collection's access policy. */
+    writePolicy: 'owner' | 'authenticated';
+    /** Scope the tool set was generated for. */
+    scope: ToolScope;
+}
+/**
+ * Generate the description string for a single collection tool.
+ */
+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

@@ -0,0 +1,100 @@
+/**
+ * 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 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/functions.
+ *   - `<ns>_whoami`           — which project + scope this surface serves.
+ *
+ * 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.
+ *
+ * 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. */
+    scope: ToolScope;
+    /**
+     * 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`.
+ *
+ * Returns the names of the collections that were exposed plus `listOk`
+ * (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;
+    collections: string[];
+    listOk: boolean;
+}>;
+export { registerCollectionToolsFor, collectionToolName, sanitizeNameFragment, } 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, 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/auto/schema-to-zod.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure mapper: a collection's live schema (the JSON returned by the
+ * `GET .../collections/:name` describe endpoint) → the zod raw shapes the
+ * auto-generated MCP tools register.
+ *
+ * Three derived shapes per collection (the auto-MCP wedge §2.2):
+ *
+ *   - `insertShape` — the typed body of an `insert` tool. Server-managed
+ *     columns (`id`, `user_id`, `created_at`, `updated_at`, `deleted_at`)
+ *     are omitted (the route stamps them); a column is REQUIRED when it is
+ *     NOT NULL and has no default, OPTIONAL otherwise.
+ *   - `whereShape` — the typed `where` of a `find` tool: one optional key
+ *     per non-vector column whose value is `value | { eq?, ne?, gt?, … }`
+ *     typed to the column. This is the single highest-value projection —
+ *     it makes the generated tool read like a hand-built typed client
+ *     rather than a free-form `where: object` blob.
+ *   - `updateShape` — the typed `set` of an `update` tool: every non
+ *     server-managed column, all optional (merge-patch semantics).
+ *
+ * Plus `rowTypeHints` — a column→plain-English type label map the
+ * description generator (`describe.ts`) reads, and `vectorColumns` — the
+ * vector columns (excluded from row input; they drive `find_nearest`).
+ *
+ * The mapper is PURE (no I/O, no zod-runtime coupling beyond building the
+ * shape) so it unit-tests in isolation and so the same projection can run
+ * in the hosted server today and in the CLI / console later.
+ */
+import { z } from 'zod';
+/** A single column as returned by the describe endpoint (`information_schema`). */
+export interface CollectionColumn {
+    column_name: string;
+    /** e.g. `text`, `integer`, `ARRAY`. For arrays this is the literal `ARRAY`. */
+    data_type: string;
+    /** Underlying type, e.g. `text`, `int4`, `_text` (array element prefixed `_`). */
+    udt_name: string;
+    is_nullable: 'YES' | 'NO';
+    column_default: string | null;
+}
+/** The describe-endpoint `data` payload the mapper consumes. */
+export interface CollectionSchemaPayload {
+    name: string;
+    columns: CollectionColumn[];
+}
+/**
+ * Columns Amba manages on every collection. They are stamped by the
+ * route, never accepted as tool input, and so are omitted from the
+ * insert / update shapes. They ARE filterable (`where`) and selectable.
+ */
+export declare const SERVER_MANAGED_COLUMNS: ReadonlySet<string>;
+/** Plain-English label for a column, used by the description generator. */
+export type ColumnKind = 'text' | 'integer' | 'number' | 'boolean' | 'json' | 'uuid' | 'date' | 'timestamp' | 'vector' | 'text[]' | 'integer[]' | 'number[]' | 'boolean[]' | 'uuid[]' | 'unknown';
+export interface MappedCollection {
+    /** zod raw shape for an `insert` tool body. */
+    insertShape: z.ZodRawShape;
+    /** zod raw shape for a `find` tool's `where` argument (one key per column). */
+    whereShape: z.ZodRawShape;
+    /** zod raw shape for an `update` tool's `set` argument. */
+    updateShape: z.ZodRawShape;
+    /** column → plain-English kind, for description generation. */
+    rowTypeHints: Record<string, ColumnKind>;
+    /** Names of vector columns (drive `find_nearest`, excluded from row input). */
+    vectorColumns: string[];
+    /** Whether the collection has at least one vector column. */
+    hasVector: boolean;
+}
+/**
+ * Classify a column into a coarse {@link ColumnKind}. Reads `data_type`
+ * first (the only reliable array signal — `data_type === 'ARRAY'`), then
+ * `udt_name`. Unknown types fall back to `unknown` (mapped to free JSON)
+ * rather than throwing, so a future column type never breaks generation.
+ */
+export declare function classifyColumn(column: CollectionColumn): ColumnKind;
+export interface MapCollectionOptions {
+    /**
+     * Admin scope: surface `user_id` as an OPTIONAL insert field so a
+     * developer can attribute a row to a specific app user (the admin row
+     * POST honors a `user_id` in the body). Other server-managed columns
+     * (`id`, `created_at`, …) stay stamped. Client scope leaves this off —
+     * the route derives `user_id` from the session.
+     */
+    includeUserIdInInsert?: boolean;
+}
+/**
+ * Project a collection schema into the zod raw shapes the auto-MCP tools
+ * register. Pure — same input always yields the same shapes.
+ */
+export declare function mapCollectionSchema(schema: CollectionSchemaPayload, options?: MapCollectionOptions): MappedCollection;

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,3 +41,5 @@ export declare function createApiClient(options: {
 }): ApiClient;
 export { ApiClient } from './api-client.js';
 export type { ApiClientOptions } from './api-client.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';