@process-cart/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Process Cart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @process-cart/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Process Cart](https://developers.processcart.com). Add it to Claude Desktop, Claude Code, Cursor
+or any other MCP client, give it an API key, and the assistant can find a workflow, start a run,
+fill in its fields, complete its tasks, decide approvals, comment and read what happened.
+
+It runs locally over stdio, calls the Process Cart API (`/api/v1`) with your key, and is built on
+[`@process-cart/sdk`](https://www.npmjs.com/package/@process-cart/sdk). Full guide:
+<https://developers.processcart.com/guides/mcp>.
+
+## Install
+
+```sh
+npx -y @process-cart/mcp
+```
+
+Your MCP client runs that command for you (see below). It needs Node.js 22.12 or later and a
+Process Cart API key: an Admin creates one under **Settings → API**. A key acts on its whole
+workspace, so give the assistant a key of its own with only the scopes it needs, and try it with
+a sandbox (`pc_test_…`) key first.
+
+## Configure
+
+### Claude Desktop
+
+**Settings → Developer → Edit Config**, then add to `claude_desktop_config.json` and restart:
+
+```json
+{
+  "mcpServers": {
+    "processcart": {
+      "command": "npx",
+      "args": ["-y", "@process-cart/mcp"],
+      "env": { "PROCESSCART_API_KEY": "pc_live_…" }
+    }
+  }
+}
+```
+
+On Windows, if `npx` does not start, use `"command": "cmd"` with
+`"args": ["/c", "npx", "-y", "@process-cart/mcp"]`.
+
+### Claude Code
+
+```sh
+claude mcp add processcart -e PROCESSCART_API_KEY=pc_live_… -- npx -y @process-cart/mcp
+```
+
+To share it through a project's checked-in `.mcp.json`, keep the key out of the file: Claude Code
+expands `${VAR}` there, so register the variable (single quotes stop your shell expanding it) and
+let each teammate export their own key:
+
+```sh
+claude mcp add processcart --scope project -e 'PROCESSCART_API_KEY=${PROCESSCART_API_KEY}' -- npx -y @process-cart/mcp
+```
+
+### Cursor
+
+The same `mcpServers` block as Claude Desktop, in `~/.cursor/mcp.json` (every project) or
+`.cursor/mcp.json` (one project).
+
+## Environment and flags
+
+| Setting                 | What it does                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| `PROCESSCART_API_KEY`   | Your API key (`pc_live_…` or `pc_test_…`). Required.                                   |
+| `PROCESSCART_BASE_URL`  | The API base URL. Default `https://app.processcart.com/api`.                           |
+| `PROCESSCART_MCP_DEBUG` | `1` logs each tool call (name, outcome, duration) to stderr — never the key or values. |
+| `--api-key <key>`       | The key as a flag (prefer the environment: a command line is visible to others).       |
+| `--base-url <url>`      | The base URL as a flag.                                                                |
+| `--read-only`           | Offer the read tools only, whatever the key allows.                                    |
+| `--help`, `--version`   | Print the usage or the version and exit.                                               |
+
+The base URL must use `https`; plain `http` is accepted only for a server on this machine
+(`localhost`, `127.x.x.x`, `::1`). Nothing but the MCP protocol is written to stdout; diagnostics go
+to stderr, with anything shaped like a key cut to its prefix (`pc_live_…`). A missing or malformed
+key, or an `http` URL to another host, exits with status 2 and a message on stderr.
+
+## Tools
+
+| Tool                  | What it does                                                                     | Scope              |
+| --------------------- | -------------------------------------------------------------------------------- | ------------------ |
+| `whoami`              | The workspace, the key, its scopes, the rate limit, the status labels, the tools | any key            |
+| `list_workflows`      | Workflows the key can see; `q` searches names and descriptions                   | `workflows:read`   |
+| `get_workflow_schema` | A workflow's fields by key, with types, allowed values and the start form        | `workflows:read`   |
+| `start_run`           | Start a run with field values, priority, labels and a due date                   | `runs:write`       |
+| `find_runs`           | Search runs by name, workflow, status, priority, labels, assignee, due window    | `runs:read`        |
+| `get_run`             | One run in full: tasks, fields, revision, app link                               | `runs:read`        |
+| `set_fields`          | Set field values by key, all or nothing                                          | `runs:write`       |
+| `complete_task`       | Complete a task; a refusal names the required fields still blank                 | `runs:write`       |
+| `reopen_task`         | Put a completed task back to to-do                                               | `runs:write`       |
+| `decide_approval`     | Approve or reject an approval task (a rejection needs a comment)                 | `approvals:decide` |
+| `add_comment`         | Comment on a task                                                                | `runs:write`       |
+| `get_activity`        | A run's trail, newest first, with its latest comments                            | `runs:read`        |
+| `update_run`          | Change a run's name, status, priority, labels or due date                        | `runs:write`       |
+| `list_people`         | Members and groups, with the ids `find_runs` filters by                          | `users:read`       |
+
+Each tool answers Markdown for the model plus JSON as `structuredContent`. A run answer is the
+whole run — tasks grouped by section with their keys, fields as "Label (`key`): value", and the
+current `revision` — and its JSON is the API's Run resource, so no second call is needed to see
+the result of a write. `find_runs` carries one summary per run (id, name, status, priority,
+labels, dates, revision, workflow, link, task progress and the open tasks — no tasks or fields),
+`list_people` carries `{ users, groups, complete }`, and `whoami` the API's `/v1/me` answer plus a
+`server` member. `get_run` flags required fields that are still blank only when the key also has
+`workflows:read` and the run is on the published version; otherwise `complete_task` names them.
+
+At startup the server calls `GET /v1/me` (one attempt, at most 10 seconds) and registers only the
+tools the key can use. A read-only key, or `--read-only`, gets the read tools only, and the
+server's instructions then say it is read-only. If the key cannot be read at startup, the server
+starts with the read tools only and `whoami` reports the error.
+
+## Safety
+
+- No admin tools, and nothing deletes: no tool deletes a run, workflow or comment; `set_fields`
+  and `update_run` can overwrite or clear values; `reopen_task` and a rejection send work back.
+  Those four carry the MCP `destructiveHint`. Webhooks, schedules, automation rules, views,
+  workflow edits, files, CSV and Trash stay in the app and the REST API.
+- Run names, field values, task titles, comments and activity are written by people, guests
+  included: the instructions and the read tools' descriptions tell the model to treat them as
+  data, never as instructions, and every such string is rendered on one line.
+- A client's cancellation aborts the API request in flight.
+- Every write carries an `Idempotency-Key`, so a retried request is applied once.
+- The write tools take `expectedRevision` (sent as `Expected-Revision`): a write that raced
+  another change is refused with `409 revision_mismatch`, naming the current revision.
+- API failures come back as tool results (`isError: true`) with the code, every field problem,
+  `currentRevision` on a 409 and the wait on a 429.
+- The key is sent only to the API and never logged.
+
+## Programmatic use
+
+```ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "@process-cart/mcp";
+
+const server = await createServer({ apiKey: process.env.PROCESSCART_API_KEY!, readOnly: true });
+await server.connect(new StdioServerTransport());
+```
+
+`createServer({ apiKey, baseUrl?, readOnly?, fetch?, log?, debug?, startupTimeoutMs? })` resolves
+to an `McpServer` with the key's tools registered; connect it to any MCP transport.
+
+## Maintainers
+
+Publish with **pnpm**, not npm: the manifest depends on `@process-cart/sdk` as `workspace:^`, which
+`pnpm publish` rewrites to the SDK's real range (`^0.1.0`) in the tarball, and `npm publish` does
+not.
+
+```sh
+pnpm --filter @process-cart/sdk build
+cd packages/mcp && pnpm publish --access public --no-git-checks
+```
+
+`prepack` rebuilds `dist/`. `pnpm pack --dry-run` shows the tarball. Bump `version` in
+`package.json`, `src/version.ts` and both versions in `server.json` together (`version.test.ts`
+checks them). The MCP Registry listing (`server.json`, name `com.processcart/mcp`) is pending.
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { parseArgs } from "./cli.js";

package/dist/bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// `processcart-mcp`: the stdio entry point. Over stdio, stdout carries only
+// the MCP transport, so any stray console output is routed to stderr before
+// the server starts. The parser is re-exported for tests; importing this
+// module does not start the server unless it is the script node runs.
+import { isEntryPoint, main } from "./cli.js";
+import { redactKeys } from "./server.js";
+export { parseArgs } from "./cli.js";
+if (isEntryPoint(import.meta.url, process.argv[1])) {
+    const toStderr = (...args) => console.error(...args);
+    console.log = toStderr;
+    console.info = toStderr;
+    console.debug = toStderr;
+    main().then((code) => {
+        if (code !== null)
+            process.exitCode = code;
+    }, (error) => {
+        process.stderr.write(`[processcart-mcp] ${redactKeys(error instanceof Error ? error.message : String(error))}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,45 @@
+import type { Readable, Writable } from "node:stream";
+export declare const HELP = "processcart-mcp 0.1.0 \u2014 the Process Cart MCP server (stdio)\n\nUsage:\n  npx -y @process-cart/mcp [options]\n\nEnvironment:\n  PROCESSCART_API_KEY    A Process Cart API key (pc_live_\u2026 or pc_test_\u2026). Required.\n  PROCESSCART_BASE_URL   The API base URL (default https://app.processcart.com/api). https; plain\n                         http only for a server on this machine (localhost, 127.x.x.x, ::1).\n  PROCESSCART_MCP_DEBUG  Set to 1 to log each tool call (name, outcome, duration) to stderr.\n\nOptions:\n  --api-key <key>        The API key (prefer the environment variable: a flag is visible to\n                         other processes on this machine).\n  --base-url <url>       The API base URL.\n  --read-only            Offer the read tools only, whatever the key allows.\n  -h, --help             Show this help.\n  -v, --version          Show the version.\n\nDocs: https://developers.processcart.com/guides/mcp\n";
+export interface ServeOptions {
+    apiKey: string;
+    baseUrl: string;
+    readOnly: boolean;
+    debug: boolean;
+}
+export type CliCommand = {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "serve";
+    options: ServeOptions;
+} | {
+    kind: "error";
+    message: string;
+};
+/** A loopback host (`localhost`, `127.0.0.0/8`, `::1`): the one place plain http may go. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Parses the command line and environment. Flags win over the environment.
+ * Never echoes the key back in a message: an unknown option is named without
+ * its value, and a bare argument that looks like a key is not repeated.
+ */
+export declare function parseArgs(argv: readonly string[], env: Readonly<Record<string, string | undefined>>): CliCommand;
+/** The process surface `main` uses, injectable for tests. */
+export interface CliIo {
+    argv: readonly string[];
+    env: Readonly<Record<string, string | undefined>>;
+    stdin: Readable;
+    stdout: Writable;
+    stderr: Pick<Writable, "write">;
+    /** Called once the client goes away (stdin ends) or a signal arrives. */
+    exit: (code: number) => void;
+    fetch?: typeof fetch;
+}
+/**
+ * Runs the CLI. Resolves to an exit code for --help, --version and usage
+ * errors (2), or to null once the server is serving on stdio.
+ */
+export declare function main(io?: CliIo): Promise<number | null>;
+/** True when `moduleUrl` is the script node was started with (symlinks and npx shims resolved). */
+export declare function isEntryPoint(moduleUrl: string, argv1: string | undefined): boolean;

package/dist/cli.js

@@ -0,0 +1,196 @@
+// The command line: `processcart-mcp` reads its key and options, builds the
+// server and serves it over stdio. Over stdio, stdout IS the MCP transport —
+// every diagnostic goes to stderr. Only --help and --version print to stdout,
+// and they exit before any transport starts.
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DEFAULT_BASE_URL } from "@process-cart/sdk";
+import { createServer, redactKeys } from "./server.js";
+import { MCP_VERSION } from "./version.js";
+export const HELP = `processcart-mcp ${MCP_VERSION} — the Process Cart MCP server (stdio)
+
+Usage:
+  npx -y @process-cart/mcp [options]
+
+Environment:
+  PROCESSCART_API_KEY    A Process Cart API key (pc_live_… or pc_test_…). Required.
+  PROCESSCART_BASE_URL   The API base URL (default ${DEFAULT_BASE_URL}). https; plain
+                         http only for a server on this machine (localhost, 127.x.x.x, ::1).
+  PROCESSCART_MCP_DEBUG  Set to 1 to log each tool call (name, outcome, duration) to stderr.
+
+Options:
+  --api-key <key>        The API key (prefer the environment variable: a flag is visible to
+                         other processes on this machine).
+  --base-url <url>       The API base URL.
+  --read-only            Offer the read tools only, whatever the key allows.
+  -h, --help             Show this help.
+  -v, --version          Show the version.
+
+Docs: https://developers.processcart.com/guides/mcp
+`;
+const API_KEY_PATTERN = /^pc_(live|test)_\S+$/;
+function truthy(value) {
+    return value !== undefined && /^(1|true|yes|on)$/i.test(value.trim());
+}
+/** A loopback host (`localhost`, `127.0.0.0/8`, `::1`): the one place plain http may go. */
+export function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase();
+    return (host === "localhost" ||
+        host === "[::1]" ||
+        host === "::1" ||
+        /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host));
+}
+/**
+ * Parses the command line and environment. Flags win over the environment.
+ * Never echoes the key back in a message: an unknown option is named without
+ * its value, and a bare argument that looks like a key is not repeated.
+ */
+export function parseArgs(argv, env) {
+    let apiKey;
+    let baseUrl;
+    let readOnly = false;
+    let version = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help")
+            return { kind: "help" };
+        if (arg === "-v" || arg === "--version") {
+            version = true;
+            continue;
+        }
+        if (arg === "--read-only") {
+            readOnly = true;
+            continue;
+        }
+        const match = /^(--api-key|--base-url)(?:=(.*))?$/.exec(arg);
+        if (match) {
+            const value = match[2] ?? argv[i + 1];
+            if (match[2] === undefined)
+                i += 1;
+            if (value === undefined ||
+                value === "" ||
+                (match[2] === undefined && value.startsWith("--"))) {
+                return { kind: "error", message: `${match[1]} needs a value` };
+            }
+            if (match[1] === "--api-key")
+                apiKey = value;
+            else
+                baseUrl = value;
+            continue;
+        }
+        if (/pc_(live|test)_/.test(arg) && !arg.startsWith("-")) {
+            return {
+                kind: "error",
+                message: "an API key is not an argument: pass the key as --api-key or PROCESSCART_API_KEY (prefer the environment variable)",
+            };
+        }
+        const name = arg.split("=", 1)[0];
+        return { kind: "error", message: `unknown option ${JSON.stringify(redactKeys(name))}` };
+    }
+    if (version)
+        return { kind: "version" };
+    const key = (apiKey ?? env.PROCESSCART_API_KEY ?? "").trim();
+    if (key === "") {
+        return {
+            kind: "error",
+            message: "no API key: set PROCESSCART_API_KEY (an Admin creates keys under Settings → API in Process Cart)",
+        };
+    }
+    if (!API_KEY_PATTERN.test(key)) {
+        return {
+            kind: "error",
+            message: "the API key is not a Process Cart API key (they start with pc_live_ or pc_test_)",
+        };
+    }
+    const base = (baseUrl ?? env.PROCESSCART_BASE_URL ?? "").trim() || DEFAULT_BASE_URL;
+    let parsed;
+    try {
+        parsed = new URL(base);
+    }
+    catch {
+        return { kind: "error", message: `the base URL ${JSON.stringify(base)} is not a URL` };
+    }
+    if (parsed.protocol !== "https:" &&
+        !(parsed.protocol === "http:" && isLoopbackHost(parsed.hostname))) {
+        return {
+            kind: "error",
+            message: "the base URL must use https (http only for a server on this machine: localhost, 127.x.x.x or ::1), so the API key never travels in cleartext",
+        };
+    }
+    return {
+        kind: "serve",
+        options: { apiKey: key, baseUrl: base, readOnly, debug: truthy(env.PROCESSCART_MCP_DEBUG) },
+    };
+}
+function processIo() {
+    return {
+        argv: process.argv.slice(2),
+        env: process.env,
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        exit: (code) => process.exit(code),
+    };
+}
+/**
+ * Runs the CLI. Resolves to an exit code for --help, --version and usage
+ * errors (2), or to null once the server is serving on stdio.
+ */
+export async function main(io = processIo()) {
+    const command = parseArgs(io.argv, io.env);
+    if (command.kind === "help") {
+        io.stdout.write(HELP);
+        return 0;
+    }
+    if (command.kind === "version") {
+        io.stdout.write(`${MCP_VERSION}\n`);
+        return 0;
+    }
+    if (command.kind === "error") {
+        io.stderr.write(`processcart-mcp: ${redactKeys(command.message)}\nRun processcart-mcp --help for usage.\n`);
+        return 2;
+    }
+    const { options } = command;
+    // Every diagnostic is redacted: MCP clients keep server stderr in log files.
+    const log = (message) => void io.stderr.write(`[processcart-mcp] ${redactKeys(message)}\n`);
+    let server;
+    try {
+        server = await createServer({
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+            readOnly: options.readOnly,
+            debug: options.debug,
+            log,
+            ...(io.fetch ? { fetch: io.fetch } : {}),
+        });
+    }
+    catch (error) {
+        log(`could not start: ${error instanceof Error ? error.message : String(error)}`);
+        return 2;
+    }
+    const transport = new StdioServerTransport(io.stdin, io.stdout);
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void server.close().finally(() => io.exit(0));
+    };
+    io.stdin.once("end", shutdown);
+    io.stdin.once("close", shutdown);
+    await server.connect(transport);
+    return null;
+}
+/** True when `moduleUrl` is the script node was started with (symlinks and npx shims resolved). */
+export function isEntryPoint(moduleUrl, argv1) {
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(path.resolve(argv1));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { buildInstructions, createServer, INSTRUCTIONS, problemOf, selectTools, STARTUP_TIMEOUT_MS, type CreateServerOptions, } from "./server.js";
+export { TOOLS } from "./tools/index.js";
+export type { ToolAccess, ToolContext, ToolDefinition, ToolOutput } from "./tools/index.js";
+export { MCP_VERSION, SERVER_NAME } from "./version.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @process-cart/mcp — the programmatic entry point. Most people run the CLI
+// (`npx -y @process-cart/mcp`); `createServer` builds the same server for a
+// host that brings its own transport.
+export { buildInstructions, createServer, INSTRUCTIONS, problemOf, selectTools, STARTUP_TIMEOUT_MS, } from "./server.js";
+export { TOOLS } from "./tools/index.js";
+export { MCP_VERSION, SERVER_NAME } from "./version.js";

package/dist/render.d.ts

@@ -0,0 +1,139 @@
+import type { ActivityItem, Comment, GetWorkflowSchemaResponse, Group, Me, ProblemFieldError, Run, RunField, User, WorkflowSummary } from "@process-cart/sdk";
+/** Caps that keep one answer readable. */
+export declare const RENDER_LIMITS: {
+    /** Tasks listed in a run before "… and N more tasks". */
+    readonly tasks: 60;
+    /** Fields listed in a run (across its tasks) before "… and N more fields". */
+    readonly fields: 120;
+    /** Fields listed in a workflow schema. */
+    readonly schemaFields: 150;
+    /** Characters of one value, description or comment before it is cut. */
+    readonly value: 300;
+};
+/**
+ * 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 declare function text(value: string, max?: number): string;
+/** Cuts `text` to `max` characters with an ellipsis. */
+export declare function truncate(text: string, max?: number): string;
+/** An ISO instant without its milliseconds (`2026-10-13T01:09:28Z`); a dash for null. */
+export declare function instant(value: string | null | undefined): string;
+/** The "pass this cursor" sentence every paged answer ends with. */
+export declare function pagingLine(nextCursor: string | null | undefined, what: string): string;
+/** A canonical value that counts as blank (what a required field may not be). */
+export declare function isBlankValue(field: Pick<RunField, "type" | "value">): boolean;
+export interface RenderRunOptions {
+    /**
+     * The field keys the run's workflow version marks required, when known
+     * (the server reads them once per version). Null or absent: no flags.
+     */
+    requiredKeys?: ReadonlySet<string> | null;
+    /** A sentence placed under the heading (what the tool just did). */
+    lead?: string;
+}
+/** Task counts over the visible tasks (what "progress" means in the app). */
+export declare function runProgress(run: Pick<Run, "tasks">): {
+    done: number;
+    total: number;
+};
+/** The full run: header, then its tasks grouped by section with each task's fields beneath it. */
+export declare function renderRun(run: Run, options?: RenderRunOptions): string;
+/** A run without its tasks and fields: what find_runs returns per item. */
+export interface RunSummary {
+    id: string;
+    name: string;
+    status: Run["status"];
+    priority: Run["priority"];
+    labels: string[];
+    dueAt: string | null;
+    keyDate: string | null;
+    revision: number;
+    updatedAt: string;
+    startedAt: string;
+    completedAt: string | null;
+    deletedAt: string | null;
+    workflow: Run["workflow"];
+    url: string;
+    progress: {
+        done: number;
+        total: number;
+    };
+    openTasks: {
+        key: string;
+        title: string;
+    }[];
+}
+export declare function summarizeRun(run: Run): RunSummary;
+/** One page of runs, one entry each (get_run shows a run's tasks and fields). */
+export declare function renderRunList(runs: readonly Run[], nextCursor: string | null): string;
+export declare function renderWorkflowList(workflows: readonly WorkflowSummary[], nextCursor: string | null, options?: {
+    query?: string;
+    totalMatches?: number;
+}): string;
+/** One writable field as get_workflow_schema describes it. */
+export interface SchemaFieldSummary {
+    key: string;
+    label: string;
+    type: string;
+    format: string | null;
+    taskKey: string | null;
+    sectionKey: string | null;
+    /** In the run-start (kickoff) form. */
+    kickoff: boolean;
+    /** Must be sent to start_run (a required kickoff field no rule can hide). */
+    requiredAtStart: boolean;
+    /** Required at start unless a visibility rule hides it. */
+    requiredUnlessHidden: boolean;
+    /** Allowed values (dropdown / multi-choice choices, subtask item keys). */
+    choices: string[];
+    /** Bounds and patterns, as short phrases. */
+    constraints: string[];
+    /** The field's help text and value notes, as the schema words them. */
+    notes: string | null;
+}
+/** Reads the API's per-workflow JSON Schemas into one summary per writable field, start fields first. */
+export declare function summarizeSchema(schema: GetWorkflowSchemaResponse): SchemaFieldSummary[];
+export declare function renderSchema(schema: GetWorkflowSchemaResponse): string;
+export declare function renderComment(comment: Comment): string;
+/** The comments get_activity shows: the last ones it read, how many it read, and whether that was all. */
+export interface CommentWindow {
+    /** The newest comments read, oldest first. */
+    shown: readonly Comment[];
+    /** How many comments were read (every one of them when `complete`). */
+    total: number;
+    /** False when the scan stopped at its cap: the run has more comments than `total`. */
+    complete?: boolean;
+}
+export declare function renderActivity(items: readonly ActivityItem[], nextCursor: string | null, comments?: CommentWindow | null): string;
+export declare function renderPeople(users: readonly User[], groups: readonly Group[], options?: {
+    query?: string;
+    truncated?: boolean;
+}): string;
+export interface ServerMode {
+    /** `--read-only` was passed. */
+    readOnlyFlag: boolean;
+    baseUrl: string;
+    /** The tools this server registered, by name. */
+    tools: readonly string[];
+    /** Why startup could not read the key (the tool list then holds read tools only). */
+    startupProblem: string | null;
+}
+export declare function renderMe(me: Me, mode: ServerMode): string;
+/** The fields of a failure the renderer reads (a `ProcessCartError`, or any error mapped to this shape). */
+export interface ProblemView {
+    status: number;
+    code: string;
+    title: string;
+    detail?: string;
+    requestId: string | null;
+    errors?: readonly ProblemFieldError[];
+    retryAfter?: number;
+    currentRevision?: number;
+}
+/** The error as a model reads it: what failed, every field problem, and what to do next. */
+export declare function renderProblem(problem: ProblemView): string;