@process-cart/mcp 0.1.0

package/dist/render.js

@@ -0,0 +1,582 @@
+/** Caps that keep one answer readable. */
+export const RENDER_LIMITS = {
+    /** Tasks listed in a run before "… and N more tasks". */
+    tasks: 60,
+    /** Fields listed in a run (across its tasks) before "… and N more fields". */
+    fields: 120,
+    /** Fields listed in a workflow schema. */
+    schemaFields: 150,
+    /** Characters of one value, description or comment before it is cut. */
+    value: 300,
+};
+// ── Small helpers ───────────────────────────────────────────────────────────
+/** C0 and C1 control characters other than the line terminators and tab / VT / FF. */
+// eslint-disable-next-line no-control-regex -- matching control characters is the point.
+const CONTROL_CHARS = /[\u0000-\u0008\u000E-\u001F\u007F-\u0084\u0086-\u009F]/g;
+/**
+ * A run of whitespace holding at least one line terminator: LF, CR (CRLF too),
+ * NEL (U+0085), LINE SEPARATOR (U+2028) or PARAGRAPH SEPARATOR (U+2029).
+ */
+const LINE_BREAK_RUN = /[\s\u0085]*[\n\r\u0085\u2028\u2029][\s\u0085]*/g;
+/**
+ * Free text written by a person — a name, title, label, choice, value or
+ * comment — made safe to interpolate into one Markdown line: every line
+ * terminator becomes " / ", other control characters are dropped and runs of
+ * whitespace collapse, so the text can never start a line of its own (a
+ * heading, a list item, a line posing as an instruction). With `max`, it is
+ * also cut to that many characters.
+ */
+export function text(value, max) {
+    const line = value
+        .replace(/[\t\v\f]/g, " ")
+        .replace(CONTROL_CHARS, "")
+        .replace(LINE_BREAK_RUN, " / ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return max === undefined ? line : truncate(line, max);
+}
+/** Cuts `text` to `max` characters with an ellipsis. */
+export function truncate(text, max = RENDER_LIMITS.value) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+/** A count as people write it: 1,000. */
+function count(n) {
+    return n.toLocaleString("en-US");
+}
+/** An ISO instant without its milliseconds (`2026-10-13T01:09:28Z`); a dash for null. */
+export function instant(value) {
+    if (!value)
+        return "—";
+    return value.replace(/\.\d{1,6}Z$/, "Z");
+}
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function code(value) {
+    return `\`${text(value).replace(/`/g, "'")}\``;
+}
+/** The "pass this cursor" sentence every paged answer ends with. */
+export function pagingLine(nextCursor, what) {
+    return nextCursor
+        ? `More ${what} available: call again with cursor ${code(nextCursor)} for the next page.`
+        : `No more ${what}.`;
+}
+// ── Runs ────────────────────────────────────────────────────────────────────
+/** A canonical value that counts as blank (what a required field may not be). */
+export function isBlankValue(field) {
+    const value = field.value;
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.trim() === "";
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (field.type === "checkbox")
+        return value === false;
+    return false;
+}
+const TASK_STATE_BOX = {
+    todo: "[ ]",
+    done: "[x]",
+    rejected_redo: "[!]",
+};
+function assigneeText(assignee) {
+    switch (assignee.kind) {
+        case "user":
+            return code(`u:${assignee.userId}`);
+        case "group":
+            return code(`g:${assignee.groupId}`);
+        case "role":
+            return `every ${assignee.role}`;
+        case "guest":
+            return `guest ${text(assignee.email)}`;
+        default:
+            return "unknown";
+    }
+}
+function taskLine(task) {
+    const box = TASK_STATE_BOX[task.state] ?? `[${task.state}]`;
+    const parts = [`${box} ${text(task.title)} (${code(task.key)})`];
+    if (task.kind !== "standard")
+        parts.push(task.kind);
+    if (task.state === "rejected_redo")
+        parts.push("sent back for redo");
+    if (!task.visible)
+        parts.push("hidden");
+    if (task.locked)
+        parts.push("locked");
+    if (task.dueAt)
+        parts.push(`due ${instant(task.dueAt)}`);
+    if (task.assignees.length > 0) {
+        parts.push(`assigned: ${task.assignees.map(assigneeText).join(", ")}`);
+    }
+    if (task.completedAt)
+        parts.push(`done ${instant(task.completedAt)}`);
+    return `- ${parts.join(" · ")}`;
+}
+function fieldLine(field, task, required) {
+    const blank = isBlankValue(field);
+    const shown = field.formatted !== ""
+        ? text(field.formatted, RENDER_LIMITS.value)
+        : blank
+            ? "(blank)"
+            : text(JSON.stringify(field.value), RENDER_LIMITS.value);
+    const notes = [];
+    if (field.type === "formula")
+        notes.push("formula, read-only");
+    if (field.type === "file")
+        notes.push("file, not writable here");
+    if (field.type === "hidden")
+        notes.push("hidden variable");
+    else if (!field.visible)
+        notes.push("hidden");
+    if (required &&
+        blank &&
+        field.visible &&
+        (task === undefined || (task.visible && task.state !== "done"))) {
+        notes.push("**required — blank**");
+    }
+    else if (required) {
+        notes.push("required");
+    }
+    if (field.validationError)
+        notes.push(`invalid: ${text(field.validationError)}`);
+    if (field.choices && field.choices.length > 0) {
+        notes.push(`choices: ${text(field.choices.join(" | "), 160)}`);
+    }
+    if (field.items && field.items.length > 0) {
+        notes.push(`items: ${text(field.items.map((i) => `${i.key} = ${i.label}`).join("; "), 160)}`);
+    }
+    return `${text(field.label)} (${code(field.key)}): ${shown}${notes.length ? ` — ${notes.join(" · ")}` : ""}`;
+}
+/** Task counts over the visible tasks (what "progress" means in the app). */
+export function runProgress(run) {
+    const visible = run.tasks.filter((t) => t.visible);
+    return { done: visible.filter((t) => t.state === "done").length, total: visible.length };
+}
+/** The full run: header, then its tasks grouped by section with each task's fields beneath it. */
+export function renderRun(run, options = {}) {
+    const required = options.requiredKeys ?? null;
+    const lines = [`# Run: ${text(run.name)}`];
+    if (options.lead)
+        lines.push("", options.lead);
+    const progress = runProgress(run);
+    const labels = run.labelDetails.length > 0
+        ? run.labelDetails.map((l) => `${text(l.name)} (${code(l.id)})`).join(", ")
+        : run.labels.length > 0
+            ? run.labels.map(code).join(", ")
+            : "none";
+    lines.push("", `- Run id: ${code(run.id)} · **revision ${run.revision}** (send it as expectedRevision on your next write to this run)`, `- Workflow: ${text(run.workflow.name)} (${code(run.workflow.id)})`, `- Status: ${run.status} · Priority: ${run.priority} · Labels: ${labels}`, `- Due: ${instant(run.dueAt)} · Key date: ${run.keyDate ?? "—"}`, `- Progress: ${progress.done} of ${plural(progress.total, "visible task")} done`, `- Started: ${instant(run.startedAt)} (${run.startedBy}${run.schedule ? `, schedule "${text(run.schedule.name)}"` : ""}) · Completed: ${instant(run.completedAt)}`);
+    if (run.deletedAt)
+        lines.push(`- In Trash since ${instant(run.deletedAt)} (read-only)`);
+    lines.push(`- Open in the app: ${run.url}`);
+    // Fields by task key, in the run's order.
+    const fieldsByTask = new Map();
+    for (const field of run.fields) {
+        const list = fieldsByTask.get(field.taskKey);
+        if (list)
+            list.push(field);
+        else
+            fieldsByTask.set(field.taskKey, [field]);
+    }
+    const taskKeys = new Set(run.tasks.map((t) => t.key));
+    // Sections in order of first appearance.
+    const sections = [];
+    for (const task of run.tasks) {
+        const last = sections.at(-1);
+        const existing = last && last.title === task.section ? last : sections.find((s) => s.title === task.section);
+        if (existing)
+            existing.tasks.push(task);
+        else
+            sections.push({ title: task.section, tasks: [task] });
+    }
+    lines.push("", `## Tasks`);
+    if (run.tasks.length === 0)
+        lines.push("", "This run has no tasks.");
+    let tasksShown = 0;
+    let fieldsShown = 0;
+    for (const section of sections) {
+        if (tasksShown >= RENDER_LIMITS.tasks)
+            break;
+        lines.push("", `### ${text(section.title) || "Untitled section"}`);
+        for (const task of section.tasks) {
+            if (tasksShown >= RENDER_LIMITS.tasks)
+                break;
+            tasksShown += 1;
+            lines.push(taskLine(task));
+            for (const field of fieldsByTask.get(task.key) ?? []) {
+                if (fieldsShown >= RENDER_LIMITS.fields)
+                    break;
+                fieldsShown += 1;
+                lines.push(`  - ${fieldLine(field, task, required?.has(field.key) ?? false)}`);
+            }
+        }
+    }
+    const orphans = run.fields.filter((f) => !taskKeys.has(f.taskKey));
+    if (orphans.length > 0 && fieldsShown < RENDER_LIMITS.fields) {
+        lines.push("", "### Other fields");
+        for (const field of orphans) {
+            if (fieldsShown >= RENDER_LIMITS.fields)
+                break;
+            fieldsShown += 1;
+            lines.push(`- ${fieldLine(field, undefined, required?.has(field.key) ?? false)}`);
+        }
+    }
+    const tasksSkipped = run.tasks.length - tasksShown;
+    const fieldsSkipped = run.fields.length - fieldsShown;
+    if (tasksSkipped > 0 || fieldsSkipped > 0) {
+        const cut = [];
+        if (tasksSkipped > 0)
+            cut.push(plural(tasksSkipped, "more task"));
+        if (fieldsSkipped > 0)
+            cut.push(plural(fieldsSkipped, "more field"));
+        lines.push("", `… and ${cut.join(" and ")} not shown (the structured result carries all of them).`);
+    }
+    if (required === null) {
+        lines.push("", "Required fields are not flagged here; complete_task names any required field that is still blank.");
+    }
+    return lines.join("\n");
+}
+export function summarizeRun(run) {
+    return {
+        id: run.id,
+        name: run.name,
+        status: run.status,
+        priority: run.priority,
+        labels: run.labels,
+        dueAt: run.dueAt,
+        keyDate: run.keyDate,
+        revision: run.revision,
+        updatedAt: run.updatedAt,
+        startedAt: run.startedAt,
+        completedAt: run.completedAt,
+        deletedAt: run.deletedAt,
+        workflow: run.workflow,
+        url: run.url,
+        progress: runProgress(run),
+        openTasks: run.tasks
+            .filter((t) => t.visible && !t.locked && t.state !== "done")
+            .map((t) => ({ key: t.key, title: t.title })),
+    };
+}
+/** One page of runs, one entry each (get_run shows a run's tasks and fields). */
+export function renderRunList(runs, nextCursor) {
+    if (runs.length === 0)
+        return `No runs match.\n\n${pagingLine(nextCursor, "runs")}`;
+    const lines = [`Found ${plural(runs.length, "run")} on this page.`, ""];
+    runs.forEach((run, i) => {
+        const s = summarizeRun(run);
+        const meta = [
+            run.status,
+            `priority ${run.priority}`,
+            run.dueAt ? `due ${instant(run.dueAt)}` : null,
+            run.keyDate ? `key date ${run.keyDate}` : null,
+            `${s.progress.done} of ${s.progress.total} tasks done`,
+            `revision ${run.revision}`,
+            run.deletedAt ? "in Trash" : null,
+        ].filter(Boolean);
+        lines.push(`${i + 1}. **${text(run.name)}** — ${meta.join(" · ")}`);
+        lines.push(`   id ${code(run.id)} · ${text(run.workflow.name)} · ${run.url}`);
+        if (s.openTasks.length > 0) {
+            const open = s.openTasks.slice(0, 5).map((t) => `${text(t.title)} (${code(t.key)})`);
+            const more = s.openTasks.length > 5 ? `, … and ${s.openTasks.length - 5} more` : "";
+            lines.push(`   open tasks: ${open.join(", ")}${more}`);
+        }
+    });
+    lines.push("", pagingLine(nextCursor, "runs"), "Use get_run for a run's tasks and fields.");
+    return lines.join("\n");
+}
+// ── Workflows ───────────────────────────────────────────────────────────────
+export function renderWorkflowList(workflows, nextCursor, options = {}) {
+    const lines = [];
+    const query = options.query === undefined ? undefined : text(options.query);
+    if (workflows.length === 0) {
+        lines.push(query ? `No workflow matches "${query}".` : "No workflows found.");
+    }
+    else if (query) {
+        const total = options.totalMatches ?? workflows.length;
+        lines.push(total > workflows.length
+            ? `${plural(total, "workflow")} match "${query}"; showing the first ${workflows.length}.`
+            : `${plural(total, "workflow")} match "${query}".`);
+    }
+    else {
+        lines.push(`Found ${plural(workflows.length, "workflow")} on this page.`);
+    }
+    workflows.forEach((w, i) => {
+        const state = [];
+        if (w.publishedVersion)
+            state.push(`published v${w.publishedVersion.number}`);
+        else
+            state.push("not published — runs cannot be started");
+        if (w.status === "archived")
+            state.push("archived — runs cannot be started");
+        state.push(plural(w.taskCount, "task"));
+        if (w.kickoffFormEnabled)
+            state.push("public kickoff form live");
+        if (w.folder)
+            state.push(`folder "${text(w.folder.name)}"`);
+        if (w.keyDateFieldKey)
+            state.push(`key date field ${code(w.keyDateFieldKey)}`);
+        lines.push("", `${i + 1}. **${text(w.name)}** (${code(w.id)}) — ${state.join(" · ")}`);
+        if (w.description)
+            lines.push(`   ${text(w.description, 200)}`);
+    });
+    if (!query)
+        lines.push("", pagingLine(nextCursor, "workflows"));
+    lines.push("", "Next: get_workflow_schema with a workflow's id to learn its field keys.");
+    return lines.join("\n");
+}
+function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+const KICKOFF_ABSENT = "Not a kickoff field";
+const REQUIRED_UNLESS_HIDDEN = "Required at start unless a rule hides it.";
+/** Reads the API's per-workflow JSON Schemas into one summary per writable field, start fields first. */
+export function summarizeSchema(schema) {
+    const startFields = asObject(asObject(asObject(schema.start)?.properties)?.fields);
+    const startProps = asObject(startFields?.properties) ?? {};
+    const startRequired = new Set(stringList(startFields?.required));
+    const allProps = asObject(asObject(schema.fields)?.properties) ?? {};
+    // Every writable field is in `fields`; `start` holds the same set (the API takes any at start).
+    const keys = [...new Set([...Object.keys(allProps), ...Object.keys(startProps)])];
+    const out = keys.map((key) => {
+        const prop = asObject(allProps[key]) ?? asObject(startProps[key]) ?? {};
+        const startProp = asObject(startProps[key]);
+        const startDescription = typeof startProp?.description === "string" ? startProp.description : "";
+        const description = typeof prop.description === "string" ? prop.description : null;
+        const items = asObject(prop.items);
+        const choices = [...stringList(prop.enum), ...stringList(items?.enum)];
+        const constraints = [];
+        if (typeof prop.minimum === "number")
+            constraints.push(`min ${prop.minimum}`);
+        if (typeof prop.maximum === "number")
+            constraints.push(`max ${prop.maximum}`);
+        if (typeof prop.minLength === "number")
+            constraints.push(`at least ${prop.minLength} characters`);
+        if (typeof prop.maxLength === "number")
+            constraints.push(`at most ${prop.maxLength} characters`);
+        if (typeof prop.pattern === "string")
+            constraints.push(`pattern ${prop.pattern}`);
+        if (typeof prop.format === "string")
+            constraints.push(`format ${prop.format}`);
+        return {
+            key,
+            label: typeof prop.title === "string" ? prop.title : key,
+            type: typeof prop["x-processcart-type"] === "string" ? prop["x-processcart-type"] : "unknown",
+            format: typeof prop["x-processcart-format"] === "string" ? prop["x-processcart-format"] : null,
+            taskKey: typeof prop["x-task"] === "string" ? prop["x-task"] : null,
+            sectionKey: typeof prop["x-section"] === "string" ? prop["x-section"] : null,
+            kickoff: startProp !== null && !startDescription.includes(KICKOFF_ABSENT),
+            requiredAtStart: startRequired.has(key),
+            requiredUnlessHidden: startDescription.includes(REQUIRED_UNLESS_HIDDEN),
+            choices,
+            constraints,
+            notes: description,
+        };
+    });
+    const rank = (f) => f.requiredAtStart ? 0 : f.requiredUnlessHidden ? 1 : f.kickoff ? 2 : 3;
+    // A stable sort keeps the workflow's own order inside each rank.
+    return out
+        .map((f, i) => ({ f, i }))
+        .sort((a, b) => rank(a.f) - rank(b.f) || a.i - b.i)
+        .map((x) => x.f);
+}
+function schemaFieldLine(f) {
+    const kind = f.format && f.format !== "none" && f.format !== f.type ? `${f.type}, ${f.format}` : f.type;
+    const parts = [`${text(f.label)} (${code(f.key)}) · ${text(kind)}`];
+    if (f.requiredAtStart)
+        parts.push("**required at start**");
+    else if (f.requiredUnlessHidden)
+        parts.push("**required at start unless a rule hides it**");
+    else if (f.kickoff)
+        parts.push("kickoff field");
+    if (f.taskKey)
+        parts.push(`task ${code(f.taskKey)}`);
+    if (f.choices.length > 0)
+        parts.push(`values: ${text(f.choices.join(" | "), 200)}`);
+    if (f.constraints.length > 0)
+        parts.push(text(f.constraints.join(", ")));
+    const line = `- ${parts.join(" · ")}`;
+    return f.notes ? `${line}\n  ${text(f.notes, 240)}` : line;
+}
+export function renderSchema(schema) {
+    const fields = summarizeSchema(schema);
+    const start = fields.filter((f) => f.requiredAtStart || f.requiredUnlessHidden || f.kickoff);
+    const lines = [
+        `# Workflow schema`,
+        "",
+        `- Workflow id: ${code(schema.workflowId)} · published version ${schema.versionNumber} (${code(schema.versionId)})`,
+        `- ${plural(fields.length, "writable field")}. start_run accepts any of them in \`fields\`; set_fields writes them on an existing run. Keys are the identity — never the labels.`,
+        "",
+        "## Start fields (the run-start form)",
+    ];
+    if (start.length === 0)
+        lines.push("", "No kickoff fields: start_run needs only a name.");
+    else
+        lines.push("", ...start.map(schemaFieldLine));
+    lines.push("", "## Every writable field");
+    const shown = fields.slice(0, RENDER_LIMITS.schemaFields);
+    lines.push("", ...shown.map(schemaFieldLine));
+    if (fields.length > shown.length) {
+        lines.push("", `… and ${plural(fields.length - shown.length, "more field")} not shown (the structured result carries the full JSON Schemas).`);
+    }
+    lines.push("", "Values: a JSON number for number / currency / percent fields (a percent is a fraction: 0.125 = 12.5 %), YYYY-MM-DD for dates, HH:mm for times, a list of strings for multi-choice, subtask and members fields, true / false for checkboxes, null to clear. Formula and file fields are not writable.");
+    return lines.join("\n");
+}
+// ── Activity and comments ───────────────────────────────────────────────────
+function authorName(author) {
+    if (typeof author.name === "string" && author.name)
+        return author.name;
+    switch (author.kind) {
+        case "guest":
+            return author.email;
+        case "user":
+            return `user ${author.userId}`;
+        case "system":
+            return "Process Cart";
+        default:
+            return author.kind;
+    }
+}
+export function renderComment(comment) {
+    return `- ${instant(comment.createdAt)} · ${text(authorName(comment.author), 120)} on ${code(comment.taskKey)}: ${text(comment.text, RENDER_LIMITS.value)}`;
+}
+function commentsHeading(comments) {
+    const { shown, total } = comments;
+    if (comments.complete === false) {
+        const first = total - shown.length + 1;
+        return `Comments ${count(first)}–${count(total)} of more than ${count(total)}, oldest first. The API lists comments oldest first and this server reads only the first ${count(total)}, so the run's newest comments are not shown:`;
+    }
+    return total > shown.length
+        ? `The latest ${shown.length} of ${count(total)} comments, oldest first:`
+        : `${plural(total, "comment")}, oldest first:`;
+}
+export function renderActivity(items, nextCursor, comments) {
+    const lines = ["## Activity (newest first)", ""];
+    if (items.length === 0)
+        lines.push("No activity on this page.");
+    for (const item of items) {
+        const task = item.taskKey ? ` · task ${code(item.taskKey)}` : "";
+        lines.push(`- ${instant(item.createdAt)} · ${text(item.description, RENDER_LIMITS.value)} (${text(item.type)}${task})`);
+    }
+    lines.push("", pagingLine(nextCursor, "activity"));
+    if (comments) {
+        lines.push("", "## Comments");
+        if (comments.total === 0) {
+            lines.push("", "No comments on this run.");
+        }
+        else {
+            lines.push("", commentsHeading(comments), "", ...comments.shown.map(renderComment));
+        }
+    }
+    return lines.join("\n");
+}
+// ── People ──────────────────────────────────────────────────────────────────
+export function renderPeople(users, groups, options = {}) {
+    const lines = [];
+    const filter = options.query ? ` matching "${text(options.query)}"` : "";
+    lines.push(`## Members${filter} (${users.length})`, "");
+    if (users.length === 0)
+        lines.push("None.");
+    for (const user of users) {
+        lines.push(`- ${user.name ? text(user.name) : "(no name)"} · ${user.role} · ${code(`u:${user.id}`)}`);
+    }
+    lines.push("", `## Groups${filter} (${groups.length})`, "");
+    if (groups.length === 0)
+        lines.push("None.");
+    for (const group of groups) {
+        lines.push(`- ${text(group.name)} · ${plural(group.memberIds.length, "member")} · ${code(`g:${group.id}`)}`);
+    }
+    if (options.truncated)
+        lines.push("", "The directory is larger than this server reads at once; narrow it with q.");
+    lines.push("", "Pass `u:<id>` or `g:<id>` as find_runs' assignee. A members field takes the bare user ids (without `u:`).");
+    return lines.join("\n");
+}
+export function renderMe(me, mode) {
+    const labels = me.org.labels.length > 0
+        ? me.org.labels.map((l) => `${text(l.name)} (${code(l.id)})`).join(", ")
+        : "none defined";
+    const scopes = me.key.scopes.includes("*")
+        ? "all scopes (`*`)"
+        : me.key.scopes.map(code).join(", ");
+    const lines = [
+        `# Connected to Process Cart`,
+        "",
+        `- Workspace: **${text(me.org.name)}** (${code(me.org.slug)}) · time zone ${text(me.org.timezone)}${me.org.sandbox ? " · **sandbox**" : ""}`,
+        `- Status labels: ${labels}`,
+        `- API key: "${text(me.key.name)}" (${code(`${me.key.prefix}…`)}) · ${me.key.readOnly ? "**read-only key**" : "read and write"} · ${scopes}`,
+        `- Rate limit: ${me.rateLimit.limit} requests per ${me.rateLimit.windowSeconds} seconds`,
+        "",
+        "## This server",
+        "",
+        `- API: ${mode.baseUrl}`,
+        `- Mode: ${mode.readOnlyFlag ? "read-only (started with --read-only)" : me.key.readOnly ? "read-only (the key is read-only)" : "read and write, as the key's scopes allow"}`,
+        `- Tools: ${mode.tools.map(code).join(", ")}`,
+    ];
+    if (mode.startupProblem) {
+        lines.push("", `At startup the server could not read the key (${text(mode.startupProblem)}), so it registered the read tools only. Restart the server to load the tools this key allows.`);
+    }
+    return lines.join("\n");
+}
+const HINTS = {
+    required_fields_unsatisfied: "Set the listed fields with set_fields (or the app), then complete the task again.",
+    insufficient_scope: "This API key does not have the scope that action needs; an Admin can change the key under Settings → API.",
+    read_only_key: "This API key is read-only; it can read but not change anything.",
+    not_allowed_for_key: "This API key is limited to certain workflows or folders, and this one is outside them.",
+    not_found: "Check the id: list_workflows and find_runs list the ones this key can see.",
+    workflow_not_published: "Publish the workflow in the app before starting runs of it.",
+    task_locked: "Complete the earlier tasks that lock this one first.",
+    task_hidden: "A visibility rule hides this task right now; it cannot be completed.",
+    approver_only: "Only the task's approvers can decide it; an API key needs the approvals:decide scope.",
+    wrong_task_kind: "Approval tasks are decided with decide_approval; standard tasks are completed with complete_task.",
+    field_not_writable: "Formula, file and display-text fields cannot be written.",
+    run_archived: "The run is archived: set its status back with update_run before changing it.",
+    run_trashed: "The run is in Trash; restore it in the app first.",
+    invalid_api_key: "The API key is not valid. Check PROCESSCART_API_KEY.",
+    key_revoked: "The API key was revoked. An Admin can create a new one under Settings → API.",
+    unauthorized: "The API key is missing or not valid. Check PROCESSCART_API_KEY.",
+    network_error: "Could not reach the Process Cart API. Check the network and PROCESSCART_BASE_URL.",
+    timeout: "The Process Cart API did not answer in time; try again.",
+    unavailable: "The Process Cart API is briefly unavailable; try again shortly.",
+};
+/** The error as a model reads it: what failed, every field problem, and what to do next. */
+export function renderProblem(problem) {
+    const status = problem.status > 0 ? `HTTP ${problem.status} · ` : "";
+    const lines = [
+        `**Process Cart error** (${status}${code(problem.code)}): ${text(problem.title)}${problem.detail && problem.detail !== problem.title ? ` — ${text(problem.detail)}` : ""}`,
+    ];
+    if (problem.errors && problem.errors.length > 0) {
+        lines.push("", problem.code === "required_fields_unsatisfied" ? "Missing:" : "Problems:");
+        for (const e of problem.errors.slice(0, 50)) {
+            lines.push(`- ${code(e.field)}: ${text(e.code)} — ${text(e.message)}`);
+        }
+        if (problem.errors.length > 50)
+            lines.push(`- … and ${problem.errors.length - 50} more`);
+    }
+    if (problem.code === "revision_mismatch") {
+        lines.push("", problem.currentRevision !== undefined
+            ? `The run changed since you read it: it is now at **revision ${problem.currentRevision}**. Read it again with get_run, check that your change still makes sense, and retry with expectedRevision ${problem.currentRevision}.`
+            : "The run changed since you read it. Read it again with get_run and retry with its new revision.");
+    }
+    if (problem.code === "rate_limited" || problem.status === 429) {
+        lines.push("", problem.retryAfter !== undefined
+            ? `Rate limited: wait ${plural(problem.retryAfter, "second")} before the next request.`
+            : "Rate limited: wait a minute before the next request.");
+    }
+    else if (problem.retryAfter !== undefined) {
+        lines.push("", `The API asked to retry after ${plural(problem.retryAfter, "second")}.`);
+    }
+    const hint = HINTS[problem.code];
+    if (hint)
+        lines.push("", hint);
+    if (problem.requestId)
+        lines.push("", `Request id: ${code(problem.requestId)} (quote it to support).`);
+    return lines.join("\n");
+}

