@tickernelz/paperclip-pro-adapter-utils 2026.925.0 → 2026.925.2

package/dist/paperclip-mcp-mount.d.ts

@@ -0,0 +1,36 @@
+import { type AdapterExecutionTarget } from "./execution-target.js";
+export interface PaperclipMcpMount {
+    dir: string;
+    filePath: string;
+    cleanup: () => Promise<void>;
+}
+export interface PaperclipMcpHttpTarget {
+    url: string;
+    headers: Record<string, string>;
+}
+/** Resolve the run's server-hosted MCP endpoint and the headers that authenticate it. */
+export declare function paperclipMcpHttpTarget(input: {
+    env: Record<string, string | undefined>;
+    toolsets: string;
+}): PaperclipMcpHttpTarget;
+/** Gemini CLI settings.json: streamable HTTP servers use `httpUrl`. */
+export declare function renderPaperclipGeminiSettings(target: PaperclipMcpHttpTarget): string;
+/** OpenCode config: remote servers live under `mcp` with `type: "remote"`. */
+export declare function renderPaperclipOpenCodeConfig(target: PaperclipMcpHttpTarget): string;
+/** Grok CLI config overlay: `[mcp_servers.<name>]` with an inline headers table. */
+export declare function renderPaperclipGrokConfig(target: PaperclipMcpHttpTarget): string;
+/** Write a run-scoped config file locally or on the execution target, with a cleanup that removes it. */
+export declare function writePaperclipMcpMount(input: {
+    runId: string;
+    target: AdapterExecutionTarget | null | undefined;
+    remote: boolean;
+    content: string;
+    fileName: string;
+    localPrefix: string;
+    remoteDir: string | null;
+    cwd: string;
+    env: Record<string, string>;
+    timeoutSec: number;
+    graceSec: number;
+}): Promise<PaperclipMcpMount>;
+//# sourceMappingURL=paperclip-mcp-mount.d.ts.map

package/dist/paperclip-mcp-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-mcp-mount.d.ts","sourceRoot":"","sources":["../src/paperclip-mcp-mount.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,uBAAuB,CAAC;AAO/B,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,sBAAsB,CAQzB;AAED,uEAAuE;AACvE,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAOpF;AAED,8EAA8E;AAC9E,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAcpF;AAMD,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAWhF;AAMD,yGAAyG;AACzG,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6C7B"}

