@setluca/mcp 0.5.1 → 0.5.2

package/dist/http.js

@@ -171,13 +171,13 @@ function sendOnce(config, input, requestIdempotencyKey, fetchImpl) {
             const now = yield* Clock.currentTimeMillis;
             const waitMs = retryAfterMs(response, now);
             const text = yield* readText.pipe(Effect.orElseSucceed(() => ""));
-            return yield* Effect.fail(new LucaHttpError({
+            return yield* new LucaHttpError({
                 status: response.status,
                 statusText: response.statusText,
                 body: yield* errorBody(text),
                 ...optionalField("requestId", response.headers.get("x-request-id")),
                 ...optionalField("retryAfterMs", waitMs),
-            }));
+            });
         }
         const text = yield* readText;
         // An empty body is not a decode failure. Several endpoints answer with

package/dist/oauth-resolver.js

@@ -38,7 +38,7 @@ function resolvePayload(response) {
     return Effect.tryPromise({
         try: () => response.json(),
         catch: unavailable("Token verification returned non-JSON content"),
-    }).pipe(Effect.flatMap((body) => decodeResolvePayload(body).pipe(Effect.mapError(unavailable("Token verification returned an unexpected body")))), Effect.map(Option.some));
+    }).pipe(Effect.flatMap((body) => decodeResolvePayload(body).pipe(Effect.mapError(unavailable("Token verification returned an unexpected body")))), Effect.asSome);
 }
 /**
  * One authenticated call to POST /oauth/resolve, answered with the config for

package/dist/operations/groups/bookings.js

@@ -115,7 +115,7 @@ export const bookingsOperations = [
         mutatesExisting: true,
         // Moves the call on the provider calendar and re-arms the lead's reminder.
         confirm: "always",
-        description: "Reschedule or update booking status.",
+        description: "Reschedule or update booking status. A Google Calendar or Cal.com booking changes on that calendar too, and the calendar can email the lead about it.",
         // Each booking carries a cancellation reason the invitee may have written.
         untrustedContent: true,
     }),
@@ -126,7 +126,7 @@ export const bookingsOperations = [
         mutatesExisting: true,
         // Cancels a real call on the lead's and the coach's calendars.
         confirm: "always",
-        description: "Cancel a booking.",
+        description: "Cancel a booking. A Google Calendar or Cal.com booking is cancelled on that calendar too, and the calendar can email the lead about it.",
         // Each booking carries a cancellation reason the invitee may have written.
         untrustedContent: true,
     }),

package/dist/operations/groups/campaigns.js

@@ -19,7 +19,7 @@ export const campaignsOperations = [
     op({
         id: "campaigns.generate",
         title: "Generate a campaign draft",
-        description: "Generate a safe AI campaign plan without creating or publishing it.",
+        description: "Build a campaign plan from a brief with fixed rules, not an AI model. Nothing is created or published: create the draft from the plan, review it, and publish it yourself.",
     }),
     op({
         id: "campaigns.draft.update",

package/dist/operations/groups/conversations.js

@@ -66,6 +66,8 @@ export const conversationsOperations = [
         untrustedContent: false,
         title: "Retry a voice-note transcription",
         mutatesExisting: true,
+        // The retried job sends the voice note to OpenRouter's speech-to-text.
+        openWorld: true,
         description: "Queue another transcription attempt for a voice note in this conversation. Only re-transcribes; never drafts or sends. A refusal says why: a retry is already running, the limit is reached, or the audio is gone.",
     }),
 ];

package/dist/operations/groups/leads.js

@@ -29,7 +29,7 @@ export const leadsOperations = [
         // Sends lead.updated to the coach's webhook subscribers, and a tag change
         // can resume a campaign step that messages the lead.
         openWorld: true,
-        description: "Update a lead's display name, stage, score, tags, or custom fields.",
+        description: "Update a lead's display name, stage, tags, or custom fields. Tags are replaced as a whole list.",
     }),
     op({
         id: "leads.fieldDefinitions.list",
@@ -99,7 +99,13 @@ export const leadsOperations = [
         id: "leads.draft",
         title: "Draft a reply to a lead",
         untrustedContent: true,
-        description: "Draft a reply for a lead, written the way the coach writes, and put it in the review queue for the coach to approve. It never sends, whatever the channel's auto-send setting. Optional guidance steers tone or content.",
+        // Drafting again replaces the lead's pending on-demand draft, as
+        // reviewQueue.regenerate replaces a queued one.
+        mutatesExisting: true,
+        // The drafter sends the conversation to OpenRouter's language model, the
+        // same reach that makes a transcription retry open-world.
+        openWorld: true,
+        description: "Draft a reply for a lead, written the way the coach writes, and put it in the review queue for the coach to approve. Drafting again replaces this lead's earlier unapproved draft from this tool. It never sends, whatever the channel's auto-send setting. Optional guidance steers tone or content.",
     }),
     op({
         id: "leads.notes.delete",

package/dist/operations/groups/reviewQueue.js

@@ -44,6 +44,9 @@ export const reviewQueueOperations = [
         untrustedContent: false,
         title: "Retry a draft's failed media",
         mutatesExisting: true,
+        // The same transcription job as conversations.media_retry, so the voice
+        // note goes to OpenRouter's speech-to-text.
+        openWorld: true,
         description: "Retry a failed voice-note transcription so the draft can be reviewed. Only re-transcribes; never redrafts or sends.",
     }),
     op({

package/dist/pagination.js

@@ -19,6 +19,30 @@ const isCursor = Schema.is(NonEmptyString);
 function pageItems(page, itemsKey) {
     return Option.getOrElse(decodeItems(page[itemsKey]), () => []);
 }
+const hasStringId = Schema.is(Schema.Struct({ id: Schema.String }));
+/**
+ * A reader for the ids of the first `limit` records on a page of `operation`,
+ * for a caller that fans out over what a list route returned. The records sit
+ * under the field the route's page contract names: `items` on the review
+ * queue, `campaigns` on a campaign page. A page without that array, or a record
+ * without a string id, contributes nothing, and the caller still has the page.
+ *
+ * Throws when `operation` is not a list route. Naming one is a wiring mistake,
+ * and an empty id list is exactly how it would stay hidden.
+ */
+export function recordIdsOf(operation) {
+    const itemsKey = operation.pageContract?.itemsKey;
+    if (itemsKey === undefined) {
+        // oxlint-disable-next-line effect/avoid-untagged-errors -- raw failure on an invariant or interop path; not a caller-recoverable domain failure
+        throw new Error(`${operation.id} carries no list of records to read ids from`);
+    }
+    return (page, limit) => isJsonObject(page)
+        ? pageItems(page, itemsKey)
+            .slice(0, limit)
+            .filter(hasStringId)
+            .map((record) => record.id)
+        : [];
+}
 /**
  * The page as something the walk can merge, or nothing when the body is not an
  * object or does not carry the array the route's page shape names. Merging a
@@ -104,7 +128,7 @@ function walkPages(walk, ref) {
             // list would read as "page 3 is down", and only a failed tool result
             // carries the challenge that sends the client back through sign-in.
             if (Result.isFailure(page) && isAuthorizationFailure(page.failure)) {
-                return yield* Effect.fail(page.failure);
+                return yield* page.failure;
             }
             yield* Ref.set(ref, Result.match(page, {
                 onFailure: (error) => failedPage(state, formatError(error)),

package/dist/remote.js

@@ -11,7 +11,7 @@ import { bearerChallenge } from "./oauth-challenge.js";
 import { logAgentSurfaceEvent } from "./observability.js";
 import { optionalField } from "./optional-field.js";
 import { RATE_LIMIT_WINDOW_MS, createLocalRateLimits, } from "./rate-limit.js";
-import { OAUTH_DEFAULT_SCOPE } from "./scopes.js";
+import { OAUTH_CHALLENGE_SCOPE } from "./scopes.js";
 import { toJsonPayload } from "./serialization.js";
 import { createLucaServer } from "./server.js";
 import { sha256Hex } from "./token-verification.js";
@@ -81,13 +81,14 @@ const throttleAnonymous = (request, rateLimits) => consume(rateLimits.perAnonymo
 /**
  * A 401 with the RFC 6750 challenge. `resource_metadata` points OAuth clients
  * at the RFC 9728 document that names the authorization server. Only a request
- * with no token also gets the `scope` hint: a client whose token was refused
+ * with no token also gets the `scope` hint, which names every scope so the
+ * coach can choose on the consent screen: a client whose token was refused
  * must refresh it, not ask for a different scope.
  */
 function unauthorized(detail, resourceMetadataUrl, error) {
     const challenge = bearerChallenge({
         resourceMetadataUrl,
-        ...(error === undefined ? { scope: OAUTH_DEFAULT_SCOPE } : { error }),
+        ...(error === undefined ? { scope: OAUTH_CHALLENGE_SCOPE } : { error }),
     });
     return jsonResponse(401, { error: "unauthorized", detail }, { "www-authenticate": challenge });
 }

