@setluca/mcp 0.1.1 → 0.2.0

package/dist/task-tools/leads.js

@@ -0,0 +1,123 @@
+import * as z from "zod/v4";
+import { confirmInput, WORKSPACE_INPUT_FIELDS } from "../operations.js";
+import { optionalField } from "../optional-field.js";
+import { numberInput, stringInput, taskRequest, textBody, } from "./runtime.js";
+const findLeads = {
+    name: "luca_find_leads",
+    title: "Find leads",
+    description: "Search the coach's leads by free-text query and optional channel. Use this to locate a lead before drafting, booking, or flagging. Example: call with { query: \"maria instagram\" } to find Maria's Instagram lead.",
+    inputSchema: {
+        ...WORKSPACE_INPUT_FIELDS,
+        query: z
+            .string()
+            .min(1)
+            .describe("Free-text search: name, handle, or keyword."),
+        channel: z
+            .string()
+            .optional()
+            .describe("Optional channel filter (telegram, instagram, messenger, whatsapp)."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("Max results (default 10)."),
+    },
+    readOnly: true,
+    untrustedContent: true,
+    composes: ["leads.list"],
+    run: (api, operationById, input) => api.request(taskRequest(operationById("leads.list"), input, {
+        query: {
+            q: stringInput(input.query),
+            ...optionalField("channel", input.channel),
+            limit: numberInput(input.limit, 10),
+        },
+    })),
+};
+const flagForHuman = {
+    name: "luca_flag_for_human",
+    title: "Flag a lead for human attention",
+    description: 'Add a note to a lead, tagged [needs-human], that the coach sees on the lead\'s timeline. This is an ordinary note with a prefix — it does not route, alert, or reprioritize anything. Use when a conversation needs judgment an agent should not exercise (payment claims, distress, legal), and tell the coach directly if it is urgent. Example: call with { leadId, reason: "lead mentioned a refund dispute" }.',
+    inputSchema: {
+        ...WORKSPACE_INPUT_FIELDS,
+        leadId: z.string().min(1).describe("The lead to flag."),
+        reason: z
+            .string()
+            .min(1)
+            .describe("Why a human should look — shown to the coach verbatim."),
+        idempotencyKey: z
+            .string()
+            .optional()
+            .describe("Reuse the same key when retrying this exact flag."),
+    },
+    readOnly: false,
+    untrustedContent: false,
+    composes: ["leads.notes.add"],
+    run: (api, operationById, input) => api.request(taskRequest(operationById("leads.notes.add"), input, {
+        pathParams: { id: stringInput(input.leadId) },
+        body: { body: `[needs-human] ${stringInput(input.reason)}` },
+    })),
+};
+const draftReply = {
+    name: "luca_draft_reply",
+    title: "Draft a reply for a lead",
+    description: 'Draft a voice-matched reply for a lead on demand and queue it for review — the middle step of the reply loop (triage → draft → approve). Optional guidance steers tone or content. Nothing is sent; approve it with luca_approve_and_send. Example: call with { leadId, guidance: "keep it short and warm" }.',
+    inputSchema: {
+        ...WORKSPACE_INPUT_FIELDS,
+        leadId: z.string().min(1).describe("The lead to draft a reply for."),
+        guidance: z
+            .string()
+            .min(1)
+            .max(500)
+            .optional()
+            .describe("Optional steer for tone or content of the draft."),
+        idempotencyKey: z
+            .string()
+            .optional()
+            .describe("Reuse the same key when retrying this exact draft."),
+    },
+    readOnly: false,
+    untrustedContent: false,
+    composes: ["leads.draft"],
+    run: (api, operationById, input) => api.request(taskRequest(operationById("leads.draft"), input, {
+        pathParams: { id: stringInput(input.leadId) },
+        body: textBody("guidance", input.guidance),
+    })),
+};
+const approveAndSend = {
+    name: "luca_approve_and_send",
+    title: "Approve a drafted reply and send it",
+    description: "Approve a pending review-queue draft and dispatch it through the lead's channel. THIS SENDS A REAL MESSAGE TO A REAL PERSON — only call it after a human has reviewed and intends to send. Pass confirm: true to proceed. Optional finalBody replaces the draft text before sending. Example: { reviewQueueId, confirm: true }.",
+    inputSchema: {
+        ...WORKSPACE_INPUT_FIELDS,
+        reviewQueueId: z
+            .string()
+            .min(1)
+            .describe("The review-queue item to approve."),
+        finalBody: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Optional edited body to send instead of the drafted text."),
+        ...confirmInput,
+        idempotencyKey: z
+            .string()
+            .optional()
+            .describe("Reuse the same key when retrying this exact approval."),
+    },
+    readOnly: false,
+    untrustedContent: false,
+    confirmRequired: true,
+    composes: ["reviewQueue.approve"],
+    run: (api, operationById, input) => api.request(taskRequest(operationById("reviewQueue.approve"), input, {
+        pathParams: { id: stringInput(input.reviewQueueId) },
+        body: textBody("finalBody", input.finalBody),
+    })),
+};
+export const leadTaskTools = [
+    findLeads,
+    flagForHuman,
+    draftReply,
+    approveAndSend,
+];

package/dist/task-tools/runtime.js

@@ -0,0 +1,92 @@
+import { Effect, Option, Schema } from "effect";
+import * as z from "zod/v4";
+import { formatError } from "../errors.js";
+import { optionalField } from "../optional-field.js";
+function workspaceOverride(input) {
+    const override = {
+        ...optionalField("workspaceId", input.workspaceId),
+        ...optionalField("workspaceSlug", input.workspaceSlug),
+    };
+    // An override naming neither field is no override at all, and sending an
+    // empty one would pin the request to nothing.
+    if (Object.keys(override).length === 0) {
+        return;
+    }
+    return override;
+}
+/**
+ * Assemble the request a task tool sends: the resolved operation plus its
+ * path/query/body, with the workspace override and idempotency key folded in
+ * the same way for every tool. This is the task-tool analogue of operations.ts
+ * `commonInput` — one seam owns "how a task request is built", so a tool body
+ * reads as the fields it maps, not the plumbing. Pass `body: undefined` to omit
+ * the body entirely (an absent optional field, never `{ body: undefined }`).
+ */
+export function taskRequest(operation, input, parts = {}) {
+    return {
+        operation,
+        ...optionalField("pathParams", parts.pathParams),
+        ...optionalField("query", parts.query),
+        ...optionalField("body", parts.body),
+        ...optionalField("idempotencyKey", input.idempotencyKey),
+        ...optionalField("workspace", workspaceOverride(input)),
+    };
+}
+/**
+ * The only part of a listing page a composing tool reads for itself: the ids of
+ * the items it then fans out over. Decoding that alone leaves the raw page
+ * intact for the caller — it is returned exactly as the API sent it — while the
+ * ids the tool acts on are validated rather than asserted.
+ */
+const ListingIds = Schema.Struct({
+    items: Schema.optional(Schema.Array(Schema.Struct({ id: Schema.optional(Schema.String) }))),
+});
+const decodeListingIds = Schema.decodeUnknownOption(ListingIds);
+/**
+ * Ids of the first `limit` items on a listing page. A page whose fields we
+ * cannot read, or whose items carry no id, contributes nothing — the tool still
+ * returns the page itself rather than failing over a fan-out it cannot do.
+ */
+export function listingIds(page, limit) {
+    // Both fallbacks below are empty arrays, and substituting a one-item array
+    // for either is an equivalent mutation rather than an untested branch: a
+    // substituted item carries no `id`, so the `filter` at the end of this
+    // function drops it and the result is the same empty id list. Substituting
+    // `undefined` for the outer fallback is a real change and is covered by the
+    // undecodable-page test.
+    const items = decodeListingIds(page).pipe(
+    // Stryker disable next-line ArrayDeclaration: a substituted item has no id and is filtered out below
+    Option.map((decoded) => decoded.items ?? []), 
+    // Stryker disable next-line ArrayDeclaration: a substituted item has no id and is filtered out below
+    Option.getOrElse(() => []));
+    return items
+        .slice(0, limit)
+        .map((item) => item.id)
+        .filter((id) => id !== undefined);
+}
+/**
+ * A request body carrying a single text field, or no body at all when the input
+ * is absent or blank — sending an empty string would mean something different to
+ * the API than leaving the field off.
+ */
+export function textBody(key, value) {
+    return Option.fromNullable(value).pipe(Option.map(String), Option.filter((text) => text.length > 0), Option.map((text) => ({ [key]: text })), Option.getOrUndefined);
+}
+/** Reads a numeric tool input, falling back when it is absent or not a number. */
+export function numberInput(value, fallback) {
+    const parsed = z.number().safeParse(value);
+    return parsed.success ? parsed.data : fallback;
+}
+/** Required string arguments have already passed the registered tool schema. */
+export function stringInput(value) {
+    return z.string().parse(value);
+}
+/**
+ * A write whose failure must not cancel the writes around it. A tool that files
+ * two independent reports has to keep the second one reachable when the first
+ * fails, so the failure comes back as a field the agent can read instead of a
+ * dead tool call that invites a retry of the half that already landed.
+ */
+export function independentWrite(errorKey, effect) {
+    return Effect.catchAll(effect, (error) => Effect.succeed({ [errorKey]: formatError(error) }));
+}

package/dist/task-tools.js

@@ -0,0 +1,21 @@
+// The task-tool registry: composed, intent-level entry points layered over the
+// generated 1:1 operation tools. It is deliberately NOT `LUCA_OPERATIONS`,
+// whose entries the OpenAPI drift checker matches one-to-one against REST
+// routes — a task tool has no route of its own. Each tool hand-writes its
+// input fields and composes existing operations through `LucaApi.request`, and
+// they are split one file per domain under `task-tools/`. The shape they all
+// share, and the request plumbing they all use, lives in `task-tools/runtime.ts`.
+import { analyticsTaskTools } from "./task-tools/analytics.js";
+import { bookingTaskTools } from "./task-tools/bookings.js";
+import { cadenceTaskTools } from "./task-tools/cadences.js";
+import { callTaskTools } from "./task-tools/calls.js";
+import { inboxTaskTools } from "./task-tools/inbox.js";
+import { leadTaskTools } from "./task-tools/leads.js";
+export const LUCA_TASK_TOOLS = [
+    ...inboxTaskTools,
+    ...leadTaskTools,
+    ...bookingTaskTools,
+    ...callTaskTools,
+    ...cadenceTaskTools,
+    ...analyticsTaskTools,
+];

package/dist/tool-cache.js

@@ -0,0 +1,39 @@
+function cache() {
+    let entries = new WeakMap();
+    return {
+        get: (key, build) => {
+            const cached = entries.get(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const built = build();
+            entries.set(key, built);
+            return built;
+        },
+        clear: () => {
+            entries = new WeakMap();
+        },
+    };
+}
+/**
+ * Only the reset of each cache is registered, not the cache itself: a list of
+ * caches would have to name a key and value type the entries do not share, and
+ * the only thing this module needs from them all is the same nullary call.
+ */
+const resets = [];
+/** A cache that {@link clearToolBuildCache} knows how to empty. */
+export function buildCache() {
+    const created = cache();
+    resets.push(created.clear);
+    return created;
+}
+/**
+ * Drops every build the caches hold. Only tests call this: a definition cached
+ * under one version of the code would otherwise be reused after the code
+ * changed underneath it, which is exactly what a mutation run does.
+ */
+export function clearToolBuildCache() {
+    for (const reset of resets) {
+        reset();
+    }
+}

package/dist/tool.js

@@ -0,0 +1,228 @@
+import { Duration, Effect, Layer } from "effect";
+import * as z from "zod/v4";
+import { mutatesExisting, toolAnnotations } from "./annotations.js";
+import { formatError, LucaToolInputError } from "./errors.js";
+import { LucaApi } from "./http.js";
+import { logAgentSurfaceEvent } from "./observability.js";
+import { optionalField } from "./optional-field.js";
+import { paginatedProgram } from "./pagination.js";
+import { provenanceFields, UNTRUSTED_CONTENT_NOTE } from "./provenance.js";
+import { JsonObjectSchema, toJsonText, } from "./serialization.js";
+import { buildCache } from "./tool-cache.js";
+/**
+ * Each derivation below is cached on the identity of the catalog entry it comes
+ * from, because nothing in a `RegisterableTool` varies by caller and the Worker
+ * builds a fresh server per request. See `tool-cache.ts` for what that buys and
+ * how a test empties it.
+ */
+const operationTools = buildCache();
+const taskTools = buildCache();
+const objectSchemas = buildCache();
+/** A tool's fields as one Zod object, built once per fields object. */
+function objectSchema(fields) {
+    return objectSchemas.get(fields, () => z.object(fields));
+}
+export function fromOperation(operation) {
+    return operationTools.get(operation, () => buildFromOperation(operation));
+}
+function buildFromOperation(operation) {
+    return {
+        name: operation.toolName,
+        title: operation.title,
+        description: operationDescription(operation),
+        inputSchema: operation.inputSchema,
+        outputSchema: operation.outputSchema,
+        readOnly: operation.method === "GET",
+        mutatesExisting: mutatesExisting(operation.method),
+        confirmRequired: operation.confirmRequired,
+        idempotencyRequired: operation.idempotencyRequired,
+        untrustedContent: operation.untrustedContent,
+        run: (input) => operationProgram(operation, input),
+    };
+}
+/**
+ * `operationById` arrives as a parameter rather than an import: the lookup map
+ * is built beside the server, and importing it here would close a cycle
+ * between this module and the one that registers with it.
+ */
+export function fromTaskTool(tool, operationById) {
+    return taskTools.get(tool, () => buildFromTaskTool(tool, operationById));
+}
+function buildFromTaskTool(tool, operationById) {
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: undefined,
+        readOnly: tool.readOnly,
+        // No task tool maps onto a single mutating route. A destructive one is
+        // destructive because it reaches a real lead, which `confirmRequired`
+        // already states.
+        mutatesExisting: false,
+        confirmRequired: tool.confirmRequired === true,
+        // A task tool sends several requests, so no single key describes the call.
+        // Each constituent write carries its own, minted by the HTTP client.
+        idempotencyRequired: false,
+        untrustedContent: tool.untrustedContent,
+        run: (input) => Effect.gen(function* () {
+            const api = yield* LucaApi;
+            return yield* tool.run(api, operationById, input);
+        }),
+    };
+}
+/**
+ * `toolset` arrives as a parameter rather than a field on the tool: the same
+ * `LucaOperation` serves both surfaces, so a tool has no business claiming to
+ * know which one registered it.
+ */
+export function registerTool(server, tool, lucaLayer, toolset) {
+    server.registerTool(tool.name, {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: objectSchema(tool.inputSchema),
+        ...optionalField("outputSchema", tool.outputSchema === undefined
+            ? undefined
+            : objectSchema(tool.outputSchema)),
+        annotations: toolAnnotations(tool),
+    }, (input) => Effect.runPromise(toolResult(tool, lucaLayer, toolset, input)));
+}
+/**
+ * The call's arguments as a JSON object, failing into the error channel rather
+ * than throwing. The SDK validates against the tool's own input schema before
+ * the handler runs, so a real client never lands here; the point is that no
+ * code ahead of `runPromise` can throw where the error channel cannot see it.
+ */
+function parseToolInput(input) {
+    return Effect.try({
+        try: () => JsonObjectSchema.parse(input),
+        catch: () => new LucaToolInputError({
+            message: "Tool arguments must be a JSON object",
+        }),
+    });
+}
+function ended(outcome, result) {
+    return { outcome, result };
+}
+/**
+ * A tool call's result, confirmation gate included. Every way the call can end —
+ * unreadable arguments, a rejected confirmation, a failed request, a thrown
+ * defect while the request was being built — leaves as a tool result, so
+ * nothing reaches the transport as an unhandled rejection.
+ *
+ * The log line sits after the defect handler, so a call produces exactly one
+ * line whichever way it ended.
+ */
+function toolResult(tool, lucaLayer, toolset, input) {
+    return parseToolInput(input).pipe(Effect.flatMap((parsed) => gatedResult(tool, lucaLayer, parsed)), Effect.catchAll((error) => Effect.succeed(ended("error", asErrorResult(error)))), Effect.catchAllDefect((defect) => Effect.succeed(ended("defect", asErrorResult(defect instanceof Error ? defect : new Error(String(defect)))))), Effect.timed, Effect.tap(([elapsed, ended_]) => Effect.sync(() => {
+        // The defect's own message never lands here: it can carry arbitrary
+        // thrown text derived from the call's input. The client still sees it
+        // in the tool result.
+        logAgentSurfaceEvent("mcp.tool.called", {
+            toolName: tool.name,
+            toolset,
+            outcome: ended_.outcome,
+            durationMs: Math.round(Duration.toMillis(elapsed)),
+        });
+    })), Effect.map(([, ended_]) => ended_.result));
+}
+/** One tool call past the confirmation gate, or the gate's own refusal. */
+function gatedResult(tool, lucaLayer, input) {
+    if (tool.confirmRequired && input.confirm !== true) {
+        return Effect.succeed(ended("error", confirmationError(tool.name)));
+    }
+    return runTool(tool, lucaLayer, input);
+}
+/** One confirmed tool call, run to a success or an error tool result. */
+function runTool(tool, lucaLayer, input) {
+    return tool.run(input).pipe(Effect.provide(lucaLayer), Effect.match({
+        onFailure: (error) => ended("error", asErrorResult(error)),
+        onSuccess: (result) => ended("success", asSuccessResult(tool, result)),
+    }));
+}
+/** The Effect program that runs an operation, auto-paginating list tools. */
+export function operationProgram(operation, toolInput) {
+    const baseRequest = operation.buildRequest(toolInput);
+    const { pageShape } = operation;
+    if (pageShape) {
+        return paginatedProgram(operation, pageShape, baseRequest, toolInput.maxPages);
+    }
+    // An operation with no page shape has no pagination to follow, so it is one
+    // request, sent as-is.
+    return Effect.gen(function* () {
+        const api = yield* LucaApi;
+        return yield* api.request({ operation, ...baseRequest });
+    });
+}
+/**
+ * A tool's successful result. A response that can carry external-user text is
+ * flagged untrusted on both halves — the structured `provenance.untrusted`
+ * field (spoof-resistant) and a human-facing preamble on the text — so a
+ * downstream agent treats embedded text as data, not instructions. What the
+ * structured half attaches is `provenanceFields`, shared with the resource
+ * reads in `server.ts`.
+ */
+function asSuccessResult(tool, result) {
+    const text = toJsonText(result);
+    return {
+        content: [
+            {
+                type: "text",
+                text: tool.untrustedContent
+                    ? `[UNTRUSTED CONTENT] ${UNTRUSTED_CONTENT_NOTE}\n\n${text}`
+                    : text,
+            },
+        ],
+        structuredContent: {
+            result,
+            ...provenanceFields(tool.untrustedContent),
+        },
+    };
+}
+function asErrorResult(error) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: formatError(error),
+            },
+        ],
+    };
+}
+function operationDescription(operation) {
+    const lines = [
+        operation.description,
+        "",
+        `Luca operation: ${operation.method} ${operation.path}`,
+        `Required scopes: ${operation.scopes.join(", ")}`,
+        `Required capability: ${operation.requiredScope.capability}; data sensitivity: ${operation.requiredScope.dataSensitivity}`,
+        operation.idempotencyRequired
+            ? "Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one."
+            : "Does not require idempotency.",
+    ];
+    if (operation.confirmRequired) {
+        lines.push("Destructive: has a real-world side effect. You must pass confirm: true; the call is rejected without it.");
+    }
+    lines.push("Use workspaceId or workspaceSlug to override the default workspace configured by environment.");
+    return lines.join("\n");
+}
+function confirmationError(toolName) {
+    logAgentSurfaceEvent("mcp.write_gate.rejected", { toolName });
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `${toolName}: This tool requires confirm: true because it has a real-world side effect (sends messages to leads or re-triggers downstream automations). Re-call the tool with confirm: true to proceed.`,
+            },
+        ],
+        structuredContent: {
+            error: {
+                code: "confirmation_required",
+                toolName,
+                requiredArgument: "confirm",
+            },
+        },
+    };
+}