@setluca/mcp 0.1.1 → 0.2.1

package/dist/operations/registry.js

@@ -0,0 +1,331 @@
+import * as z from "zod/v4";
+import { OPENAPI_INPUTS } from "../generated/openapi-inputs.js";
+import { OPENAPI_OUTPUTS } from "../generated/openapi-outputs.js";
+import { ROUTE_CATALOG } from "../generated/route-catalog.js";
+import { openApiToolInputFields, openApiToolOutputFields, } from "../openapi-zod.js";
+import { optionalField } from "../optional-field.js";
+import { pageShapeFor } from "../page-shape.js";
+export const LUCA_OPERATION_GROUPS = {
+    capabilities: {
+        title: "Capabilities",
+        description: "Public API capabilities and boundary discovery.",
+    },
+    leads: {
+        title: "Leads",
+        description: "Lead identity, consent, notes, custom fields, and imports.",
+    },
+    conversations: {
+        title: "Conversations",
+        description: "Conversation search and message context.",
+    },
+    reviewQueue: {
+        title: "Review Queue",
+        description: "Human review queue visibility.",
+    },
+    bookings: {
+        title: "Bookings",
+        description: "Booking creation, scheduling, and cancellation.",
+    },
+    callEvents: {
+        title: "Call Events",
+        description: "What happened on a call: outcome, coach feedback, summary, and CRM push.",
+    },
+    campaigns: {
+        title: "Campaigns",
+        description: "Campaign drafts, enrollment, analytics, comments, and simulations.",
+    },
+    broadcasts: {
+        title: "Broadcasts",
+        description: "Broadcast draft, approval, launch, pause, retry, and cancel flows.",
+    },
+    webhooks: {
+        title: "Webhooks",
+        description: "Webhook subscriptions, deliveries, events, signatures, and replays.",
+    },
+    integrations: {
+        title: "Integrations",
+        description: "CRM connections, OAuth, mappings, sync runs, and event logs.",
+    },
+    voice: {
+        title: "Voice",
+        description: "The voice fingerprint and the corpus behind it, read-only. Corpus text is blanked for a redacted-tier key.",
+    },
+    coach: {
+        title: "Coach",
+        description: "The coach's own configuration: profile, niche and offer, objection playbook, post-call preferences. Read-only.",
+    },
+    usage: {
+        title: "Usage",
+        description: "Message-pool and model-spend counters for the current plan.",
+    },
+    safety: {
+        title: "Account Safety",
+        description: "Per-channel account health, send pacing, and the human-approval window.",
+    },
+    insights: {
+        title: "Insights",
+        description: "The proactive-insights feed and the acknowledgements that clear it.",
+    },
+    learning: {
+        title: "Teach Luca",
+        description: "The profile questions Luca still owes an answer to, and answering them.",
+    },
+    knowledge: {
+        title: "Knowledge",
+        description: "Profile suggestions extracted from the coach's own knowledge sources.",
+    },
+    memory: {
+        title: "Memory",
+        description: "What Luca remembers about a lead or the business, and how to correct it.",
+    },
+    cadences: {
+        title: "Cadences",
+        description: "Silent-lead rescue cadence control.",
+    },
+    reports: {
+        title: "Reports",
+        description: "Digest reports over the coach's workspace.",
+    },
+    analytics: {
+        title: "Analytics",
+        description: "Business intelligence, funnel analytics, revenue attribution, and coach performance metrics.",
+    },
+};
+function requiredScopeFor(input) {
+    let capability = "draft";
+    if (input.method === "GET") {
+        capability = "read";
+    }
+    else if (input.confirmRequired) {
+        // Real-world side effect (sends, enrollments, replays) = operating the
+        // live queue.
+        capability = "queue_ops";
+    }
+    return {
+        capability,
+        dataSensitivity: input.untrustedContent ? "full_content" : "redacted",
+    };
+}
+/**
+ * Operation groups whose responses carry text authored by leads or other
+ * external users (conversation messages, lead-provided profile fields, the
+ * review queue's inbound context). Output from these tools is wrapped with an
+ * untrusted-content boundary so a downstream agent treats it as data, never as
+ * instructions (prompt-injection defense).
+ */
+const UNTRUSTED_CONTENT_GROUPS = new Set([
+    "callEvents",
+    "conversations",
+    "leads",
+    // A memory is a fact Luca extracted from a lead's message, and the Teach
+    // Luca panel shows a lead DM the coach pasted in. Both read back as the
+    // lead's words even though neither group is named after a lead.
+    "learning",
+    "memory",
+    "reviewQueue",
+]);
+/** Server-side bounded auto-pagination guard for list tools. */
+export const DEFAULT_MAX_PAGES = 10;
+const MAX_PAGES_LIMIT = 50;
+const OPENAPI_INPUTS_BY_ROUTE = new Map(Object.entries(OPENAPI_INPUTS));
+const OPENAPI_OUTPUTS_BY_ROUTE = new Map(Object.entries(OPENAPI_OUTPUTS));
+export const WORKSPACE_INPUT_FIELDS = {
+    workspaceId: z
+        .uuid()
+        .optional()
+        .describe("Optional Luca workspace id override."),
+    workspaceSlug: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional Luca workspace slug override."),
+};
+const idempotencyInput = {
+    idempotencyKey: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Stable key for safe retries. If omitted, the MCP server generates a unique key for this call."),
+};
+/**
+ * The confirmation gate's input field, shared by the generated operation tools
+ * and the hand-written task tools. One wording covers both because a client
+ * sees one tool list: the effects named here are the union of what either kind
+ * can do, not a guess at which one the reader is holding.
+ */
+export const confirmInput = {
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("This tool has a real-world side effect: it messages a real lead, starts outbound touches, or re-triggers downstream automations. Pass confirm: true to proceed; the call is rejected without it."),
+};
+const paginationInput = {
+    maxPages: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGES_LIMIT)
+        .optional()
+        .describe(`Max pages the server auto-fetches and merges (default ${DEFAULT_MAX_PAGES}, hard cap ${MAX_PAGES_LIMIT}). If more remain, the result is marked truncated with a nextCursor to continue.`),
+};
+/**
+ * Fold the fields every operation tool shares, meaning query, body, idempotency
+ * key, and workspace override, into a request fields, omitting each when absent
+ * so the outgoing request never carries `undefined` keys. Path params are the one
+ * per-operation piece and are assembled separately by {@link pathParams}.
+ */
+function commonInput(input) {
+    return {
+        ...optionalField("query", input.query),
+        ...optionalField("body", input.body),
+        ...optionalField("idempotencyKey", input.idempotencyKey),
+        workspace: {
+            ...optionalField("workspaceId", input.workspaceId),
+            ...optionalField("workspaceSlug", input.workspaceSlug),
+        },
+    };
+}
+function pathParams(input, path) {
+    const params = {};
+    for (const [, key] of path.matchAll(/\{([^}]+)\}/g)) {
+        // The capture group requires at least one character, so a match always
+        // carries a non-empty key. This guard exists to satisfy the compiler's
+        // view of `RegExpMatchArray`, and no path string can reach it.
+        // Stryker disable next-line ConditionalExpression,BlockStatement: unreachable, the capture group cannot match empty
+        if (!key) {
+            continue;
+        }
+        const value = z.string().safeParse(input[key]);
+        if (value.success) {
+            params[key] = value.data;
+        }
+    }
+    return params;
+}
+function inputSchemaFor(input) {
+    const fields = openApiToolInputFields({
+        spec: OPENAPI_INPUTS_BY_ROUTE.get(`${input.method} ${input.path}`),
+        workspaceInput: WORKSPACE_INPUT_FIELDS,
+        idempotencyInput,
+        idempotencyRequired: input.idempotencyRequired,
+    });
+    if (input.confirmRequired) {
+        Object.assign(fields, confirmInput);
+    }
+    if (input.paginates) {
+        Object.assign(fields, paginationInput);
+    }
+    return fields;
+}
+/**
+ * Build an operation's output schema and, if it declares `redactedFields`
+ * (see the `op()` parameter doc), attach an
+ * `x-luca-redacted-fields` marker to `result` so an MCP client can tell those
+ * fields may arrive blanked for a `redacted`-tier key. `.meta()` is metadata
+ * only. It never affects `.parse()` or runtime validation, and it is defined
+ * on the classic `z.ZodType` interface, not the core `$ZodType` that
+ * `ZodFields` values are typed as. The cast is safe because every value
+ * here is built by `schemaToZod()` in `openapi-zod.ts`, which only ever
+ * constructs classic zod instances.
+ */
+export function outputSchemaFor(input) {
+    const fields = openApiToolOutputFields({
+        body: OPENAPI_OUTPUTS_BY_ROUTE.get(`${input.method} ${input.path}`),
+        untrustedContent: input.untrustedContent,
+    });
+    // This guard also runs while `LUCA_OPERATIONS` is built at module
+    // initialization. Forcing either half of it makes the second operand read
+    // `.length` off an absent `redactedFields`, which throws during import: the
+    // test file then fails to collect and reports zero tests, so there is no
+    // failing test for the mutation runner to attribute the kill to and it
+    // registers as a survivor. The branch itself is real and covered: the absent,
+    // empty, and populated cases all assert on the marker.
+    // Stryker disable next-line LogicalOperator,BooleanLiteral: crashes at import, leaving no test to attribute the kill to
+    if (!input.redactedFields || input.redactedFields.length === 0) {
+        return fields;
+    }
+    return {
+        ...fields,
+        // openApiToolOutputFields always sets `result`; ZodRawShape's index
+        // signature cannot express that invariant.
+        result: z.any().pipe(fields.result).meta({
+            "x-luca-redacted-fields": input.redactedFields,
+        }),
+    };
+}
+/**
+ * The group is the id's prefix before the first dot. `op()`'s `id` parameter
+ * is typed as {@link LucaOperationId}, so a prefix that doesn't name a real
+ * group is a compile-time error at the `op({...})` call site in
+ * `catalog.ts`, so a typo'd id never reaches this function. The split below
+ * only recovers, at runtime, the value TypeScript already proved is one of
+ * `LucaOperationGroup`.
+ */
+function operationGroupForId(id) {
+    // SAFETY: `id`'s type is `${LucaOperationGroup}.${string}`, so splitting on
+    // the first "." always yields a valid group as the first element.
+    const [group] = id.split(".");
+    return group;
+}
+/**
+ * Declare one 1:1 operation tool. The route's id says which allowlisted route
+ * it is; {@link ROUTE_CATALOG} answers with the method, path, scopes, and
+ * idempotency rule the API grants it. `op()` derives the rest uniformly: the
+ * `luca_*` tool name, the group that {@link operationGroupForId} reads off the
+ * id prefix, the generated input and output schemas
+ * ({@link inputSchemaFor}), the required scope tier ({@link requiredScopeFor}),
+ * the untrusted-content boundary, and a `buildRequest` that maps tool input to
+ * an HTTP request. What stays here is what only the tool surface knows: the
+ * title, the agent-facing description, the confirmation gate, and which fields
+ * can come back blanked. Task tools (composed, intent-level) are declared
+ * separately in `task-tools.ts`.
+ */
+export function op(input) {
+    const route = ROUTE_CATALOG[input.id];
+    // SAFETY: `ROUTE_CATALOG` is generated from the allowlist and its methods are
+    // the ones the public API serves; the snapshot carries them as plain strings.
+    const method = route.method;
+    const { path, scopes, idempotencyRequired } = route;
+    const confirmRequired = input.confirmRequired ?? false;
+    const pageShape = pageShapeFor(method, path);
+    const group = operationGroupForId(input.id);
+    const untrustedContent = input.untrustedContent ??
+        (method === "GET" && UNTRUSTED_CONTENT_GROUPS.has(group));
+    const operation = {
+        id: input.id,
+        group,
+        toolName: `luca_${input.id.replaceAll(".", "_")}`,
+        title: input.title,
+        method,
+        path,
+        scopes,
+        idempotencyRequired,
+        confirmRequired,
+        ...optionalField("pageShape", pageShape),
+        untrustedContent,
+        requiredScope: requiredScopeFor({
+            method,
+            confirmRequired,
+            untrustedContent,
+        }),
+        description: input.description,
+        inputSchema: inputSchemaFor({
+            method,
+            path,
+            idempotencyRequired,
+            confirmRequired,
+            paginates: pageShape !== undefined,
+        }),
+        outputSchema: outputSchemaFor({
+            method,
+            path,
+            untrustedContent,
+            ...optionalField("redactedFields", input.redactedFields),
+        }),
+        buildRequest: (toolInput) => ({
+            pathParams: pathParams(toolInput, path),
+            ...commonInput(toolInput),
+        }),
+    };
+    return operation;
+}