package/dist/paperclip-mcp-mount.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runAdapterExecutionTargetShellCommand, } from "./execution-target.js";
+import { PAPERCLIP_MCP_SERVER_NAME, paperclipMcpEndpoint, paperclipMcpHttpHeaders, } from "./paperclip-mcp.js";
+/** Resolve the run's server-hosted MCP endpoint and the headers that authenticate it. */
+export function paperclipMcpHttpTarget(input) {
+    return {
+        url: paperclipMcpEndpoint(input.env.PAPERCLIP_API_URL ?? "", input.toolsets),
+        headers: paperclipMcpHttpHeaders({
+            apiKey: (input.env.PAPERCLIP_API_KEY ?? "").trim(),
+            runId: input.env.PAPERCLIP_RUN_ID ?? "",
+        }),
+    };
+}
+/** Gemini CLI settings.json: streamable HTTP servers use `httpUrl`. */
+export function renderPaperclipGeminiSettings(target) {
+    const settings = {
+        mcpServers: {
+            [PAPERCLIP_MCP_SERVER_NAME]: { httpUrl: target.url, headers: target.headers },
+        },
+    };
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+/** OpenCode config: remote servers live under `mcp` with `type: "remote"`. */
+export function renderPaperclipOpenCodeConfig(target) {
+    const config = {
+        $schema: "https://opencode.ai/config.json",
+        mcp: {
+            [PAPERCLIP_MCP_SERVER_NAME]: {
+                type: "remote",
+                url: target.url,
+                enabled: true,
+                oauth: false,
+                headers: target.headers,
+            },
+        },
+    };
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+/** Grok CLI config overlay: `[mcp_servers.<name>]` with an inline headers table. */
+export function renderPaperclipGrokConfig(target) {
+    const headers = Object.entries(target.headers)
+        .map(([key, value]) => `${tomlString(key)} = ${tomlString(value)}`)
+        .join(", ");
+    return [
+        `[mcp_servers.${tomlString(PAPERCLIP_MCP_SERVER_NAME)}]`,
+        `url = ${tomlString(target.url)}`,
+        "enabled = true",
+        `headers = { ${headers} }`,
+        "",
+    ].join("\n");
+}
+function shellQuoteSingle(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** Write a run-scoped config file locally or on the execution target, with a cleanup that removes it. */
+export async function writePaperclipMcpMount(input) {
+    if (!input.remote) {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), input.localPrefix));
+        await fs.chmod(dir, 0o700);
+        const filePath = path.join(dir, input.fileName);
+        await fs.writeFile(filePath, input.content, { encoding: "utf8", mode: 0o600 });
+        return {
+            dir,
+            filePath,
+            cleanup: async () => {
+                await fs.rm(dir, { recursive: true, force: true });
+            },
+        };
+    }
+    const dir = input.remoteDir ?? path.posix.join(input.cwd, ".paperclip-runtime", "mcp");
+    const filePath = path.posix.join(dir, input.fileName);
+    const quotedDir = shellQuoteSingle(dir);
+    const quotedFile = shellQuoteSingle(filePath);
+    const shellOptions = {
+        cwd: input.cwd,
+        env: input.env,
+        timeoutSec: Math.min(input.timeoutSec || 15, 15),
+        graceSec: Math.min(input.graceSec, 5),
+    };
+    const heredoc = [
+        `mkdir -p ${quotedDir}`,
+        `cat > ${quotedFile} <<'PAPERCLIP_MCP_MOUNT'`,
+        input.content.replace(/\n$/, ""),
+        "PAPERCLIP_MCP_MOUNT",
+        `chmod 600 ${quotedFile}`,
+    ].join("\n");
+    await runAdapterExecutionTargetShellCommand(input.runId, input.target, heredoc, shellOptions);
+    return {
+        dir,
+        filePath,
+        cleanup: async () => {
+            await runAdapterExecutionTargetShellCommand(input.runId, input.target, `rm -rf ${quotedDir}`, shellOptions).catch(() => { });
+        },
+    };
+}
+//# sourceMappingURL=paperclip-mcp-mount.js.map

package/dist/paperclip-mcp-mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-mcp-mount.js","sourceRoot":"","sources":["../src/paperclip-mcp-mount.ts"],"names":[],"mappings":"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"}

package/dist/paperclip-mcp.d.ts

