@rallycry/conveyor-mcp 2.1.1

package/dist/tunnel-cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import {
+  ConveyorConnection
+} from "./chunk-UIDBFQNZ.js";
+import {
+  runTunnel
+} from "./chunk-N2XC2PGJ.js";
+
+// src/tunnel-cli.ts
+var HELP = `conveyor-tunnel \u2014 attach your local terminal to a cloud Claude Code session.
+
+Usage:
+  conveyor-tunnel [title...]            Create a card, build it, and attach.
+  conveyor-tunnel --task <taskId>       Attach to an existing task's cloud session.
+
+Options:
+  --task, --task-id <id>   Attach to an existing task instead of creating one.
+  --title <text>           Card title (defaults to positional args).
+  --description, -d <text> Card description (new card only).
+  --plan <text>            Card plan (new card only).
+  -h, --help               Show this help.
+
+Environment:
+  CONVEYOR_API_URL         Conveyor API base URL (required).
+  CONVEYOR_PROJECT_TOKEN   Project runner token (required).
+  CONVEYOR_PROJECT_ID      Project id (required).
+
+While attached, press Ctrl-C to detach. The cloud session keeps running \u2014
+detaching never stops the build.
+`;
+var VALUE_FLAGS = {
+  "--task": "taskId",
+  "--task-id": "taskId",
+  "--title": "title",
+  "--description": "description",
+  "-d": "description",
+  "--plan": "plan"
+};
+function parseArgs(argv) {
+  const out = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      out.help = true;
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (arg.startsWith("--") && eq !== -1) {
+      const key = VALUE_FLAGS[arg.slice(0, eq)];
+      if (key) out[key] = arg.slice(eq + 1);
+      continue;
+    }
+    const valueKey = VALUE_FLAGS[arg];
+    if (valueKey) {
+      out[valueKey] = argv[++i];
+      continue;
+    }
+    if (!arg.startsWith("-")) positionals.push(arg);
+  }
+  if (!out.title && positionals.length > 0) out.title = positionals.join(" ");
+  return out;
+}
+var log = (msg) => {
+  process.stderr.write(`${msg}
+`);
+};
+var args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  process.stderr.write(HELP);
+  process.exit(0);
+}
+var apiUrl = process.env.CONVEYOR_API_URL;
+var projectToken = process.env.CONVEYOR_PROJECT_TOKEN;
+var projectId = process.env.CONVEYOR_PROJECT_ID;
+if (!apiUrl || !projectToken || !projectId) {
+  log(
+    "Error: CONVEYOR_API_URL, CONVEYOR_PROJECT_TOKEN, and CONVEYOR_PROJECT_ID environment variables are required."
+  );
+  process.exit(1);
+}
+if (!args.taskId && !args.title) {
+  log("Error: provide a card title or --task <taskId>. See --help.");
+  process.exit(1);
+}
+var conn = new ConveyorConnection({ apiUrl, projectToken, projectId });
+var stdinIsTty = process.stdin.isTTY === true;
+var tty = {
+  write(data) {
+    process.stdout.write(data);
+  },
+  onInput(handler) {
+    process.stdin.on("data", handler);
+    return () => {
+      process.stdin.off("data", handler);
+    };
+  },
+  onResize(handler) {
+    const fn = () => handler(process.stdout.columns ?? 80, process.stdout.rows ?? 24);
+    process.stdout.on("resize", fn);
+    return () => {
+      process.stdout.off("resize", fn);
+    };
+  },
+  size() {
+    return { cols: process.stdout.columns ?? 80, rows: process.stdout.rows ?? 24 };
+  }
+};
+var handle;
+var cleanedUp = false;
+function cleanupAndExit(code) {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  try {
+    handle?.detach();
+  } catch {
+  }
+  if (stdinIsTty) {
+    try {
+      process.stdin.setRawMode(false);
+    } catch {
+    }
+  }
+  process.stdin.pause();
+  conn.disconnect();
+  process.exit(code);
+}
+process.on("SIGINT", () => cleanupAndExit(0));
+process.on("SIGTERM", () => cleanupAndExit(0));
+try {
+  await conn.connect();
+  log("Connected to Conveyor API.");
+} catch (err) {
+  log(`Failed to connect to Conveyor API: ${err instanceof Error ? err.message : String(err)}`);
+  conn.disconnect();
+  process.exit(1);
+}
+try {
+  const session = await runTunnel(conn, tty, {
+    taskId: args.taskId,
+    title: args.title,
+    description: args.description,
+    plan: args.plan,
+    log,
+    onReady: () => {
+      if (stdinIsTty) {
+        process.stdin.setRawMode(true);
+      }
+      process.stdin.resume();
+    },
+    onDetachRequest: () => {
+      log("\nDetaching \u2014 the cloud session keeps running.");
+      cleanupAndExit(0);
+    }
+  });
+  handle = session.handle;
+} catch (err) {
+  log(`Tunnel failed: ${err instanceof Error ? err.message : String(err)}`);
+  cleanupAndExit(1);
+}
+//# sourceMappingURL=tunnel-cli.js.map

