@setluca/mcp 0.1.1 → 0.2.0

package/dist/http.js

@@ -1,103 +1,100 @@
-import { Context, Effect, Layer } from "effect";
-import { LucaConfig } from "./config.js";
+import { Context, Effect, Layer, Match, Option } from "effect";
+import * as z from "zod/v4";
+import { DEFAULT_REQUEST_TIMEOUT_MS, LucaConfig } from "./config.js";
 import { LucaDecodeError, LucaHttpError, LucaNetworkError, } from "./errors.js";
+import { optionalField } from "./optional-field.js";
+import { resilient } from "./resilience.js";
+import { fromJson, toJsonPayload } from "./serialization.js";
+import { LUCA_MCP_USER_AGENT } from "./version.js";
 export const LucaApi = Context.GenericTag("@luca/mcp/LucaApi");
 function isPresent(value) {
     return value !== undefined && value !== null && value !== "";
 }
 function encodePath(path, params) {
-    return path.replace(/\{([^}]+)\}/g, (_, key) => {
-        const value = params?.[key];
-        if (!value) {
-            throw new Error(`Missing path parameter: ${key}`);
-        }
-        return encodeURIComponent(value);
-    });
+    return path.replaceAll(/\{([^}]+)\}/g, (_, key) => Option.fromNullable(params?.[key]).pipe(Option.filter((value) => value.length > 0), Option.map(encodeURIComponent), Option.getOrThrowWith(() => new Error(`Missing path parameter: ${key}`))));
 }
 function appendQuery(url, query) {
-    if (!query) {
-        return;
-    }
-    for (const [key, value] of Object.entries(query)) {
-        if (Array.isArray(value)) {
-            for (const item of value) {
-                if (isPresent(item)) {
-                    url.searchParams.append(key, String(item));
-                }
-            }
-        }
-        else if (isPresent(value)) {
-            url.searchParams.set(key, String(value));
+    for (const [key, value] of Object.entries(query ?? {})) {
+        // A scalar is a one-element list here, so array and single-value params take
+        // the same path: append every value the caller actually set.
+        const values = Array.isArray(value) ? value : [value];
+        for (const item of values.filter(isPresent)) {
+            url.searchParams.append(key, String(item));
         }
     }
 }
-function parseJson(text) {
-    if (!text) {
-        return null;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        throw new LucaDecodeError({
-            message: "Luca API returned non-JSON content",
-            body: text,
-        });
-    }
-}
 function buildUrl(config, input) {
     const path = encodePath(input.operation.path, input.pathParams);
     const url = new URL(path, `${config.apiBaseUrl}/`);
     appendQuery(url, input.query);
     return url;
 }
-function buildHeaders(config, input) {
-    const headers = new Headers({
-        accept: "application/json",
-        "user-agent": "luca-mcp/0.1.0",
-    });
-    setAuthHeaders(headers, config);
-    setWorkspaceHeaders(headers, config, input);
-    setPayloadHeaders(headers, input);
-    return headers;
+/** The API key, under whichever header this config authenticates with. */
+function authFields(config) {
+    return Match.value(config.authHeader).pipe(Match.when("authorization", () => ({
+        authorization: `Bearer ${config.apiKey}`,
+    })), Match.orElse(() => ({ "x-api-key": config.apiKey })));
 }
-function setAuthHeaders(headers, config) {
-    if (config.authHeader === "authorization") {
-        headers.set("authorization", `Bearer ${config.apiKey}`);
+const RETRY_AFTER_MS_PER_SECOND = 1000;
+/**
+ * The wait a `Retry-After` header asks for, in milliseconds. The header comes
+ * in two forms — delta-seconds and an HTTP date — and both are read here so the
+ * retry rules never have to look at a header again. An unreadable value is the
+ * same as no header: the client falls back to its own backoff.
+ */
+function retryAfterMs(response, now) {
+    const header = response.headers.get("retry-after")?.trim();
+    if (!header) {
+        return;
     }
-    else {
-        headers.set("x-api-key", config.apiKey);
+    const seconds = z.coerce.number().int().min(0).safeParse(header);
+    if (seconds.success) {
+        return seconds.data * RETRY_AFTER_MS_PER_SECOND;
     }
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - now);
 }
-function setWorkspaceHeaders(headers, config, input) {
-    const workspaceId = input.workspace?.workspaceId ?? config.workspaceId;
-    const workspaceSlug = input.workspace?.workspaceSlug ?? config.workspaceSlug;
-    if (workspaceId) {
-        headers.set("x-luca-workspace-id", workspaceId);
-    }
-    if (workspaceSlug) {
-        headers.set("x-luca-workspace-slug", workspaceSlug);
-    }
+/** The JSON payload of a request; absent for a GET or a bodiless call. */
+function requestBody(input) {
+    return Option.liftPredicate(input, (candidate) => candidate.operation.method !== "GET" && candidate.body !== undefined).pipe(Option.map((candidate) => toJsonPayload(candidate.body)));
 }
-function setPayloadHeaders(headers, input) {
-    const hasBody = input.operation.method !== "GET" && input.body !== undefined;
-    if (hasBody) {
-        headers.set("content-type", "application/json");
-    }
-    if (input.operation.idempotencyRequired) {
-        headers.set("idempotency-key", input.idempotencyKey ?? crypto.randomUUID());
-    }
-}
-function buildRequestInit(input, headers) {
-    const hasBody = input.operation.method !== "GET" && input.body !== undefined;
+function buildRequestInit(config, input, requestIdempotencyKey) {
+    // The body decides its own content-type header, so both are read from the one
+    // value rather than from two independent recomputations of "does this have a
+    // body" that could drift apart.
+    const body = requestBody(input);
+    const headers = new Headers({
+        accept: "application/json",
+        "user-agent": LUCA_MCP_USER_AGENT,
+        ...authFields(config),
+        ...optionalField("x-luca-workspace-id", input.workspace?.workspaceId ?? config.workspaceId),
+        ...optionalField("x-luca-workspace-slug", input.workspace?.workspaceSlug ?? config.workspaceSlug),
+        ...optionalField("content-type", Option.getOrUndefined(Option.map(body, () => "application/json"))),
+        ...optionalField("idempotency-key", requestIdempotencyKey),
+    });
     return {
         method: input.operation.method,
         headers,
-        ...(hasBody ? { body: JSON.stringify(input.body) } : {}),
+        ...optionalField("body", Option.getOrUndefined(body)),
     };
 }
-function readResponseBody(response) {
+/** One trip to the API, with no retry and no timeout of its own. */
+function sendOnce(config, input, requestIdempotencyKey) {
     return Effect.gen(function* () {
+        const url = buildUrl(config, input);
+        const init = buildRequestInit(config, input, requestIdempotencyKey);
+        const response = yield* Effect.tryPromise({
+            try: (signal) => 
+            // fallow-ignore-next-line security-sink -- the origin is the configured Luca api base url and the path comes from the generated operation manifest with its params encoded, so a tool argument can never move the destination host
+            fetch(url, {
+                ...init,
+                signal,
+            }),
+            catch: (cause) => new LucaNetworkError({
+                message: `Could not reach Luca API at ${url.toString()}`,
+                cause,
+            }),
+        });
         const text = yield* Effect.tryPromise({
             try: () => response.text(),
             catch: (cause) => new LucaNetworkError({
@@ -105,41 +102,36 @@ function readResponseBody(response) {
                 cause,
             }),
         });
-        return yield* Effect.try({
-            try: () => parseJson(text),
-            catch: (cause) => cause instanceof LucaDecodeError
-                ? cause
-                : new LucaDecodeError({ message: String(cause), body: text }),
-        });
+        // An empty body is not a decode failure — several endpoints answer with
+        // no content at all, and null is the JSON value that stands for it.
+        const json = yield* Option.liftPredicate(text, (raw) => raw.length > 0).pipe(Option.match({
+            onNone: () => Effect.succeed(null),
+            onSome: (raw) => Effect.try({
+                try: () => fromJson(raw),
+                catch: () => new LucaDecodeError({
+                    message: "Luca API returned non-JSON content",
+                    body: raw,
+                }),
+            }),
+        }));
+        if (response.ok) {
+            return json;
+        }
+        return yield* Effect.fail(new LucaHttpError({
+            status: response.status,
+            statusText: response.statusText,
+            body: json,
+            ...optionalField("requestId", response.headers.get("x-request-id")),
+            ...optionalField("retryAfterMs", retryAfterMs(response, Date.now())),
+        }));
     });
 }
 export function makeLucaApi(config) {
+    const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     return {
-        request: (input) => Effect.gen(function* () {
-            const url = buildUrl(config, input);
-            const init = buildRequestInit(input, buildHeaders(config, input));
-            const response = yield* Effect.tryPromise({
-                try: (signal) => fetch(url, {
-                    ...init,
-                    signal,
-                }),
-                catch: (cause) => new LucaNetworkError({
-                    message: `Could not reach Luca API at ${url.toString()}`,
-                    cause,
-                }),
-            });
-            const json = yield* readResponseBody(response);
-            if (!response.ok) {
-                const requestId = response.headers.get("x-request-id") ?? undefined;
-                return yield* Effect.fail(new LucaHttpError({
-                    status: response.status,
-                    statusText: response.statusText,
-                    body: json,
-                    ...(requestId ? { requestId } : {}),
-                }));
-            }
-            return json;
-        }),
+        // The key each attempt carries is minted by `resilient`, which also decides
+        // whether a failure may be replayed under it.
+        request: (input) => resilient(input, timeoutMs, (key) => sendOnce(config, input, key)),
     };
 }
 export const LucaApiLive = Layer.effect(LucaApi, Effect.gen(function* () {

package/dist/index.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createLucaServer } from "./server.js";
-async function main() {
-    const server = createLucaServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-main().catch((error) => {
-    console.error("Fatal error in Luca MCP server:", error);
-    process.exit(1);
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createLucaServer, parseToolset } from "./server.js";
+/**
+ * `serveStdio` owns the era decision for the connection: the opening exchange
+ * picks either the 2026-07-28 protocol or the 2025 `initialize` handshake, and
+ * one instance from this factory is pinned for the connection's lifetime. The
+ * factory registers the same surface either way, so a client on either
+ * revision sees an identical toolset.
+ */
+serveStdio(() => createLucaServer({ toolset: parseToolset(process.env.LUCA_TOOLSET) }), {
+    // stdout carries the protocol, so every diagnostic goes to stderr. These
+    // are out-of-band errors: reporting them never changes what the client
+    // receives, and the connection stays up.
+    onerror: (error) => {
+        console.error("Luca MCP server error:", error);
+    },
 });

package/dist/oauth-resolver.js

@@ -1,3 +1,6 @@
+import { Duration, Effect, Option } from "effect";
+import * as z from "zod/v4";
+import { DEFAULT_REQUEST_TIMEOUT_MS, parseTimeoutMs, } from "./config.js";
 const TRAILING_SLASHES = /\/+$/;
 /**
  * Developer API keys are handled by apiKeyResolver and never leave this
@@ -5,9 +8,47 @@ const TRAILING_SLASHES = /\/+$/;
  * developer keys — they fall through to the resolver, which rejects them
  * server-side (fail closed, no client-side oracle).
  */
-const API_KEY_SHAPE = /^luca_(?!ort_)[a-f0-9]/i;
+const API_KEY_FIELDS = /^luca_(?!ort_)[a-f0-9]/i;
+const ResolvePayloadSchema = z.object({
+    apiKey: z.string().optional(),
+    scopes: z.array(z.string()).optional(),
+});
 /**
- * Resolver for OAuth access tokens (docs/specs/mcp-oauth-authorization-server.md
+ * The body of a resolve response, absent when the API refused the token. A
+ * refusal is not read at all: its body carries nothing this resolver acts on.
+ */
+function resolvePayload(response) {
+    return Option.match(Option.liftPredicate(response, (res) => res.ok), {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: (res) => Effect.tryPromise(() => res.json()).pipe(Effect.map((payload) => ResolvePayloadSchema.parse(payload)), Effect.map(Option.some)),
+    });
+}
+/** The identity a payload names, absent when it names no vended key. */
+function identityFromPayload(apiBaseUrl, authHeader, payload) {
+    return Option.map(Option.fromNullable(payload.apiKey), (apiKey) => ({
+        config: { apiBaseUrl, apiKey, authHeader },
+        scopes: payload.scopes ?? [],
+    }));
+}
+/**
+ * One authenticated call to POST /oauth/resolve, answered with the identity the
+ * token maps to. A network failure, a refusal, and an unreadable body are all
+ * the same answer — no identity — because the transport replies 401 to each of
+ * them and telling them apart would hand a caller an oracle.
+ */
+function requestIdentity(apiBaseUrl, authHeader, fetchImpl, token, timeoutMs) {
+    return Effect.tryPromise(() => fetchImpl(`${apiBaseUrl}/oauth/resolve`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+    })).pipe(Effect.flatMap(resolvePayload), Effect.map((payload) => Option.flatMap(payload, (body) => identityFromPayload(apiBaseUrl, authHeader, body))), 
+    // Timeout but no retry. This call sits on the auth path of every request,
+    // has no idempotency to reason about, and already answers "no identity" for
+    // every failure — a plain `timeout` is enough because `orElseSucceed`
+    // discards the error shape anyway.
+    Effect.timeout(Duration.millis(timeoutMs)), Effect.orElseSucceed(() => Option.none()));
+}
+/**
+ * Resolver for OAuth access tokens (docs/runbooks/mcp-oauth-authorization-server.md
  * §5.2): one authenticated call to the Luca API's POST /oauth/resolve, which
  * verifies the JWT and returns the hidden vended key for the token's own
  * grant. Fail closed: any error, non-200, or malformed body → null → 401.
@@ -15,41 +56,22 @@ const API_KEY_SHAPE = /^luca_(?!ort_)[a-f0-9]/i;
 export function oauthResolver(env, fetchImpl = fetch) {
     const apiBaseUrl = (env.LUCA_API_BASE_URL ?? "https://api.setluca.com").replace(TRAILING_SLASHES, "");
     const authHeader = env.LUCA_AUTH_HEADER ?? "x-api-key";
-    return async (token) => {
-        if (API_KEY_SHAPE.test(token)) {
-            return null;
-        }
-        try {
-            const response = await fetchImpl(`${apiBaseUrl}/oauth/resolve`, {
-                method: "POST",
-                headers: { authorization: `Bearer ${token}` },
-            });
-            if (!response.ok) {
-                return null;
-            }
-            const payload = (await response.json());
-            if (!payload.apiKey) {
-                return null;
-            }
-            return {
-                config: { apiBaseUrl, apiKey: payload.apiKey, authHeader },
-                scopes: payload.scopes ?? [],
-            };
-        }
-        catch {
-            return null;
-        }
-    };
+    // Read through the same parser the API client uses, so the stdio and Worker
+    // paths cannot end up bounding their requests differently.
+    const timeoutMs = parseTimeoutMs(env.LUCA_REQUEST_TIMEOUT_MS) ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    // A developer API key is another resolver's business, so it is refused here
+    // without a network call rather than sent to an endpoint that would reject it
+    // anyway.
+    return (token) => Option.match(Option.liftPredicate(token, (candidate) => !API_KEY_FIELDS.test(candidate)), {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: (candidate) => requestIdentity(apiBaseUrl, authHeader, fetchImpl, candidate, timeoutMs),
+    }).pipe(Effect.map(Option.getOrNull), Effect.runPromise);
 }
 /** Try resolvers in order; the first non-null identity wins. */
 export function chainResolvers(...resolvers) {
-    return async (token) => {
-        for (const resolve of resolvers) {
-            const identity = await resolve(token);
-            if (identity) {
-                return identity;
-            }
-        }
-        return null;
-    };
+    return (token) => Effect.reduce(resolvers, Option.none(), (identity, resolve) => Option.match(identity, {
+        // Once one resolver has answered, the rest are never called.
+        onSome: (present) => Effect.succeed(Option.some(present)),
+        onNone: () => Effect.promise(() => resolve(token)).pipe(Effect.map(Option.fromNullable)),
+    })).pipe(Effect.map(Option.getOrNull), Effect.runPromise);
 }

package/dist/observability.js

@@ -9,11 +9,19 @@
  * contract (event names + payload shape).
  */
 export function logAgentSurfaceEvent(event, fields) {
-    const clean = { msg: "mcp.agent_surface", event };
+    const clean = new Map([
+        ["msg", "mcp.agent_surface"],
+        ["event", event],
+    ]);
     for (const [k, v] of Object.entries(fields)) {
+        // Equivalent to always assigning: `JSON.stringify` omits own properties whose
+        // value is `undefined`, so guarding here vs. assigning an undefined value to
+        // the accumulator key yields byte-identical logged output. The guard keeps
+        // the object tidy.
+        // Stryker disable next-line ConditionalExpression: JSON.stringify drops undefined-valued keys regardless
         if (v !== undefined) {
-            clean[k] = v;
+            clean.set(k, v);
         }
     }
-    console.log(JSON.stringify(clean));
+    console.log(JSON.stringify(Object.fromEntries(clean)));
 }