vessels-mcp 0.2.0

package/dist/index.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { Vessels } from "vessels-sdk";
+function resolveKey() {
+  const env = process.env.VESSELS_API_KEY;
+  if (env && !env.startsWith("${")) return env;
+  try {
+    const k = readFileSync(join(homedir(), ".thru-do-vessels-key"), "utf8").trim();
+    if (k) return k;
+  } catch {
+  }
+  return void 0;
+}
+var apiKey = resolveKey();
+var defaultVessel = process.env.VESSELS_VESSEL ?? "claude-code";
+var vesselTitle = process.env.VESSELS_VESSEL_TITLE ?? "Claude Code";
+var baseUrl = process.env.VESSELS_BASE_URL ?? "https://vessels.app";
+if (!apiKey) {
+  console.error("[vessels-mcp] no VESSELS_API_KEY (env or ~/.thru-do-vessels-key)");
+  process.exit(1);
+}
+var v = new Vessels({ apiKey, baseUrl });
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var ok = (text) => ({ content: [{ type: "text", text }] });
+async function drain() {
+  for (; ; ) {
+    const r = await v.poll({ ack: true, limit: 100 });
+    if (!r.hasMore) return;
+  }
+}
+function formatAnswer(e) {
+  const r = e.response ?? {};
+  switch (e.interactionType) {
+    case "approval":
+      return (r.action === "approved" ? "APPROVED" : "REJECTED") + (r.reason ? `: ${r.reason}` : "");
+    case "choice":
+      return `CHOSE: ${r.selected}${r.customValue ? ` (custom: ${r.customValue})` : ""}`;
+    case "checklist":
+      return `SELECTED: ${(r.selected ?? []).join(", ") || "(none)"}`;
+    case "text_input":
+      return `TEXT: ${r.text ?? ""}`;
+    case "questions":
+      return (r.answers ?? []).map((a) => `${a.questionId}=${(a.selected ?? []).join("/")}${a.other ? ` (${a.other})` : ""}`).join("; ");
+    default:
+      return JSON.stringify(r);
+  }
+}
+async function ask(vessel, prompt, build, expectedType) {
+  var _a, _b;
+  await drain();
+  const { messageId } = await v.push({ vessel, vesselTitle, message: prompt, interaction: build });
+  console.error(`[vessels-mcp] ask posted ${messageId} (${expectedType}) on "${vessel}" \u2014 waiting\u2026`);
+  for (; ; ) {
+    const r = await v.poll({ ack: true, limit: 100 });
+    for (const e of r.events) {
+      if (e.type !== "interaction.response") continue;
+      const idMatch = e.messageId === messageId || ((_a = e.originMessage) == null ? void 0 : _a.id) === messageId;
+      const vesselMatch = ((_b = e.vessel) == null ? void 0 : _b.externalId) === vessel && e.interactionType === expectedType;
+      if (idMatch || vesselMatch) return formatAnswer(e);
+    }
+    if (!r.hasMore) await sleep(2e3);
+  }
+}
+var server = new McpServer({ name: "vessels", version: "0.2.0" });
+server.registerTool(
+  "list_vessels",
+  {
+    title: "List vessels",
+    description: "List the vessels (conversations) in the workspace so you can pick one to act on. Returns one compact line per vessel: external_id, status, title, labels. Use the external_id as the `vessel` argument to other tools.",
+    inputSchema: {
+      limit: z.number().optional().describe("Max vessels to return (default 30)."),
+      archived: z.boolean().optional().describe("Include archived vessels (default false).")
+    }
+  },
+  async ({ limit, archived }) => {
+    const res = await fetch(`${baseUrl}/api/v1/vessels?archived=${archived ? "true" : "false"}`, {
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    const data = await res.json();
+    if (!res.ok) return ok(`error: ${data.error ?? res.status}`);
+    const rows = (data.vessels ?? []).slice(0, limit ?? 30);
+    if (!rows.length) return ok("(no vessels)");
+    const lines = rows.map((x) => {
+      const labels = (x.labels ?? []).length ? ` [${x.labels.join(",")}]` : "";
+      return `${x.external_id}  \xB7${x.status}${x.pinned ? " \xB7pinned" : ""}  "${x.title ?? ""}"${labels}`;
+    });
+    return ok(lines.join("\n"));
+  }
+);
+server.registerTool(
+  "read_vessel",
+  {
+    title: "Read a vessel",
+    description: 'Read the recent messages in a vessel as a compact transcript (oldest\u2192newest), so you have context before replying. Each line is "[source] text" (truncated). Use after list_vessels.',
+    inputSchema: {
+      vessel: z.string().optional().describe(`Vessel external_id (default "${defaultVessel}").`),
+      limit: z.number().optional().describe("How many recent messages (default 20).")
+    }
+  },
+  async ({ vessel, limit }) => {
+    const { messages: msgs } = await v.getMessages({ vessel: vessel ?? defaultVessel, limit: limit ?? 20 });
+    if (!msgs.length) return ok("(no messages)");
+    const lines = msgs.map((m) => {
+      let body = m.content ?? "";
+      if (!body && m.interaction) body = `[${m.interaction.type}] ${m.interaction.prompt ?? ""}`;
+      body = body.replace(/\s+/g, " ").slice(0, 200);
+      return `[${m.source}] ${body}`;
+    });
+    return ok(lines.join("\n"));
+  }
+);
+server.registerTool(
+  "notify",
+  {
+    title: "Notify (one-way)",
+    description: "Send a one-line status message to the human. Does not wait. Use to keep them informed.",
+    inputSchema: {
+      message: z.string().describe("The message text."),
+      vessel: z.string().optional().describe(`Vessel external_id (default "${defaultVessel}").`)
+    }
+  },
+  async ({ message, vessel }) => {
+    await v.push({ vessel: vessel ?? defaultVessel, vesselTitle, message });
+    return ok("ok");
+  }
+);
+server.registerTool(
+  "send",
+  {
+    title: "Send a message or artifact",
+    description: 'Post a message to a vessel. For a chat reply pass `message`. For a full-width artifact (proposal, report, diff, review) pass `body` (block markdown: headings/lists/tables/quotes) and optionally `title` + `card`. Also supports `pinCard` (persistent header), `labels`, `suggestions` (quick-reply chips), `previewUrl` (a link card), and `status` to set the vessel state. Returns the new message id as "mid:<id>".',
+    inputSchema: {
+      message: z.string().optional().describe("Chat-bubble text (use this OR body)."),
+      body: z.string().optional().describe("Surface artifact body \u2014 block markdown."),
+      title: z.string().optional().describe("Surface heading."),
+      card: z.object({ title: z.string().optional(), fields: z.array(z.object({ label: z.string(), value: z.string() })) }).optional().describe("Glance-facts card (label/value rows)."),
+      pinCard: z.object({ title: z.string().optional(), fields: z.array(z.object({ label: z.string(), value: z.string() })) }).optional().describe("Persistent pinned header card for the vessel."),
+      labels: z.array(z.string()).optional().describe("Triage labels (replace semantics)."),
+      suggestions: z.array(z.string()).optional().describe("Quick-reply suggestion chips."),
+      previewUrl: z.string().optional().describe("A single URL rendered as a link card."),
+      status: z.enum(["active", "waiting", "resolved"]).optional().describe("Set the vessel status."),
+      vessel: z.string().optional().describe(`Vessel external_id (default "${defaultVessel}").`)
+    }
+  },
+  async ({ message, body, title, card, pinCard, labels, suggestions, previewUrl, status, vessel }) => {
+    const common = {
+      vessel: vessel ?? defaultVessel,
+      vesselTitle,
+      ...title ? { title } : {},
+      ...card ? { card } : {},
+      ...pinCard ? { pinCard } : {},
+      ...labels ? { labels } : {},
+      ...suggestions ? { suggestions } : {},
+      ...previewUrl ? { previewUrl } : {},
+      ...status ? { vesselStatus: status } : {}
+    };
+    if (!message && !body) return ok("error: provide `message` or `body`");
+    const res = body ? await v.surface({ ...common, body }) : await v.push({ ...common, message });
+    return ok(`mid:${res.messageId}`);
+  }
+);
+server.registerTool(
+  "ask_human",
+  {
+    title: "Ask the human (blocks until answered)",
+    description: 'Ask the operator a question via Vessels and BLOCK until they answer (may take a long time \u2014 that is fine). Types: "approval" (yes/no \u2192 APPROVED/REJECTED, default), "choice" (pick one of `choices`), "checklist" (pick many of `choices`), "text" (free text), "questions" (a small multi-question form via `questions`). Returns the answer as a terse string.',
+    inputSchema: {
+      prompt: z.string().describe("The question/heading. Be specific; include what you did."),
+      type: z.enum(["approval", "choice", "checklist", "text", "questions"]).optional().describe('Default "approval".'),
+      choices: z.array(z.string()).optional().describe("Options for choice/checklist."),
+      minSelections: z.number().optional().describe("Checklist: minimum picks."),
+      multiline: z.boolean().optional().describe("Text: allow multiline."),
+      reasonRequired: z.boolean().optional().describe("Approval: require a typed reason."),
+      questions: z.array(
+        z.object({
+          id: z.string(),
+          question: z.string(),
+          header: z.string().optional(),
+          options: z.array(z.object({ id: z.string(), label: z.string(), description: z.string().optional() })),
+          multiSelect: z.boolean().optional()
+        })
+      ).optional().describe('For type "questions": 1\u20134 questions, each with 2\u20134 options.'),
+      vessel: z.string().optional().describe(`Vessel external_id (default "${defaultVessel}").`)
+    }
+  },
+  async ({ prompt, type, choices, minSelections, multiline, reasonRequired, questions, vessel }) => {
+    const tgt = vessel ?? defaultVessel;
+    const t = type ?? "approval";
+    let build;
+    let expected = "approval";
+    if (t === "choice") {
+      build = v.choice({ prompt, options: (choices ?? []).map((c) => ({ id: c, label: c })), allowCustom: true });
+      expected = "choice";
+    } else if (t === "checklist") {
+      build = v.checklist({ prompt, options: (choices ?? []).map((c) => ({ id: c, label: c })), minSelections });
+      expected = "checklist";
+    } else if (t === "text") {
+      build = v.textInput({ prompt, multiline });
+      expected = "text_input";
+    } else if (t === "questions") {
+      build = v.questions({ prompt, questions: questions ?? [] });
+      expected = "questions";
+    } else {
+      build = v.approval({ prompt, reasonRequired });
+      expected = "approval";
+    }
+    return ok(await ask(tgt, prompt, build, expected));
+  }
+);
+server.registerTool(
+  "wait_for_reply",
+  {
+    title: "Wait for a free-text reply (blocks)",
+    description: "Optionally post `prompt`, then BLOCK until the human sends a free-text message in the vessel, and return that message text. Use for open-ended back-and-forth (vs ask_human for structured decisions).",
+    inputSchema: {
+      prompt: z.string().optional().describe("Optional message to post before waiting."),
+      vessel: z.string().optional().describe(`Vessel external_id (default "${defaultVessel}").`)
+    }
+  },
+  async ({ prompt, vessel }) => {
+    var _a, _b;
+    const tgt = vessel ?? defaultVessel;
+    await drain();
+    if (prompt) await v.push({ vessel: tgt, vesselTitle, message: prompt });
+    for (; ; ) {
+      const r = await v.poll({ ack: true, limit: 100 });
+      for (const e of r.events) {
+        if (e.type === "message.user" && ((_a = e.vessel) == null ? void 0 : _a.externalId) === tgt) {
+          return ok(((_b = e.message) == null ? void 0 : _b.content) ?? "");
+        }
+      }
+      if (!r.hasMore) await sleep(2e3);
+    }
+  }
+);
+server.registerTool(
+  "update_message",
+  {
+    title: "Edit a message",
+    description: "Patch an existing message by id (from a `send`/`activity` result). Update its `message` text, `card`, `title`, or `status`. Useful to revise an artifact or close out a vessel.",
+    inputSchema: {
+      messageId: z.string().describe('The message id (e.g. from "mid:<id>").'),
+      message: z.string().optional(),
+      title: z.string().optional(),
+      card: z.object({ title: z.string().optional(), fields: z.array(z.object({ label: z.string(), value: z.string() })) }).optional(),
+      status: z.enum(["active", "waiting", "resolved"]).optional().describe("Set the vessel status.")
+    }
+  },
+  async ({ messageId, message, title, card, status }) => {
+    const patch = {
+      ...message ? { content: message } : {},
+      ...title ? { title } : {},
+      ...card ? { card } : {},
+      ...status ? { vesselStatus: status } : {}
+    };
+    await v.editMessage(messageId, patch);
+    return ok("ok");
+  }
+);
+server.registerTool(
+  "activity",
+  {
+    title: "Drive a working card",
+    description: 'Show a live "working" card. action "start" opens it (returns "mid:<id>"); "update" sets the `plan` (full todo list, each "label" or "label|done"/"label|in_progress"), appends a `step` label, or sets `status` (working/awaiting_input); "finish" seals it. Pass the start id as `workId` for update/finish.',
+    inputSchema: {
+      action: z.enum(["start", "update", "finish"]),
+      workId: z.string().optional().describe('Message id from "start" (required for update/finish).'),
+      label: z.string().optional().describe("start: the card headline."),
+      plan: z.array(z.string()).optional().describe('update: full todo list ("label" or "label|done"|"label|in_progress").'),
+      step: z.string().optional().describe("update: append a step with this label."),
+      status: z.enum(["working", "awaiting_input"]).optional().describe("update: lifecycle."),
+      vessel: z.string().optional().describe(`Vessel external_id (default "${defaultVessel}").`)
+    }
+  },
+  async ({ action, workId, label, plan, step, status, vessel }) => {
+    const tgt = vessel ?? defaultVessel;
+    const todos = plan == null ? void 0 : plan.map((p) => {
+      const [l, s] = p.split("|");
+      return { label: l.trim(), ...s ? { status: s.trim() } : {} };
+    });
+    if (action === "start") {
+      const res = await v.push({
+        vessel: tgt,
+        vesselTitle,
+        message: label ?? "Working\u2026",
+        agentActivity: todos ? { todos } : { status: "working" }
+      });
+      return ok(`mid:${res.messageId}`);
+    }
+    if (!workId) return ok("error: workId required for update/finish");
+    if (action === "finish") {
+      await v.editMessage(workId, { agentActivity: null });
+      return ok("ok");
+    }
+    if (todos) await v.editMessage(workId, { agentActivity: { todos } });
+    if (step) await v.editMessage(workId, { agentActivity: { type: "tool_use", label: step } });
+    if (status) await v.editMessage(workId, { agentActivity: { status } });
+    return ok("ok");
+  }
+);
+await server.connect(new StdioServerTransport());
+console.error(`[vessels-mcp] ready \u2014 default vessel "${defaultVessel}" @ ${baseUrl}`);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "vessels-mcp",
+  "version": "0.2.0",
+  "description": "Vessels MCP server — give any MCP client (Claude Code, Cursor, …) a tool to message a human and BLOCK until they answer.",
+  "type": "module",
+  "bin": {
+    "vessels-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "agents",
+    "vessels",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22",
+    "vessels-sdk": "0.16.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5",
+    "@types/node": "^25.5.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}