@layers/amba-mcp 4.0.4 → 4.0.6

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

@@ -0,0 +1,63 @@
+/**
+ * `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`).
+ *
+ * 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
+ *
+ * `find_nearest` is intentionally Phase 2 (client scope + vector route).
+ *
+ * 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.
+ */
+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';
+}
+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. Phase 1 ships `admin`. */
+    scope: ToolScope;
+}
+/**
+ * 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 admin routes via `apiClient`.
+ */
+export declare function registerCollectionToolsFor(server: McpServer, apiClient: ApiClient, options: RegisterCollectionToolsOptions): void;

package/dist/auto/describe.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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. NO provider leakage:
+ * "collection", "row", "column", "function" only — never the underlying
+ * storage engine.
+ */
+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;
+/** Description for the `<ns>_whoami` meta tool. */
+export declare function describeWhoami(namespace: string): string;

package/dist/auto/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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:
+ *
+ *   - `<ns>_list_collections` — the index of exposed collections.
+ *   - `<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.
+ *
+ * Phase 1 = admin scope, collections only. Function tools, client scope,
+ * and the manifest cache are later phases.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiClient } from '../api-client.js';
+import { type ToolScope } from './describe.js';
+import { mapCollectionSchema, type CollectionSchemaPayload } from './schema-to-zod.js';
+export interface RegisterAutoMcpOptions {
+    /** Project whose collections become the tool surface. */
+    projectId: string;
+    /** Scope to generate. Phase 1 ships `admin`. */
+    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.
+     */
+    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).
+ */
+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 { CollectionPolicy, RegisterCollectionToolsOptions } from './collection-tools.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';

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/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, 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';