@setluca/mcp 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -10,6 +10,34 @@ input schema, or changing what a tool does to a workspace.
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-10-06
+
+### Fixed
+
+- Mark live booking provider and calendar reads, plus call feedback that can
+  start no-show recovery, as reaching outside the Luca workspace in MCP tool
+  annotations.
+- Mark booking outcomes that can queue CRM deal-stage updates as reaching
+  outside Luca, calendar selection as reading Google, and CRM OAuth URL creation
+  as a state-changing GET. State-changing GETs no longer retry without an
+  idempotency key.
+- Require confirmation for won or lost booking outcomes, directly and through
+  the call-closing task tool, before either can queue a connected CRM deal update.
+  Existing calls without `confirm: true` now receive `confirmation_required`;
+  this safety change is intentionally included in 0.3.3 despite the normal
+  major-version rule for a changed tool-call contract.
+- Keep unexpected tool and transport error messages out of client results and
+  Worker logs.
+
+## [0.3.2] - 2026-10-06
+
+### Fixed
+
+- Correct MCP safety hints for CRM schema and health probes, knowledge-source
+  syncs, and the settings read that creates defaults on first use.
+- Clarify the display names and descriptions of the ghosted-lead analytics and
+  weekly business report tools without changing their stable tool names.
+
 ## [0.3.1] - 2026-10-06
 
 ### Fixed

package/dist/annotations.js

