copapers-mcp 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# copapers-mcp
+
+MCP server for [Copapers](https://copapers.com) — let your agents edit your Copapers
+documents. An AI agent (Claude Code, Claude Desktop, Codex, …) can list, pull, edit, and push
+**tracked suggestions**, attributed to your signed-in Copapers account.
+
+It runs locally over stdio and talks to a Copapers server over HTTPS. You authenticate once
+with the built-in `connect` tool — no API keys to manage.
+
+## Install
+
+### Claude Code
+
+```sh
+claude mcp add copapers -s user -- npx -y copapers-mcp --server https://copapers.com
+```
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.copapers]
+command = "npx"
+args = ["-y", "copapers-mcp", "--server", "https://copapers.com"]
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "copapers": {
+      "command": "npx",
+      "args": ["-y", "copapers-mcp", "--server", "https://copapers.com"]
+    }
+  }
+}
+```
+
+## Sign in
+
+After the server is added, in your agent call the **`connect`** tool:
+
+1. It returns a URL (`https://copapers.com/?connect=<code>`) and a short code.
+2. Open the URL in the browser where you're **already signed in** to Copapers and approve.
+3. Call `connect` again to finish. The credential is saved to `~/.copapers/credentials.json`
+   (mode 0600) and refreshed automatically. One `connect` authenticates every agent on the
+   machine. `disconnect` signs out.
+
+If any tool returns `not_authenticated`, just call `connect` and retry.
+
+## Tools
+
+`list_documents`, `list_checkouts`, `pull_document`, `push_document`, `resolve_suggestion`,
+`resolve_comment`, `connect`, `disconnect`.
+
+The workflow is: `list_documents` → `pull_document` (writes the doc to a local Markdown file)
+→ edit that file with normal tools → `push_document` (the server diffs your edits and records
+them as tracked suggestions). Never hand-write CriticMarkup; existing `{++ ++}` / `{-- --}`
+spans in the pulled file are read-only.
+
+## Options
+
+| Flag / env | Default | Purpose |
+| --- | --- | --- |
+| `--server <url>` / `COPAPERS_SERVER_URL` | `http://127.0.0.1:3077` | Copapers server to talk to |
+| `--state-dir <dir>` / `COPAPERS_MCP_STATE_DIR` | `.copapers-mcp` | local checkout state |
+| `COPAPERS_CONFIG_DIR` | `~/.copapers` | credential dir (set per-agent for a distinct identity) |
+| `COPAPERS_ACCESS_TOKEN` | — | bearer-token override (CI); otherwise the stored credential is used |

package/dist/cli.js