@@ -0,0 +1,53 @@
+export declare const PAPERCLIP_MCP_SERVER_NAME = "paperclip";
+export declare const PAPERCLIP_MCP_PACKAGE = "@tickernelz/paperclip-pro-mcp-server";
+export declare const PAPERCLIP_MCP_BIN = "paperclip-mcp-server";
+export declare const PAPERCLIP_MCP_DEFAULT_TOOLSETS = "core";
+export declare const PAPERCLIP_MCP_TOOLSETS_ENV = "PAPERCLIP_MCP_TOOLSETS";
+export declare const PAPERCLIP_MCP_HTTP_PATH = "/mcp/paperclip";
+export declare const PAPERCLIP_MCP_RUN_ID_HEADER = "X-Paperclip-Run-Id";
+/** Which Paperclip access surface an adapter arms for a run. */
+export type PaperclipAccessMode = "mcp" | "rest";
+export type PaperclipMcpTransportKind = "http" | "stdio";
+export interface PaperclipMcpCommand {
+    command: string;
+    args: string[];
+    source: "bin" | "dist" | "path";
+}
+export declare function paperclipMcpToolsets(config: Record<string, unknown>): string;
+export declare function paperclipMcpTransport(config: Record<string, unknown>): PaperclipMcpTransportKind;
+/** Server-hosted MCP endpoint for this run, mirroring the API base the REST path uses. */
+export declare function paperclipMcpEndpoint(apiUrl: string, toolsets: string): string;
+/** MCP needs the `paperclipMcp` toggle on plus an API base and a run credential; everything else is REST. */
+export declare function paperclipAccessMode(config: Record<string, unknown>, env: Record<string, string | undefined>): PaperclipAccessMode;
+export declare function paperclipMcpHttpHeaders(input: {
+    apiKey: string;
+    runId?: string;
+}): Record<string, string>;
+/** Locate the stdio MCP server shipped with this install: nearest `.bin` shim, then `dist/stdio.js`, then PATH. */
+export declare function resolvePaperclipMcpServerCommand(options?: {
+    searchFrom?: string;
+    exists?: (candidate: string) => boolean;
+    nodePath?: string;
+}): PaperclipMcpCommand;
+export interface PaperclipMcpServerEntryInput {
+    enabled: boolean;
+    transport: PaperclipMcpTransportKind;
+    command: PaperclipMcpCommand;
+    toolsets: string;
+    env: Record<string, string>;
+    /** `placeholder` emits `${PAPERCLIP_API_KEY}` for runtimes that expand env references; `literal` writes the token. */
+    credential?: "placeholder" | "literal";
+}
+export declare function buildPaperclipMcpServerEntry(input: PaperclipMcpServerEntryInput): Record<string, unknown>;
+export declare function renderPaperclipMcpConfig(input: PaperclipMcpServerEntryInput): string;
+export declare function paperclipMcpGuidance(toolsets: string, toolCount?: number | null): string;
+/** Guidance for runtimes without the Paperclip MCP: reach the board over REST with the run credentials in env. */
+export declare function paperclipRestGuidance(options?: {
+    shellHint?: string;
+}): string;
+export declare function paperclipAccessGuidance(access: PaperclipAccessMode, options?: {
+    toolsets?: string;
+    toolCount?: number | null;
+    shellHint?: string;
+}): string;
+//# sourceMappingURL=paperclip-mcp.d.ts.map

package/dist/paperclip-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-mcp.d.ts","sourceRoot":"","sources":["../src/paperclip-mcp.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,qBAAqB,yCAAyC,CAAC;AAC5E,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AACxD,eAAO,MAAM,8BAA8B,SAAS,CAAC;AACrD,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AACnE,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AACxD,eAAO,MAAM,2BAA2B,uBAAuB,CAAC;AAUhE,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;CACjC;AAYD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAM5E;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,yBAAyB,CAEhG;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,mBAAmB,CAKrB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzB;AAED,mHAAmH;AACnH,wBAAgB,gCAAgC,CAAC,OAAO,GAAE;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,mBAAmB,CAc3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,yBAAyB,CAAC;IACrC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,sHAAsH;IACtH,UAAU,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACxC;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,4BAA4B,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,4BAA4B,GAAG,MAAM,CAGpF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,CAO9F;AAED,kHAAkH;AAClH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAelF;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjF,MAAM,CAIR"}