@@ -8,7 +8,7 @@ import { optionalField } from "./optional-field.js";
 export function operationAnnotationSource(operation) {
     return {
         title: operation.title,
-        readOnly: operation.method === "GET",
+        readOnly: operation.readOnly,
         mutatesExisting: operation.mutatesExisting,
         ...optionalField("confirm", operation.confirm),
         openWorld: operation.openWorld,

package/dist/operations/groups/analytics.js

@@ -36,8 +36,8 @@ export const analyticsOperations = [
     }),
     op({
         id: "analytics.ghostedLeads",
-        title: "List ghosted leads",
-        description: "Ghosted-lead counts, rescue-recovery rate, lost-revenue estimate, and top conversation-killer clusters for a period.",
+        title: "Analyze leads who stopped replying",
+        description: "Summarize leads who stopped replying during a period, including their count, follow-up recovery rate, estimated lost revenue, and common reasons conversations stalled. This is an aggregate report, not a list of individual leads.",
         // Each top-killer cluster label is free text drawn from lead messages.
         untrustedContent: true,
     }),

package/dist/operations/groups/bookings.js

@@ -1,3 +1,4 @@
+import { isJsonObject } from "../../serialization.js";
 import { op } from "../registry.js";
 export const bookingsOperations = [
     op({
@@ -29,11 +30,15 @@ export const bookingsOperations = [
     op({
         id: "bookings.availability",
         title: "Read open call slots",
+        // Availability comes from the connected booking provider.
+        openWorld: true,
         description: "List open slots the coach can actually be booked into. Check this before booking.",
     }),
     op({
         id: "bookings.managedAvailability",
         title: "Read Luca-managed call slots",
+        // Google Calendar removes conflicts from Luca-managed slots.
+        openWorld: true,
         description: "List open slots for one of Luca's own call types, with calendar conflicts already removed.",
     }),
     op({
@@ -59,6 +64,8 @@ export const bookingsOperations = [
     op({
         id: "bookings.providers.get",
         title: "Get a booking provider",
+        // Event types and calendars are fetched from the provider account.
+        openWorld: true,
         description: "List the event types and calendars in one connected provider account.",
     }),
     op({
@@ -127,7 +134,14 @@ export const bookingsOperations = [
         id: "bookings.outcome.record",
         title: "Record a booking's outcome",
         mutatesExisting: true,
-        description: "Record what the call was worth: won, lost with a reason, or still open. To correct an earlier outcome send the expectedVersion you read; a stale version returns 409 with the current one.",
+        // Won and lost outcomes queue a deal-stage change in the connected CRM.
+        openWorld: true,
+        confirm: {
+            applies: (input) => isJsonObject(input.body) &&
+                (input.body.status === "won" || input.body.status === "lost"),
+            description: "status is won or lost (can update a connected CRM deal)",
+        },
+        description: "Record what the call was worth: won, lost with a reason, or still open. Won and lost outcomes can update a connected CRM deal stage, so pass confirm: true for those outcomes. To correct an earlier outcome send the expectedVersion you read; a stale version returns 409 with the current one.",
     }),
     op({
         id: "bookings.lifecycleResolution",
@@ -206,6 +220,8 @@ export const bookingsOperations = [
         id: "bookings.calendars.select",
         title: "Select a booking calendar",
         mutatesExisting: true,
+        // Selection checks that the calendar exists in the connected Google account.
+        openWorld: true,
         description: "Add or update a calendar selection, either for conflict checks or as the destination new bookings are written to. The destination has to be writable: a read-only calendar returns 400, and a Google connection needing attention returns 409.",
     }),
     op({

package/dist/operations/groups/callEvents.js

@@ -27,6 +27,8 @@ export const callEventsOperations = [
     op({
         id: "callEvents.feedback",
         title: "Report how a call went",
+        // A no-show report can start recovery messaging to the lead.
+        openWorld: true,
         mutatesExisting: true,
         untrustedContent: true,
         // Only a no_show can start recovery that messages the lead, so only that

package/dist/operations/groups/insights.js

@@ -26,6 +26,7 @@ export const insightsOperations = [
     op({
         id: "insights.settings.get",
         title: "Read alert delivery settings",
+        readOnly: false,
         description: "Read which insight alerts reach the coach and how. The row is created with defaults on the first read, so this never 404s. Check it before concluding a quiet feed means nothing is happening \u2014 it may just be muted.",
     }),
     op({

package/dist/operations/groups/integrations.js

@@ -8,7 +8,9 @@ export const integrationsOperations = [
     op({
         id: "integrations.crm.oauthUrl",
         title: "Start a CRM connection",
-        description: "Create a CRM provider OAuth URL.",
+        // This GET stores a fresh OAuth state record for the callback.
+        readOnly: false,
+        description: "Create a CRM provider OAuth URL and store its one-time state.",
     }),
     op({
         id: "integrations.crm.connections.list",
@@ -24,6 +26,7 @@ export const integrationsOperations = [
     op({
         id: "integrations.crm.connections.schema",
         title: "Read a CRM's field schema",
+        openWorld: true,
         // sampleRecords are literal contact and deal rows from the coach's CRM, which leads and other people filled in.
         untrustedContent: true,
         description: "Discover CRM provider schema.",
@@ -31,6 +34,7 @@ export const integrationsOperations = [
     op({
         id: "integrations.crm.connections.health",
         title: "Check a CRM connection's health",
+        openWorld: true,
         description: "Probe CRM provider health.",
     }),
     op({

package/dist/operations/groups/knowledge.js

@@ -27,6 +27,7 @@ export const knowledgeOperations = [
         id: "knowledge.sources.sync",
         title: "Re-sync a knowledge source",
         mutatesExisting: true,
+        openWorld: true,
         description: "Queue a re-read of one knowledge source now rather than waiting for its next scheduled sync. It returns as soon as the job is queued, so any new suggestions appear on a later read.",
     }),
     op({

package/dist/operations/registry.js

@@ -291,6 +291,7 @@ export function op(input) {
         path,
         scopes,
         mutatesExisting: mutatesExistingRoute,
+        readOnly: input.readOnly ?? method === "GET",
         idempotencyRequired,
         ...optionalField("confirm", input.confirm),
         openWorld: input.openWorld ?? false,

package/dist/resilience.js

@@ -8,16 +8,14 @@ import * as Schedule from "effect/Schedule";
 import * as Str from "effect/String";
 import { formatError, LucaHttpError, LucaTimeoutError, } from "./errors.js";
 /**
- * The statuses worth sending again. All four mean the request never reached the
- * handler, so a replay cannot repeat an effect the first attempt already had.
+ * The statuses worth considering for a retry. A gateway can answer after the
+ * handler ran, so a replay is still subject to read-only or idempotency rules.
  *
  * 500 is deliberately not here. A 500 means the handler ran and threw, which
  * may well be after it wrote something. Replaying that without an idempotency
  * key can double the write.
  */
 const RETRYABLE_STATUSES = HashSet.fromIterable([429, 502, 503, 504]);
-/** Methods with no effect to repeat, so a replay is safe with or without a key. */
-const REPLAYABLE_METHODS = HashSet.fromIterable(["GET", "HEAD"]);
 /**
  * The longest server-requested wait we will sit through. Past this the server
  * is not asking for a retry, it is asking us to come back later. Holding a
@@ -74,7 +72,7 @@ function isTransient(error) {
         : HashSet.has(TRANSIENT_TAGS, error._tag);
 }
 /**
- * Whether this failure may be sent again. Reads are always replayable. A write
+ * Whether this failure may be sent again. Read-only calls are replayable. A write
  * is replayable only when it carries an idempotency key, because the API dedupes
  * by [organizationId, coachId, actorId, method, path, key] and that is the only
  * replay which cannot file the same write twice.
@@ -89,8 +87,7 @@ export function mayRetry(policy, error) {
     if (Option.exists(requestedDelay(error), (ms) => ms > MAX_RETRY_AFTER_MS)) {
         return false;
     }
-    return (HashSet.has(REPLAYABLE_METHODS, policy.method) ||
-        policy.idempotencyKey !== undefined);
+    return policy.readOnly || policy.idempotencyKey !== undefined;
 }
 /**
  * The backoff schedule with a `Retry-After` folded in: the next replay waits
@@ -124,13 +121,13 @@ function lastFailureNote(lastFailure) {
     });
 }
 /**
- * The timeout a caller reads. A read can be sent again. A write that timed out
- * may or may not have landed, so the message says so and names the key that
- * makes a second send safe.
+ * The timeout a caller reads. A read-only call can be sent again. A call that
+ * changes state and timed out may or may not have landed, so the message says
+ * so and names the key that makes a second send safe when there is one.
  */
 function timeoutError(policy, ms, lastFailure = Option.none()) {
     const base = `Luca API did not answer within ${ms}ms${lastFailureNote(lastFailure)}`;
-    if (HashSet.has(REPLAYABLE_METHODS, policy.method)) {
+    if (policy.readOnly) {
         return new LucaTimeoutError({ message: base });
     }
     const replay = policy.idempotencyKey === undefined
@@ -163,6 +160,7 @@ export function resilient(request, timeoutMs, attempt, deadlineMs = CALL_DEADLIN
         const lastFailure = yield* Ref.make(Option.none());
         const policy = {
             method: request.operation.method,
+            readOnly: request.operation.readOnly,
             idempotencyKey,
         };
         return yield* attempt(idempotencyKey).pipe(Effect.timeoutOrElse({

package/dist/task-tools/analytics.js

@@ -177,8 +177,8 @@ const getAnalytics = taskTool({
 });
 const magicMonday = taskTool({
     name: "luca_analytics_magic_monday",
-    title: "Get the Magic Monday report",
-    description: "Return the coach's weekly business intelligence report: pipeline funnel, revenue and ROI, response-speed impact, a point-in-time revenue forecast, and call intelligence (show/close rates), all for the current week. Composes five analytics reads into a single call. Example: call with {} on Monday morning for the week's report.",
+    title: "Read the weekly business report",
+    description: "Return the current week's business report (called Magic Monday in Luca): pipeline funnel, revenue and ROI, response-speed impact, a point-in-time revenue forecast, and call intelligence (show/close rates). Composes five analytics reads into a single call. Example: call with {} for the weekly report.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
     },

package/dist/task-tools/calls.js

@@ -91,12 +91,13 @@ function outcomeBody(input) {
 const closeCallLoop = taskTool({
     name: "luca_close_call_loop",
     title: "Close the loop on a call",
-    description: 'File what happened on a call and what it was worth, in one call. Reports attendance on the call event (completed, no_show, rescheduled, or cancelled) and, when an outcome is given, records the booking outcome: won with an amount, lost with a reason id from luca_bookings_outcome_reasons_list, or open with the next follow-up. This tool sends no message to the lead itself, but the records it files start work in the API. Reporting a no_show can start no-show recovery, which schedules a message to the lead when the booking type has recovery on, so pass confirm: true only after the coach says to report the no-show. A completed call queues its summary, which can later sync to the connected CRM. A won or lost outcome queues a CRM deal-stage update, and lost also moves the lead to lost. Example: { bookingId, attendance: "completed", outcome: "won", amountMinor: 250000, currency: "USD" }.',
-    // Only a no_show can message the lead (through recovery), so only that
-    // report needs approval. The other attendance values stay ungated.
+    description: 'File what happened on a call and what it was worth, in one call. Reports attendance on the call event (completed, no_show, rescheduled, or cancelled) and, when an outcome is given, records the booking outcome: won with an amount, lost with a reason id from luca_bookings_outcome_reasons_list, or open with the next follow-up. This tool sends no message to the lead itself, but the records it files start work in the API. Reporting a no_show can start no-show recovery, which schedules a message to the lead when the booking type has recovery on. A completed call queues its summary, which can later sync to the connected CRM. A won or lost outcome queues a CRM deal-stage update, and lost also moves the lead to lost. Pass confirm: true before reporting a no_show or recording a won or lost outcome. Example: { bookingId, attendance: "completed", outcome: "won", amountMinor: 250000, currency: "USD", confirm: true }.',
+    // Recovery messaging and CRM deal updates are the two external effects.
     confirm: {
-        applies: (input) => input.attendance === "no_show",
-        description: "attendance is no_show (can start recovery messaging)",
+        applies: (input) => input.attendance === "no_show" ||
+            input.outcome === "won" ||
+            input.outcome === "lost",
+        description: "attendance is no_show or outcome is won or lost (can message a lead or update a connected CRM deal)",
     },
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,

package/dist/tool.js

@@ -91,7 +91,7 @@ function buildFromTaskTool(tool) {
             ...openApiToolOutputFields({ body: null, untrustedContent }),
             result: tool.outputSchema,
         },
-        readOnly: composed.every((operation) => operation.method === "GET"),
+        readOnly: composed.every((operation) => operation.readOnly),
         // A task tool overwrites or removes existing state when any write it
         // composes does.
         mutatesExisting: composed.some((operation) => operation.mutatesExisting),
@@ -144,9 +144,8 @@ function toolResult(tool, lucaLayer, surface,
 // oxlint-disable-next-line anti-slop/no-unknown-parameters -- input is the same raw MCP JSON-RPC tool-call arguments registerTool's server.registerTool callback hands in; parseToolInput below is what actually validates it.
 input) {
     const logCall = (outcome, elapsed) => 
-    // A 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.
+    // A defect's own message never lands here or in the tool result: it can
+    // carry arbitrary thrown text derived from the call's input.
     logAgentSurfaceEvent("mcp.tool.called", {
         toolName: tool.name,
         toolset: surface.toolset,
@@ -184,12 +183,11 @@ function settle(tool, surface, exit) {
             asErrorResult(failure, authChallengeMeta(failure, tool.oauthScope, surface.resourceMetadataUrl)),
         ];
     }
-    const defect = Cause.squash(cause);
     return [
         "defect",
-        asErrorResult(
-        // oxlint-disable-next-line effect/avoid-untagged-errors -- boundary narrows an unknown thrown value that carries no tag
-        defect instanceof Error ? defect : new Error(String(defect))),
+        // A defect may include request data or credentials in its message. Keep
+        // the protocol error generic and record only the defect outcome in logs.
+        asErrorResult("Unexpected Luca MCP tool failure"),
     ];
 }
 /** The Effect program that runs an operation, auto-paginating list tools. */

package/dist/version.js

@@ -9,6 +9,6 @@
  *
  * Bump this in the same commit as package.json and server.json.
  */
-export const LUCA_MCP_VERSION = "0.3.1";
+export const LUCA_MCP_VERSION = "0.3.3";
 /** The user-agent every outbound Luca API call identifies itself with. */
 export const LUCA_MCP_USER_AGENT = `luca-mcp/${LUCA_MCP_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@setluca/mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": false,
   "description": "Let your AI assistant help with Luca conversations, leads, replies, campaigns, and bookings.",
   "keywords": [