@setluca/mcp 0.2.0 → 0.3.0

package/dist/tool.js

@@ -1,13 +1,24 @@
-import { Duration, Effect, Layer } from "effect";
-import * as z from "zod/v4";
-import { mutatesExisting, toolAnnotations } from "./annotations.js";
-import { formatError, LucaToolInputError } from "./errors.js";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { operationAnnotationSource, toolAnnotations } from "./annotations.js";
+import { formatError, LucaConfirmationRequired, LucaToolInputError, } from "./errors.js";
+import { confirmInput } from "./fields.js";
 import { LucaApi } from "./http.js";
+import { authChallengeMeta } from "./oauth-challenge.js";
 import { logAgentSurfaceEvent } from "./observability.js";
+import { openApiToolOutputFields } from "./openapi-schema.js";
+import { needsConfirmation, operationById, } from "./operations.js";
 import { optionalField } from "./optional-field.js";
 import { paginatedProgram } from "./pagination.js";
 import { provenanceFields, UNTRUSTED_CONTENT_NOTE } from "./provenance.js";
-import { JsonObjectSchema, toJsonText, } from "./serialization.js";
+import { oauthScopeForOperation, oauthScopeForTool, } from "./scopes.js";
+import { JsonObject, toJsonText } from "./serialization.js";
+import { toolInputSchema, toolSchema } from "./standard-schema.js";
+import { taskRequest } from "./task-tools/runtime.js";
 import { buildCache } from "./tool-cache.js";
 /**
  * Each derivation below is cached on the identity of the catalog entry it comes
@@ -17,75 +28,99 @@ import { buildCache } from "./tool-cache.js";
  */
 const operationTools = buildCache();
 const taskTools = buildCache();