@@ -0,0 +1,665 @@
+#!/usr/bin/env node
+
+// ../../src/mcp/copapers-mcp.js
+import { createHash } from "node:crypto";
+import { mkdir as mkdir2, readFile as readFile2, readdir, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ../../src/cli/credentials.js
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var EXPIRY_SKEW_MS = 3e4;
+var NotAuthenticatedError = class extends Error {
+  constructor(message = "Not authenticated. Run the `connect` tool (or set COPAPERS_ACCESS_TOKEN) to sign in.") {
+    super(message);
+    this.name = "NotAuthenticatedError";
+    this.code = "not_authenticated";
+  }
+};
+function credentialsDir(env = process.env) {
+  return env.COPAPERS_CONFIG_DIR || join(homedir(), ".copapers");
+}
+function credentialsPath(env = process.env) {
+  return join(credentialsDir(env), "credentials.json");
+}
+async function loadCredentials(env = process.env) {
+  try {
+    return JSON.parse(await readFile(credentialsPath(env), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function saveCredentials(credentials, env = process.env) {
+  const path = credentialsPath(env);
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(path, `${JSON.stringify(credentials, null, 2)}
+`, { mode: 384 });
+  await chmod(path, 384).catch(() => {
+  });
+}
+async function clearCredentials(env = process.env) {
+  await rm(credentialsPath(env), { force: true });
+}
+async function resolveBearerToken({ env = process.env, fetchImpl = fetch, now = Date.now } = {}) {
+  if (env.COPAPERS_ACCESS_TOKEN) return env.COPAPERS_ACCESS_TOKEN;
+  const credentials = await loadCredentials(env);
+  if (!credentials) return null;
+  const valid = credentials.accessToken && credentials.expiresAt && credentials.expiresAt - EXPIRY_SKEW_MS > now();
+  if (valid) return credentials.accessToken;
+  if (credentials.refreshToken && credentials.supabaseUrl) {
+    const session = await refreshSession({ ...credentials, fetchImpl });
+    const next = {
+      ...credentials,
+      accessToken: session.access_token,
+      refreshToken: session.refresh_token ?? credentials.refreshToken,
+      expiresAt: expiresAtMs(session, now)
+    };
+    await saveCredentials(next, env);
+    return next.accessToken;
+  }
+  return credentials.accessToken ?? null;
+}
+function notAuthenticatedFrom(status, body) {
+  if (status !== 401) return null;
+  const detail = body?.error?.message ? `${body.error.message} ` : "";
+  return new NotAuthenticatedError(`${detail}Run the \`connect\` tool (or set COPAPERS_ACCESS_TOKEN) to authenticate.`);
+}
+async function refreshSession({ supabaseUrl, anonKey, refreshToken, fetchImpl = fetch }) {
+  const response = await fetchImpl(`${stripTrailingSlash(supabaseUrl)}/auth/v1/token?grant_type=refresh_token`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...anonKey ? { apikey: anonKey, authorization: `Bearer ${anonKey}` } : {} },
+    body: JSON.stringify({ refresh_token: refreshToken })
+  });
+  if (!response.ok) {
+    throw new NotAuthenticatedError("Your session has expired. Run the `connect` tool to sign in again.");
+  }
+  return response.json();
+}
+function expiresAtMs(session, now) {
+  if (session.expires_at) return session.expires_at * 1e3;
+  if (session.expires_in) return now() + session.expires_in * 1e3;
+  return now() + 36e5;
+}
+function stripTrailingSlash(value) {
+  return String(value ?? "").replace(/\/+$/, "");
+}
+
+// ../../src/mcp/copapers-mcp.js
+var DEFAULT_COPAPERS_SERVER_URL = "http://127.0.0.1:3077";
+var DEFAULT_COPAPERS_MCP_STATE_DIR = ".copapers-mcp";
+var COPAPERS_MCP_CHECKOUT_STATE_KIND = "copapers.mcp-checkout-state.v1";
+function createCopapersMcpTools(options2 = {}) {
+  const config = normalizeConfig(options2);
+  const connectState = { grant: null };
+  return {
+    listDocuments: (args) => listDocuments({ ...config, ...args ?? {} }),
+    listCheckouts: (args) => listCheckouts({ ...config, ...args ?? {} }),
+    pullDocument: (args) => pullDocument({ ...config, ...args ?? {} }),
+    pushDocument: (args) => pushDocument({ ...config, ...args ?? {} }),
+    resolveSuggestion: (args) => resolveSuggestion({ ...config, ...args ?? {} }),
+    resolveComment: (args) => resolveComment({ ...config, ...args ?? {} }),
+    connect: () => connectAgent({ ...config, connectState }),
+    disconnect: () => disconnectAgent(config)
+  };
+}
+function createCopapersMcpServer(options2 = {}) {
+  const server = new McpServer(
+    { name: "copapers", version: "0.1.0" },
+    {
+      instructions: [
+        "Use this Copapers server for Copapers documents and app doc ids such as report_123 or fixture-doc. Do not use Google Docs/Drive for these ids unless the user explicitly says Google.",
+        "A Copapers document link looks like https://<host>/d/<docId> \u2014 the id is the last path segment. If the user pastes such a link, pass it straight to pull_document (it extracts the id); you do NOT need list_documents first.",
+        "Authentication: these tools call a Copapers server with your stored credential. If a tool returns a not_authenticated error, call the `connect` tool \u2014 it returns a URL and a short code for the user to open and approve in their browser (where they are already signed in); relay those to the user, then call `connect` again to finish and retry the original tool. One connect authenticates every Copapers session on this machine (no per-project sign-in); `disconnect` signs out. Your changes are attributed to your signed-in account and this tool \u2014 you never pass an actor or author name.",
+        "Workflow: list_documents -> pull_document -> edit the returned documentPath file with your normal file tools -> push_document. These tools only manage checkout state; the document text lives in documentPath. Edit only that file; never edit the checkout state (.json) files.",
+        'Edit the file as an ordinary Markdown document. To change the DOCUMENT, do NOT write suggestion CriticMarkup yourself \u2014 never type {++ ++}, {-- --}, {~~ ~> ~~}, or {^^ ^^}. Just insert, delete, and rewrite text normally; on push the server diffs your edits against the document. Depending on your permission on the doc those edits either apply DIRECTLY (a clean edit) or are recorded as tracked SUGGESTIONS for you \u2014 pull_document reports which under agentAuthority.mode ("direct" or "suggest"), and the push result confirms it as appliedMode. Either way you never hand-write suggestion syntax; that corrupts the diff. To deliberately record a suggestion even when you are allowed to edit directly, pass suggesting:true to push_document.',
+        "Resolving existing suggestions is an EXPLICIT action: use resolve_suggestion to accept or reject a pending change \u2014 target one by its changeId (from pull_document's pendingSuggestions list), or every change by an actor, or all. Whether you may accept depends on your role (pull_document's agentAuthority): editors/owners accept or reject anyone's; a suggest-only agent may only reject its OWN. Editing the text near a suggestion never silently accepts or rejects it \u2014 only resolve_suggestion does.",
+        "COMMENTS use the ONE kind of CriticMarkup you may type. To leave a comment, add a NEW span {>> your comment <<} where it applies. To reply to an existing thread, add a NEW span {>> reply c_ID: your reply <<} where c_ID is the bare thread id shown in that comment block (e.g. {>> reply c_7gk2: agreed, trimmed <<}) \u2014 write the id exactly as shown, with NO surrounding < > brackets. To RESOLVE a thread, use the resolve_comment tool with its thread id \u2014 whether you may resolve depends on your role (pull_document's agentAuthority): editors/owners resolve anyone's thread, a suggest-only agent only threads it authored. You CANNOT reopen or delete a comment (a person does that in the editor). Never edit, move, or retype an existing {>> <<} block \u2014 like every other span it is read-only; only ADD new ones.",
+        'Existing spans are already rendered inline in the file as CriticMarkup: suggestions {++inserted++}, {--deleted--}, {~~old~>new~~}, {^^formatted^^}, and comment threads {>>\\ncomment c_\u2026 (open) \u2014 re: "\u2026"\\n@Name: \u2026\\n<<}. They are obvious on a normal read \u2014 do not grep for them or compute character offsets. Every existing span is READ-ONLY: never edit, delete, reorder, or retype one \u2014 changing even one character of any span makes the WHOLE push fail (it is rejected, nothing is applied). Make all your edits in the plain text around the spans (and add new {>> <<} comments anywhere); if the text you need to change sits inside a span, re-pull and edit elsewhere.',
+        "Supported content: headings, paragraphs, bold/italic/inline-code/links, bullet/numbered/task lists, blockquotes, fenced code blocks, GFM tables, horizontal rules, and images. NOT supported: raw HTML and HTML comments, merged table cells (colspan/rowspan), and nested tables \u2014 express those with the supported elements instead. A push containing unsupported Markdown is rejected with an unsupported_markdown error.",
+        "Review granularity for a pending change to a code block, table, or horizontal rule is WHOLE-BLOCK: it appears as ONE multi-line, line-anchored CriticMarkup span \u2014 {++\\n\u2026\\n++}, {--\\n\u2026\\n--}, or {~~\\n old \\n~>\\n new \\n~~} with each delimiter alone on its own line. Treat the whole span as one read-only unit (the same rule as inline spans): never edit inside it; edit the text around it or re-pull. The block content between the delimiters may contain ```, |, ~>, etc. \u2014 that is the literal code/table, not structure."
+      ].join("\n")
+    }
+  );
+  const tools = createCopapersMcpTools({
+    ...options2,
+    getClientName: () => server.server?.getClientVersion?.()?.name
+  });
+  server.registerTool(
+    "list_documents",
+    {
+      title: "Copapers: List Documents",
+      description: "List Copapers app documents. Use first when the user asks for a Copapers doc, a report doc, or a doc id like report_123/fixture-doc; this is not Google Docs.",
+      inputSchema: z.object({
+        query: z.string().optional().describe("Optional case-insensitive Copapers document id or title filter, e.g. report_123.")
+      }),
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    (args) => toMcpResult(() => tools.listDocuments(args))
+  );
+  server.registerTool(
+    "list_checkouts",
+    {
+      title: "Copapers: List Checkouts",
+      description: "List local Copapers MCP checkouts created by pull_document.",
+      inputSchema: z.object({
+        doc_id: z.string().min(1).optional().describe("Optional filter for a Copapers document id.")
+      }),
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    (args) => toMcpResult(() => tools.listCheckouts(args))
+  );
+  server.registerTool(
+    "pull_document",
+    {
+      title: "Copapers: Pull Document",
+      description: "Pull a Copapers document by doc_id into a local Markdown checkout and return documentPath for file editing. The file is the full document with any existing pending suggestions shown inline as CriticMarkup context; edit it as plain Markdown (do not write CriticMarkup yourself). The result reports agentAuthority (whether your pushes apply directly or as suggestions, and whether you may resolve others' suggestions) and a pendingSuggestions list (changeId + author + preview) you can target with resolve_suggestion.",
+      inputSchema: z.object({
+        doc_id: z.string().min(1).describe("Copapers document id (e.g. report_123 or fixture-doc), or a pasted document URL like https://host/d/<docId> \u2014 the id is extracted from it."),
+        actor: z.string().min(1).optional().describe("Deprecated/ignored: identity comes from your signed-in credential, not this hint.")
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    (args) => toMcpResult(() => tools.pullDocument(args))
+  );
+  server.registerTool(
+    "push_document",
+    {
+      title: "Copapers: Push Document",
+      description: "Push the edited checkout file. Your changes are diffed against the document and applied as a DIRECT edit or recorded as tracked SUGGESTIONS depending on your permission (pull_document's agentAuthority.mode tells you in advance; the result's appliedMode confirms what happened, and downgraded:true means a direct edit fell back to a suggestion for lack of edit access). Pass suggesting:true to force a tracked suggestion even when you could edit directly. You never write suggestion CriticMarkup yourself, but you MAY add new {>> comment <<} spans (and {>> reply c_ID: \u2026 <<} replies, using the bare thread id with no < > brackets) \u2014 those are recorded as comments. The whole push is rejected if you changed any EXISTING span (leave every {.. ..} and {>> <<} span exactly as-is) or used unsupported Markdown (raw HTML, HTML comments, merged table cells, or nested tables).",
+      inputSchema: z.object({
+        checkout_id: z.string().min(1).describe("Checkout id returned by pull_document."),
+        summary: z.string().optional().describe("Short summary of the change you are pushing."),
+        suggesting: z.boolean().optional().describe("Force this push to land as a tracked suggestion instead of a direct edit. Default: a direct edit when you have edit access, otherwise a suggestion."),
+        doc_id: z.string().min(1).optional().describe("Optional safety check; must match the checkout document id.")
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    (args) => toMcpResult(() => tools.pushDocument(args))
+  );
+  server.registerTool(
+    "resolve_suggestion",
+    {
+      title: "Copapers: Resolve Suggestion",
+      description: "Accept or reject EXISTING pending suggestions on a Copapers document. Target one change by its changeId (from pull_document's pendingSuggestions), every change by an actor, or all of them. Accepting requires editor/owner authority; a suggest-only agent may only reject its own suggestions. This is the only way to resolve a suggestion \u2014 editing the text never does.",
+      inputSchema: z.object({
+        doc_id: z.string().min(1).describe("Copapers document id whose suggestion(s) to resolve."),
+        action: z.enum(["accept", "reject"]).describe("accept = apply the change into the clean document; reject = discard it."),
+        change_id: z.string().min(1).optional().describe("Resolve a single change by its changeId (from pull_document pendingSuggestions)."),
+        actor: z.string().min(1).optional().describe("Resolve every pending change authored by this actorId."),
+        all: z.boolean().optional().describe("Resolve ALL pending suggestions on the document. Requires editor/owner authority.")
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    (args) => toMcpResult(() => tools.resolveSuggestion(args))
+  );
+  server.registerTool(
+    "resolve_comment",
+    {
+      title: "Copapers: Resolve Comment",
+      description: "Mark a comment THREAD resolved (done) by its c_\u2026 id, shown in the {>> <<} comment block on pull_document. Resolve-only: you cannot reopen or delete a comment (a person does that in the editor). Resolving anyone's thread requires editor/owner authority; a suggest-only agent may resolve only threads it authored (pull_document's agentAuthority.canReview / reviewOwnOnly tell you).",
+      inputSchema: z.object({
+        doc_id: z.string().min(1).describe("Copapers document id (e.g. report_123), or a pasted document URL \u2014 the id is extracted from it."),
+        thread_id: z.string().min(1).describe("The comment thread id (c_\u2026 ) shown in the comment block on pull.")
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    (args) => toMcpResult(() => tools.resolveComment(args))
+  );
+  server.registerTool(
+    "connect",
+    {
+      title: "Copapers: Connect (sign in)",
+      description: "Authenticate this machine with Copapers \u2014 run this when a tool returns not_authenticated, or when the user asks to sign in/connect. It returns a URL and a short code; the user opens the URL in the browser where they are signed in to Copapers and approves. Relay the URL + code to the user, then call connect again to finish. One connect authenticates every Copapers MCP/CLI session on this machine \u2014 no per-project sign-in.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    () => toMcpResult(() => tools.connect())
+  );
+  server.registerTool(
+    "disconnect",
+    {
+      title: "Copapers: Disconnect (sign out)",
+      description: "Remove this machine's stored Copapers credential. This signs out every Copapers MCP/CLI session on this machine; run connect to sign back in.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    () => toMcpResult(() => tools.disconnect())
+  );
+  return server;
+}
+async function runCopapersMcpServer(options2 = {}) {
+  const server = createCopapersMcpServer(options2);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+async function listDocuments({ serverUrl, query, resolveToken }) {
+  const response = await fetchJson(new URL("/documents", serverUrl), { token: await resolveToken?.() });
+  const normalizedQuery = query?.trim().toLowerCase();
+  const documents = normalizedQuery ? response.documents.filter((document) => document.docId.toLowerCase().includes(normalizedQuery) || (document.title ?? "").toLowerCase().includes(normalizedQuery)) : response.documents;
+  return {
+    kind: "copapers.mcp.document-list",
+    serverUrl,
+    query: query ?? null,
+    count: documents.length,
+    documents
+  };
+}
+async function listCheckouts({ stateDir, doc_id: docId }) {
+  const checkoutsDir = join2(stateDir, "checkouts");
+  let names;
+  try {
+    names = await readdir(checkoutsDir);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    names = [];
+  }
+  const checkouts = [];
+  for (const checkoutId of names.sort()) {
+    if (!isSafeCheckoutId(checkoutId)) continue;
+    const state = await readCheckoutState({ stateDir, checkoutId });
+    if (docId && state.docId !== docId) continue;
+    checkouts.push({
+      ...summarizeCheckoutState(state),
+      local: await inspectCheckoutLocalState(state)
+    });
+  }
+  return {
+    kind: "copapers.mcp.checkout-list",
+    count: checkouts.length,
+    checkouts
+  };
+}
+async function pullDocument({ serverUrl, stateDir, defaultActor, resolveToken, doc_id: rawDocId, actor }) {
+  const docId = extractDocId(rawDocId);
+  const checkout = await fetchJson(checkoutUrl(serverUrl, docId, actor ?? defaultActor), { token: await resolveToken?.() });
+  const paths = checkoutPaths(stateDir, checkout.manifest.checkoutId);
+  const state = {
+    kind: COPAPERS_MCP_CHECKOUT_STATE_KIND,
+    serverUrl,
+    savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    docId: checkout.docId,
+    title: checkout.title,
+    version: checkout.version,
+    checkoutId: checkout.manifest.checkoutId,
+    checkoutDir: paths.checkoutDir,
+    documentPath: paths.documentPath,
+    originalPath: paths.originalPath,
+    originalMarkdown: checkout.markdown,
+    manifest: checkout.manifest
+  };
+  await writeCheckoutFiles({ stateDir, state, markdown: checkout.markdown });
+  return {
+    kind: "copapers.mcp.checkout",
+    ...summarizeCheckoutState(state),
+    // What this agent may do on the doc, and the addressable pending changes it can resolve.
+    agentAuthority: checkout.agentAuthority ?? null,
+    pendingSuggestions: checkout.pendingSuggestions ?? []
+  };
+}
+async function pushDocument({ serverUrl, stateDir, defaultActor, getClientName, resolveToken, checkout_id: checkoutId, summary = "", doc_id: rawDocId, suggesting }) {
+  const state = await readCheckoutState({ stateDir, checkoutId });
+  const editedMarkdown = await readFile2(state.documentPath, "utf8");
+  const docId = rawDocId ? extractDocId(rawDocId) : rawDocId;
+  if (docId && docId !== state.docId) {
+    throw new Error(`Checkout ${checkoutId} belongs to ${state.docId}, not ${docId}.`);
+  }
+  const result = await fetchJson(pushUrl(state.serverUrl ?? serverUrl, state.docId), {
+    method: "POST",
+    token: await resolveToken?.(),
+    body: JSON.stringify({
+      manifest: state.manifest,
+      originalMarkdown: state.originalMarkdown,
+      editedMarkdown,
+      summary,
+      // Opt this push into a tracked suggestion even when the agent could edit directly. Only
+      // `true` is meaningful (the server defaults to a direct edit when allowed); omit otherwise.
+      ...suggesting === true ? { suggesting: true } : {},
+      // Display-only hint: the server groups this push under ${userId}::mcp::<tool>. The tool
+      // name is auto-read from the MCP clientInfo handshake (getClientName), falling back to the
+      // configured name only when there is no client to read it from. Identity (the userId) is
+      // the bearer token's principal, never this hint.
+      client: { kind: "mcp", name: getClientName?.() ?? defaultActor }
+    })
+  });
+  return summarizePushResult(result);
+}
+async function resolveSuggestion({ serverUrl, resolveToken, doc_id: docId, action, change_id: changeId, actor, all }) {
+  if (action !== "accept" && action !== "reject") {
+    throw new Error("resolve_suggestion action must be 'accept' or 'reject'.");
+  }
+  const filter = changeId ? { changeId } : actor ? { actor } : all === true ? { all: true } : null;
+  if (!filter) {
+    throw new Error("resolve_suggestion requires one target: change_id, actor, or all:true.");
+  }
+  const result = await fetchJson(resolveUrl(serverUrl, docId), {
+    method: "POST",
+    token: await resolveToken?.(),
+    body: JSON.stringify({ filter, action })
+  });
+  return {
+    kind: "copapers.mcp.resolve-result",
+    docId,
+    action: result.action ?? action,
+    // How many pending changes this action resolved (the matched changes in scope).
+    resolvedChanges: result.resolution?.unresolvedChanges ?? null
+  };
+}
+async function resolveComment({ serverUrl, defaultActor, getClientName, resolveToken, doc_id: rawDocId, thread_id: threadId }) {
+  const docId = rawDocId ? extractDocId(rawDocId) : rawDocId;
+  if (!docId) throw new Error("resolve_comment requires doc_id.");
+  if (!threadId) throw new Error("resolve_comment requires thread_id (the c_\u2026 id shown in the comment block).");
+  const result = await fetchJson(resolveCommentUrl(serverUrl, docId, threadId), {
+    method: "POST",
+    token: await resolveToken?.(),
+    // resolved:true (resolve, not reopen) is implicit server-side; client identity attributes the
+    // resolver to this agent (the name is auto-read from the MCP clientInfo handshake).
+    body: JSON.stringify({ resolved: true, client: { kind: "mcp", name: getClientName?.() ?? defaultActor } })
+  });
+  return {
+    kind: "copapers.mcp.resolve-comment-result",
+    docId,
+    threadId,
+    resolved: result.thread?.status === "resolved"
+  };
+}
+async function connectAgent({ serverUrl, saveCredentials: saveCredentials2, sleep, now, connectWaitMs, connectState, getClientName }) {
+  const existing = connectState.grant;
+  if (existing && existing.deadline > now()) {
+    const outcome = await pollForApproval({ serverUrl, grant: existing, sleep, now, waitMs: connectWaitMs });
+    if (outcome.status === "approved") {
+      await saveCredentials2(outcome.credential);
+      connectState.grant = null;
+      return connectedResult(outcome.credential);
+    }
+    if (outcome.status === "pending") return pendingConnectResult(existing);
+    connectState.grant = null;
+  }
+  const clientLabel = typeof getClientName === "function" ? getClientName() : null;
+  const start = await fetchJson(new URL("/auth/device/start", serverUrl), {
+    method: "POST",
+    body: JSON.stringify({ client_label: clientLabel ?? null })
+  });
+  connectState.grant = {
+    deviceCode: start.device_code,
+    userCode: start.user_code,
+    verificationUrl: start.verification_url,
+    verificationUrlComplete: start.verification_url_complete,
+    interval: start.interval,
+    deadline: now() + (start.expires_in ?? 600) * 1e3
+  };
+  return pendingConnectResult(connectState.grant);
+}
+async function pollForApproval({ serverUrl, grant, sleep, now, waitMs }) {
+  const deadline = Math.min(now() + Math.max(waitMs, 0), grant.deadline);
+  const intervalMs = Math.max((grant.interval ?? 3) * 1e3, 500);
+  for (; ; ) {
+    const poll = await fetchJson(new URL("/auth/device/poll", serverUrl), {
+      method: "POST",
+      body: JSON.stringify({ device_code: grant.deviceCode })
+    });
+    if (poll.status === "approved") return { status: "approved", credential: poll.credential };
+    if (poll.status === "expired") return { status: "expired" };
+    if (now() >= deadline) return { status: "pending" };
+    await sleep(Math.min(intervalMs, Math.max(deadline - now(), 0)));
+  }
+}
+function pendingConnectResult(grant) {
+  const url = grant.verificationUrlComplete ?? grant.verificationUrl;
+  return {
+    kind: "copapers.mcp.connect",
+    status: "pending",
+    verificationUrl: url,
+    userCode: grant.userCode,
+    message: `To connect, open ${url} in the browser where you're signed in to copapers and approve the request (code ${grant.userCode}). Then call connect again to finish \u2014 I'll wait for your approval.`
+  };
+}
+function connectedResult(credential) {
+  return {
+    kind: "copapers.mcp.connect",
+    status: "connected",
+    email: credential.email ?? null,
+    message: `Connected to copapers${credential.email ? ` as ${credential.email}` : ""}. Pulls and pushes are now authenticated on this machine \u2014 you won't need to connect again.`
+  };
+}
+async function disconnectAgent({ clearCredentials: clearCredentials2 }) {
+  await clearCredentials2();
+  return {
+    kind: "copapers.mcp.connect",
+    status: "disconnected",
+    message: "Disconnected from copapers on this machine. Call connect to sign in again."
+  };
+}
+function summarizePushResult(result) {
+  const conflicts = result.conflicts ?? [];
+  return {
+    kind: "copapers.mcp.push-result",
+    status: result.status ?? null,
+    // 'direct' (a clean edit landed) or 'suggest' (a tracked suggestion); downgraded means a
+    // would-be direct edit fell back to a suggestion for lack of edit access on the doc.
+    appliedMode: result.appliedMode ?? null,
+    ...result.downgraded ? { downgraded: true } : {},
+    proposalId: result.proposalId,
+    ...conflicts.length > 0 ? { conflicts } : {}
+  };
+}
+function summarizeCheckoutState(state) {
+  return {
+    checkoutId: state.checkoutId,
+    docId: state.docId,
+    title: state.title,
+    documentPath: state.documentPath,
+    protectedSpanCount: state.manifest.review?.protectedSpanCount ?? 0
+  };
+}
+async function inspectCheckoutLocalState(state) {
+  try {
+    const editedMarkdown = await readFile2(state.documentPath, "utf8");
+    const editedMarkdownHash = sha256(editedMarkdown);
+    return {
+      status: editedMarkdownHash === state.manifest.originalMarkdownHash ? "clean" : "dirty",
+      editedMarkdownHash
+    };
+  } catch (error) {
+    return {
+      status: "unknown",
+      message: error.message
+    };
+  }
+}
+async function toMcpResult(callback) {
+  try {
+    const value = await callback();
+    return jsonToolResult(value);
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: formatError(error) }],
+      isError: true
+    };
+  }
+}
+function jsonToolResult(value) {
+  return {
+    content: [{ type: "text", text: `${JSON.stringify(value)}
+` }],
+    structuredContent: value
+  };
+}
+async function fetchJson(url, options2 = {}) {
+  const { token, headers: extraHeaders, ...rest } = options2;
+  let response;
+  try {
+    response = await fetch(url, {
+      ...rest,
+      headers: {
+        accept: "application/json",
+        ...rest.body ? { "content-type": "application/json" } : {},
+        ...token ? { authorization: `Bearer ${token}` } : {},
+        ...extraHeaders ?? {}
+      }
+    });
+  } catch (error) {
+    throw new Error(`Could not reach copapers server at ${url.origin}. Run "copapers serve" or set COPAPERS_SERVER_URL. ${error.message}`);
+  }
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const authError = notAuthenticatedFrom(response.status, body);
+    if (authError) throw authError;
+    const detail = body?.error;
+    const message = detail ? `${detail.message} (${detail.code})` : `Server returned HTTP ${response.status}.`;
+    const error = new Error(message);
+    error.httpStatus = response.status;
+    error.body = body;
+    throw error;
+  }
+  return body;
+}
+async function writeCheckoutFiles({ stateDir, state, markdown }) {
+  const paths = checkoutPaths(stateDir, state.checkoutId);
+  await mkdir2(paths.checkoutDir, { recursive: true });
+  await writeFile2(paths.documentPath, markdown);
+  await writeFile2(paths.originalPath, markdown);
+  await writeFile2(paths.statePath, `${JSON.stringify(state, null, 2)}
+`);
+}
+async function readCheckoutState({ stateDir, checkoutId }) {
+  const path = checkoutPaths(stateDir, checkoutId).statePath;
+  const state = JSON.parse(await readFile2(path, "utf8"));
+  if (state.kind !== COPAPERS_MCP_CHECKOUT_STATE_KIND) {
+    throw new Error(`Invalid checkout state file for ${checkoutId}.`);
+  }
+  return state;
+}
+function checkoutPaths(stateDir, checkoutId) {
+  assertSafeCheckoutId(checkoutId);
+  const checkoutDir = join2(stateDir, "checkouts", checkoutId);
+  return {
+    checkoutDir,
+    documentPath: join2(checkoutDir, "document.md"),
+    originalPath: join2(checkoutDir, "original.md"),
+    statePath: join2(checkoutDir, "checkout.json")
+  };
+}
+function assertSafeCheckoutId(checkoutId) {
+  if (!isSafeCheckoutId(checkoutId)) {
+    throw new Error(`Invalid checkout id "${checkoutId}".`);
+  }
+}
+function isSafeCheckoutId(checkoutId) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(checkoutId);
+}
+function checkoutUrl(serverUrl, docId, actor) {
+  const url = documentUrl(serverUrl, docId, "/checkout");
+  url.searchParams.set("actor", actor);
+  return url;
+}
+function pushUrl(serverUrl, docId) {
+  return documentUrl(serverUrl, docId, "/push");
+}
+function resolveUrl(serverUrl, docId) {
+  return documentUrl(serverUrl, docId, "/suggestions/resolve");
+}
+function resolveCommentUrl(serverUrl, docId, threadId) {
+  return documentUrl(serverUrl, docId, `/comments/${encodeURIComponent(threadId)}/resolve`);
+}
+function documentUrl(serverUrl, docId, suffix = "") {
+  return new URL(`/documents/${encodeURIComponent(docId)}${suffix}`, serverUrl);
+}
+function normalizeConfig(options2) {
+  return {
+    serverUrl: stripTrailingSlash2(options2.serverUrl ?? process.env.COPAPERS_SERVER_URL ?? DEFAULT_COPAPERS_SERVER_URL),
+    stateDir: resolve(process.cwd(), options2.stateDir ?? process.env.COPAPERS_MCP_STATE_DIR ?? DEFAULT_COPAPERS_MCP_STATE_DIR),
+    // The grouping-label fallback used only when there is no MCP client handshake to read the
+    // tool name from (e.g. the tools invoked directly). With a real client, getClientName wins.
+    defaultActor: options2.actor ?? process.env.COPAPERS_ACTOR ?? "mcp-agent",
+    // Reads clientInfo.name from the live MCP handshake (set by createCopapersMcpServer).
+    getClientName: options2.getClientName ?? null,
+    // Resolves the bearer token (env hatch → stored credential, refreshing as needed). Override
+    // in tests. The bearer authenticates every server call; identity is the token's principal.
+    resolveToken: options2.resolveToken ?? (() => resolveBearerToken()),
+    // `connect`/`disconnect` write the shared machine-wide credential. Injectable for tests.
+    saveCredentials: options2.saveCredentials ?? ((credential) => saveCredentials(credential)),
+    clearCredentials: options2.clearCredentials ?? (() => clearCredentials()),
+    sleep: options2.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms))),
+    now: options2.now ?? Date.now,
+    // How long a connect RESUME call waits inline for approval before returning "still pending"
+    // (capped by the grant's expiry). The first connect call always returns the URL immediately.
+    // 0 in tests → a single poll, no sleeping.
+    connectWaitMs: options2.connectWaitMs ?? 9e4
+  };
+}
+function stripTrailingSlash2(value) {
+  return value.replace(/\/+$/, "");
+}
+function extractDocId(input) {
+  if (typeof input !== "string") return input;
+  const value = input.trim();
+  const match = value.match(/\/d\/([^/?#]+)/);
+  return match ? decodeURIComponent(match[1]) : value;
+}
+function sha256(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+function formatError(error) {
+  if (error?.code === "not_authenticated") {
+    return "not_authenticated. Call the `connect` tool now to sign in \u2014 it returns a URL and a short code for the user to open and approve in their browser, then call `connect` again to finish and retry this tool. Do NOT tell the user to authenticate elsewhere or give up; `connect` is the way to authenticate and you can call it directly.";
+  }
+  if (error?.body?.error) {
+    return JSON.stringify(error.body.error);
+  }
+  return error?.message ?? String(error);
+}
+
+// ../../bin/copapers-mcp.js
+var options = parseOptions(process.argv.slice(2));
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+runCopapersMcpServer(options).catch((error) => {
+  console.error(`copapers-mcp: ${error.message}`);
+  process.exit(1);
+});
+function parseOptions(args) {
+  return {
+    help: hasFlag(args, "--help") || hasFlag(args, "-h"),
+    serverUrl: optionValue(args, "--server"),
+    stateDir: optionValue(args, "--state-dir"),
+    actor: optionValue(args, "--actor")
+  };
+}
+function optionValue(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return void 0;
+  return args[index + 1];
+}
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+function printHelp() {
+  console.log(`Usage:
+  copapers-mcp [--server <url>] [--state-dir <dir>]
+
+Auth:
+  Call the "connect" tool to sign in: it returns a URL + short code to approve in your browser
+  (where you're signed in), and stores a credential shared by every copapers session on this
+  machine. "disconnect" signs out. Suggestions are attributed to your signed-in account and this
+  MCP client's name \u2014 the agent passes no actor.
+
+Environment:
+  COPAPERS_SERVER_URL       Default copapers server URL
+  COPAPERS_MCP_STATE_DIR    Directory for MCP checkout state
+  COPAPERS_CONFIG_DIR       Credential dir (default ~/.copapers; set per-MCP for a distinct identity)
+  COPAPERS_ACCESS_TOKEN     Bearer token override (otherwise the stored credential is used)
+
+Example:
+  node bin/copapers.js serve
+  copapers-mcp --server http://127.0.0.1:3077
+`);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "copapers-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Copapers — let your agents edit your Copapers documents.",
+  "homepage": "https://copapers.com",
+  "author": "Andy Bromberg <andy@andybromberg.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "copapers-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "copapers",
+    "claude",
+    "codex"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  }
+}