shipnoted-mcp 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# shipnoted-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let your coding agent draft and publish release notes, and read what your users are asking for.
+
+```sh
+claude mcp add shipnoted \
+  -e SHIPNOTED_API_KEY=snk_your_key \
+  -e SHIPNOTED_URL=https://shipnoted.com \
+  -e SHIPNOTED_PROJECT=your-slug \
+  -- npx -y shipnoted-mcp
+```
+
+Tools: `project_info`, `top_feedback`, `search_feedback`, `segments`, `get_request`, `themes`, `loop_status`, `list_releases`, `draft_release`, `set_feedback_status`, `file_request`, `publish_release`, `publish_draft`, `update_release`, `comment_on_request`. Read-only tools are marked `readOnlyHint`, and the ones customers can see have `destructiveHint`, so clients can ask before running them. Needs a Pro or Team plan (API keys). Give the key only the scopes the agent needs (a Read only key makes every write tool fail). Docs: https://shipnoted.com/docs/mcp

package/index.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// Shipnoted MCP server. Speaks Model Context Protocol over stdio (newline-delimited JSON-RPC 2.0) with no dependencies.
+// Env: SHIPNOTED_API_KEY (snk_...), SHIPNOTED_URL (default https://shipnoted.com), SHIPNOTED_PROJECT (your project slug).
+import readline from "node:readline"
+
+const KEY = process.env.SHIPNOTED_API_KEY ?? ""
+const URL_ = (process.env.SHIPNOTED_URL ?? "https://shipnoted.com").replace(/\/$/, "")
+const PROJECT = process.env.SHIPNOTED_PROJECT ?? ""
+const PROTOCOL = "2025-06-18"
+
+async function call(method, path, body) {
+  if (!KEY) throw new Error("SHIPNOTED_API_KEY is not set. Create a key in your Shipnoted dashboard under Install & connect.")
+  if (!PROJECT) throw new Error("SHIPNOTED_PROJECT is not set.")
+  const res = await fetch(`${URL_}/api/v1/${encodeURIComponent(PROJECT)}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${KEY}`, ...(body ? { "content-type": "application/json" } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  const data = await res.json().catch(() => ({}))
+  if (!res.ok || data.ok === false) throw new Error(data.error ?? `Shipnoted returned ${res.status}`)
+  return data
+}
+
+const TOOLS = [
+  {
+    name: "list_releases",
+    description: "List this project's recent releases, newest first, with their status (draft, scheduled, published).",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    run: async () => (await call("GET", "/releases")).releases.slice(0, 20).map((r) => `${r.status.toUpperCase()}  ${r.version || "-"}  ${r.title}  (${r.id})`).join("\n") || "No releases yet.",
+  },
+  {
+    name: "draft_release",
+    description: "Write a DRAFT release from a list of changes (pull request titles or commit messages). The draft is not published; review it in the dashboard or publish it with publish_release.",
+    inputSchema: { type: "object", properties: { changes: { type: "array", items: { type: "string" }, description: "One entry per change, e.g. 'feat: dark mode'" } }, required: ["changes"], additionalProperties: false },
+    run: async ({ changes }) => {
+      const r = await call("POST", "/draft", { items: (changes ?? []).map((title) => ({ title: String(title) })) })
+      return `Draft created (${r.source}). Release id: ${r.releaseId}. Review it in the dashboard before publishing.`
+    },
+  },
+  {
+    name: "publish_release",
+    description: "Create and publish a release immediately. Set email=true to email confirmed subscribers. Only do this when the user has approved the text.",
+    inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string", description: "Markdown" }, version: { type: "string" }, tags: { type: "array", items: { type: "string", enum: ["new", "improved", "fixed", "breaking"] } }, email: { type: "boolean" } }, required: ["title", "body"], additionalProperties: false },
+    run: async (a) => {
+      const r = await call("POST", "/releases", { ...a, publish: true })
+      return `Published: ${r.release.url}${r.emailed ? ` (${r.emailed} subscribers emailed)` : ""}`
+    },
+  },
+  {
+    name: "top_feedback",
+    description: "List the most-voted open feedback requests, to decide what to build next.",
+    inputSchema: { type: "object", properties: { status: { type: "string", enum: ["open", "planned", "progress", "shipped", "declined", "all"] } }, additionalProperties: false },
+    run: async ({ status }) => {
+      const r = await call("GET", `/feedback?sort=top${status && status !== "all" ? `&status=${status}` : ""}`)
+      return r.feedback.slice(0, 15).map((f) => `${String(f.votes).padStart(4)} votes  [${f.status}]  ${f.title}  (${f.id})`).join("\n") || "No feedback yet."
+    },
+  },
+  {
+    name: "get_request",
+    description: "Read one feedback request by its reference (SN-42) or id: its text, votes, revenue behind it, status, linked GitHub issues and public comments.",
+    inputSchema: { type: "object", properties: { ref: { type: "string", description: "SN-42 or a request id" } }, required: ["ref"], additionalProperties: false },
+    run: async ({ ref }) => {
+      const { request: r } = await call("GET", `/feedback/${encodeURIComponent(ref)}`)
+      return `${r.ref} [${r.status}] ${r.title}\n${r.votes} votes${r.mrrCents ? `, $${(r.mrrCents / 100).toLocaleString()}/mo behind it` : ""}\n\n${r.body || "(no description)"}${r.issues.length ? `\n\nIssues: ${r.issues.map((i) => `${i.repo}#${i.number} (${i.state})`).join(", ")}` : ""}${r.comments.length ? `\n\nComments:\n${r.comments.map((c) => `- ${c.author}${c.team ? " (team)" : ""}: ${c.body}`).join("\n")}` : ""}`
+    },
+  },
+  {
+    name: "comment_on_request",
+    description: "Reply to a request as the team (public), or leave an internal note only the team sees.",
+    inputSchema: { type: "object", properties: { ref: { type: "string" }, body: { type: "string" }, internal: { type: "boolean" } }, required: ["ref", "body"], additionalProperties: false },
+    run: async ({ ref, body, internal }) => {
+      await call("POST", `/feedback/${encodeURIComponent(ref)}/comments`, { body, internal: internal === true })
+      return internal ? "Internal note added." : "Reply posted."
+    },
+  },
+  {
+    name: "loop_status",
+    description: "How the feedback loop is doing: requests shipped, median days to ship, people told, and pull requests waiting for confirmation.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    run: async () => {
+      const { stats: s, suggestions } = await call("GET", "/loop")
+      return `Last 90 days: ${s.shipped} shipped of ${s.received} received. Median ${s.medianDaysToShip ?? "-"} days to ship. ${s.notified} people told.\nNext release draft holds ${s.waiting.draftItems} merged pull requests.${suggestions.length ? `\nWaiting for confirmation:\n${suggestions.map((x) => `- PR #${x.pullRequest ?? "?"} "${x.title}" may answer "${x.request}"`).join("\n")}` : ""}`
+    },
+  },
+  {
+    name: "themes",
+    description: "Open requests grouped into themes (the same wish in different words), biggest by revenue then votes. Use it to decide what to build.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    run: async () => (await call("GET", "/themes")).themes.slice(0, 10).map((t) => `${String(t.votes).padStart(4)} votes${t.mrrCents ? `  $${(t.mrrCents / 100).toLocaleString()}/mo` : ""}  ${t.label}  (${t.requests.length} request${t.requests.length === 1 ? "" : "s"}: ${t.requests.slice(0, 3).map((q) => q.id).join(", ")})`).join("\n") || "No themes yet.",
+  },
+  {
+    name: "publish_draft",
+    description: "Publish an existing draft release by id (for example the rolling draft from merged pull requests). Linked requests become Shipped and their voters are emailed. Only do this when the user has approved the text.",
+    inputSchema: { type: "object", properties: { id: { type: "string" }, email: { type: "boolean", description: "Also email subscribers" } }, required: ["id"], additionalProperties: false },
+    run: async ({ id, email }) => {
+      const r = await call("POST", `/releases/${encodeURIComponent(id)}/publish`, { email: email === true })
+      return `Published: ${r.url}. ${r.requestsShipped} requests shipped, ${r.votersNotified} voters told${r.emailed ? `, ${r.emailed} subscribers emailed` : ""}.`
+    },
+  },
+  {
+    name: "set_feedback_status",
+    description: "Move a feedback request to a new status so the public roadmap stays accurate.",
+    inputSchema: { type: "object", properties: { id: { type: "string" }, status: { type: "string", enum: ["open", "planned", "progress", "shipped", "declined"] } }, required: ["id", "status"], additionalProperties: false },
+    run: async ({ id, status }) => {
+      await call("POST", "/feedback", { id, status })
+      return `Moved ${id} to ${status}.`
+    },
+  },
+  {
+    name: "project_info",
+    description: "Which project this is: name, public address, the widget script tag, and counts of releases, requests and subscribers. A good first call to check the connection.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    run: async () => {
+      const { project: p } = await call("GET", "/project")
+      return `${p.name} (${p.slug}), ${p.live ? "live" : "offline"}\n${p.url}\n${p.counts.releases} releases, ${p.counts.requests} requests, ${p.counts.subscribers} subscribers\nWidget: ${p.widget}`
+    },
+  },
+  {
+    name: "search_feedback",
+    description: "Search requests by words or by customer group, for example everything the beta customers asked for. Returns the reference, votes, revenue and status of each.",
+    inputSchema: { type: "object", properties: { q: { type: "string" }, segment: { type: "string", description: 'A group such as "plan:Pro", "company:Acme" or "beta:true". See the segments tool.' }, status: { type: "string", enum: ["open", "planned", "progress", "shipped", "declined"] }, sort: { type: "string", enum: ["top", "revenue", "new"] } }, additionalProperties: false },
+    run: async ({ q, segment, status, sort }) => {
+      const p = new URLSearchParams()
+      for (const [k, v] of Object.entries({ q, segment, status, sort })) if (v) p.set(k, String(v))
+      const r = await call("GET", `/feedback${p.size ? `?${p}` : ""}`)
+      return r.feedback.slice(0, 25).map((f) => `${(f.ref || "").padEnd(7)} ${String(f.votes).padStart(4)} votes${f.mrrCents ? `  $${(f.mrrCents / 100).toLocaleString()}/mo` : ""}  [${f.status}]  ${f.title}`).join("\n") || "Nothing matches."
+    },
+  },
+  {
+    name: "segments",
+    description: "The customer groups that have voted (plan, company, custom attributes like beta:true) with their votes and revenue. Use the segment values with search_feedback.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    run: async () => (await call("GET", "/segments")).segments.map((s) => `${s.segment}  ${s.votes} votes${s.mrrCents ? `, $${(s.mrrCents / 100).toLocaleString()}/mo` : ""}`).join("\n") || "No identified customers have voted yet.",
+  },
+  {
+    name: "file_request",
+    description: "File a new feedback request on the board, for example from a support conversation. Send a stable idempotency_key (a ticket id) so a retry never files it twice.",
+    inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" }, email: { type: "string" }, name: { type: "string" }, source: { type: "string", description: "Where it came from, such as Intercom" }, idempotency_key: { type: "string" } }, required: ["title"], additionalProperties: false },
+    run: async ({ title, body, email, name, source, idempotency_key }) => {
+      const r = await call("POST", "/feedback", { title, body, email, name, source, idempotencyKey: idempotency_key })
+      return r.duplicate ? `Already filed as ${r.ref}.` : `Filed as ${r.ref}.`
+    },
+  },
+  {
+    name: "update_release",
+    description: "Edit a release (draft or published): title, version, notes, tags, or who it is for. Changes to a published release go live at once.",
+    inputSchema: { type: "object", properties: { id: { type: "string" }, title: { type: "string" }, version: { type: "string" }, body: { type: "string", description: "Markdown" }, tags: { type: "array", items: { type: "string", enum: ["new", "improved", "fixed", "breaking"] } }, audience: { type: "string", description: 'Aim it at a group, such as "plan:pro", or "" for everyone' } }, required: ["id"], additionalProperties: false },
+    run: async ({ id, ...fields }) => {
+      const r = await call("PATCH", `/releases/${encodeURIComponent(id)}`, fields)
+      return `Updated ${r.release.title} (${r.release.status}).`
+    },
+  },
+]
+
+const READ_ONLY = new Set(["list_releases", "top_feedback", "get_request", "loop_status", "themes", "project_info", "search_feedback", "segments"])
+// Tools that change what customers see or get emailed. Clients can use this to ask before running them.
+const PUBLIC_EFFECT = new Set(["publish_release", "publish_draft", "comment_on_request", "update_release"])
+const annotate = (name) => ({ title: name.replace(/_/g, " "), readOnlyHint: READ_ONLY.has(name), destructiveHint: PUBLIC_EFFECT.has(name), idempotentHint: READ_ONLY.has(name) || name === "set_feedback_status", openWorldHint: false })
+
+const send = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...msg }) + "\n")
+
+async function handle(msg) {
+  const { id, method, params } = msg
+  if (id === undefined) return // notifications need no reply
+  try {
+    if (method === "initialize") return send({ id, result: { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: "shipnoted", version: "0.3.0" } } })
+    if (method === "ping") return send({ id, result: {} })
+    if (method === "tools/list") return send({ id, result: { tools: TOOLS.map(({ run, ...t }) => ({ ...t, annotations: annotate(t.name) })) } })
+    if (method === "tools/call") {
+      const tool = TOOLS.find((t) => t.name === params?.name)
+      if (!tool) return send({ id, error: { code: -32602, message: `Unknown tool: ${params?.name}` } })
+      try {
+        const text = await tool.run(params.arguments ?? {})
+        return send({ id, result: { content: [{ type: "text", text: String(text) }] } })
+      } catch (e) {
+        return send({ id, result: { isError: true, content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }] } })
+      }
+    }
+    send({ id, error: { code: -32601, message: `Method not found: ${method}` } })
+  } catch (e) {
+    send({ id, error: { code: -32603, message: e instanceof Error ? e.message : "Internal error" } })
+  }
+}
+
+readline.createInterface({ input: process.stdin }).on("line", (line) => {
+  if (!line.trim()) return
+  try {
+    handle(JSON.parse(line))
+  } catch {
+    send({ id: null, error: { code: -32700, message: "Parse error" } })
+  }
+})

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "shipnoted-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "MCP server for Shipnoted: let your coding agent draft and publish release notes and read your users' feedback.",
+  "type": "module",
+  "bin": {
+    "shipnoted-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}