@ketch.to/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @ketch.to/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [Ketch](https://ketch.to), the one place your agents ask you things. It lets any MCP client (Claude Code, Claude Desktop, Cursor, scripts) put a card in your Ketch queue and read your answer back.
+
+## Install
+
+Claude Code:
+
+```sh
+claude mcp add ketch -e KETCH_API_KEY=ketch_sk_… -- npx -y @ketch.to/mcp
+```
+
+Claude Desktop, Cursor and other clients (`mcpServers` config):
+
+```json
+{ "mcpServers": { "ketch": { "command": "npx", "args": ["-y", "@ketch.to/mcp"], "env": { "KETCH_API_KEY": "ketch_sk_…" } } } }
+```
+
+Streamable HTTP instead of stdio:
+
+```sh
+KETCH_API_KEY=ketch_sk_… npx -y @ketch.to/mcp --http 3333     # http://127.0.0.1:3333/mcp
+```
+
+Create the API key in the Ketch app under Settings. `KETCH_API_URL` overrides the API base (default `https://api.ketch.to/v1`).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `create_card` | Ask the person something. One card, one answer. |
+| `list_cards` | List open, snoozed or done cards, so you don't ask twice. |
+| `get_outcome` | The answer to one card, if there is one yet. |
+| `list_outcomes_since` | Every answer since a timestamp. Treat `not_good` as "don't send me this kind again". |

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare const DEFAULT_API_URL = "https://api.ketch.to/v1";
+export declare function main(argv?: string[], env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/src/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * ketch-mcp — MCP server for Ketch.
+ *
+ *   KETCH_API_KEY=ketch_sk_… npx @ketch.to/mcp            # stdio (Claude Desktop, Claude Code, Cursor…)
+ *   KETCH_API_KEY=ketch_sk_… npx @ketch.to/mcp --http 3333 # streamable HTTP on http://127.0.0.1:3333/mcp
+ *
+ * Env: KETCH_API_KEY (required), KETCH_API_URL (default https://api.ketch.to/v1).
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:http";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { KetchClient } from "./client.js";
+import { createKetchMcpServer } from "./server.js";
+export const DEFAULT_API_URL = "https://api.ketch.to/v1";
+function usage(msg) {
+    if (msg)
+        console.error(msg);
+    console.error("usage: KETCH_API_KEY=ketch_sk_… ketch-mcp [--http [port]] [--api-url URL]");
+    process.exit(2);
+}
+export async function main(argv = process.argv.slice(2), env = process.env) {
+    let http = null;
+    let apiUrl = env.KETCH_API_URL ?? DEFAULT_API_URL;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--http") {
+            const next = argv[i + 1];
+            if (next && /^\d+$/.test(next)) {
+                http = Number(next);
+                i++;
+            }
+            else
+                http = 3333;
+        }
+        else if (a === "--api-url") {
+            apiUrl = argv[++i] ?? usage("--api-url needs a value");
+        }
+        else if (a === "-h" || a === "--help")
+            usage();
+        else
+            usage(`unknown argument: ${a}`);
+    }
+    const apiKey = env.KETCH_API_KEY;
+    if (!apiKey)
+        usage("KETCH_API_KEY is required (create one in the app's Settings, or POST /keys)");
+    const client = new KetchClient({ baseUrl: apiUrl, apiKey });
+    if (http === null) {
+        const server = createKetchMcpServer(client);
+        await server.connect(new StdioServerTransport());
+        return;
+    }
+    // Stateless streamable HTTP: one server+transport per request, nothing to clean up.
+    const httpServer = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (url.pathname !== "/mcp") {
+            res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "POST /mcp" }));
+            return;
+        }
+        const server = createKetchMcpServer(client);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            transport.close();
+            server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        catch (err) {
+            console.error(err);
+            if (!res.headersSent)
+                res.writeHead(500).end();
+        }
+    });
+    await new Promise((r) => httpServer.listen(http, "127.0.0.1", r));
+    console.error(`ketch-mcp: streamable HTTP on http://127.0.0.1:${http}/mcp → ${apiUrl}`);
+}
+// npx and global installs run this file through a symlink named after the bin, so compare real paths.
+function isEntryPoint() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+const invokedDirectly = isEntryPoint();
+if (invokedDirectly) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/src/client.d.ts

