@setluca/mcp 0.2.0 → 0.2.1

package/dist/server.js

@@ -8,9 +8,9 @@ import { LucaApi, LucaApiLive } from "./http.js";
 import { logAgentSurfaceEvent } from "./observability.js";
 import { LUCA_OPERATIONS, operationGroups, operationManifest, } from "./operations.js";
 import { optionalField } from "./optional-field.js";
-import { LUCA_PROMPTS, } from "./prompts.js";
+import { LUCA_API_PLANNER_PROMPT, LUCA_PROMPTS, } from "./prompts.js";
 import { provenanceFields } from "./provenance.js";
-import { LUCA_RESOURCES } from "./resources.js";
+import { LUCA_OPERATION_MANIFEST_RESOURCE, LUCA_RESOURCES, } from "./resources.js";
 import { toJsonText } from "./serialization.js";
 import { LUCA_TASK_TOOLS } from "./task-tools.js";
 import { fromOperation, fromTaskTool, operationProgram, registerTool, } from "./tool.js";
@@ -48,9 +48,9 @@ export const LUCA_SERVER_INFO = {
  *
  * `private` throughout: the tool surface varies with the `?toolset=` query
  * param, so a shared cache keyed on anything less than the whole request
- * could answer one shape with another. `resources/read` is deliberately
- * absent — it returns live coach data and keeps the conservative default of
- * no caching at all.
+ * could answer one shape with another. `resources/read` is left out on purpose.
+ * It returns live coach data and keeps the conservative default of no caching
+ * at all.
  *
  * These hints reach a client on the remote Streamable HTTP transport only.
  * The SDK installs the modern-revision handlers from its HTTP entry
@@ -58,8 +58,8 @@ export const LUCA_SERVER_INFO = {
  * constructed here and connected straight to a stdio or in-memory transport
  * negotiates the legacy `initialize` handshake instead, and the legacy wire
  * codec stamps no cache fields. Passing the table is still correct on both
- * paths — it is inert on stdio rather than wrong — but only the remote
- * handler can be asserted against, which is where the coverage lives.
+ * paths, inert on stdio rather than wrong, but only the remote handler can be
+ * asserted against, which is where the coverage lives.
  */
 const STATIC_LIST_TTL_MS = 3_600_000;
 const LUCA_CACHE_HINTS = {
@@ -79,8 +79,8 @@ export function parseToolset(value) {
 }
 const OPERATIONS_BY_ID = new Map(
 // This map is built once at module load, so a mutant inside it never takes
-// effect under a test runner that caches the module — it is unkillable by
-// construction rather than untested; the lookups below are covered.
+// effect under a test runner that caches the module. It is unkillable by
+// construction rather than untested, and the lookups below are covered.
 // Stryker disable next-line ArrowFunction: module-level initializer, never re-evaluated per test
 LUCA_OPERATIONS.map((operation) => [operation.id, operation]));
 function operationByIdOrThrow(id) {
@@ -88,7 +88,7 @@ function operationByIdOrThrow(id) {
     // the same CI-validated manifest, so this throw is unreachable with real data
     // and the message text is never observed.
     return Option.fromNullable(OPERATIONS_BY_ID.get(id)).pipe(Option.getOrThrowWith(
-    // Stryker disable next-line all: unreachable defensive throw — every composed id exists in the manifest
+    // Stryker disable next-line all: unreachable defensive throw, every composed id exists in the manifest
     () => new Error(`task tool composes unknown operation: ${id}`)));
 }
 function registerLucaResources(server, lucaLayer, completions) {
@@ -114,15 +114,15 @@ function resourceOperationOrThrow(operationId) {
     // CI-validated manifest, so this throw is unreachable with real data and the
     // message text is never observed.
     Option.getOrThrowWith(
-    // Stryker disable next-line all: unreachable defensive throw — every resource operation id exists in the manifest
+    // Stryker disable next-line all: unreachable defensive throw, every resource operation id exists in the manifest
     () => new Error(`Unknown resource operation: ${operationId}`)));
 }
 function registerTemplatedResource(server, resource, operation, lucaLayer, metadata, completions) {
     return Option.fromNullable(resource.uriTemplate).pipe(Option.match({
         onNone: () => undefined,
         onSome: (template) => server.registerResource(resource.name, 
-        // These templates are not enumerable — a lead or conversation uri is
-        // addressable but not listable — which an explicit `list: undefined`
+        // These templates are not enumerable. A lead or conversation uri is
+        // addressable but not listable, which an explicit `list: undefined`
         // states at the call site. Omitting the key entirely reads the same
         // to the SDK, so a mutant that drops it changes nothing observable.
         // Stryker disable next-line ObjectLiteral: an absent `list` and an undefined one are the same to the SDK
@@ -158,14 +158,16 @@ function readResult(operation, uri, result) {
         contents: [resourceContent(uri, resourcePayload(operation, result))],
     };
 }
-/** The operation input a resource read runs, recorded as it is built. */
+/**
+ * The operation input a resource read runs, recorded as it is built.
+ *
+ * Only the resource's name is logged. Every variable a template carries is an
+ * id the client already typed, and a resource read takes no cursor: each one
+ * answers with a whole record or a single page.
+ */
 function resourceReadInput(resource, variables) {
-    const input = resource.buildInput(variables);
-    logAgentSurfaceEvent("mcp.resources.read", {
-        resourceType: resource.name,
-        hasCursor: input.cursor !== undefined,
-    });
-    return input;
+    logAgentSurfaceEvent("mcp.resources.read", { resourceType: resource.name });
+    return resource.buildInput(variables);
 }
 /**
  * The payload of a successful read, provenance-tagged when it carries text an
@@ -185,9 +187,9 @@ function resourceContent(uri, payload) {
     };
 }
 function registerOperationManifestResource(server) {
-    server.registerResource("luca-public-operations", "luca://operations", {
-        title: "Luca Public API Operations",
-        description: "MCP operation manifest derived from Luca's public API key policy.",
+    server.registerResource(LUCA_OPERATION_MANIFEST_RESOURCE.name, LUCA_OPERATION_MANIFEST_RESOURCE.uri, {
+        title: LUCA_OPERATION_MANIFEST_RESOURCE.title,
+        description: LUCA_OPERATION_MANIFEST_RESOURCE.description,
         mimeType: "application/json",
     }, async (uri) => ({
         contents: [
@@ -211,14 +213,11 @@ function registerOperationManifestResource(server) {
  * Two details of the SDK shape this. It looks for the completion metadata on
  * the schema *inside* the optional wrapper, not on the wrapper. And
  * `completable` stamps that metadata with a non-configurable property, so a
- * schema can be stamped once and never again — while `LUCA_PROMPTS` is a
+ * schema can be stamped once and never again, while `LUCA_PROMPTS` is a
  * module singleton the Worker re-registers on every request. Cloning the inner
  * schema first gives each build its own object to stamp.
  */
 function completableArgs(schema, completions) {
-    if (!completions) {
-        return schema;
-    }
     return Object.fromEntries(Object.entries(schema).map(([name, field]) => [
         name,
         isCompletionVariable(name)
@@ -241,26 +240,33 @@ function promptArgsSchema(prompt, completions) {
     return z.object(completableArgs(prompt.argsSchema, completions));
 }
 /**
- * Registers the static planner prompt plus every prompt in `prompts`.
+ * Registers the planner prompt plus every prompt in `prompts`.
  *
  * The list is a parameter so a test can drive this with its own prompt instead
  * of mutating the exported `LUCA_PROMPTS` array out from under other tests.
  */
-export function registerPrompts(server, prompts = LUCA_PROMPTS, completions) {
-    server.registerPrompt("luca-api-planner", {
-        title: "Luca API Planner",
-        description: "Plan a Luca API workflow using the MCP tools, scopes, and idempotency rules.",
-        argsSchema: z.object({
-            task: z
-                .string()
-                .optional()
-                .describe("The Luca API workflow the user wants to perform."),
-        }),
-    }, (args) => {
-        const { task } = args;
+export function registerPrompts(server, prompts, completions) {
+    for (const prompt of [LUCA_API_PLANNER_PROMPT, ...prompts]) {
+        registerPrompt(server, prompt, completions);
+    }
+}
+function registerPrompt(server, prompt, completions) {
+    const config = {
+        title: prompt.title,
+        description: prompt.description,
+        ...optionalField("argsSchema", promptArgsSchema(prompt, completions)),
+    };
+    server.registerPrompt(prompt.name, config, (args) => {
+        // Parse with the prompt's own argsSchema, not a shared guess at one. A
+        // schema that does not match what the client was told to send silently
+        // drops any argument outside it before `prompt.build` ever sees it.
+        const parsedArgs = z.object(prompt.argsSchema).parse(args ?? {});
         logAgentSurfaceEvent("mcp.prompts.get", {
-            prompt: "luca-api-planner",
-            hasGuidance: false,
+            prompt: prompt.name,
+            // Booleans and the arg name only, never guidance text: `guidance` only
+            // exists on one prompt's schema, so this reads it without assuming
+            // every prompt shares that field.
+            hasGuidance: Boolean(parsedArgs.guidance),
         });
         return {
             messages: [
@@ -268,58 +274,19 @@ export function registerPrompts(server, prompts = LUCA_PROMPTS, completions) {
                     role: "user",
                     content: {
                         type: "text",
-                        text: [
-                            "Use Luca MCP tools only for public API operations.",
-                            "Do not ask for database access, internal endpoints, webhook ingress secrets, or browser cookies.",
-                            "For writes, pass a stable idempotencyKey when retrying the same user intent.",
-                            "Check luca://operations when you need exact tool names, scopes, and paths.",
-                            Option.fromNullable(task).pipe(Option.filter((value) => value.length > 0), Option.map((value) => `User task: ${value}`), Option.getOrUndefined),
-                        ]
-                            .filter(Boolean)
-                            .join("\n"),
+                        text: prompt.build(parsedArgs),
                     },
                 },
             ],
         };
     });
-    for (const prompt of prompts) {
-        const config = {
-            title: prompt.title,
-            description: prompt.description,
-            ...optionalField("argsSchema", promptArgsSchema(prompt, completions)),
-        };
-        server.registerPrompt(prompt.name, config, (args) => {
-            // Parse with the prompt's own argsSchema, not a shared guess at one — a
-            // schema that does not match what the client was told to send silently
-            // drops any argument outside it before `prompt.build` ever sees it.
-            const parsedArgs = z.object(prompt.argsSchema).parse(args ?? {});
-            logAgentSurfaceEvent("mcp.prompts.get", {
-                prompt: prompt.name,
-                // Booleans and the arg name only, never guidance text: `guidance` only
-                // exists on one prompt's schema, so this reads it without assuming
-                // every prompt shares that field.
-                hasGuidance: Boolean(parsedArgs.guidance),
-            });
-            return {
-                messages: [
-                    {
-                        role: "user",
-                        content: {
-                            type: "text",
-                            text: prompt.build(parsedArgs),
-                        },
-                    },
-                ],
-            };
-        });
-    }
 }
 /**
  * Build the Luca MCP server: registers the operation tools, the task tools, the
  * `luca://…` resources, and the planner prompt against a shared `LucaApi` layer.
  * `options.lucaLayer` swaps the HTTP client (tests inject an in-memory handler);
- * `options.toolset` trims the surface — `"tasks"` exposes only the task tools
- * plus capability discovery, `"full"` (default) exposes everything.
+ * `options.toolset` picks the tool set. `"tasks"` exposes only the task tools
+ * plus capability discovery, and `"full"`, the default, exposes everything.
  */
 export function createLucaServer(options = {}) {
     const lucaLayer = options.lucaLayer ?? LucaLive;
@@ -331,8 +298,8 @@ export function createLucaServer(options = {}) {
     const server = new McpServer(LUCA_SERVER_INFO, {
         cacheHints: LUCA_CACHE_HINTS,
     });
-    // The tasks surface carries one operation — capability discovery — so a client
-    // can still learn what the workspace supports without the full tool list.
+    // The tasks set carries one operation, capability discovery, so a client can
+    // still learn what the workspace supports without the full tool list.
     const operations = toolset === "tasks"
         ? [operationByIdOrThrow("capabilities.get")]
         : LUCA_OPERATIONS;

package/dist/task-tools/analytics.js

@@ -30,7 +30,7 @@ const getAnalytics = {
         }));
         // broadcasts.list doesn't depend on the per-campaign analytics loop, so
         // it runs alongside it instead of after it. Effect.all defaults to
-        // concurrency 1 (sequential) — without `concurrency: "unbounded"` here
+        // concurrency 1 (sequential), so without `concurrency: "unbounded"` here
         // the broadcasts call would still wait on the whole loop below.
         const [perCampaign, broadcasts] = yield* Effect.all([
             Effect.forEach(listingIds(campaignPage, campaignLimit), (id) => api

package/dist/task-tools/bookings.js

@@ -11,7 +11,7 @@ const AVAILABILITY_WINDOW_MS = 24 * 60 * 60 * 1000;
  * `Option.none()` means "we could not tell", which is different from "nothing
  * is open". The availability route answers with `source: "fallback"` or
  * `"provider_error"` when it could not reach the provider, and it defaults to
- * Calendly when the caller names no provider — so a coach on Cal.com asking
+ * Calendly when the caller names no provider, so a coach on Cal.com asking
  * without one gets a confident-looking answer about the wrong calendar. Only a
  * `live_provider` read is worth blocking a booking over.
  */
@@ -40,11 +40,14 @@ const AvailabilityPageSchema = z.object({
     source: z.string(),
     slots: z.array(z.object({ startsAt: z.string() })),
 });
-/** Whether two ISO-8601 instants name the same moment, whatever their offset. */
+/**
+ * Whether two ISO-8601 instants name the same moment, whatever their offset.
+ *
+ * An unparseable instant is `NaN`, which is not equal to itself, so a garbled
+ * slot on either side answers false without a guard of its own.
+ */
 function sameInstant(left, right) {
-    const a = new Date(left).getTime();
-    const b = new Date(right).getTime();
-    return !(Number.isNaN(a) || Number.isNaN(b)) && a === b;
+    return new Date(left).getTime() === new Date(right).getTime();
 }
 const bookCall = {
     name: "luca_book_call",

package/dist/task-tools/calls.js

@@ -24,7 +24,7 @@ const postCallQueue = {
 /**
  * The id of the call event attached to a booking, if the API has one. A booking
  * whose call has not happened yet answers 404, which is the normal case rather
- * than a failure — so is any other read error here, because the outcome write
+ * than a failure. So is any other read error here, because the outcome write
  * below is worth doing on its own.
  */
 const CallEventId = Schema.Struct({
@@ -153,7 +153,7 @@ const closeCallLoop = {
         const feedback = yield* Option.match(decodeCallEventId(page), {
             onNone: () => 
             // No call event means attendance has nowhere to go. The revenue write
-            // below still runs — that is the half the coach is usually after.
+            // below still runs, and that is the half the coach is usually after.
             Effect.succeed({
                 reported: false,
                 reason: "no_call_event_for_booking",

package/dist/task-tools/inbox.js

@@ -1,13 +1,63 @@
 import { Effect, Record } from "effect";
 import * as z from "zod/v4";
 import { formatError } from "../errors.js";
+import { logAgentSurfaceEvent } from "../observability.js";
 import { WORKSPACE_INPUT_FIELDS } from "../operations.js";
 import { listingIds, numberInput, taskRequest, } from "./runtime.js";
 const DEFAULT_QUEUE_LIMIT = 20;
 const DEFAULT_EXPLAIN_TOP = 3;
+const TRIAGE_INBOX_TOOL_NAME = "luca_triage_inbox";
+/**
+ * One explanation, with a failed lookup carried in the result instead of
+ * cancelling the others. A queue the coach can read with two explanations
+ * missing beats no queue at all.
+ */
+function explainOne(api, operation, input, id) {
+    return api
+        .request(taskRequest(operation, input, { pathParams: { id } }))
+        .pipe(Effect.map((explanation) => ({
+        id,
+        explanation,
+        failed: false,
+    })), Effect.catchAll((error) => 
+    // Keep the structured formatter, not a lossy String(error): a
+    // LucaHttpError's status/requestId survive for debugging a partial
+    // failure inside the composed tool.
+    Effect.succeed({
+        id,
+        explanation: { explainError: formatError(error) },
+        failed: true,
+    })));
+}
+/**
+ * How the explain fan-out went, as counts.
+ *
+ * `mcp.tool.called` reports this tool as a success even when every explanation
+ * inside it failed, because a failed lookup comes back as an `explainError`
+ * field rather than an error result. Without this line, an explain route that
+ * is broken for every caller looks identical in logs to one that works.
+ *
+ * The single-route explain tools need no line of their own: `mcp.tool.called`
+ * already carries their name and outcome. This fan-out is the only place where
+ * a failure has nowhere else to show up.
+ *
+ * Counts only, never an id or an explanation. Both are lead-derived.
+ */
+function logExplainFanOut(attempts) {
+    if (attempts.length === 0) {
+        return;
+    }
+    const failed = attempts.filter((attempt) => attempt.failed).length;
+    logAgentSurfaceEvent("mcp.explain", {
+        toolName: TRIAGE_INBOX_TOOL_NAME,
+        requested: attempts.length,
+        explained: attempts.length - failed,
+        failed,
+    });
+}
 /** The review session's entry point: the queue, with the top items explained. */
 const triageInbox = {
-    name: "luca_triage_inbox",
+    name: TRIAGE_INBOX_TOOL_NAME,
     title: "Triage the review queue",
     description: "Return the coach's prioritized reply queue: pending drafts with lead context and, for the top items, why Luca drafted what it drafted. Start every review session here, then act on an item with luca_approve_and_send, luca_draft_reply, or luca_reviewQueue_reject. Example: call with { explainTop: 3 } to get the queue plus explanations for the three most urgent drafts.",
     inputSchema: {
@@ -35,24 +85,20 @@ const triageInbox = {
             query: { limit: input.limit ?? DEFAULT_QUEUE_LIMIT },
         }));
         const ids = listingIds(queue, numberInput(input.explainTop, DEFAULT_EXPLAIN_TOP));
-        const explained = yield* Effect.forEach(ids, (id) => api
-            .request(taskRequest(operationById("reviewQueue.explain"), input, {
-            pathParams: { id },
-        }))
-            .pipe(Effect.catchAll((error) => 
-        // Keep the structured formatter, not a lossy String(error): a
-        // LucaHttpError's status/requestId survive for debugging a
-        // partial failure inside the composed tool.
-        Effect.succeed({ explainError: formatError(error) })), Effect.map((explanation) => [
-            id,
-            explanation,
-        ])), 
+        const explain = operationById("reviewQueue.explain");
+        const attempts = yield* Effect.forEach(ids, (id) => explainOne(api, explain, input, id), 
         // Effect.forEach defaults to concurrency 1 (sequential). `explainTop`
-        // caps this fan-out at 5 independent lookups, so unbounded is fine —
-        // there's no unbounded caller input that could turn this into a
-        // thundering herd.
+        // caps this fan-out at 5 independent lookups, so unbounded is fine.
+        // No caller input can grow it into a thundering herd.
         { concurrency: "unbounded" });
-        return { queue, explanations: Record.fromEntries(explained) };
+        logExplainFanOut(attempts);
+        return {
+            queue,
+            explanations: Record.fromEntries(attempts.map((attempt) => [
+                attempt.id,
+                attempt.explanation,
+            ])),
+        };
     }),
 };
 /** The day's opening read: the last 24h of queue activity, already counted. */

package/dist/task-tools/runtime.js

@@ -18,7 +18,7 @@ function workspaceOverride(input) {
  * 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
+ * `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 }`).
  */
@@ -35,8 +35,8 @@ export function taskRequest(operation, input, parts = {}) {
 /**
  * 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.
+ * intact for the caller, 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) }))),
@@ -44,7 +44,7 @@ const ListingIds = Schema.Struct({
 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
+ * 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) {
@@ -66,7 +66,7 @@ export function listingIds(page, limit) {
 }
 /**
  * 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
+ * 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) {

package/dist/task-tools.js

@@ -1,7 +1,7 @@
 // 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
+// routes, and 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`.

package/dist/tool.js

@@ -105,10 +105,10 @@ 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.
+ * A tool call's result, confirmation gate included. Every way the call can end
+ * leaves as a tool result, so nothing reaches the transport as an unhandled
+ * rejection. That covers unreadable arguments, a rejected confirmation, a
+ * failed request, and a defect thrown while the request was being built.
  *
  * The log line sits after the defect handler, so a call produces exactly one
  * line whichever way it ended.
@@ -156,8 +156,8 @@ export function operationProgram(operation, toolInput) {
 }
 /**
  * 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
+ * flagged untrusted on both halves, the structured `provenance.untrusted`
+ * field that a lead cannot spoof 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`.