@open-and-async/mcp 0.0.1

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@open-and-async/mcp",
+  "version": "0.0.1",
+  "description": "Model Context Protocol server for the book Open and Async — async-first method tools plus the book's outline, taglines, and summaries. Ships the method, never the manuscript.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Ben Balter",
+  "homepage": "https://open-and-async.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-and-async/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/open-and-async/mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "async",
+    "remote-work",
+    "open-and-async",
+    "claude"
+  ],
+  "bin": {
+    "open-async-mcp": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "data/book.json",
+    "README.md",
+    "CODE-LICENSE.md",
+    "DATA-LICENSE.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  }
+}

package/src/data.js

@@ -0,0 +1,67 @@
+/**
+ * Loads the derived data artifact (data/book.json) and exposes shared helpers
+ * for the content tools and resources.
+ *
+ * The data file is built in the book repo by `just mcp-data`
+ * (script/build-mcp-data.js) and committed here as data/book.json. It contains
+ * ONLY already-public summaries (outline, TL;DRs, key-takeaways, taglines) and
+ * reviewed, paraphrased derived layers (frameworks, objections) — never
+ * verbatim book prose. See the book repo's docs/mcp-server-spec.md.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DATA_PATH = path.join(__dirname, "..", "data", "book.json");
+
+/** @typedef {{ slug: string, title: string, tldr: string, anchor: string }} Chapter */
+
+export const book = JSON.parse(fs.readFileSync(DATA_PATH, "utf8"));
+
+export const BUY_URL = book.buyUrl || "https://open-and-async.com";
+
+/** Every chapter, flattened out of the outline's section grouping. */
+export const chapters = book.outline.flatMap((section) =>
+  section.chapters.map((ch) => ({ ...ch, section: section.section })),
+);
+
+/** Look up a chapter by its slug (anchor without the leading #). */
+export function chapterBySlug(slug) {
+  const needle = String(slug || "")
+    .trim()
+    .replace(/^#/, "");
+  return chapters.find((ch) => ch.slug === needle) || null;
+}
+
+/**
+ * Guardrail: cap any text derived from the book at ~60 words so no single
+ * response reconstructs a chapter. Adds an ellipsis when truncated.
+ * @param {string} text
+ * @param {number} maxWords
+ * @returns {string}
+ */
+export function capWords(text, maxWords = 60) {
+  const words = String(text || "").split(/\s+/).filter(Boolean);
+  if (words.length <= maxWords) return words.join(" ");
+  return words.slice(0, maxWords).join(" ") + "…";
+}
+
+/**
+ * Build the attribution + funnel line every content response must include.
+ * @param {Chapter & { section?: string }} chapter
+ * @returns {string}
+ */
+export function cite(chapter) {
+  if (!chapter) return `— Open and Async. Get the book: ${BUY_URL}`;
+  return `— "${chapter.title}", Open and Async. Get the book: ${BUY_URL}`;
+}
+
+/** Wrap a tool result as MCP text content. */
+export function text(body) {
+  return { content: [{ type: "text", text: body }] };
+}
+
+/** Title-cased edition string for "which edition is this?" answers. */
+export const edition = `Open and Async — data v${book.version}`;

package/src/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/**
+ * Open and Async MCP server.
+ *
+ * Exposes the book's async-first *method* — decision-doc/ADR scaffolds, a
+ * meeting-to-async converter, a status-update rubric, an async standup, and a
+ * sync-vs-async triage — plus its already-public *summary* layer (outline,
+ * chapter TL;DRs, taglines, key-takeaways) and reviewed *derived* layer
+ * (frameworks, objections).
+ *
+ * It ships the method, never the manuscript: the only data file is
+ * data/book.json (built by `just mcp-data` in the book repo from already-public
+ * and reviewed-paraphrased content). No verbatim book prose is bundled.
+ *
+ * Transport: stdio. Run with `npx @open-and-async/mcp`.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { book } from "./data.js";
+import { registerMethodTools } from "./tools/methods.js";
+import { registerContentTools } from "./tools/content.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
+
+const server = new McpServer({
+  name: "open-async",
+  version: book.version,
+});
+
+registerMethodTools(server);
+registerContentTools(server);
+registerResources(server);
+registerPrompts(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// stderr is safe for logging on a stdio transport (stdout carries the protocol).
+console.error(
+  `open-async MCP server running (data v${book.version}) — method + summary tools ready.`,
+);

package/src/prompts.js

@@ -0,0 +1,108 @@
+/**
+ * Prompts — the "prompt pack," surfaced as native MCP prompts so users can
+ * invoke them directly from their client (e.g. slash commands). Each is a
+ * parameterized template that puts the book's method to work. No book prose.
+ */
+
+import { z } from "zod";
+
+/** Wrap a single user-role text message, the shape registerPrompt expects. */
+function userMessage(text) {
+  return { messages: [{ role: "user", content: { type: "text", text } }] };
+}
+
+export function registerPrompts(server) {
+  server.registerPrompt(
+    "async-standup",
+    {
+      title: "Async standup",
+      description:
+        "Draft an async standup post from your day's work — outcome-first, " +
+        "blockers surfaced, everything linked.",
+      argsSchema: {
+        work: z
+          .string()
+          .optional()
+          .describe("What you did / are doing, in rough notes."),
+      },
+    },
+    ({ work }) =>
+      userMessage(
+        `Write my async standup as exactly three short lines — "🟢 Shipped/progress", ` +
+          `"🎯 Today/next", "🔴 Blockers" — outcome-first and with links where I name work. ` +
+          `If I have no blockers, say "none" explicitly. Here are my rough notes:\n\n` +
+          `${work || "(paste your notes here)"}`,
+      ),
+  );
+
+  server.registerPrompt(
+    "write-adr",
+    {
+      title: "Write an ADR",
+      description:
+        "Draft an architecture/architectural decision record from a decision " +
+        "and its options.",
+      argsSchema: {
+        decision: z.string().describe("The decision to record."),
+        options: z
+          .string()
+          .optional()
+          .describe("Options under consideration, comma-separated."),
+      },
+    },
+    ({ decision, options }) =>
+      userMessage(
+        `Draft a decision record (ADR) for: "${decision}". ` +
+          `${options ? `Options under consideration: ${options}. ` : ""}` +
+          `Use these sections: Context, Options considered (each with pros, cons, ` +
+          `cost, risk), Decision (chosen option + one-sentence reason), ` +
+          `Reversibility (one-way vs two-way door), and Open questions / dissent. ` +
+          `Keep it tight and async-friendly so someone can follow it without a meeting.`,
+      ),
+  );
+
+  server.registerPrompt(
+    "meeting-to-issue",
+    {
+      title: "Meeting → issue",
+      description:
+        "Convert a meeting agenda into the async artifact that should replace it.",
+      argsSchema: {
+        agenda: z.string().describe("The meeting agenda or purpose."),
+      },
+    },
+    ({ agenda }) =>
+      userMessage(
+        `Here's a meeting agenda:\n\n${agenda}\n\n` +
+          `Convert it into the async equivalent. For each topic, tell me: the ` +
+          `artifact that replaces it (issue, doc, or PR comment), who the decision ` +
+          `owner is, and a "decide by" date. Flag anything that genuinely needs to ` +
+          `stay synchronous (sensitive, high-ambiguity, or active incident) and why. ` +
+          `Default to async; treat a meeting as the escalation, not the norm.`,
+      ),
+  );
+
+  server.registerPrompt(
+    "weekly-update",
+    {
+      title: "Weekly update",
+      description:
+        "Draft a weekly update that doesn't suck — outcomes over activity, " +
+        "risks surfaced early, skimmable.",
+      argsSchema: {
+        notes: z
+          .string()
+          .optional()
+          .describe("Your raw notes from the week."),
+      },
+    },
+    ({ notes }) =>
+      userMessage(
+        `Turn my week into a status update that leads with outcomes, not activity. ` +
+          `Structure it as: Headline (one line), Shipped (bullets, each linking the ` +
+          `work), Risks/blockers (surface anything at risk *before* it's late — say ` +
+          `"no surprises"), and Next. Keep it skimmable. My raw notes:\n\n` +
+          `${notes || "(paste your notes here)"}`,
+      ),
+  );
+}

package/src/resources.js

@@ -0,0 +1,58 @@
+/**
+ * Resources — read-only reference data, surfaced as MCP resources so clients
+ * can attach them to context directly.
+ *
+ * Both expose already-public summary data only (no body prose).
+ */
+
+import { book } from "./data.js";
+
+export function registerResources(server) {
+  server.registerResource(
+    "outline",
+    "book://outline",
+    {
+      title: "Open and Async — outline",
+      description:
+        "Sections, chapters, and one-line TL;DRs. The book's table of contents.",
+      mimeType: "application/json",
+    },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(
+            { version: book.version, outline: book.outline },
+            null,
+            2,
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerResource(
+    "taglines",
+    "book://taglines",
+    {
+      title: "Open and Async — taglines",
+      description:
+        "Shareable 'bumper-sticker' lines, each with its /q/<slug> quote-card URL.",
+      mimeType: "application/json",
+    },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(
+            { version: book.version, taglines: book.taglines },
+            null,
+            2,
+          ),
+        },
+      ],
+    }),
+  );
+}