@@ -0,0 +1,38 @@
+import type { Card, NewCard, Outcome } from "@ketch.to/schema";
+export interface ClientOptions {
+    /** e.g. https://api.ketch.to/v1 or http://127.0.0.1:8787/v1 */
+    baseUrl: string;
+    apiKey: string;
+    fetch?: typeof fetch;
+}
+export declare class KetchApiError extends Error {
+    status: number;
+    code: string;
+    details?: unknown | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined);
+}
+export interface OutcomeItem {
+    card: Card;
+    outcome: Outcome;
+}
+/** Thin, typed client over the v1 API. Producers only need these calls. */
+export declare class KetchClient {
+    private baseUrl;
+    private apiKey;
+    private fetchImpl;
+    constructor(opts: ClientOptions);
+    private call;
+    createCard(card: NewCard, idempotencyKey?: string): Promise<Card>;
+    listCards(opts?: {
+        status?: "open" | "snoozed" | "done" | "all";
+        since?: string;
+        limit?: number;
+    }): Promise<Card[]>;
+    getCard(id: string): Promise<Card>;
+    getOutcome(id: string): Promise<Outcome | null>;
+    listOutcomes(opts?: {
+        since?: string;
+        action?: string;
+        limit?: number;
+    }): Promise<OutcomeItem[]>;
+}

package/dist/src/client.js

@@ -0,0 +1,67 @@
+export class KetchApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Thin, typed client over the v1 API. Producers only need these calls. */
+export class KetchClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    async call(method, path, body, headers = {}) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: { authorization: `Bearer ${this.apiKey}`, ...(body !== undefined ? { "content-type": "application/json" } : {}), ...headers },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        const json = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            const e = json?.error ?? {};
+            throw new KetchApiError(res.status, e.code ?? "http_error", e.message ?? `HTTP ${res.status}`, e.details);
+        }
+        return json;
+    }
+    createCard(card, idempotencyKey) {
+        return this.call("POST", "/cards", card, idempotencyKey ? { "idempotency-key": idempotencyKey } : {});
+    }
+    async listCards(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.status)
+            q.set("status", opts.status);
+        if (opts.since)
+            q.set("since", opts.since);
+        if (opts.limit)
+            q.set("limit", String(opts.limit));
+        const s = q.toString();
+        return (await this.call("GET", `/cards${s ? `?${s}` : ""}`)).cards;
+    }
+    getCard(id) {
+        return this.call("GET", `/cards/${encodeURIComponent(id)}`);
+    }
+    async getOutcome(id) {
+        return (await this.call("GET", `/cards/${encodeURIComponent(id)}/outcome`)).outcome;
+    }
+    async listOutcomes(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.since)
+            q.set("since", opts.since);
+        if (opts.action)
+            q.set("action", opts.action);
+        if (opts.limit)
+            q.set("limit", String(opts.limit));
+        const s = q.toString();
+        return (await this.call("GET", `/outcomes${s ? `?${s}` : ""}`)).outcomes;
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { KetchClient, KetchApiError, type ClientOptions, type OutcomeItem } from "./client.js";
+export { createKetchMcpServer, NewCardShape, SERVER_NAME, SERVER_VERSION } from "./server.js";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { KetchClient, KetchApiError } from "./client.js";
+export { createKetchMcpServer, NewCardShape, SERVER_NAME, SERVER_VERSION } from "./server.js";

package/dist/src/server.d.ts

@@ -0,0 +1,64 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { type KetchClient } from "./client.js";
+export declare const SERVER_NAME = "ketch";
+export declare const SERVER_VERSION = "0.1.0";
+export declare const NewCardShape: {
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        app: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        app?: string | undefined;
+        context?: string | undefined;
+    }, {
+        app?: string | undefined;
+        context?: string | undefined;
+    }>>;
+    link: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodOptional<z.ZodEnum<[string, ...string[]]>>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        style: z.ZodOptional<z.ZodEnum<["positive", "snooze", "neutral"]>>;
+        input: z.ZodOptional<z.ZodEnum<["optional", "required"]>>;
+        snooze_for: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        label: string;
+        style?: "positive" | "snooze" | "neutral" | undefined;
+        input?: "optional" | "required" | undefined;
+        snooze_for?: string | undefined;
+    }, {
+        id: string;
+        label: string;
+        style?: "positive" | "snooze" | "neutral" | undefined;
+        input?: "optional" | "required" | undefined;
+        snooze_for?: string | undefined;
+    }>, "many">>;
+    input: z.ZodOptional<z.ZodObject<{
+        placeholder: z.ZodOptional<z.ZodString>;
+        spawns: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        placeholder?: string | undefined;
+        spawns?: boolean | undefined;
+    }, {
+        placeholder?: string | undefined;
+        spawns?: boolean | undefined;
+    }>>;
+    recurrence: z.ZodOptional<z.ZodObject<{
+        every: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        every: string;
+    }, {
+        every: string;
+    }>>;
+    show_after: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+};
+/** The four tools from CLAUDE.md. Everything else a producer might want goes through the HTTP API. */
+export declare function createKetchMcpServer(client: KetchClient): McpServer;

