@setluca/mcp 0.1.1 → 0.2.1

package/dist/config.js

@@ -1,47 +1,73 @@
-import { Context, Effect, Layer } from "effect";
+import { Context, Effect, Layer, Match, Option } from "effect";
+import * as z from "zod/v4";
 import { LucaConfigError } from "./errors.js";
+import { optionalField } from "./optional-field.js";
 const TRAILING_SLASHES = /\/+$/;
+/** How long one HTTP attempt may run before it is cancelled and retried. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 export const LucaConfig = Context.GenericTag("@luca/mcp/LucaConfig");
 function nonEmpty(value) {
-    const trimmed = value?.trim();
-    return trimmed ? trimmed : undefined;
+    // An all-whitespace variable is the same as an unset one, so it collapses to
+    // undefined and lets every caller's `??` fallback take over.
+    return value?.trim() || undefined;
 }
 function normalizeBaseUrl(value) {
     const raw = nonEmpty(value) ?? "https://api.setluca.com";
     return raw.replace(TRAILING_SLASHES, "");
 }
-function parseAuthHeader(value) {
-    const normalized = nonEmpty(value)?.toLowerCase();
-    if (!normalized || normalized === "x-api-key") {
-        return "x-api-key";
-    }
-    if (normalized === "authorization" || normalized === "bearer") {
-        return "authorization";
-    }
-    throw new LucaConfigError({
-        message: "LUCA_AUTH_HEADER must be x-api-key or authorization",
-    });
+/**
+ * Every spelling of LUCA_AUTH_HEADER we accept, mapped to the header the client
+ * actually sends. "bearer" is here because it is what people write when they
+ * mean the Authorization header, and refusing it would be a papercut.
+ */
+const AUTH_HEADER_ALIASES = new Map([
+    ["x-api-key", "x-api-key"],
+    ["authorization", "authorization"],
+    ["bearer", "authorization"],
+]);
+/**
+ * The per-attempt timeout a variable asks for, absent when it is unset or is
+ * not a positive whole number of milliseconds. Absent means the caller's
+ * default applies, so a typo degrades to the default rather than to no timeout
+ * at all.
+ */
+export function parseTimeoutMs(value) {
+    const parsed = z.coerce
+        .number()
+        .int()
+        .positive()
+        .safeParse(nonEmpty(value) ?? undefined);
+    return parsed.success ? parsed.data : undefined;
 }