package/src/tools/content.js

@@ -0,0 +1,330 @@
+/**
+ * Content tools — derived/summary only, capped, always cited, always funnel.
+ *
+ * These surface the book's already-public layer (outline, TL;DRs, taglines,
+ * key-takeaways) and its reviewed derived layer (frameworks, objections). Every
+ * response is capped at ~60 words from any one chapter, cites the chapter, and
+ * links to buy. No tool returns body text; nothing reconstructs a chapter.
+ */
+
+import { z } from "zod";
+import {
+  book,
+  chapters,
+  chapterBySlug,
+  capWords,
+  cite,
+  text,
+  BUY_URL,
+} from "../data.js";
+
+/** Lowercase haystack for keyword scoring. */
+function tokens(s) {
+  return String(s || "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 2);
+}
+
+export function registerContentTools(server) {
+  server.registerTool(
+    "book_outline",
+    {
+      title: "Book outline",
+      description:
+        "The map of Open and Async: every section and chapter with a one-line " +
+        "TL;DR. Use it to find the right chapter for a topic.",
+      inputSchema: {},
+    },
+    async () => {
+      const lines = book.outline.map((section) => {
+        const chs = section.chapters
+          .map((ch) => `  - **${ch.title}** (${ch.slug}) — ${ch.tldr}`)
+          .join("\n");
+        return `### ${section.section}\n${chs}`;
+      });
+      return text(
+        [
+          `# Open and Async — outline (v${book.version})`,
+          ``,
+          ...lines,
+          ``,
+          `Read the book: ${BUY_URL}`,
+        ].join("\n"),
+      );
+    },
+  );
+
+  server.registerTool(
+    "get_chapter_summary",
+    {
+      title: "Get a chapter summary",
+      description:
+        "Return a chapter's TL;DR plus its taglines and a link to read the full " +
+        "chapter. Summary only — no body text.",
+      inputSchema: {
+        slug: z
+          .string()
+          .describe("Chapter slug, e.g. 'impact-over-input' (from book_outline)."),
+      },
+    },
+    async ({ slug }) => {
+      const ch = chapterBySlug(slug);
+      if (!ch) {
+        const names = chapters.map((c) => c.slug).join(", ");
+        return text(
+          `No chapter with slug "${slug}". Available slugs:\n${names}`,
+        );
+      }
+      const tags = book.taglines.filter((t) => t.chapter === ch.slug);
+      const tagLines = tags.length
+        ? tags.map((t) => `- ${t.text} (${t.card})`).join("\n")
+        : "_(no taglines for this chapter)_";
+
+      return text(
+        [
+          `## ${ch.title}`,
+          `_Section: ${ch.section}_`,
+          ``,
+          `**TL;DR:** ${ch.tldr}`,
+          ``,
+          `**Taglines:**`,
+          tagLines,
+          ``,
+          cite(ch),
+        ].join("\n"),
+      );
+    },
+  );
+
+  server.registerTool(
+    "search_principles",
+    {
+      title: "Search the book's principles",
+      description:
+        "Keyword search across the book's summary corpus (TL;DRs, key-takeaways, " +
+        "taglines, and reviewed frameworks). Returns short, cited snippets — a " +
+        "snippet view, not full text.",
+      inputSchema: {
+        query: z.string().describe("What you're looking for."),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(10)
+          .optional()
+          .describe("Max results (default 5, capped at 10)."),
+      },
+    },
+    async ({ query, limit = 5 }) => {
+      const q = new Set(tokens(query));
+      const score = (s) => {
+        const t = tokens(s);
+        let n = 0;
+        for (const w of t) if (q.has(w)) n++;
+        return n;
+      };
+
+      const corpus = [];
+      for (const ch of chapters) {
+        corpus.push({ kind: "TL;DR", body: ch.tldr, ch });
+      }
+      for (const set of book.takeaways) {
+        for (const p of set.points) corpus.push({ kind: "Takeaway", body: p });
+      }
+      for (const t of book.taglines) {
+        corpus.push({
+          kind: "Tagline",
+          body: t.text,
+          ch: chapterBySlug(t.chapter),
+        });
+      }
+      for (const f of book.frameworks || []) {
+        corpus.push({
+          kind: "Framework",
+          body: f.guidance,
+          ch: chapterBySlug(f.anchor || f.chapter),
+        });
+      }
+
+      const ranked = corpus
+        .map((item) => ({ item, s: score(item.body) }))
+        .filter((r) => r.s > 0)
+        .sort((a, b) => b.s - a.s)
+        .slice(0, Math.min(limit, 10));
+
+      if (ranked.length === 0) {
+        return text(
+          `No matches for "${query}". Try book_outline to browse topics, then ` +
+            `get_chapter_summary for a specific chapter.\n\nRead the book: ${BUY_URL}`,
+        );
+      }
+
+      const out = ranked.map(({ item }) => {
+        const where = item.ch ? `\n${cite(item.ch)}` : "";
+        return `**[${item.kind}]** ${capWords(item.body)}${where}`;
+      });
+
+      return text(
+        [
+          `# Results for "${query}" (${ranked.length})`,
+          ``,
+          out.join("\n\n"),
+          ``,
+          `These are summaries. The full argument and stories are in the book: ${BUY_URL}`,
+        ].join("\n"),
+      );
+    },
+  );
+
+  server.registerTool(
+    "handle_objection",
+    {
+      title: "Handle an objection",
+      description:
+        "Map a common objection to open/async work ('async is slow', 'remote " +
+        "kills culture') to the book's reframe, with a chapter citation.",
+      inputSchema: {
+        objection: z.string().describe("The skepticism or pushback to address."),
+      },
+    },
+    async ({ objection }) => {
+      const objections = book.objections || [];
+      if (objections.length === 0) {
+        // Derived objection layer not yet reviewed/published — fall back to a
+        // pointer rather than inventing book content.
+        return text(
+          [
+            `The objection-handling layer is part of the book's reviewed derived ` +
+              `content and isn't bundled in this build yet.`,
+            ``,
+            `In the meantime, try \`search_principles\` with the core of the ` +
+              `objection (e.g. "${capWords(objection, 8)}") to find the relevant ` +
+              `chapter, then \`get_chapter_summary\`.`,
+            ``,
+            `The full reframe lives in the book: ${BUY_URL}`,
+          ].join("\n"),
+        );
+      }
+
+      const q = new Set(tokens(objection));
+      const best = objections
+        .map((o) => {
+          const t = tokens(`${o.trigger} ${o.reframe}`);
+          let n = 0;
+          for (const w of t) if (q.has(w)) n++;
+          return { o, n };
+        })
+        .sort((a, b) => b.n - a.n)[0];
+
+      if (!best || best.n === 0) {
+        return text(
+          `No direct match. Try \`search_principles\` for "${capWords(objection, 8)}".\n\nRead the book: ${BUY_URL}`,
+        );
+      }
+
+      const ch = chapterBySlug(best.o.anchor || best.o.chapter);
+      return text(
+        [
+          `**Objection:** "${best.o.trigger}"`,
+          ``,
+          `**Reframe:** ${capWords(best.o.reframe)}`,
+          ``,
+          cite(ch),
+        ].join("\n"),
+      );
+    },
+  );
+
+  server.registerTool(
+    "get_guidance",
+    {
+      title: "Get role-aware guidance",
+      description:
+        "Role-aware guidance (manager or IC) for a topic, paraphrased from the " +
+        "book's role callouts, with a chapter citation.",
+      inputSchema: {
+        topic: z.string().describe("The topic you want guidance on."),
+        role: z
+          .enum(["manager", "ic", "any"])
+          .optional()
+          .describe("Audience: 'manager', 'ic', or 'any' (default)."),
+      },
+    },
+    async ({ topic, role = "any" }) => {
+      const frameworks = book.frameworks || [];
+      if (frameworks.length === 0) {
+        return text(
+          [
+            `Role-aware guidance comes from the book's reviewed derived layer, ` +
+              `which isn't bundled in this build yet.`,
+            ``,
+            `Try \`search_principles\` for "${capWords(topic, 8)}" to find the ` +
+              `relevant chapter, then \`get_chapter_summary\`.`,
+            ``,
+            `Read the book: ${BUY_URL}`,
+          ].join("\n"),
+        );
+      }
+
+      const q = new Set(tokens(topic));
+      const ranked = frameworks
+        .filter((f) => role === "any" || !f.role || f.role === "any" || f.role === role)
+        .map((f) => {
+          const t = tokens(`${f.topic} ${f.guidance}`);
+          let n = 0;
+          for (const w of t) if (q.has(w)) n++;
+          return { f, n };
+        })
+        .filter((r) => r.n > 0)
+        .sort((a, b) => b.n - a.n)
+        .slice(0, 3);
+
+      if (ranked.length === 0) {
+        return text(
+          `No guidance matched "${topic}" for role "${role}". Try \`search_principles\`.\n\nRead the book: ${BUY_URL}`,
+        );
+      }
+
+      const out = ranked.map(({ f }) => {
+        const ch = chapterBySlug(f.anchor || f.chapter);
+        const label = f.role && f.role !== "any" ? ` _(${f.role})_` : "";
+        return `**${f.topic}**${label}\n${capWords(f.guidance)}\n${cite(ch)}`;
+      });
+
+      return text(out.join("\n\n"));
+    },
+  );
+
+  server.registerTool(
+    "get_taglines",
+    {
+      title: "Get taglines",
+      description:
+        "Return the book's shareable taglines and their quote-card URLs. " +
+        "Optionally filter to one chapter.",
+      inputSchema: {
+        chapter: z
+          .string()
+          .optional()
+          .describe("Chapter slug to filter by (omit for all)."),
+      },
+    },
+    async ({ chapter }) => {
+      let tags = book.taglines;
+      if (chapter) {
+        const slug = chapter.replace(/^#/, "");
+        tags = tags.filter((t) => t.chapter === slug);
+        if (tags.length === 0) {
+          return text(`No taglines for chapter "${chapter}".`);
+        }
+      }
+      const lines = tags.map(
+        (t) => `- **${t.text}**\n  ${t.chapter_title} · ${t.card}`,
+      );
+      return text(
+        [`# Taglines${chapter ? ` — ${chapter}` : ""}`, ``, ...lines].join("\n"),
+      );
+    },
+  );
+}