package/dist/scopes.js

@@ -40,6 +40,20 @@ export const LUCA_OAUTH_SCOPES = [
 export const LUCA_RESOURCE_SCOPES = Arr.filter(LUCA_OAUTH_SCOPES, (scope) => scope !== "offline_access");
 /** Least-privilege default for a new OAuth connection. */
 export const OAUTH_DEFAULT_SCOPE = "luca:read luca:draft";
+/**
+ * The scope a 401 challenge asks for: every scope this resource accepts, plus
+ * `offline_access`. Claude and ChatGPT request exactly what the challenge
+ * names, and the consent screen offers only what was requested, so naming less
+ * would leave a coach no way to let an assistant send or book. The screen
+ * still starts at {@link OAUTH_DEFAULT_SCOPE}: read is locked on, draft starts
+ * on, and every higher scope starts unchecked for the coach to tick.
+ *
+ * `offline_access` is here for the refresh token. The authorization server
+ * issues one only when the grant carries it, and a client asks for no more
+ * than the challenge names, so without it every connection lapses when its
+ * one-hour access token does.
+ */
+export const OAUTH_CHALLENGE_SCOPE = LUCA_OAUTH_SCOPES.join(" ");
 const READ_TIER_SCOPES = [
     "analytics:read",
     "bookings:read",

package/dist/server.js

@@ -25,12 +25,30 @@ import { fromOperation, fromTaskTool, operationProgram, registerTool, } from "./
 import { TOOLSETS } from "./toolsets.js";
 import { LUCA_MCP_VERSION } from "./version.js";
 const LucaLive = LucaApiLive.pipe(Layer.provide(LucaConfigLive));
+/**
+ * SetLuca's icons, for the Worker's server card. They stay out of
+ * {@link LUCA_SERVER_INFO}: claude.ai abandons a session whose `initialize`
+ * answer carries `serverInfo.icons`, at any protocol version
+ * (anthropics/claude-ai-mcp#474, open). The directories take their icon from
+ * the listing upload, not the handshake, so leaving them out costs nothing.
+ */
+export const LUCA_SERVER_ICONS = [
+    {
+        src: "https://setluca.com/favicon.svg?v=wordmark-1",
+        mimeType: "image/svg+xml",
+    },
+    {
+        src: "https://setluca.com/android-chrome-512x512.png?v=wordmark-1",
+        mimeType: "image/png",
+        sizes: ["512x512"],
+    },
+];
 /**
  * How this server identifies itself to a client. Protocol revision 2026-07-28
- * carries a title, description, website, and icons alongside the name and
- * version, and a client renders those in its server list instead of the bare
- * package name. The Worker's server card is built from the same values, so
- * the two descriptions of this server cannot drift apart.
+ * carries a title, description, and website alongside the name and version,
+ * and a client renders those in its server list instead of the bare package
+ * name. The Worker's server card is built from the same values, so the two
+ * descriptions of this server cannot drift apart.
  */
 export const LUCA_SERVER_INFO = {
     name: "luca-mcp",
@@ -40,17 +58,6 @@ export const LUCA_SERVER_INFO = {
     // live and says which one is not.
     description: "SetLuca runs DM sales for coaches, creators, and experts. Work with leads, conversations, drafted replies, campaigns, broadcasts, and booked calls on Telegram, Instagram, and Messenger. WhatsApp is coming soon.",
     websiteUrl: "https://setluca.com",
-    icons: [
-        {
-            src: "https://setluca.com/favicon.svg?v=wordmark-1",
-            mimeType: "image/svg+xml",
-        },
-        {
-            src: "https://setluca.com/android-chrome-512x512.png?v=wordmark-1",
-            mimeType: "image/png",
-            sizes: ["512x512"],
-        },
-    ],
 };
 /**
  * What a client hands its model at connection time: where to start and which

package/dist/task-tools/analytics.js

@@ -6,10 +6,13 @@ import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import { formatError } from "../errors.js";
 import { NonEmptyString, WORKSPACE_INPUT_FIELDS } from "../fields.js";
+import { operationById } from "../operations.js";
 import { optionalField } from "../optional-field.js";
-import { failureAsField, listingIds, numberInput, operationResult, resultOrError, sectionResult, taskTool, } from "./runtime.js";
+import { recordIdsOf } from "../pagination.js";
+import { failureAsField, numberInput, operationResult, resultOrError, sectionResult, taskTool, } from "./runtime.js";
 const DEFAULT_CAMPAIGN_LIMIT = 5;
 const CAMPAIGN_BROADCAST_LIMIT = 10;
+const campaignIds = recordIdsOf(operationById("campaigns.list"));
 const ANALYTICS_PERIOD_VALUES = [
     "this_week",
     "this_month",
@@ -130,7 +133,7 @@ function analyticsFanOut(call, period, reads) {
  * {@link failureAsField}.
  */
 function campaignAnalytics(call, page, limit) {
-    return Effect.forEach(listingIds(page, limit), (id) => failureAsField("analyticsError", call("campaigns.analytics", { pathParams: { id } })).pipe(Effect.map((analytics) => [id, analytics])), 
+    return Effect.forEach(campaignIds(page, limit), (id) => failureAsField("analyticsError", call("campaigns.analytics", { pathParams: { id } })).pipe(Effect.map((analytics) => [id, analytics])), 
     // Effect.forEach also defaults to concurrency 1. The limit caps this at 5
     // independent per-campaign lookups, so unbounded is fine.
     { concurrency: "unbounded" }).pipe(Effect.map(R.fromEntries));

package/dist/task-tools/bookings.js

@@ -239,7 +239,7 @@ const DEFAULT_GUEST_LINK_HOURS = 168;
 const rescheduleCall = taskTool({
     name: "luca_reschedule_call",
     title: "Move a call to a new time",
-    description: "Move a booked call to a new time and hand back a fresh reschedule link for the lead. Checks the new slot is open first, against the schedule of its booking type when it has one, and returns the open slots instead of moving the call when it is taken. A call with an idempotencyKey skips that check so a retry gets the original result back. A manual booking moves in Luca only. A Cal.com or Google Calendar booking moves on that calendar too, but only once the provider confirms: until then the booking's operation.state reads pending_provider and it keeps its old time, so read the booking again before telling the coach the call moved. A Calendly, GoHighLevel or iClosed booking is refused so the coach can move it with the provider, and so is a provider booking with no calendar event, such as one recorded with luca_bookings_create. Moving the call re-arms the lead's reminder for the new time, so pass confirm: true only after the coach approves the move. Example: call with { bookingId, slotAt: \"2026-07-16T15:00:00Z\", confirm: true } after the lead asked to push the call. No message about the move is sent: send the lead the link yourself, or draft the message through the review queue.",
+    description: "Move a booked call to a new time and hand back a fresh reschedule link for the lead. Checks the new slot is open first, against the schedule of its booking type when it has one, and returns the open slots instead of moving the call when it is taken. A call with an idempotencyKey skips that check so a retry gets the original result back. A manual booking moves in SetLuca only. A Cal.com or Google Calendar booking moves on that calendar too, but only once the provider confirms: until then the booking's operation.state reads pending_provider and it keeps its old time, so read the booking again before telling the coach the call moved. A Calendly, GoHighLevel or iClosed booking is refused so the coach can move it with the provider, and so is a provider booking with no calendar event, such as one recorded with luca_bookings_create. Moving the call re-arms the lead's reminder for the new time, so pass confirm: true only after the coach approves the move. Example: call with { bookingId, slotAt: \"2026-07-16T15:00:00Z\", confirm: true } after the lead asked to push the call. SetLuca sends the lead no DM about the move, but a Google Calendar booking's calendar emails the lead the updated invite, and Cal.com may too. Send the lead the link yourself, or draft the message through the review queue.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
         bookingId: NonEmptyString.annotate({ description: "The booking to move." }),
@@ -282,7 +282,7 @@ const rescheduleCall = taskTool({
                 ...window,
                 bookingTypeId,
                 timezone: "UTC",
-            }).pipe(Effect.map(Option.some)),
+            }).pipe(Effect.asSome),
         })));
         if (Option.isSome(open) &&
             !open.value.some((candidate) => sameInstant(candidate, slotAt))) {

package/dist/task-tools/inbox.js

@@ -5,9 +5,12 @@ import * as Schema from "effect/Schema";
 import { formatError } from "../errors.js";
 import { WORKSPACE_INPUT_FIELDS } from "../fields.js";
 import { logAgentSurfaceEvent } from "../observability.js";
-import { isPartialFailure, listingIds, numberInput, operationResult, resultOrError, taskTool, } from "./runtime.js";
+import { operationById } from "../operations.js";
+import { recordIdsOf } from "../pagination.js";
+import { isPartialFailure, numberInput, operationResult, resultOrError, taskTool, } from "./runtime.js";
 const DEFAULT_QUEUE_LIMIT = 20;
 const DEFAULT_EXPLAIN_TOP = 3;
+const queueIds = recordIdsOf(operationById("reviewQueue.list"));
 const TRIAGE_INBOX_TOOL_NAME = "luca_triage_inbox";
 /**
  * One explanation, with a failed lookup carried in the result instead of
@@ -79,7 +82,7 @@ const triageInbox = taskTool({
         const queue = yield* call("reviewQueue.list", {
             query: { limit: numberInput(input.limit, DEFAULT_QUEUE_LIMIT) },
         });
-        const ids = listingIds(queue, numberInput(input.explainTop, DEFAULT_EXPLAIN_TOP));
+        const ids = queueIds(queue, numberInput(input.explainTop, DEFAULT_EXPLAIN_TOP));
         const attempts = yield* Effect.forEach(ids, (id) => explainOne(call, id), 
         // Effect.forEach defaults to concurrency 1 (sequential). `explainTop`
         // caps this fan-out at 5 independent lookups, so unbounded is fine.

package/dist/task-tools/leads.js

@@ -48,7 +48,7 @@ const flagForHuman = taskTool({
 const draftReply = taskTool({
     name: "luca_draft_reply",
     title: "Draft a reply for a lead",
-    description: 'Draft a reply for a lead, written the way the coach writes, and put it in the SetLuca review queue, where it waits for the coach to approve it. It never sends, whatever the channel\'s auto-send setting. Optional guidance steers tone or content. Example: call with { leadId, guidance: "keep it short and warm" }.',
+    description: "Draft a reply for a lead, written the way the coach writes, and put it in the SetLuca review queue, where it waits for the coach to approve it. Drafting again replaces this lead's earlier unapproved draft from this tool. It never sends, whatever the channel's auto-send setting. Optional guidance steers tone or content. Example: call with { leadId, guidance: \"keep it short and warm\" }.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
         leadId: NonEmptyString.annotate({

package/dist/task-tools/runtime.js

@@ -63,38 +63,6 @@ export function taskRequest(operation, input, parts = {}) {
         ...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, 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

package/dist/toolsets.js

@@ -1,8 +1,8 @@
 import { LUCA_TASK_TOOLS } from "./task-tools.js";
 /**
- * The tools the `claude` toolset exposes. This list is the contract with the
- * connector directory submission, and a test pins it name for name. Adding or
- * removing a tool here changes what the directory lists.
+ * The tools the `claude` toolset exposes, and a test pins it name for name.
+ * Coaches who chose `?toolset=claude` rely on it staying read and draft, so a
+ * tool that sends, books, or changes settings does not belong here.
  */
 export const CLAUDE_TOOL_NAMES = [
     "luca_triage_inbox",

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.5.1";
+export const LUCA_MCP_VERSION = "0.5.2";
 /** 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.5.1",
+  "version": "0.5.2",
   "private": false,
   "description": "Connect SetLuca to Claude, ChatGPT, Cursor, or any MCP client to triage the review queue, look up leads, draft replies, and check campaigns.",
   "keywords": [
@@ -68,15 +68,17 @@
     "registry:check": "bun scripts/check-registry.ts",
     "docs:generate": "bun scripts/generate-docs.ts --write",
     "docs:check": "bun scripts/generate-docs.ts --check",
-    "clean": "rm -rf .turbo dist coverage node_modules"
+    "clean": "rm -rf .turbo dist coverage node_modules",
+    "prepare": "effect-tsgo patch --typescript --no-oxlint"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "effect": "4.0.0"
+    "effect": "4.0.6"
   },
   "devDependencies": {
-    "@effect/platform-bun": "4.0.0",
-    "@effect/vitest": "4.0.0",
+    "@effect/platform-bun": "4.0.6",
+    "@effect/tsgo": "0.56.0",
+    "@effect/vitest": "4.0.6",
     "@modelcontextprotocol/client": "^2.0.0",
     "@modelcontextprotocol/inspector": "^2.5.0",
     "@mpsuesser/oxlint-plugin-effect": "0.6.0",