package/dist/tunnel-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tunnel-cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { ConveyorConnection } from \"./connection.js\";\nimport { runTunnel, type TunnelHandle, type TunnelTty } from \"./tunnel.js\";\n\nconst HELP = `conveyor-tunnel — attach your local terminal to a cloud Claude Code session.\n\nUsage:\n  conveyor-tunnel [title...]            Create a card, build it, and attach.\n  conveyor-tunnel --task <taskId>       Attach to an existing task's cloud session.\n\nOptions:\n  --task, --task-id <id>   Attach to an existing task instead of creating one.\n  --title <text>           Card title (defaults to positional args).\n  --description, -d <text> Card description (new card only).\n  --plan <text>            Card plan (new card only).\n  -h, --help               Show this help.\n\nEnvironment:\n  CONVEYOR_API_URL         Conveyor API base URL (required).\n  CONVEYOR_PROJECT_TOKEN   Project runner token (required).\n  CONVEYOR_PROJECT_ID      Project id (required).\n\nWhile attached, press Ctrl-C to detach. The cloud session keeps running —\ndetaching never stops the build.\n`;\n\ninterface ParsedArgs {\n  taskId?: string;\n  title?: string;\n  description?: string;\n  plan?: string;\n  help?: boolean;\n}\n\ntype StringArgKey = \"taskId\" | \"title\" | \"description\" | \"plan\";\n\nconst VALUE_FLAGS: Record<string, StringArgKey> = {\n  \"--task\": \"taskId\",\n  \"--task-id\": \"taskId\",\n  \"--title\": \"title\",\n  \"--description\": \"description\",\n  \"-d\": \"description\",\n  \"--plan\": \"plan\",\n};\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const out: ParsedArgs = {};\n  const positionals: string[] = [];\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    if (arg === \"-h\" || arg === \"--help\") {\n      out.help = true;\n      continue;\n    }\n    const eq = arg.indexOf(\"=\");\n    if (arg.startsWith(\"--\") && eq !== -1) {\n      const key = VALUE_FLAGS[arg.slice(0, eq)];\n      if (key) out[key] = arg.slice(eq + 1);\n      continue;\n    }\n    const valueKey = VALUE_FLAGS[arg];\n    if (valueKey) {\n      out[valueKey] = argv[++i];\n      continue;\n    }\n    if (!arg.startsWith(\"-\")) positionals.push(arg);\n  }\n  if (!out.title && positionals.length > 0) out.title = positionals.join(\" \");\n  return out;\n}\n\nconst log = (msg: string): void => {\n  // stdout is reserved for raw PTY passthrough — all human-facing output is stderr.\n  process.stderr.write(`${msg}\\n`);\n};\n\nconst args = parseArgs(process.argv.slice(2));\n\nif (args.help) {\n  process.stderr.write(HELP);\n  process.exit(0);\n}\n\nconst apiUrl = process.env.CONVEYOR_API_URL;\nconst projectToken = process.env.CONVEYOR_PROJECT_TOKEN;\nconst projectId = process.env.CONVEYOR_PROJECT_ID;\n\nif (!apiUrl || !projectToken || !projectId) {\n  log(\n    \"Error: CONVEYOR_API_URL, CONVEYOR_PROJECT_TOKEN, and CONVEYOR_PROJECT_ID environment variables are required.\",\n  );\n  process.exit(1);\n}\n\nif (!args.taskId && !args.title) {\n  log(\"Error: provide a card title or --task <taskId>. See --help.\");\n  process.exit(1);\n}\n\nconst conn = new ConveyorConnection({ apiUrl, projectToken, projectId });\n\nconst stdinIsTty = process.stdin.isTTY === true;\n\nconst tty: TunnelTty = {\n  write(data) {\n    process.stdout.write(data);\n  },\n  onInput(handler) {\n    process.stdin.on(\"data\", handler);\n    return () => {\n      process.stdin.off(\"data\", handler);\n    };\n  },\n  onResize(handler) {\n    const fn = (): void => handler(process.stdout.columns ?? 80, process.stdout.rows ?? 24);\n    process.stdout.on(\"resize\", fn);\n    return () => {\n      process.stdout.off(\"resize\", fn);\n    };\n  },\n  size() {\n    return { cols: process.stdout.columns ?? 80, rows: process.stdout.rows ?? 24 };\n  },\n};\n\nlet handle: TunnelHandle | undefined;\nlet cleanedUp = false;\n\nfunction cleanupAndExit(code: number): void {\n  if (cleanedUp) return;\n  cleanedUp = true;\n  // Detach the relay — this tears down listeners but, by design, never stops\n  // the cloud build. The session continues running after we disconnect.\n  try {\n    handle?.detach();\n  } catch {\n    // best-effort teardown\n  }\n  if (stdinIsTty) {\n    try {\n      process.stdin.setRawMode(false);\n    } catch {\n      // best-effort restore\n    }\n  }\n  process.stdin.pause();\n  conn.disconnect();\n  process.exit(code);\n}\n\n// Signal fallbacks for non-raw stdin (e.g. piped). In raw mode Ctrl-C arrives\n// as ETX in the input stream and is handled by onDetachRequest instead. Either\n// path only detaches — it must never stop the cloud session.\nprocess.on(\"SIGINT\", () => cleanupAndExit(0));\nprocess.on(\"SIGTERM\", () => cleanupAndExit(0));\n\ntry {\n  await conn.connect();\n  log(\"Connected to Conveyor API.\");\n} catch (err) {\n  log(`Failed to connect to Conveyor API: ${err instanceof Error ? err.message : String(err)}`);\n  conn.disconnect();\n  process.exit(1);\n}\n\ntry {\n  const session = await runTunnel(conn, tty, {\n    taskId: args.taskId,\n    title: args.title,\n    description: args.description,\n    plan: args.plan,\n    log,\n    onReady: () => {\n      // Enter raw mode only now — before the PTY is ready, Ctrl-C must still\n      // raise SIGINT so the user can abort the wait. In raw mode, Ctrl-C\n      // instead arrives as ETX and is intercepted as a detach.\n      if (stdinIsTty) {\n        process.stdin.setRawMode(true);\n      }\n      process.stdin.resume();\n    },\n    onDetachRequest: () => {\n      log(\"\\nDetaching — the cloud session keeps running.\");\n      cleanupAndExit(0);\n    },\n  });\n  handle = session.handle;\n} catch (err) {\n  log(`Tunnel failed: ${err instanceof Error ? err.message : String(err)}`);\n  cleanupAndExit(1);\n}\n"],"mappings":"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","names":[]}