package/dist/paperclip-mcp.js

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+export const PAPERCLIP_MCP_SERVER_NAME = "paperclip";
+export const PAPERCLIP_MCP_PACKAGE = "@tickernelz/paperclip-pro-mcp-server";
+export const PAPERCLIP_MCP_BIN = "paperclip-mcp-server";
+export const PAPERCLIP_MCP_DEFAULT_TOOLSETS = "core";
+export const PAPERCLIP_MCP_TOOLSETS_ENV = "PAPERCLIP_MCP_TOOLSETS";
+export const PAPERCLIP_MCP_HTTP_PATH = "/mcp/paperclip";
+export const PAPERCLIP_MCP_RUN_ID_HEADER = "X-Paperclip-Run-Id";
+const RUN_ENV_KEYS = [
+    "PAPERCLIP_API_URL",
+    "PAPERCLIP_API_KEY",
+    "PAPERCLIP_COMPANY_ID",
+    "PAPERCLIP_AGENT_ID",
+    "PAPERCLIP_RUN_ID",
+];
+function readToggle(value, fallback) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["true", "1", "yes", "on"].includes(normalized))
+            return true;
+        if (["false", "0", "no", "off"].includes(normalized))
+            return false;
+    }
+    return fallback;
+}
+export function paperclipMcpToolsets(config) {
+    const parts = (typeof config.paperclipMcpToolsets === "string" ? config.paperclipMcpToolsets : "")
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    return parts.length > 0 ? parts.join(",") : PAPERCLIP_MCP_DEFAULT_TOOLSETS;
+}
+export function paperclipMcpTransport(config) {
+    return config.paperclipMcpTransport === "stdio" ? "stdio" : "http";
+}
+/** Server-hosted MCP endpoint for this run, mirroring the API base the REST path uses. */
+export function paperclipMcpEndpoint(apiUrl, toolsets) {
+    const trimmed = apiUrl.trim().replace(/\/+$/, "");
+    const base = trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+    return `${base}${PAPERCLIP_MCP_HTTP_PATH}?toolsets=${encodeURIComponent(toolsets)}`;
+}
+/** MCP needs the `paperclipMcp` toggle on plus an API base and a run credential; everything else is REST. */
+export function paperclipAccessMode(config, env) {
+    if (!readToggle(config.paperclipMcp, true))
+        return "rest";
+    if (!(env.PAPERCLIP_API_URL ?? "").trim())
+        return "rest";
+    if (!(env.PAPERCLIP_API_KEY ?? "").trim())
+        return "rest";
+    return "mcp";
+}
+export function paperclipMcpHttpHeaders(input) {
+    const headers = { Authorization: `Bearer ${input.apiKey}` };
+    const runId = (input.runId ?? "").trim();
+    if (runId)
+        headers[PAPERCLIP_MCP_RUN_ID_HEADER] = runId;
+    return headers;
+}
+/** Locate the stdio MCP server shipped with this install: nearest `.bin` shim, then `dist/stdio.js`, then PATH. */
+export function resolvePaperclipMcpServerCommand(options = {}) {
+    const exists = options.exists ?? existsSync;
+    const nodePath = options.nodePath ?? process.execPath;
+    let dir = path.resolve(options.searchFrom ?? import.meta.dirname);
+    for (;;) {
+        const modules = path.join(dir, "node_modules");
+        const bin = path.join(modules, ".bin", PAPERCLIP_MCP_BIN);
+        if (exists(bin))
+            return { command: bin, args: [], source: "bin" };
+        const dist = path.join(modules, PAPERCLIP_MCP_PACKAGE, "dist", "stdio.js");
+        if (exists(dist))
+            return { command: nodePath, args: [dist], source: "dist" };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return { command: PAPERCLIP_MCP_BIN, args: [], source: "path" };
+        dir = parent;
+    }
+}
+export function buildPaperclipMcpServerEntry(input) {
+    const literal = input.credential === "literal";
+    const apiKey = (input.env.PAPERCLIP_API_KEY ?? "").trim();
+    if (input.transport === "http") {
+        return {
+            type: "http",
+            enabled: input.enabled,
+            url: paperclipMcpEndpoint(input.env.PAPERCLIP_API_URL ?? "", input.toolsets),
+            headers: paperclipMcpHttpHeaders({
+                apiKey: literal ? apiKey : "${PAPERCLIP_API_KEY}",
+                runId: input.env.PAPERCLIP_RUN_ID ?? "",
+            }),
+        };
+    }
+    const env = {};
+    for (const key of RUN_ENV_KEYS) {
+        const value = input.env[key];
+        if (typeof value !== "string" || !value.trim())
+            continue;
+        env[key] = key === "PAPERCLIP_API_KEY" && !literal ? `\${${key}}` : value.trim();
+    }
+    env[PAPERCLIP_MCP_TOOLSETS_ENV] = input.toolsets;
+    return {
+        type: "stdio",
+        enabled: input.enabled,
+        command: input.command.command,
+        args: [...input.command.args, "--toolsets", input.toolsets],
+        env,
+    };
+}
+export function renderPaperclipMcpConfig(input) {
+    const servers = { [PAPERCLIP_MCP_SERVER_NAME]: buildPaperclipMcpServerEntry(input) };
+    return `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`;
+}
+export function paperclipMcpGuidance(toolsets, toolCount = null) {
+    return [
+        `Paperclip's API is mounted as MCP tools on the "${PAPERCLIP_MCP_SERVER_NAME}" server (toolsets: ${toolsets}${toolCount === null ? "" : `, ${toolCount} tools`}).`,
+        'Every tool name starts with "paperclip", for example paperclipListIssues or paperclipAddComment.',
+        "These tools are the only way to reach Paperclip; they already carry this run's identity, API key and run id.",
+        `When no dedicated tool covers an endpoint, use the ${PAPERCLIP_MCP_SERVER_NAME} escape-hatch tool paperclipApiRequest instead of a shell HTTP client.`,
+    ].join("\n");
+}
+/** Guidance for runtimes without the Paperclip MCP: reach the board over REST with the run credentials in env. */
+export function paperclipRestGuidance(options = {}) {
+    const shell = options.shellHint?.trim();
+    return [
+        "This runtime has no paperclip* tools. Reach Paperclip over its REST API instead.",
+        shell
+            ? `Use ${shell} with curl; normalize the base URL first: PAPERCLIP_API_BASE="\${PAPERCLIP_API_URL%/}"; PAPERCLIP_API_BASE="\${PAPERCLIP_API_BASE%/api}".`
+            : 'Use a terminal with curl; normalize the base URL first: PAPERCLIP_API_BASE="${PAPERCLIP_API_URL%/}"; PAPERCLIP_API_BASE="${PAPERCLIP_API_BASE%/api}".',
+        'Send `Authorization: Bearer $PAPERCLIP_API_KEY` on every request and `X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID` on every mutation.',
+        "GET example:",
+        '  curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" "$PAPERCLIP_API_BASE/api/agents/me"',
+        "Write example:",
+        '  curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" -H "Content-Type: application/json" -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" -d \'{"body":"Status update from agent."}\' "$PAPERCLIP_API_BASE/api/issues/$PAPERCLIP_TASK_ID/comments"',
+        "Never send a placeholder like {id} in a URL; substitute a real issue id from the current context.",
+        "Do not copy printed tokens into comments or config; reference the environment variables.",
+    ].join("\n");
+}
+export function paperclipAccessGuidance(access, options = {}) {
+    return access === "mcp"
+        ? paperclipMcpGuidance(options.toolsets ?? PAPERCLIP_MCP_DEFAULT_TOOLSETS, options.toolCount ?? null)
+        : paperclipRestGuidance({ shellHint: options.shellHint });
+}
+//# sourceMappingURL=paperclip-mcp.js.map