-export function loadConfig(env = process.env) {
-    const apiKey = nonEmpty(env.LUCA_API_KEY) ?? nonEmpty(env.LUCA_API_TOKEN);
-    if (!apiKey) {
+function parseAuthHeader(value) {
+    const alias = nonEmpty(value)?.toLowerCase() ?? "x-api-key";
+    return Match.value(AUTH_HEADER_ALIASES.get(alias)).pipe(Match.when(Match.undefined, () => {
         throw new LucaConfigError({
-            message: "Set LUCA_API_KEY to a Luca developer API key.",
+            message: "LUCA_AUTH_HEADER must be x-api-key or authorization",
         });
-    }
-    const workspaceId = nonEmpty(env.LUCA_WORKSPACE_ID);
-    const workspaceSlug = nonEmpty(env.LUCA_WORKSPACE_SLUG);
+    }), Match.orElse((header) => header));
+}
+export function loadConfig(env = process.env) {
+    const apiKey = Option.fromNullable(nonEmpty(env.LUCA_API_KEY) ?? nonEmpty(env.LUCA_API_TOKEN)).pipe(Option.getOrThrowWith(() => new LucaConfigError({
+        message: "Set LUCA_API_KEY to a Luca developer API key.",
+    })));
     return {
         apiBaseUrl: normalizeBaseUrl(env.LUCA_API_BASE_URL),
         apiKey,
         authHeader: parseAuthHeader(env.LUCA_AUTH_HEADER),
-        ...(workspaceId ? { workspaceId } : {}),
-        ...(workspaceSlug ? { workspaceSlug } : {}),
+        ...optionalField("workspaceId", nonEmpty(env.LUCA_WORKSPACE_ID)),
+        ...optionalField("workspaceSlug", nonEmpty(env.LUCA_WORKSPACE_SLUG)),
+        ...optionalField("requestTimeoutMs", parseTimeoutMs(env.LUCA_REQUEST_TIMEOUT_MS)),
     };
 }
-export const LucaConfigLive = Layer.effect(LucaConfig, Effect.try({
-    try: () => loadConfig(),
-    catch: (cause) => cause instanceof LucaConfigError
-        ? cause
-        : new LucaConfigError({ message: String(cause) }),
-}));
+/**
+ * Every way `loadConfig` can fail has to reach the caller as a `LucaConfigError`
+ * so the layer's error channel stays one type. A config error passes through
+ * untouched. Anything else is wrapped rather than escaping as an untyped
+ * defect, whether that is a getter on the environment that throws or a future
+ * caller of this helper raising something unexpected.
+ */
+export function toConfigError(cause) {
+    return Match.value(cause).pipe(Match.when(Match.instanceOf(LucaConfigError), (error) => error), Match.orElse((other) => new LucaConfigError({ message: String(other) })));
+}
+export const LucaConfigLive = Layer.effect(LucaConfig, Effect.try({ try: () => loadConfig(), catch: toConfigError }));

package/dist/errors.js

@@ -1,4 +1,6 @@
-import { Data } from "effect";
+import { Data, Match, Option } from "effect";
+import * as z from "zod/v4";
+import { toJsonPayload } from "./serialization.js";
 export class LucaConfigError extends Data.TaggedError("LucaConfigError") {
 }
 export class LucaNetworkError extends Data.TaggedError("LucaNetworkError") {
@@ -7,19 +9,58 @@ export class LucaDecodeError extends Data.TaggedError("LucaDecodeError") {
 }
 export class LucaHttpError extends Data.TaggedError("LucaHttpError") {
 }
+/**
+ * One attempt ran past the request timeout and was cancelled. It is its own
+ * error rather than a network error because a caller can retry it safely under
+ * the same rules but cannot tell from a network failure whether the request
+ * reached the API.
+ */
+export class LucaTimeoutError extends Data.TaggedError("LucaTimeoutError") {
+}
+/**
+ * A tool was called with arguments that are not a JSON object. The MCP SDK
+ * validates against the tool's own input schema before the handler runs, so a
+ * real client cannot reach this. It exists so no code ahead of `runPromise` can
+ * throw where the error channel cannot see it.
+ */
+export class LucaToolInputError extends Data.TaggedError("LucaToolInputError") {
+}
+const DECODE_BODY_EXCERPT = 500;
+function formatDecodeError(error) {
+    return `${error.message}: ${error.body.slice(0, DECODE_BODY_EXCERPT)}`;
+}
+function formatHttpError(error) {
+    const request = Option.fromNullable(error.requestId).pipe(Option.match({
+        onNone: () => "",
+        onSome: (requestId) => ` requestId=${requestId}`,
+    }));
+    return `Luca API returned ${error.status} ${error.statusText}${request}: ${toJsonPayload(error.body)}`;
+}
+/**
+ * A value that carries no message of its own, rendered for a human. A string is
+ * handed back as it was thrown, since quoting it would put the reader a step
+ * further from the value than the throw site was. Everything else comes back as
+ * JSON rather than "[object Object]". Numbers and booleans need no case of
+ * their own: JSON renders each of them exactly as `String` would.
+ */
+function formatJsonValue(error) {
+    const text = z.string().safeParse(error);
+    return text.success ? text.data : toJsonPayload(error);
+}
+/** Any failure this server can hand a client, as one line of text. */
 export function formatError(error) {
-    if (error instanceof LucaConfigError) {
-        return error.message;
-    }
-    if (error instanceof LucaNetworkError) {
-        return error.message;
-    }
-    if (error instanceof LucaDecodeError) {
-        return `${error.message}: ${error.body.slice(0, 500)}`;
-    }
-    if (error instanceof LucaHttpError) {
-        const request = error.requestId ? ` requestId=${error.requestId}` : "";
-        return `Luca API returned ${error.status} ${error.statusText}${request}: ${JSON.stringify(error.body)}`;
-    }
-    return error instanceof Error ? error.message : String(error);
+    return error instanceof Error ? formatThrown(error) : formatJsonValue(error);
+}
+/**
+ * A thrown value rendered for a human. The two structured errors get their own
+ * rendering; every other tagged error carries a `message`, and one branch
+ * covers all of them rather than a case per tag that would all say the same
+ * thing.
+ *
+ * The match is on the class, not on `_tag`. This takes any `Error`, including
+ * one thrown by a dependency that carries no tag at all, so there is no tagged
+ * union here for `Match.tag` to narrow.
+ */
+function formatThrown(error) {
+    return Match.value(error).pipe(Match.when(Match.instanceOf(LucaDecodeError), formatDecodeError), Match.when(Match.instanceOf(LucaHttpError), formatHttpError), Match.orElse((thrown) => thrown.message));
 }