package/dist/src/server.js

@@ -0,0 +1,130 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DURATION_RE, KINDS, KIND_PRESETS, validateNewCard } from "@ketch.to/schema";
+import { z } from "zod";
+import { KetchApiError } from "./client.js";
+export const SERVER_NAME = "ketch";
+export const SERVER_VERSION = "0.1.0";
+const Duration = z.string().regex(DURATION_RE, "duration like 1h, 3d, 14d, 2w");
+const ActionShape = z.object({
+    id: z.string().regex(/^[a-z][a-z0-9_]{0,31}$/).describe("Echoed back as outcome.action. 'snooze' and 'not_good' are reserved and always available."),
+    label: z.string().min(1).max(24).describe("Button text."),
+    style: z.enum(["positive", "snooze", "neutral"]).optional().describe("positive = swipe-right target; snooze = tap 1h / hold for days; neutral (default) = plain button."),
+    input: z.enum(["optional", "required"]).optional().describe("Open a text sheet before posting this action."),
+    snooze_for: Duration.optional().describe("Only with style 'snooze': default snooze on tap (default 1h)."),
+});
+const presetHelp = KINDS.map((k) => `${k}: ${KIND_PRESETS[k].actions.map((a) => a.label).join(" / ")}`).join("; ");
+export const NewCardShape = {
+    title: z.string().min(1).max(140).describe("What you're asking. Short, specific, one line."),
+    body: z.string().max(4000).optional().describe("Context the person needs to answer without opening anything. Plain text or light markdown."),
+    source: z
+        .object({
+        app: z.string().min(1).max(40).optional().describe("Defaults to this API key's name."),
+        context: z.string().min(1).max(120).optional().describe("Where this came from, e.g. the thread, meeting or project name."),
+    })
+        .optional(),
+    link: z.string().regex(/^(https:\/\/|shortcuts:\/\/)\S+$/).optional().describe("https:// or shortcuts:// link opened from the card."),
+    priority: z.number().int().min(1).max(5).optional().describe("1 urgent … 5 ambient. Default 3. 1–2 push a notification; use sparingly."),
+    kind: z.enum(KINDS).optional().describe(`Preset that fills in default actions. ${presetHelp}. Default do.`),
+    actions: z.array(ActionShape).min(1).max(4).optional().describe("Override the preset's buttons (1–4, in order)."),
+    input: z
+        .object({
+        placeholder: z.string().max(80).optional(),
+        spawns: z.boolean().optional().describe("Each entry the person types becomes a new card."),
+    })
+        .optional()
+        .describe("Optional free-text field on the card."),
+    recurrence: z.object({ every: Duration }).optional().describe("Re-show after an action instead of retiring (checkin cards default to 14d)."),
+    show_after: z.string().datetime({ offset: true }).optional().describe("Hide until this ISO 8601 time."),
+    expires_at: z.string().datetime({ offset: true }).optional().describe("Retire automatically at this ISO 8601 time if unanswered."),
+    meta: z.record(z.unknown()).optional().describe("Your own bag (ids, rule names). Echoed back untouched in outcomes and webhooks."),
+    idempotency_key: z.string().min(1).max(255).optional().describe("Send the same key on retries to avoid duplicate cards. Strongly recommended, e.g. '<rule>-<thread id>'."),
+};
+const summarizeCard = (c) => {
+    const src = c.source.context ? `${c.source.app} · ${c.source.context}` : c.source.app;
+    const extra = c.status === "snoozed" && c.show_after ? ` until ${c.show_after}` : c.outcome ? ` → ${c.outcome.action}${c.outcome.text ? `: ${c.outcome.text}` : ""}` : "";
+    return `${c.id}  [${c.status}${extra}]  p${c.priority} ${c.kind}  "${c.title}"  (${src})`;
+};
+const summarizeOutcome = (o) => `${o.action}${o.text ? ` — "${o.text}"` : ""}${o.snoozed_until ? ` (until ${o.snoozed_until})` : ""} at ${o.at}`;
+function errorResult(err) {
+    if (err instanceof KetchApiError) {
+        const details = err.details ? `\n${JSON.stringify(err.details, null, 2)}` : "";
+        return { isError: true, content: [{ type: "text", text: `${err.code} (${err.status}): ${err.message}${details}` }] };
+    }
+    return { isError: true, content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }] };
+}
+/** The four tools from CLAUDE.md. Everything else a producer might want goes through the HTTP API. */
+export function createKetchMcpServer(client) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    server.registerTool("create_card", {
+        title: "Create a card",
+        description: "Ask the person something. Creates one card in their Ketch queue; they answer with one tap and the outcome comes back via get_outcome / list_outcomes_since. " +
+            "Use a kind preset instead of custom actions whenever one fits. Keep titles short and bodies self-contained. " +
+            "Always pass idempotency_key when you might retry.",
+        inputSchema: NewCardShape,
+    }, async ({ idempotency_key, ...input }) => {
+        const v = validateNewCard(input);
+        if (!v.ok)
+            return { isError: true, content: [{ type: "text", text: `Invalid card:\n${v.errors.map((e) => `- ${e.path || "/"}: ${e.message}`).join("\n")}` }] };
+        try {
+            const card = await client.createCard(v.value, idempotency_key);
+            return { content: [{ type: "text", text: `Created ${summarizeCard(card)}` }], structuredContent: { card } };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("list_cards", {
+        title: "List cards",
+        description: "List the person's cards. Default: what's in the queue now (status open). Use status=done to see what they've answered, snoozed for deferred ones, all for everything. " +
+            "Use since (ISO 8601) to see only cards updated after a time, e.g. to avoid creating duplicates.",
+        inputSchema: {
+            status: z.enum(["open", "snoozed", "done", "all"]).optional(),
+            since: z.string().datetime({ offset: true }).optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+    }, async (args) => {
+        try {
+            const cards = await client.listCards(args);
+            const text = cards.length ? cards.map(summarizeCard).join("\n") : `No ${args.status ?? "open"} cards.`;
+            return { content: [{ type: "text", text }], structuredContent: { cards } };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("get_outcome", {
+        title: "Get a card's outcome",
+        description: "What the person did with a card: the action id, any text they typed, when, and the snoozed-until time if they snoozed. Null if they haven't answered yet.",
+        inputSchema: { card_id: z.string().regex(/^card_[0-9A-HJKMNP-TV-Z]{26}$/) },
+    }, async ({ card_id }) => {
+        try {
+            const outcome = await client.getOutcome(card_id);
+            return { content: [{ type: "text", text: outcome ? summarizeOutcome(outcome) : "No outcome yet." }], structuredContent: { outcome } };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("list_outcomes_since", {
+        title: "List outcomes since a time",
+        description: "Every answer the person gave since a time, oldest first, each with its card (including your meta). This is your feedback loop: " +
+            "action=not_good lists the cards they said 'not a good one' to — stop sending those. Store the last `at` you processed and pass it as since next time.",
+        inputSchema: {
+            since: z.string().datetime({ offset: true }).describe("ISO 8601. Outcomes at or after this time."),
+            action: z.string().optional().describe("Only this action id, e.g. not_good."),
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+    }, async (args) => {
+        try {
+            const outcomes = await client.listOutcomes(args);
+            const text = outcomes.length
+                ? outcomes.map(({ card, outcome }) => `${card.id}  "${card.title}"  (${card.source.app}${card.source.context ? ` · ${card.source.context}` : ""})\n    ${summarizeOutcome(outcome)}${Object.keys(card.meta ?? {}).length ? `\n    meta: ${JSON.stringify(card.meta)}` : ""}`).join("\n")
+                : "No outcomes since then.";
+            return { content: [{ type: "text", text }], structuredContent: { outcomes } };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@ketch.to/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Ketch — the one place your agents ask you things",
+  "type": "module",
+  "bin": {
+    "ketch-mcp": "./dist/src/cli.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "start": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@ketch.to/schema": "0.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@ketch.to/api": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://ketch.to",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ketch",
+    "agents"
+  ]
+}