package/dist/paperclip-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-mcp.js","sourceRoot":"","sources":["../src/paperclip-mcp.ts"],"names":[],"mappings":"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"}

package/dist/paperclip-mcp.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=paperclip-mcp.test.d.ts.map

package/dist/paperclip-mcp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-mcp.test.d.ts","sourceRoot":"","sources":["../src/paperclip-mcp.test.ts"],"names":[],"mappings":""}

package/dist/paperclip-mcp.test.js

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { paperclipAccessGuidance, paperclipAccessMode, paperclipMcpEndpoint, paperclipMcpHttpHeaders, paperclipMcpToolsets, renderPaperclipMcpConfig, } from "./paperclip-mcp.js";
+import { paperclipMcpHttpTarget, renderPaperclipGeminiSettings, renderPaperclipGrokConfig, renderPaperclipOpenCodeConfig, } from "./paperclip-mcp-mount.js";
+import { paperclipAgentPromptTemplate, renderPaperclipWakePrompt, } from "./server-utils.js";
+const TOOL_NAME_RE = /\bpaperclip[A-Z]\w*/;
+const runEnv = {
+    PAPERCLIP_API_URL: "https://paperclip.test",
+    PAPERCLIP_API_KEY: "run-key",
+    PAPERCLIP_RUN_ID: "run-7",
+};
+describe("paperclipAccessMode", () => {
+    it("arms MCP only when the toggle is on and the run carries a reachable credential", () => {
+        expect(paperclipAccessMode({}, runEnv)).toBe("mcp");
+        expect(paperclipAccessMode({ paperclipMcp: false }, runEnv)).toBe("rest");
+        expect(paperclipAccessMode({ paperclipMcp: "false" }, runEnv)).toBe("rest");
+        expect(paperclipAccessMode({}, { ...runEnv, PAPERCLIP_API_KEY: "  " })).toBe("rest");
+        expect(paperclipAccessMode({}, { ...runEnv, PAPERCLIP_API_URL: undefined })).toBe("rest");
+    });
+});
+describe("paperclipAgentPromptTemplate", () => {
+    it("names the MCP tools only on the mcp surface and the REST routes otherwise", () => {
+        const mcp = paperclipAgentPromptTemplate("mcp");
+        expect(mcp).toContain("paperclipAddComment");
+        expect(mcp).toContain("paperclipSuggestTasks");
+        const rest = paperclipAgentPromptTemplate("rest");
+        expect(rest).not.toMatch(TOOL_NAME_RE);
+        expect(rest).toContain("POST /api/issues/$PAPERCLIP_TASK_ID/interactions");
+        expect(rest).toContain("PATCH /api/issues/$PAPERCLIP_TASK_ID");
+    });
+    it("keeps the execution contract identical apart from the access-surface lines", () => {
+        const mcpLines = paperclipAgentPromptTemplate("mcp").split("\n");
+        const restLines = paperclipAgentPromptTemplate("rest").split("\n");
+        expect(restLines).toHaveLength(mcpLines.length);
+        const differing = mcpLines.filter((line, index) => line !== restLines[index]);
+        expect(differing).toHaveLength(2);
+    });
+});
+describe("renderPaperclipWakePrompt", () => {
+    const wake = {
+        reason: "issue_assigned",
+        issue: { id: "issue-1", identifier: "PC-1", title: "Ship it", status: "todo" },
+        checkedOutByHarness: true,
+    };
+    it("points the already-checked-out note at the surface the run actually has", () => {
+        expect(renderPaperclipWakePrompt(wake)).toContain("`paperclipCheckoutIssue`");
+        const rest = renderPaperclipWakePrompt(wake, { paperclipAccess: "rest" });
+        expect(rest).not.toMatch(TOOL_NAME_RE);
+        expect(rest).toContain("POST /api/issues/$PAPERCLIP_TASK_ID/checkout");
+    });
+});
+describe("paperclipAccessGuidance", () => {
+    it("teaches tools on mcp and curl with the run headers on rest", () => {
+        const mcp = paperclipAccessGuidance("mcp", { toolsets: "core,extended" });
+        expect(mcp).toContain("toolsets: core,extended");
+        expect(mcp).toContain("paperclipListIssues");
+        const rest = paperclipAccessGuidance("rest", { shellHint: "run_shell_command" });
+        expect(rest).not.toMatch(TOOL_NAME_RE);
+        expect(rest).toContain("Authorization: Bearer $PAPERCLIP_API_KEY");
+        expect(rest).toContain("X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID");
+        expect(rest).toContain("run_shell_command");
+    });
+});
+describe("paperclip MCP endpoint", () => {
+    it("normalizes the API base and encodes the toolsets", () => {
+        expect(paperclipMcpEndpoint("https://paperclip.test/", "core")).toBe("https://paperclip.test/api/mcp/paperclip?toolsets=core");
+        expect(paperclipMcpEndpoint("https://paperclip.test/api", "core,extended")).toBe("https://paperclip.test/api/mcp/paperclip?toolsets=core%2Cextended");
+    });
+    it("defaults the toolsets and drops empty entries", () => {
+        expect(paperclipMcpToolsets({})).toBe("core");
+        expect(paperclipMcpToolsets({ paperclipMcpToolsets: " , " })).toBe("core");
+        expect(paperclipMcpToolsets({ paperclipMcpToolsets: " extended , core " })).toBe("extended,core");
+    });
+    it("omits the run-id header when the run does not carry one", () => {
+        expect(paperclipMcpHttpHeaders({ apiKey: "k", runId: "  " })).toEqual({
+            Authorization: "Bearer k",
+        });
+    });
+});
+describe("per-runtime MCP config renderers", () => {
+    const target = paperclipMcpHttpTarget({ env: runEnv, toolsets: "core" });
+    it("resolves the endpoint and the authenticating headers once", () => {
+        expect(target).toEqual({
+            url: "https://paperclip.test/api/mcp/paperclip?toolsets=core",
+            headers: {
+                Authorization: "Bearer run-key",
+                "X-Paperclip-Run-Id": "run-7",
+            },
+        });
+    });
+    it("renders the shape each runtime reads", () => {
+        expect(JSON.parse(renderPaperclipGeminiSettings(target))).toEqual({
+            mcpServers: { paperclip: { httpUrl: target.url, headers: target.headers } },
+        });
+        expect(JSON.parse(renderPaperclipOpenCodeConfig(target)).mcp.paperclip).toEqual({
+            type: "remote",
+            url: target.url,
+            enabled: true,
+            oauth: false,
+            headers: target.headers,
+        });
+        const grok = renderPaperclipGrokConfig(target);
+        expect(grok).toContain('[mcp_servers."paperclip"]');
+        expect(grok).toContain(`url = ${JSON.stringify(target.url)}`);
+        expect(grok).toContain('"Authorization" = "Bearer run-key"');
+        expect(grok).toContain('"X-Paperclip-Run-Id" = "run-7"');
+    });
+    it("keeps the credential out of the omp config file as an env reference", () => {
+        const config = JSON.parse(renderPaperclipMcpConfig({
+            enabled: true,
+            transport: "http",
+            command: { command: "paperclip-mcp-server", args: [], source: "path" },
+            toolsets: "core",
+            env: runEnv,
+        }));
+        expect(config.mcpServers.paperclip.headers.Authorization).toBe("Bearer ${PAPERCLIP_API_KEY}");
+        expect(config.mcpServers.paperclip.headers["X-Paperclip-Run-Id"]).toBe("run-7");
+    });
+});
+//# sourceMappingURL=paperclip-mcp.test.js.map

