@setluca/mcp 0.1.1 → 0.2.1

package/dist/operations/groups/insights.js

@@ -0,0 +1,33 @@
+import { op } from "../registry.js";
+export const insightsOperations = [
+    op({
+        id: "insights.unreadCount",
+        title: "Count unread insights",
+        description: "How many insights the coach has not read yet. Cheap enough to poll before pulling the whole feed.",
+    }),
+    op({
+        id: "insights.markRead",
+        title: "Mark an insight read",
+        description: "Mark one insight read, so it stops coming back at the top of the feed.",
+    }),
+    op({
+        id: "insights.dismiss",
+        title: "Dismiss an insight",
+        description: "Dismiss one insight the coach does not want to act on. Use this rather than leaving it unread forever.",
+    }),
+    op({
+        id: "insights.markActioned",
+        title: "Mark an insight actioned",
+        description: "Record that the thing an insight asked for was actually done. Use it after doing the work, not instead of it.",
+    }),
+    op({
+        id: "insights.settings.get",
+        title: "Read alert delivery settings",
+        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({
+        id: "insights.settings.update",
+        title: "Update alert delivery settings",
+        description: "Merge-patch the coach's alert-delivery settings. Send only what you are changing; anything left out keeps its current value.",
+    }),
+];

package/dist/operations/groups/integrations.js

@@ -0,0 +1,80 @@
+import { op } from "../registry.js";
+export const integrationsOperations = [
+    op({
+        id: "integrations.connectors.list",
+        title: "List available connectors",
+        description: "List Zapier, Make, and CRM provider capabilities.",
+    }),
+    op({
+        id: "integrations.crm.oauthUrl",
+        title: "Start a CRM connection",
+        description: "Create a CRM provider OAuth URL.",
+    }),
+    op({
+        id: "integrations.crm.oauthCallback",
+        title: "Finish a CRM connection",
+        description: "Exchange a CRM OAuth code and store encrypted credentials.",
+    }),
+    op({
+        id: "integrations.crm.connections.list",
+        title: "List CRM connections",
+        description: "List CRM connections.",
+    }),
+    op({
+        id: "integrations.crm.connections.create",
+        title: "Create a CRM connection",
+        description: "Create or update a workspace-scoped CRM connection.",
+    }),
+    op({
+        id: "integrations.crm.connections.schema",
+        title: "Read a CRM's field schema",
+        description: "Discover CRM provider schema.",
+        redactedFields: ["sampleRecords"],
+    }),
+    op({
+        id: "integrations.crm.connections.health",
+        title: "Check a CRM connection's health",
+        description: "Probe CRM provider health.",
+    }),
+    op({
+        id: "integrations.crm.connections.webhooksSetup",
+        title: "Set up a CRM's webhooks",
+        description: "Configure CRM provider webhook status.",
+    }),
+    op({
+        id: "integrations.crm.webhooks.record",
+        title: "Record a CRM webhook",
+        description: "Record an inbound CRM provider webhook event. Idempotent on the provider's event id, so a redelivery is recorded once.",
+    }),
+    op({
+        id: "integrations.crm.mappings.suggest",
+        title: "Suggest CRM field mappings",
+        description: "Suggest CRM field mappings.",
+    }),
+    op({
+        id: "integrations.crm.mappings.confirm",
+        title: "Confirm CRM field mappings",
+        description: "Confirm CRM field mappings.",
+    }),
+    op({
+        id: "integrations.crm.syncRuns.list",
+        title: "List CRM sync runs",
+        description: "List CRM sync history.",
+        redactedFields: [
+            "syncRuns[].appliedMutations[].fields",
+            "syncRuns[].plannedMutations[].fields",
+        ],
+    }),
+    op({
+        id: "integrations.crm.syncRuns.create",
+        title: "Start a CRM sync",
+        description: "Create a CRM dry-run or live sync run.",
+        redactedFields: ["appliedMutations[].fields", "plannedMutations[].fields"],
+    }),
+    op({
+        id: "integrations.events.list",
+        title: "List integration events",
+        description: "List integration event log.",
+        redactedFields: ["events[].payload"],
+    }),
+];

package/dist/operations/groups/knowledge.js

@@ -0,0 +1,34 @@
+import { op } from "../registry.js";
+export const knowledgeOperations = [
+    op({
+        id: "knowledge.suggestions",
+        title: "List knowledge suggestions",
+        description: "List profile changes proposed from the coach's own knowledge sources, each with the excerpt it was drawn from and the value it would replace.",
+    }),
+    op({
+        id: "knowledge.approveSuggestion",
+        title: "Approve a knowledge suggestion",
+        confirmRequired: true,
+        description: "Approve a profile suggestion and write it into the coach's profile. Every later draft reads the result, so check the excerpt supports the change before approving.",
+    }),
+    op({
+        id: "knowledge.rejectSuggestion",
+        title: "Reject a knowledge suggestion",
+        description: "Reject a profile suggestion so it stops being offered. The profile is left as it stands.",
+    }),
+    op({
+        id: "knowledge.sources.list",
+        title: "List knowledge sources",
+        description: "List the content sources the coach has connected \u2014 Notion, Google Docs, a website, an Instagram bio \u2014 with the sync state of each one. Connecting a new source is app-only; this lists what is already there.",
+    }),
+    op({
+        id: "knowledge.sources.sync",
+        title: "Re-sync a knowledge source",
+        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({
+        id: "knowledge.sources.disconnect",
+        title: "Disconnect a knowledge source",
+        description: "Delete a knowledge source. Its pending suggestions go with it; values the coach already approved stay in the profile, because approving copies them there.",
+    }),
+];

package/dist/operations/groups/leads.js

@@ -0,0 +1,101 @@
+import { op } from "../registry.js";
+export const leadsOperations = [
+    op({
+        id: "leads.list",
+        title: "List leads",
+        description: "List leads. Query supports limit, cursor, channel, and q according to Luca OpenAPI.",
+        redactedFields: ["leads[].displayName", "leads[].externalUserId"],
+    }),
+    op({
+        id: "leads.get",
+        title: "Get a lead's timeline",
+        description: "Get a lead's full timeline and notes.",
+        redactedFields: [
+            "identities[].displayName",
+            "identities[].externalUserId",
+            "lead.customFields",
+            "lead.displayName",
+            "messages[].body",
+            "messages[].media",
+            "notes[].body",
+        ],
+    }),
+    op({
+        id: "leads.explain",
+        title: "Explain why a lead qualified",
+        description: "Explain why a lead qualified: the qualifier's reasoning, signals, and confidence from its most recent drafted turn.",
+        redactedFields: ["qualification"],
+    }),
+    op({
+        id: "leads.create",
+        title: "Create or upsert a lead",
+        description: "Create or upsert a lead identity. Body requires channel and externalUserId.",
+        redactedFields: [
+            "lead.customFields",
+            "lead.displayName",
+            "lead.externalUserId",
+        ],
+    }),
+    op({
+        id: "leads.update",
+        title: "Update a lead",
+        description: "Update a lead's display name, stage, score, tags, or custom fields.",
+        redactedFields: [
+            "lead.customFields",
+            "lead.displayName",
+            "lead.externalUserId",
+        ],
+    }),
+    op({
+        id: "leads.fieldDefinitions.list",
+        title: "List custom lead fields",
+        description: "List custom lead field definitions.",
+    }),
+    op({
+        id: "leads.fieldDefinitions.upsert",
+        title: "Define a custom lead field",
+        description: "Create or update a custom lead field definition.",
+    }),
+    op({
+        id: "leads.importPreview",
+        title: "Preview a lead import",
+        description: "Preview a mapped CSV lead import before applying it.",
+    }),
+    op({
+        id: "leads.importApply",
+        title: "Apply a lead import",
+        description: "Apply a mapped lead import with consent evidence.",
+    }),
+    op({
+        id: "leads.identities.attach",
+        title: "Attach a channel identity to a lead",
+        description: "Attach a verified or claimed identity to a lead.",
+    }),
+    op({
+        id: "leads.consents.grant",
+        title: "Record a lead's consent",
+        description: "Grant explicit lead consent for a channel purpose.",
+    }),
+    op({
+        id: "leads.consents.revoke",
+        title: "Revoke a lead's consent",
+        description: "Revoke explicit lead consent for a channel purpose.",
+    }),
+    op({
+        id: "leads.notes.add",
+        title: "Add a note to a lead",
+        description: "Append a coach note to a lead. Body requires body.",
+        redactedFields: ["note.body"],
+    }),
+    op({
+        id: "leads.draft",
+        title: "Draft a reply to a lead",
+        description: "Draft a voice-matched reply for a lead on demand and queue it for review. Optional guidance steers tone or content.",
+        redactedFields: ["draft.body"],
+    }),
+    op({
+        id: "leads.notes.delete",
+        title: "Delete a lead note",
+        description: "Remove one coach note from a lead and leave the rest of the timeline alone. This is how a note filed by mistake gets taken back.",
+    }),
+];

package/dist/operations/groups/learning.js

@@ -0,0 +1,24 @@
+import { op } from "../registry.js";
+export const learningOperations = [
+    op({
+        id: "learning.panel",
+        title: "Read what Luca wants to learn",
+        description: "Read which of the three profile questions Luca still owes an answer to, with suggested answers inferred from the coach's own words. The worked example pair is blanked for a redacted-tier key.",
+        redactedFields: ["exampleDm", "exampleDraft"],
+    }),
+    op({
+        id: "learning.frameworkPerformance",
+        title: "Read framework objection performance",
+        description: "Win rate by objection bucket for the sales framework the coach has configured right now, over a rolling window. These numbers are correlational \u2014 read them as a signal, not as proof a framework caused the result.",
+    }),
+    op({
+        id: "learning.proposals.list",
+        title: "List learning proposals",
+        description: "List what the coach's tests have learned and are proposing they act on, newest first. Dismissed proposals are left out unless you ask for them.",
+    }),
+    op({
+        id: "learning.proposals.dismiss",
+        title: "Dismiss a learning proposal",
+        description: "Dismiss one learning proposal so it drops out of the default list. Use it when the coach has decided against the change, not when you have simply read it.",
+    }),
+];

package/dist/operations/groups/memory.js

@@ -0,0 +1,27 @@
+import { op } from "../registry.js";
+export const memoryOperations = [
+    op({
+        id: "memory.list",
+        title: "List what Luca remembers",
+        description: "List what Luca remembers, filtered by lead, scope, source, trust level, or free text. The fact, the reasoning, and the quoted evidence are blanked for a redacted-tier key; trust level, lead, and dates always come back.",
+        redactedFields: [
+            "memories[].content",
+            "memories[].evidence",
+            "memories[].reason",
+        ],
+    }),
+    op({
+        id: "memory.update",
+        title: "Edit a memory",
+        // The corrected memory comes back in full, and a memory is a fact Luca
+        // extracted from what a lead wrote.
+        untrustedContent: true,
+        description: "Correct one memory: edit the fact, flag it disputed when it turns out to be wrong, restore an archived one, or make it win over a conflicting memory.",
+        redactedFields: ["content", "evidence", "reason"],
+    }),
+    op({
+        id: "memory.setArchived",
+        title: "Archive or restore memories",
+        description: "Archive or restore several memories at once. Archiving stops Luca using a fact while the record and its provenance survive, so it is always reversible.",
+    }),
+];

package/dist/operations/groups/reports.js

@@ -0,0 +1,14 @@
+import { op } from "../registry.js";
+export const reportsOperations = [
+    op({
+        id: "reports.scorecard",
+        title: "Read the scorecard",
+        description: "Read the sales scorecard for a window: calls booked and completed, show rate, won and lost, draft approvals, and hours saved.",
+    }),
+    op({
+        id: "reports.morning",
+        title: "Read the morning report",
+        description: "Structured 24h review-queue digest (items + counts) for the coach. No model call; summarize client-side.",
+        redactedFields: ["items[].draftBody"],
+    }),
+];

package/dist/operations/groups/reviewQueue.js

@@ -0,0 +1,57 @@
+import { op } from "../registry.js";
+export const reviewQueueOperations = [
+    op({
+        id: "reviewQueue.list",
+        title: "List the review queue",
+        description: "List review-queue items when the API key has review queue access.",
+        redactedFields: [
+            "items[].criticIssues",
+            "items[].draftBody",
+            "items[].draftParts",
+            "items[].leadDisplayName",
+            "items[].media",
+            "items[].mediaContext",
+            "items[].objectionVariants",
+            "items[].qualification",
+            "items[].safetyFindings",
+            "items[].signals",
+        ],
+    }),
+    op({
+        id: "reviewQueue.explain",
+        title: "Explain a queued draft",
+        description: "Explain the signals behind a drafted reply: its voice-match score, any critic findings, and the qualification that motivated it.",
+        redactedFields: ["criticIssues", "draftBody", "qualification"],
+    }),
+    op({
+        id: "reviewQueue.approve",
+        title: "Approve and send a queued draft",
+        confirmRequired: true,
+        description: "Approve a pending draft for sending; dispatches through the lead's channel. Sends a real message.",
+    }),
+    op({
+        id: "reviewQueue.reject",
+        title: "Reject a queued draft",
+        description: "Reject a pending review-queue draft so it never sends. Stops any related booking-recovery cadence and emits review.rejected.",
+    }),
+    op({
+        id: "reviewQueue.restore",
+        title: "Restore a rejected draft",
+        description: "Restore a rejected review-queue item back to pending. Fails if it's a booking message whose recovery window already passed.",
+    }),
+    op({
+        id: "reviewQueue.media.retry",
+        title: "Retry a draft's failed media",
+        description: "Retry a failed voice-note transcription so the draft can be reviewed. Only re-transcribes; never redrafts or sends.",
+    }),
+    op({
+        id: "reviewQueue.sla",
+        title: "Check the review queue's response times",
+        description: "Read median first-response time and its daily trend. Tells you whether the queue is being cleared fast enough.",
+    }),
+    op({
+        id: "reviewQueue.objectionVariant",
+        title: "Record an objection variant choice",
+        description: "Record which objection-specialist variant was picked for one queued draft. It is how the objection tests learn which handling works, so record the variant the coach actually chose.",
+    }),
+];

package/dist/operations/groups/safety.js

@@ -0,0 +1,8 @@
+import { op } from "../registry.js";
+export const safetyOperations = [
+    op({
+        id: "safety.accounts",
+        title: "Check connected account safety",
+        description: "Read each connected channel account's safety status, 24-hour send count, and human-approval window. An account inside its approval window must not be automated against.",
+    }),
+];

package/dist/operations/groups/usage.js

@@ -0,0 +1,13 @@
+import { op } from "../registry.js";
+export const usageOperations = [
+    op({
+        id: "usage.spend",
+        title: "Read this period's spend",
+        description: "Read model spend for the period, rolled up by agent and by day, against the plan's cap.",
+    }),
+    op({
+        id: "usage.messages",
+        title: "Read this period's message count",
+        description: "Read the message pool: used, allowed, and remaining for the period. Check this before starting work that drafts in bulk.",
+    }),
+];

package/dist/operations/groups/voice.js

@@ -0,0 +1,14 @@
+import { op } from "../registry.js";
+export const voiceOperations = [
+    op({
+        id: "voice.profile",
+        title: "Read the coach's voice fingerprint",
+        description: "Read a non-verbatim voice-fingerprint summary: version, example count, and last refresh. No corpus text.",
+    }),
+    op({
+        id: "voice.corpus",
+        title: "Read the coach's voice corpus",
+        description: "List the coach's voice corpus: the writing every draft is matched against. Entry id, source, channel, and age always come back; the writing itself is blanked for a redacted-tier key.",
+        redactedFields: ["entries[].content"],
+    }),
+];

package/dist/operations/groups/webhooks.js

@@ -0,0 +1,76 @@
+import { op } from "../registry.js";
+export const webhooksOperations = [
+    op({
+        id: "webhooks.subscriptions.list",
+        title: "List webhook subscriptions",
+        description: "List outbound webhook subscriptions.",
+    }),
+    op({
+        id: "webhooks.subscriptions.create",
+        title: "Create a webhook subscription",
+        // Naturally idempotent: an active subscription with the same target URL
+        // is updated in place (target URLs are unique per Zap/scenario webhook),
+        // so this route requires no Idempotency-Key (see the matching comment on
+        // its policy entry in apps/api/src/lib/public-route-policy.ts).
+        description: "Create an outbound webhook subscription.",
+    }),
+    op({
+        id: "webhooks.subscriptions.update",
+        title: "Update a webhook subscription",
+        description: "Update an outbound webhook subscription.",
+    }),
+    op({
+        id: "webhooks.subscriptions.delete",
+        title: "Delete a webhook subscription",
+        // Deleting by id is naturally idempotent (the route matches its policy
+        // entry, which carries no requireIdempotency), so no Idempotency-Key is
+        // sent and it stays out of the confirm-gated tier that re-triggers live
+        // downstream automation; re-running the delete is a safe no-op.
+        description: "Delete an outbound webhook subscription. Terminal, idempotent soft delete: delivery history stays queryable and the subscription can never be resurrected.",
+    }),
+    op({
+        id: "webhooks.testDelivery",
+        title: "Send a test webhook",
+        description: "Queue a canonical test webhook event.",
+    }),
+    op({
+        id: "webhooks.deliveries.list",
+        title: "List webhook deliveries",
+        description: "List webhook deliveries.",
+    }),
+    op({
+        id: "webhooks.signatureGuide",
+        title: "Read the webhook signature guide",
+        description: "Describe Luca webhook HMAC verification.",
+    }),
+    op({
+        id: "webhooks.deliveries.replay",
+        title: "Replay a webhook delivery",
+        confirmRequired: true,
+        description: "Replay one webhook delivery without changing the event id. Re-triggers the subscriber's downstream automation.",
+    }),
+    op({
+        id: "webhooks.events.list",
+        title: "List webhook events",
+        description: "List canonical webhook events of one type, newest first, in the delivered payload fields. Falls back to a documented sample payload when the workspace has none yet.",
+        // Not framed untrusted: every event's delivered payload is structured ids,
+        // enums, and counts (e.g. `message.received` is
+        // `{ leadId, conversationId, channel, providerMessageId }`). No verbatim
+        // lead text, draft body, or PII. The one content-shaped field in the whole
+        // catalog is a fictional `text` in the "no events yet" sample fallback,
+        // which the live pipeline never emits. Contrast `campaigns.commentEvents.list`,
+        // which reads real verbatim commenter text and stays untrusted.
+    }),
+    op({
+        id: "webhooks.events.replay",
+        title: "Replay a webhook event",
+        confirmRequired: true,
+        description: "Replay one canonical webhook event. Re-triggers subscribers' downstream automations.",
+    }),
+    op({
+        id: "webhooks.events.bulkReplay",
+        title: "Replay a batch of webhook events",
+        confirmRequired: true,
+        description: "Bulk replay webhook events by type and time range. Re-triggers downstream automations at scale.",
+    }),
+];

package/dist/operations/manifest.js

@@ -0,0 +1,40 @@
+// Views derived from the operation table. Nothing here holds state of its own;
+// each function reads `LUCA_OPERATIONS` and reshapes it for one caller: the
+// `luca://operations` resource, the docs generator, or the registry check.
+import { operationAnnotations } from "../annotations.js";
+import { LUCA_OPERATIONS } from "./catalog.js";
+import { LUCA_OPERATION_GROUPS } from "./registry.js";
+export function operationManifest() {
+    return LUCA_OPERATIONS.map((operation) => ({
+        id: operation.id,
+        group: operation.group,
+        toolName: operation.toolName,
+        method: operation.method,
+        path: operation.path,
+        scopes: operation.scopes,
+        idempotencyRequired: operation.idempotencyRequired,
+        confirmRequired: operation.confirmRequired,
+        paginates: operation.pageShape !== undefined,
+        untrustedContent: operation.untrustedContent,
+        requiredScope: operation.requiredScope,
+        annotations: operationAnnotations(operation),
+        description: operation.description,
+    }));
+}
+export function operationGroups() {
+    return Object.entries(LUCA_OPERATION_GROUPS).map(([id, metadata]) => {
+        const operations = LUCA_OPERATIONS.filter((operation) => operation.group === id);
+        return {
+            // SAFETY: Object.entries widens the key to `string`; the cast recovers
+            // what TypeScript already knows about LUCA_OPERATION_GROUPS's own keys.
+            id: id,
+            title: metadata.title,
+            description: metadata.description,
+            toolCount: operations.length,
+            scopes: [
+                ...new Set(operations.flatMap((operation) => operation.scopes)),
+            ].sort(),
+            tools: operations.map((operation) => operation.toolName),
+        };
+    });
+}