package/dist/server.d.ts

@@ -0,0 +1,57 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ClientOptions } from "@process-cart/sdk";
+import { type ProblemView } from "./render.js";
+import { type ToolDefinition } from "./tools/shared.js";
+/**
+ * The startup `getMe` gets one attempt of at most this long, so a slow or
+ * unreachable API never holds back the client's `initialize` (clients give
+ * up after about 60 s) — the server then starts with the read tools only.
+ */
+export declare const STARTUP_TIMEOUT_MS = 10000;
+/** Replaces every API key in a diagnostic with its prefix (`pc_live_…`). */
+export declare function redactKeys(message: string): string;
+export interface CreateServerOptions {
+    /** A Process Cart API key (`pc_live_…` or `pc_test_…`), from Settings → API. */
+    apiKey: string;
+    /** Default `https://app.processcart.com/api`. */
+    baseUrl?: string;
+    /** Register the read tools only, whatever the key's scopes allow. */
+    readOnly?: boolean;
+    /** A WHATWG-compatible fetch (default `globalThis.fetch`). */
+    fetch?: typeof fetch;
+    /**
+     * Where diagnostics go (default: one line on stderr). Never handed the API
+     * key, field values or comment text.
+     */
+    log?: (message: string) => void;
+    /** Log every tool call: its name, outcome and duration. */
+    debug?: boolean;
+    /** The SDK client's retry policy (see `@process-cart/sdk`). */
+    retry?: ClientOptions["retry"];
+    /** The SDK client's per-attempt timeout, in milliseconds. */
+    timeoutMs?: number;
+    /** The startup `getMe`'s one attempt, in milliseconds (default `STARTUP_TIMEOUT_MS`). */
+    startupTimeoutMs?: number;
+}
+/**
+ * What the model is told about working with this server (the `instructions`
+ * of `initialize`), built from the tools it registered: a read-only server
+ * says so and names no write tool.
+ */
+export declare function buildInstructions(tools: readonly Pick<ToolDefinition, "name" | "access">[]): string;
+/** The instructions of a server that registered every tool (a full-access key). */
+export declare const INSTRUCTIONS: string;
+/** Which tools a key may use: read tools by scope; write tools only for a writable key, and never with `--read-only`. */
+export declare function selectTools(tools: readonly ToolDefinition[], key: {
+    scopes: readonly string[];
+    readOnly: boolean;
+} | null, readOnlyFlag: boolean): ToolDefinition[];
+/** Any failure as the renderer reads it. */
+export declare function problemOf(error: unknown): ProblemView;
+/**
+ * Builds the server: reads the key's identity, then registers the tools it may
+ * use. Connect it to a transport (`StdioServerTransport` in the CLI) to serve.
+ * Rejects only for an option the SDK refuses (a malformed API key); an API
+ * failure at startup is logged and leaves the read tools registered.
+ */
+export declare function createServer(options: CreateServerOptions): Promise<McpServer>;