package/dist/tunnel.d.ts

@@ -0,0 +1,322 @@
+interface ConveyorMcpConfig {
+    apiUrl: string;
+    projectToken: string;
+    projectId: string;
+}
+/** A single PTY output frame broadcast on the `pty:data` room event. */
+interface PtyDataChunk {
+    sessionId: string;
+    seq: number;
+    data: string;
+    cols?: number;
+    rows?: number;
+}
+/** Ring-buffer snapshot returned by `ptyAttach` for catch-up replay. */
+interface PtyAttachSnapshot {
+    sessionId: string;
+    chunks: {
+        seq: number;
+        data: string;
+    }[];
+    cols: number;
+    rows: number;
+    totalBytes: number;
+}
+/**
+ * Result of `getActivePtySession`. `sessionId` is null until the cloud agent
+ * has booted a PTY and produced at least one ring frame (readiness signal).
+ */
+interface ActivePtySession {
+    sessionId: string | null;
+    cols?: number;
+    rows?: number;
+}
+declare class ConveyorConnection {
+    private socket;
+    private config;
+    constructor(config: ConveyorMcpConfig);
+    get projectId(): string;
+    connect(): Promise<void>;
+    private call;
+    /**
+     * Fire-and-forget emit (no ack). The quickdraw-core server method handler
+     * invokes the ack callback via optional chaining, so omitting it still runs
+     * the full auth/schema/ACL pipeline — it just skips the response round-trip.
+     * Used for high-frequency PTY input/resize so each keystroke does not arm a
+     * 15s timeout timer.
+     */
+    private emit;
+    listTasks(params: {
+        status?: string;
+        assigneeId?: string;
+        limit?: number;
+    }): Promise<unknown[]>;
+    getTask(taskId: string): Promise<unknown>;
+    searchTasks(params: {
+        tagNames?: string[];
+        searchQuery?: string;
+        statusFilters?: string[];
+        limit?: number;
+    }): Promise<unknown[]>;
+    createTask(params: {
+        title: string;
+        description?: string;
+        plan?: string;
+        status?: string;
+    }): Promise<{
+        id: string;
+        slug: string;
+    }>;
+    updateTask(params: {
+        taskId: string;
+        title?: string;
+        description?: string;
+        plan?: string;
+        status?: string;
+        assignedUserId?: string | null;
+    }): Promise<{
+        id: string;
+        status: string;
+    }>;
+    startBuild(taskId: string): Promise<{
+        taskId: string;
+        status: string;
+    }>;
+    stopBuild(taskId: string): Promise<{
+        taskId: string;
+        stopped: boolean;
+    }>;
+    getBuildStatus(taskId: string): Promise<{
+        session: {
+            status: string | null;
+            agentRunnerStatus: string | null;
+        } | null;
+    }>;
+    getTaskChat(taskId: string, limit?: number): Promise<unknown[]>;
+    postToTaskChat(taskId: string, content: string): Promise<{
+        messageId: string;
+    }>;
+    getTaskCli(taskId: string, limit?: number, source?: string): Promise<{
+        type: string;
+        data: Record<string, unknown>;
+        timestamp: string;
+    }[]>;
+    listTags(): Promise<{
+        id: string;
+        name: string;
+        color: string;
+    }[]>;
+    getProjectSummary(): Promise<unknown>;
+    approveTask(taskId: string): Promise<{
+        status: string;
+    }>;
+    requestChanges(taskId: string, feedback: string): Promise<void>;
+    approveAndMergePR(childTaskId: string): Promise<{
+        merged: boolean;
+        childTaskId: string;
+        prNumber: number;
+    }>;
+    listTaskFiles(taskId: string): Promise<unknown[]>;
+    getAttachment(taskId: string, fileId: string): Promise<unknown>;
+    createPullRequest(params: {
+        taskId: string;
+        title: string;
+        body: string;
+        head?: string;
+        base?: string;
+    }): Promise<{
+        prNumber: number;
+        prUrl: string;
+    }>;
+    createSubtask(params: {
+        parentTaskId: string;
+        title: string;
+        description?: string;
+        plan?: string;
+        ordinal?: number;
+        storyPointValue?: number;
+    }): Promise<{
+        id: string;
+        slug: string;
+    }>;
+    updateSubtask(params: {
+        subtaskId: string;
+        title?: string;
+        description?: string;
+        plan?: string;
+        status?: string;
+        ordinal?: number;
+        storyPointValue?: number;
+    }): Promise<{
+        id: string;
+        status: string;
+    }>;
+    listSubtasks(taskId: string): Promise<unknown[]>;
+    deleteSubtask(subtaskId: string): Promise<{
+        deleted: boolean;
+    }>;
+    getDependencies(taskId: string): Promise<unknown[]>;
+    addDependency(params: {
+        taskId: string;
+        dependsOnSlugOrId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    removeDependency(params: {
+        taskId: string;
+        dependsOnSlugOrId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    createSuggestion(params: {
+        title: string;
+        description?: string;
+        tagNames?: string[];
+    }): Promise<{
+        id: string;
+        merged: boolean;
+        mergedIntoId?: string;
+    }>;
+    /**
+     * Poll target: returns the active cloud PTY session for a task once its ring
+     * buffer has frames. `sessionId` is resolved server-side from `taskId` (never
+     * accepted from the wire), preserving the one-active-session-per-task invariant.
+     */
+    getActivePtySession(taskId: string): Promise<ActivePtySession>;
+    /** Fetch the ring-buffer snapshot for catch-up replay on (re)attach. */
+    ptyAttach(sessionId: string): Promise<PtyAttachSnapshot>;
+    /**
+     * Join the session room so `pty:data` frames are delivered. Uses the standard
+     * quickdraw-core subscribe envelope; "Read" is sufficient for output streaming.
+     */
+    subscribeToSession(sessionId: string): void;
+    /** Relay a stdin chunk to the cloud PTY (raw utf8, fire-and-forget). */
+    ptyInput(sessionId: string, data: string): void;
+    /** Relay a terminal resize to the cloud PTY (fire-and-forget). */
+    ptyResize(sessionId: string, cols: number, rows: number): void;
+    /** Subscribe to raw PTY output frames. Returns an unsubscribe function. */
+    onPtyData(handler: (chunk: PtyDataChunk) => void): () => void;
+    disconnect(): void;
+}
+
+/**
+ * The slice of {@link ConveyorConnection} the tunnel needs. Defined as a
+ * structural interface so tests can inject a mock — and, deliberately, so the
+ * relay has NO reference to `stopBuild`. Detaching the local terminal must
+ * never stop the cloud session, and the cleanest way to guarantee that is to
+ * make stopping unreachable from this layer.
+ */
+interface TunnelConnection {
+    createTask(params: {
+        title: string;
+        description?: string;
+        plan?: string;
+        status?: string;
+    }): Promise<{
+        id: string;
+        slug: string;
+    }>;
+    startBuild(taskId: string): Promise<{
+        taskId: string;
+        status: string;
+    }>;
+    getActivePtySession(taskId: string): Promise<ActivePtySession>;
+    ptyAttach(sessionId: string): Promise<PtyAttachSnapshot>;
+    subscribeToSession(sessionId: string): void;
+    ptyInput(sessionId: string, data: string): void;
+    ptyResize(sessionId: string, cols: number, rows: number): void;
+    onPtyData(handler: (chunk: PtyDataChunk) => void): () => void;
+}
+/**
+ * Local terminal abstraction. The CLI binds this to the real process TTY; tests
+ * bind it to an in-memory fake. All output is raw utf8 (node-pty does not use
+ * base64), matching the S2 relay encoding.
+ */
+interface TunnelTty {
+    /** Write raw PTY output to the local terminal. */
+    write(data: string): void;
+    /** Register a stdin handler. Returns an unsubscribe function. */
+    onInput(handler: (data: Buffer) => void): () => void;
+    /** Register a resize handler. Returns an unsubscribe function. */
+    onResize(handler: (cols: number, rows: number) => void): () => void;
+    /** Current local terminal dimensions. */
+    size(): {
+        cols: number;
+        rows: number;
+    };
+}
+/** A live tunnel attachment. */
+interface TunnelHandle {
+    sessionId: string;
+    /**
+     * Tear down the local relay (stdin/resize/output listeners). Does NOT stop
+     * the cloud build — the session keeps running after detach. Idempotent.
+     */
+    detach(): void;
+}
+/** Resolved (non-null) active PTY session. */
+interface ResolvedPtySession {
+    sessionId: string;
+    cols?: number;
+    rows?: number;
+}
+interface WaitForPtySessionOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    log?: (msg: string) => void;
+    /** Injectable for tests; defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll {@link TunnelConnection.getActivePtySession} until the cloud agent has
+ * booted its PTY and produced at least one ring frame. `sessionId` is resolved
+ * server-side from `taskId`, so the local side never invents or supplies one.
+ */
+declare function waitForPtySession(conn: TunnelConnection, taskId: string, options?: WaitForPtySessionOptions): Promise<ResolvedPtySession>;
+interface AttachTunnelOptions {
+    /**
+     * Called when the local user requests a detach (Ctrl-C / ETX in the input
+     * stream). When provided, the ETX byte is intercepted and NOT forwarded to
+     * the cloud PTY; when omitted, all input passes through unmodified.
+     */
+    onDetachRequest?: () => void;
+}
+/**
+ * Attach the local TTY to a cloud PTY session, reusing the S2 `pty:*` relay
+ * envelope. Replays the ring snapshot then streams live frames, with the same
+ * seq-based dedup the web `PtyTerminal` uses so no bytes are dropped or doubled
+ * across the attach boundary.
+ */
+declare function attachTunnel(conn: TunnelConnection, session: ResolvedPtySession, tty: TunnelTty, options?: AttachTunnelOptions): Promise<TunnelHandle>;
+interface RunTunnelOptions {
+    /** Reuse an existing task instead of creating a new card. */
+    taskId?: string;
+    /** Card fields (used only when `taskId` is not supplied). */
+    title?: string;
+    description?: string;
+    plan?: string;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    log?: (msg: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    onDetachRequest?: () => void;
+    /**
+     * Invoked once the PTY session is ready, immediately before attaching. The
+     * CLI uses this to enable raw TTY mode only at the last moment — before this
+     * point Ctrl-C should still raise SIGINT so the user can abort the wait.
+     */
+    onReady?: (session: ResolvedPtySession) => void;
+}
+interface TunnelSession {
+    taskId: string;
+    sessionId: string;
+    handle: TunnelHandle;
+}
+/**
+ * End-to-end flow: (optionally) create a cloud card, start the build, wait for
+ * the cloud PTY to come up, then attach the local terminal. Returns once the
+ * relay is live; the caller keeps the process alive and calls `handle.detach()`.
+ */
+declare function runTunnel(conn: TunnelConnection, tty: TunnelTty, options?: RunTunnelOptions): Promise<TunnelSession>;
+
+export { type ActivePtySession as A, type AttachTunnelOptions, ConveyorConnection as C, type PtyAttachSnapshot as P, type ResolvedPtySession, type RunTunnelOptions, type TunnelConnection, type TunnelHandle, type TunnelSession, type TunnelTty, type WaitForPtySessionOptions, type ConveyorMcpConfig as a, attachTunnel, type PtyDataChunk as b, runTunnel, waitForPtySession };

package/dist/tunnel.js

@@ -0,0 +1,11 @@
+import {
+  attachTunnel,
+  runTunnel,
+  waitForPtySession
+} from "./chunk-N2XC2PGJ.js";
+export {
+  attachTunnel,
+  runTunnel,
+  waitForPtySession
+};
+//# sourceMappingURL=tunnel.js.map

package/dist/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rallycry/conveyor-mcp",
+  "version": "2.1.1",
+  "description": "Conveyor MCP server for Claude Code PM integration",
+  "keywords": [
+    "claude",
+    "conveyor",
+    "mcp",
+    "project-management"
+  ],
+  "license": "MIT",
+  "bin": {
+    "conveyor-mcp": "dist/cli.js",
+    "conveyor-tunnel": "dist/tunnel-cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "tsup",
+    "build": "tsup",
+    "build:js": "tsup --no-dts --no-clean",
+    "dev": "tsup --watch",
+    "lint": "oxlint -c ../../.oxlintrc.json src",
+    "lint:fix": "oxlint -c ../../.oxlintrc.json --fix src",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:unit": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "socket.io-client": "^4.7.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.17"
+  }
+}