package/dist/paperclip-mcp.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip-mcp.test.js","sourceRoot":"","sources":["../src/paperclip-mcp.test.ts"],"names":[],"mappings":"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"}

package/dist/server-utils.d.ts

@@ -2,6 +2,7 @@ import type { ExecutionContinuationEnvelope } from "@tickernelz/paperclip-pro-sh
 import { type ChildProcess } from "node:child_process";
 import { type LocalProcessSandboxOptions } from "./local-process-sandbox.js";
 import { type SshRemoteExecutionSpec } from "./ssh.js";
+import type { PaperclipAccessMode } from "./paperclip-mcp.js";
 import type { AdapterRuntimeToolAccess, AdapterSkillSnapshot } from "./types.js";
 export declare function buildRuntimeToolsEnv(access: AdapterRuntimeToolAccess | null | undefined): Record<string, string>;
 export interface RunProcessResult {
@@ -52,6 +53,8 @@ export declare function resolvePaperclipInstanceRootForAdapter(input?: {
     instanceId?: string;
     env?: NodeJS.ProcessEnv;
 }): string;
+/** The heartbeat contract, rendered against the Paperclip surface the adapter actually armed. */
+export declare function paperclipAgentPromptTemplate(access: PaperclipAccessMode): string;
 export declare const DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE: string;
 export declare const DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE: string;
 export declare const WATCHDOG_DEFAULT_MANDATE: string;
@@ -469,6 +472,7 @@ declare function renderPaperclipWakePromptBody(value: unknown, options?: {
     conversationMode?: boolean;
     nativeWakeReaderAvailable?: boolean;
     suppressIssueDescription?: boolean;
+    paperclipAccess?: PaperclipAccessMode;
 }): string;
 export declare function redactEnvForLogs(env: Record<string, string>): Record<string, string>;
 export declare function redactCommandTextForLogs(command: string): string;