-const objectSchemas = buildCache();
-/** A tool's fields as one Zod object, built once per fields object. */
-function objectSchema(fields) {
-    return objectSchemas.get(fields, () => z.object(fields));
+const inputSchemas = buildCache();
+const outputSchemas = buildCache();
+/**
+ * A tool's fields as one Standard Schema object, built once per fields object.
+ * Building one renders its JSON Schema, which is the expensive part. Inputs and
+ * outputs are cached apart because only an input refuses undeclared keys.
+ */
+function inputObjectSchema(fields) {
+    return inputSchemas.get(fields, () => toolInputSchema(fields));
+}
+function outputObjectSchema(fields) {
+    return outputSchemas.get(fields, () => toolSchema(fields));
 }
 export function fromOperation(operation) {
     return operationTools.get(operation, () => buildFromOperation(operation));
 }
 function buildFromOperation(operation) {
     return {
+        ...operationAnnotationSource(operation),
         name: operation.toolName,
-        title: operation.title,
         description: operationDescription(operation),
         inputSchema: operation.inputSchema,
         outputSchema: operation.outputSchema,
-        readOnly: operation.method === "GET",
-        mutatesExisting: mutatesExisting(operation.method),
-        confirmRequired: operation.confirmRequired,
-        idempotencyRequired: operation.idempotencyRequired,
         untrustedContent: operation.untrustedContent,
+        oauthScope: oauthScopeForOperation(operation),
         run: (input) => operationProgram(operation, input),
     };
 }
+export function fromTaskTool(tool) {
+    return taskTools.get(tool, () => buildFromTaskTool(tool));
+}
+function confirmFor(tool, composed) {
+    if (composed.some((operation) => operation.confirm === "always")) {
+        return "always";
+    }
+    const conditional = composed.some((operation) => operation.confirm !== undefined);
+    return conditional ? (tool.confirm ?? "always") : tool.confirm;
+}
 /**
- * `operationById` arrives as a parameter rather than an import: the lookup map
- * is built beside the server, and importing it here would close a cycle
- * between this module and the one that registers with it.
+ * Every safety flag on a task tool comes from the operations it composes, so a
+ * tool cannot claim to be safer than the routes it calls.
  */
-export function fromTaskTool(tool, operationById) {
-    return taskTools.get(tool, () => buildFromTaskTool(tool, operationById));
-}
-function buildFromTaskTool(tool, operationById) {
+function buildFromTaskTool(tool) {
+    const composed = tool.composes.map(operationById);
+    const untrustedContent = tool.untrustedContent === true ||
+        composed.some((operation) => operation.untrustedContent);
+    // One approval covers the whole call. A composed write gated for every call
+    // gates the task tool every time. A composed write gated only for some inputs
+    // cannot be evaluated here, because the tool's own input is not the input
+    // that write receives. The tool then has to name its own narrower gate, and
+    // without one it is gated every time.
+    const confirm = confirmFor(tool, composed);
     return {
         name: tool.name,
         title: tool.title,
         description: tool.description,
-        inputSchema: tool.inputSchema,
-        outputSchema: undefined,
-        readOnly: tool.readOnly,
-        // No task tool maps onto a single mutating route. A destructive one is
-        // destructive because it reaches a real lead, which `confirmRequired`
-        // already states.
-        mutatesExisting: false,
-        confirmRequired: tool.confirmRequired === true,
-        // A task tool sends several requests, so no single key describes the call.
-        // Each constituent write carries its own, minted by the HTTP client.
-        idempotencyRequired: false,
-        untrustedContent: tool.untrustedContent,
-        run: (input) => Effect.gen(function* () {
-            const api = yield* LucaApi;
-            return yield* tool.run(api, operationById, input);
-        }),
+        inputSchema: confirm === undefined
+            ? tool.inputSchema
+            : { ...tool.inputSchema, ...confirmInput },
+        outputSchema: {
+            ...openApiToolOutputFields({ body: null, untrustedContent }),
+            result: tool.outputSchema,
+        },
+        readOnly: composed.every((operation) => operation.method === "GET"),
+        // A task tool overwrites or removes existing state when any write it
+        // composes does.
+        mutatesExisting: composed.some((operation) => operation.mutatesExisting),
+        ...optionalField("confirm", confirm),
+        untrustedContent,
+        // A task tool reaches as far as the furthest operation it composes.
+        openWorld: composed.some((operation) => operation.openWorld),
+        oauthScope: oauthScopeForTool(composed),
+        run: (input) => tool.run((id, parts) => Effect.flatMap(LucaApi, (api) => api.request(taskRequest(operationById(id), input, parts))), input),
     };
 }
-/**
- * `toolset` arrives as a parameter rather than a field on the tool: the same
- * `LucaOperation` serves both surfaces, so a tool has no business claiming to
- * know which one registered it.
- */
-export function registerTool(server, tool, lucaLayer, toolset) {
+export function registerTool(server, tool, lucaLayer, surface) {
     server.registerTool(tool.name, {
         title: tool.title,
         description: tool.description,
-        inputSchema: objectSchema(tool.inputSchema),
-        ...optionalField("outputSchema", tool.outputSchema === undefined
-            ? undefined
-            : objectSchema(tool.outputSchema)),
+        inputSchema: inputObjectSchema(tool.inputSchema),
+        outputSchema: outputObjectSchema(tool.outputSchema),
         annotations: toolAnnotations(tool),
-    }, (input) => Effect.runPromise(toolResult(tool, lucaLayer, toolset, input)));
+        // ChatGPT reads this to know a tool needs a linked account, and which
+        // scope to ask for when it does.
+        _meta: {
+            securitySchemes: [{ type: "oauth2", scopes: [tool.oauthScope] }],
+        },
+    }, 
+    // The client's cancellation interrupts the program, which aborts the
+    // request it has in flight.
+    (input, ctx) => Effect.runPromise(toolResult(tool, lucaLayer, surface, input), {
+        signal: ctx.mcpReq.signal,
+    }));
 }
 /**
  * The call's arguments as a JSON object, failing into the error channel rather
@@ -93,59 +128,76 @@ export function registerTool(server, tool, lucaLayer, toolset) {
  * the handler runs, so a real client never lands here; the point is that no
  * code ahead of `runPromise` can throw where the error channel cannot see it.
  */
+const decodeToolInput = Schema.decodeUnknownEffect(JsonObject);
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- the SDK hands over the arguments its own schema decoded, typed loosely; this is where they become a JSON object.
 function parseToolInput(input) {
-    return Effect.try({
-        try: () => JsonObjectSchema.parse(input),
-        catch: () => new LucaToolInputError({
-            message: "Tool arguments must be a JSON object",
-        }),
-    });
-}
-function ended(outcome, result) {
-    return { outcome, result };
+    return decodeToolInput(input).pipe(Effect.mapError(() => new LucaToolInputError({
+        message: "Tool arguments must be a JSON object",
+    })));
 }
 /**
- * A tool call's result, confirmation gate included. Every way the call can end —
- * unreadable arguments, a rejected confirmation, a failed request, a thrown
- * defect while the request was being built — leaves as a tool result, so
- * nothing reaches the transport as an unhandled rejection.
- *
- * The log line sits after the defect handler, so a call produces exactly one
- * line whichever way it ended.
+ * 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, and every way logs exactly one line.
  */
-function toolResult(tool, lucaLayer, toolset, input) {
-    return parseToolInput(input).pipe(Effect.flatMap((parsed) => gatedResult(tool, lucaLayer, parsed)), Effect.catchAll((error) => Effect.succeed(ended("error", asErrorResult(error)))), Effect.catchAllDefect((defect) => Effect.succeed(ended("defect", asErrorResult(defect instanceof Error ? defect : new Error(String(defect)))))), Effect.timed, Effect.tap(([elapsed, ended_]) => Effect.sync(() => {
-        // The defect's own message never lands here: it can carry arbitrary
-        // thrown text derived from the call's input. The client still sees it
-        // in the tool result.
-        logAgentSurfaceEvent("mcp.tool.called", {
-            toolName: tool.name,
-            toolset,
-            outcome: ended_.outcome,
-            durationMs: Math.round(Duration.toMillis(elapsed)),
-        });
-    })), Effect.map(([, ended_]) => ended_.result));
-}
-/** One tool call past the confirmation gate, or the gate's own refusal. */
-function gatedResult(tool, lucaLayer, input) {
-    if (tool.confirmRequired && input.confirm !== true) {
-        return Effect.succeed(ended("error", confirmationError(tool.name)));
-    }
-    return runTool(tool, lucaLayer, input);
+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.
+    logAgentSurfaceEvent("mcp.tool.called", {
+        toolName: tool.name,
+        toolset: surface.toolset,
+        outcome,
+        durationMs: elapsed === undefined
+            ? undefined
+            : Math.round(Duration.toMillis(elapsed)),
+    });
+    return parseToolInput(input).pipe(Effect.flatMap((parsed) => needsConfirmation(tool.confirm, parsed) && parsed.confirm !== true
+        ? Effect.fail(new LucaConfirmationRequired({ toolName: tool.name }))
+        : tool.run(parsed)), Effect.provide(lucaLayer), Effect.exit, Effect.timed, Effect.map(([elapsed, exit]) => {
+        const [outcome, result] = settle(tool, surface, exit);
+        logCall(outcome, elapsed);
+        return result;
+    }), 
+    // A cancellation from the client stops the program before the exit above
+    // is read, so it is logged on the way out instead.
+    Effect.onInterrupt(() => Effect.sync(() => logCall("interrupted"))));
 }
-/** One confirmed tool call, run to a success or an error tool result. */
-function runTool(tool, lucaLayer, input) {
-    return tool.run(input).pipe(Effect.provide(lucaLayer), Effect.match({
-        onFailure: (error) => ended("error", asErrorResult(error)),
-        onSuccess: (result) => ended("success", asSuccessResult(tool, result)),
-    }));
+/** A finished call as the outcome it logs and the result the client gets. */
+function settle(tool, surface, exit) {
+    if (Exit.isSuccess(exit)) {
+        return ["success", asSuccessResult(tool, exit.value)];
+    }
+    const { cause } = exit;
+    const error = Cause.findErrorOption(cause);
+    if (Option.isSome(error)) {
+        const failure = error.value;
+        if (failure instanceof LucaConfirmationRequired) {
+            logAgentSurfaceEvent("mcp.write_gate.rejected", { toolName: tool.name });
+            return ["error", confirmationError(tool.name)];
+        }
+        return [
+            "error",
+            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))),
+    ];
 }
 /** The Effect program that runs an operation, auto-paginating list tools. */
 export function operationProgram(operation, toolInput) {
     const baseRequest = operation.buildRequest(toolInput);
-    const { pageShape } = operation;
-    if (pageShape) {
-        return paginatedProgram(operation, pageShape, baseRequest, toolInput.maxPages);
+    const { pageContract } = operation;
+    if (pageContract) {
+        return paginatedProgram(operation, pageContract, baseRequest, toolInput.maxPages);
     }
     // An operation with no page shape has no pagination to follow, so it is one
     // request, sent as-is.
@@ -156,8 +208,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`.
@@ -179,7 +231,7 @@ function asSuccessResult(tool, result) {
         },
     };
 }
-function asErrorResult(error) {
+function asErrorResult(error, meta) {
     return {
         isError: true,
         content: [
@@ -188,6 +240,7 @@ function asErrorResult(error) {
                 text: formatError(error),
             },
         ],
+        ...optionalField("_meta", meta),
     };
 }
 function operationDescription(operation) {
@@ -196,25 +249,27 @@ function operationDescription(operation) {
         "",
         `Luca operation: ${operation.method} ${operation.path}`,
         `Required scopes: ${operation.scopes.join(", ")}`,
-        `Required capability: ${operation.requiredScope.capability}; data sensitivity: ${operation.requiredScope.dataSensitivity}`,
+        `Required OAuth scope: ${oauthScopeForOperation(operation)}; data sensitivity: ${operation.requiredScope.dataSensitivity}`,
         operation.idempotencyRequired
             ? "Requires Idempotency-Key. Provide idempotencyKey for safe retries, or the server will generate one."
             : "Does not require idempotency.",
     ];
-    if (operation.confirmRequired) {
-        lines.push("Destructive: has a real-world side effect. You must pass confirm: true; the call is rejected without it.");
+    if (operation.confirm !== undefined) {
+        const when = operation.confirm === "always"
+            ? ""
+            : ` when ${operation.confirm.description}`;
+        lines.push(`Destructive${when}: has a real-world side effect. You must pass confirm: true; the call is rejected without it.`);
     }
     lines.push("Use workspaceId or workspaceSlug to override the default workspace configured by environment.");
     return lines.join("\n");
 }
 function confirmationError(toolName) {
-    logAgentSurfaceEvent("mcp.write_gate.rejected", { toolName });
     return {
         isError: true,
         content: [
             {
                 type: "text",
-                text: `${toolName}: This tool requires confirm: true because it has a real-world side effect (sends messages to leads or re-triggers downstream automations). Re-call the tool with confirm: true to proceed.`,
+                text: `${toolName}: This tool requires confirm: true because it has a real-world side effect. Re-call the tool with confirm: true to proceed.`,
             },
         ],
         structuredContent: {

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.2.0";
+export const LUCA_MCP_VERSION = "0.3.0";
 /** 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,22 +1,26 @@
 {
   "name": "@setluca/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
-  "description": "Model Context Protocol server for the Luca public API.",
+  "description": "Let your AI assistant help with Luca conversations, leads, replies, campaigns, and bookings.",
   "keywords": [
     "ai",
-    "crm",
     "luca",
     "mcp",
     "model-context-protocol"
   ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/setluca/luca-mcp.git"
+  },
   "bin": {
     "luca-mcp": "dist/index.js"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "exports": {
@@ -34,45 +38,63 @@
     "test": "TZ=UTC vitest run --exclude test/stdio-smoke.test.ts",
     "test:mutation": "TZ=UTC stryker run",
     "test:stdio": "vitest run test/stdio-smoke.test.ts",
+    "lint": "oxlint . --deny-warnings",
+    "lint:anti-slop": "oxlint . --deny-warnings",
+    "format": "oxfmt --write . --disable-nested-config",
+    "format:check": "oxfmt --check . --disable-nested-config",
+    "knip": "knip",
+    "fallow:dead-code": "fallow dead-code --fail-on-issues",
+    "fallow:dupes": "fallow dupes --fail-on-issues --summary",
+    "fallow:security": "fallow security --fail-on-issues --summary",
+    "fallow:health:gate": "fallow health --min-score 85 --summary",
+    "quality": "bun run format:check && bun run lint && bun run knip && bun run fallow:dead-code && bun run fallow:dupes && bun run fallow:security && bun run fallow:health:gate",
     "dev:remote": "wrangler dev",
     "deploy": "wrangler deploy --env production",
+    "deploy:dry-run": "wrangler deploy --env production --dry-run",
     "test:integration": "vitest run test/integration",
     "coverage": "bun run test -- --coverage",
     "typecheck": "tsc --noEmit",
-    "verify": "bun run docs:check && bun run catalog:check && bun run openapi:inputs:check && bun run openapi:outputs:check && bun run openapi:check && bun run registry:check && bun run redaction:check && bun run typecheck && bun run test && bun run build && bun run test:stdio",
+    "verify": "bun run quality && bun run docs:check && bun run catalog:check && bun run openapi:inputs:check && bun run openapi:outputs:check && bun run openapi:check && bun run registry:check && bun run typecheck && bun run coverage && bun run build && bun run test:stdio && bun run contracts:deployed:check",
     "openapi:generate": "bun run catalog:generate && bun scripts/generate-openapi-inputs.ts --write && bun scripts/generate-openapi-outputs.ts --write",
+    "contracts:sync": "bun scripts/contract-sync.ts",
+    "contracts:deployed:check": "bun scripts/check-deployed-luca-contracts.ts",
     "catalog:generate": "bun scripts/generate-route-catalog.ts --write",
     "catalog:check": "bun scripts/generate-route-catalog.ts --check",
     "openapi:inputs:check": "bun scripts/generate-openapi-inputs.ts --check",
     "openapi:outputs:check": "bun scripts/generate-openapi-outputs.ts --check",
     "openapi:check": "bun scripts/check-openapi.ts",
     "registry:check": "bun scripts/check-registry.ts",
-    "redaction:check": "bun scripts/check-redaction.ts",
     "docs:generate": "bun scripts/generate-docs.ts --write",
     "docs:check": "bun scripts/generate-docs.ts --check",
-    "run-all": "bun run openapi:generate && bun run docs:generate && bun run typecheck && bun run test",
     "clean": "rm -rf .turbo dist coverage node_modules"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "effect": "^3.22.1",
-    "zod": "^4.4.3"
+    "effect": "4.0.0"
   },
   "devDependencies": {
-    "@luca/config": "workspace:*",
-    "@luca/test-utils": "workspace:*",
+    "@effect/platform-bun": "4.0.0",
+    "@effect/vitest": "4.0.0",
     "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/inspector": "^2.2.0",
-    "@types/node": "^26.2.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "oxfmt": "^0.63.0",
+    "@modelcontextprotocol/inspector": "^2.5.0",
+    "@mpsuesser/oxlint-plugin-effect": "0.6.0",
+    "@oxlint/plugins": "1.82.0",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
+    "@types/node": "^26.5.0",
+    "@vitest/coverage-v8": "^5.0.0",
+    "fallow": "3.23.0",
+    "knip": "6.34.0",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10",
-    "wrangler": "^4.123.0"
+    "ultracite": "7.11.0",
+    "vitest": "^5.0.0",
+    "wrangler": "4.113.0"
   },
   "engines": {
     "node": ">=20"
   },
-  "//publish": "Publish name is @setluca/mcp (the @setluca npm org). To publish: set NPM_TOKEN (scoped to @setluca), tag mcp-v*. See docs/release.md.",
+  "//publish": "Publish name is @setluca/mcp (the @setluca npm org). To publish: tag mcp-v*. The workflow authenticates to npm with OIDC Trusted Publishing, so there is no NPM_TOKEN. See docs/release.md.",
   "mcpName": "io.github.setluca/luca-mcp"
 }