@shadow-garden/bapbong-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Le Phuoc Minh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/host.cjs

@@ -0,0 +1,548 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/mcp/src/host.ts
+var host_exports = {};
+__export(host_exports, {
+  AnchorError: () => AnchorError,
+  NoDocumentError: () => NoDocumentError,
+  PmDocSession: () => PmDocSession,
+  RemoteSession: () => RemoteSession,
+  VersionConflictError: () => VersionConflictError,
+  createMcpServer: () => createMcpServer,
+  executeOp: () => executeOp,
+  reviveError: () => reviveError
+});
+module.exports = __toCommonJS(host_exports);
+
+// packages/mcp/src/lib/contract.ts
+var VersionConflictError = class extends Error {
+  constructor(current, expected) {
+    super(
+      `Document changed (version is now ${current}, you expected ${expected}). Call get_document again, re-locate your anchor, then retry.`
+    );
+    this.name = "VersionConflictError";
+  }
+};
+var AnchorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AnchorError";
+  }
+};
+var NoDocumentError = class extends Error {
+  constructor(message = "No document is open. Ask the user to open a document first.") {
+    super(message);
+    this.name = "NoDocumentError";
+  }
+};
+
+// packages/mcp/src/lib/pm-session.ts
+var MARK_BY_FLAG = { bold: "strong", italic: "em", underline: "underline", strike: "strike" };
+var PmDocSession = class {
+  constructor(host) {
+    this.host = host;
+    this.capabilities = { selection: typeof host.selection === "function" };
+  }
+  host;
+  capabilities;
+  // ── reads ────────────────────────────────────────────────────────────
+  async snapshot() {
+    const blocks = this.textblocks().map(({ node }, index) => {
+      const block = { index, type: blockType(node), text: node.textContent };
+      const images = blockImages(node).map(({ node: img }, i) => ({
+        index: i,
+        alt: String(img.attrs["alt"] ?? ""),
+        width: Number(img.attrs["width"]) || 0,
+        height: Number(img.attrs["height"]) || 0,
+        rotation: Number(img.attrs["rotation"]) || 0,
+        kind: img.attrs["shape"] ? "shape" : "bitmap"
+      }));
+      if (images.length > 0) block.images = images;
+      return block;
+    });
+    return { docVersion: this.host.getVersion(), blocks, meta: this.host.meta() };
+  }
+  async find(query) {
+    return this.hits(query).map((h, i) => ({ blockIndex: h.blockIndex, occurrence: i + 1, context: h.context }));
+  }
+  async getSelection() {
+    const sel = this.host.selection?.();
+    if (!sel || sel.from === sel.to) return null;
+    const state = this.host.getState();
+    const text = state.doc.textBetween(sel.from, sel.to, "\n");
+    const blockIndex = this.textblocks().findIndex(
+      ({ node, pos }) => sel.from >= pos && sel.from <= pos + node.nodeSize
+    );
+    return { text, blockIndex };
+  }
+  // ── mutations ────────────────────────────────────────────────────────
+  async replaceText(oldText, newText, opts = {}) {
+    this.checkVersion(opts.expectedVersion);
+    const hit = this.uniqueHit(oldText, opts.occurrence);
+    this.host.apply(this.host.getState().tr.insertText(newText, hit.from, hit.to));
+    return { docVersion: this.host.getVersion(), range: { from: hit.from, to: hit.from + newText.length } };
+  }
+  async insertContent(content, anchor, opts = {}) {
+    this.checkVersion(opts.expectedVersion);
+    const state = this.host.getState();
+    const { schema } = state;
+    const paragraphs = content.split("\n").map((line) => schema.node("paragraph", null, line.length > 0 ? [schema.text(line)] : []));
+    let insertAt;
+    if (anchor.position === "document_end") {
+      insertAt = state.doc.content.size;
+    } else {
+      const hit = this.uniqueHit(anchor.text, anchor.occurrence);
+      const block = this.textblocks()[hit.blockIndex];
+      insertAt = anchor.position === "before" ? block.pos : block.pos + block.node.nodeSize;
+    }
+    const inserted = paragraphs.reduce((size, node) => size + node.nodeSize, 0);
+    this.host.apply(state.tr.insert(insertAt, paragraphs));
+    return { docVersion: this.host.getVersion(), range: { from: insertAt, to: insertAt + inserted } };
+  }
+  async applyFormatting(target, format, opts = {}) {
+    this.checkVersion(opts.expectedVersion);
+    const hit = this.uniqueHit(target, opts.occurrence);
+    const state = this.host.getState();
+    const { schema } = state;
+    let tr = state.tr;
+    for (const [flag, markName] of Object.entries(MARK_BY_FLAG)) {
+      const want = format[flag];
+      if (want === void 0) continue;
+      const mark = schema.marks[markName];
+      if (!mark) continue;
+      tr = want ? tr.addMark(hit.from, hit.to, mark.create()) : tr.removeMark(hit.from, hit.to, mark);
+    }
+    if (format.align) {
+      const block = this.textblocks()[hit.blockIndex];
+      tr = tr.setNodeMarkup(block.pos, void 0, { ...block.node.attrs, align: format.align });
+    }
+    if (tr.steps.length === 0) {
+      return { docVersion: this.host.getVersion() };
+    }
+    this.host.apply(tr);
+    return { docVersion: this.host.getVersion(), range: { from: hit.from, to: hit.to } };
+  }
+  async updateImage(blockIndex, imageIndex, changes, opts = {}) {
+    this.checkVersion(opts.expectedVersion);
+    const blocks = this.textblocks();
+    const block = blocks[blockIndex];
+    if (!block) {
+      throw new AnchorError(
+        `blockIndex ${blockIndex} is out of range \u2014 the document has ${blocks.length} block(s). Block indexes change with every edit; call get_document again.`
+      );
+    }
+    const images = blockImages(block.node).map((img2) => ({ ...img2, pos: block.pos + 1 + img2.offset }));
+    if (images.length === 0) {
+      throw new AnchorError(`Block ${blockIndex} has no images. get_document lists each block's images.`);
+    }
+    const img = images[imageIndex];
+    if (!img) {
+      throw new AnchorError(
+        `imageIndex ${imageIndex} is out of range \u2014 block ${blockIndex} has ${images.length} image(s) (0-${images.length - 1}).`
+      );
+    }
+    let tr = this.host.getState().tr;
+    if (changes.width !== void 0) tr = tr.setNodeAttribute(img.pos, "width", Math.max(1, Math.round(changes.width)));
+    if (changes.height !== void 0) tr = tr.setNodeAttribute(img.pos, "height", Math.max(1, Math.round(changes.height)));
+    if (changes.rotation !== void 0) {
+      tr = tr.setNodeAttribute(img.pos, "rotation", (changes.rotation % 360 + 360) % 360);
+    }
+    if (tr.steps.length === 0) return { docVersion: this.host.getVersion() };
+    this.host.apply(tr);
+    return { docVersion: this.host.getVersion(), range: { from: img.pos, to: img.pos + 1 } };
+  }
+  async save() {
+    await this.host.save();
+  }
+  async close() {
+  }
+  // ── internals ────────────────────────────────────────────────────────
+  checkVersion(expected) {
+    const current = this.host.getVersion();
+    if (expected !== void 0 && expected !== current) {
+      throw new VersionConflictError(current, expected);
+    }
+  }
+  /** All textblocks (paragraphs, incl. inside table cells) in reading order. */
+  textblocks() {
+    const out = [];
+    this.host.getState().doc.descendants((node, pos) => {
+      if (node.isTextblock) {
+        out.push({ node, pos });
+        return false;
+      }
+      return true;
+    });
+    return out;
+  }
+  /** Every occurrence of `query`, atom-safe (matches never span images/fields
+   *  or block boundaries), in document order with absolute PM positions. */
+  hits(query) {
+    if (query.length === 0) return [];
+    const out = [];
+    this.textblocks().forEach(({ node, pos }, blockIndex) => {
+      const segments = [];
+      let joined = "";
+      node.forEach((child, offset) => {
+        if (child.isText && child.text) {
+          segments.push({ joinedStart: joined.length, length: child.text.length, startPos: pos + 1 + offset });
+          joined += child.text;
+        } else {
+          joined += "\uFFFF";
+        }
+      });
+      let at = joined.indexOf(query);
+      while (at !== -1) {
+        const seg = segments.find((s) => at >= s.joinedStart && at < s.joinedStart + s.length);
+        if (seg) {
+          const from = seg.startPos + (at - seg.joinedStart);
+          out.push({
+            from,
+            to: from + query.length,
+            blockIndex,
+            context: contextAround(joined.replace(/￿/g, " "), at, query.length)
+          });
+        }
+        at = joined.indexOf(query, at + 1);
+      }
+    });
+    return out;
+  }
+  uniqueHit(text, occurrence2) {
+    const all = this.hits(text);
+    if (all.length === 0) {
+      throw new AnchorError(
+        `Text not found in the document: ${JSON.stringify(clip(text))}. Anchors match within one paragraph \u2014 check get_document for the exact text.`
+      );
+    }
+    if (occurrence2 !== void 0) {
+      const hit = all[occurrence2 - 1];
+      if (!hit) {
+        throw new AnchorError(`occurrence ${occurrence2} is out of range \u2014 the text matches ${all.length} time(s).`);
+      }
+      return hit;
+    }
+    if (all.length > 1) {
+      throw new AnchorError(
+        `The text matches ${all.length} times \u2014 pass occurrence (1-${all.length}) to pick one, or use a longer, unique anchor.`
+      );
+    }
+    return all[0];
+  }
+};
+function blockImages(block) {
+  const out = [];
+  block.forEach((child, offset) => {
+    if (child.type.name === "image") out.push({ node: child, offset });
+  });
+  return out;
+}
+function blockType(node) {
+  const heading = node.attrs["heading"];
+  if (typeof heading === "number" && heading >= 1) return `heading${heading}`;
+  return node.type.name;
+}
+function contextAround(text, at, len) {
+  const before = text.slice(Math.max(0, at - 30), at);
+  const after = text.slice(at + len, at + len + 30);
+  return `${before}\xAB${text.slice(at, at + len)}\xBB${after}`;
+}
+function clip(s) {
+  return s.length > 60 ? `${s.slice(0, 57)}\u2026` : s;
+}
+
+// packages/mcp/src/lib/wire.ts
+async function executeOp(session, request) {
+  try {
+    if (!session) throw new NoDocumentError();
+    const value = await run(session, request);
+    return { id: request.id, ok: true, value };
+  } catch (err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    return { id: request.id, ok: false, error: { name: e.name, message: e.message } };
+  }
+}
+function run(session, { op, args }) {
+  switch (op) {
+    case "snapshot":
+      return session.snapshot();
+    case "find":
+      return session.find(args[0]);
+    case "replaceText":
+      return session.replaceText(args[0], args[1], args[2]);
+    case "insertContent":
+      return session.insertContent(args[0], args[1], args[2]);
+    case "applyFormatting":
+      return session.applyFormatting(args[0], args[1], args[2]);
+    case "updateImage":
+      return session.updateImage(
+        args[0],
+        args[1],
+        args[2],
+        args[3]
+      );
+    case "getSelection":
+      return session.getSelection?.() ?? Promise.resolve(null);
+    case "save":
+      return session.save();
+    default:
+      return Promise.reject(new Error(`unknown session op: ${op}`));
+  }
+}
+function reviveError(error) {
+  switch (error.name) {
+    case "AnchorError":
+      return new AnchorError(error.message);
+    case "NoDocumentError":
+      return new NoDocumentError(error.message);
+    case "VersionConflictError": {
+      const revived = new VersionConflictError("?", "?");
+      revived.message = error.message;
+      return revived;
+    }
+    default: {
+      const generic = new Error(error.message);
+      generic.name = error.name;
+      return generic;
+    }
+  }
+}
+var RemoteSession = class {
+  constructor(send, capabilities) {
+    this.send = send;
+    this.capabilities = capabilities;
+  }
+  send;
+  capabilities;
+  async call(op, args = []) {
+    return await this.send(op, args);
+  }
+  snapshot() {
+    return this.call("snapshot");
+  }
+  find(query) {
+    return this.call("find", [query]);
+  }
+  replaceText(oldText, newText, opts) {
+    return this.call("replaceText", [oldText, newText, opts]);
+  }
+  insertContent(content, anchor, opts) {
+    return this.call("insertContent", [content, anchor, opts]);
+  }
+  applyFormatting(target, format, opts) {
+    return this.call("applyFormatting", [target, format, opts]);
+  }
+  updateImage(blockIndex, imageIndex, changes, opts) {
+    return this.call("updateImage", [blockIndex, imageIndex, changes, opts]);
+  }
+  async getSelection() {
+    return this.call("getSelection");
+  }
+  async save() {
+    await this.call("save");
+  }
+  async close() {
+  }
+};
+
+// packages/mcp/src/lib/server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_zod = require("zod");
+var documentId = import_zod.z.string().optional().describe("Target document id. Omit for the currently open document (desktop).");
+var expectedVersion = import_zod.z.string().optional().describe("docVersion you last read. If the document changed since, the call fails and you must re-read.");
+var occurrence = import_zod.z.number().int().min(1).optional().describe("1-based pick when the anchor text matches more than once (document order).");
+function json(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 1) }] };
+}
+function errorText(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function createMcpServer(provider, opts = {}) {
+  const server = new import_mcp.McpServer({
+    name: opts.name ?? "bapbong",
+    version: opts.version ?? "0.0.1"
+  });
+  const withSession = async (id, fn) => {
+    const session = await provider.get(id);
+    if (!session) {
+      return errorText(
+        id === void 0 ? "No document is open. Ask the user to open a document first." : `No document with id ${JSON.stringify(id)}.`
+      );
+    }
+    try {
+      return await fn(session);
+    } catch (err) {
+      if (err instanceof AnchorError || err instanceof VersionConflictError || err instanceof NoDocumentError) {
+        return errorText(err.message);
+      }
+      throw err;
+    }
+  };
+  server.registerTool(
+    "get_document",
+    {
+      title: "Read the document",
+      description: "Read the whole document as numbered blocks (paragraphs, headings \u2014 table-cell paragraphs included, in reading order). Returns docVersion: pass it as expectedVersion to mutation tools so concurrent edits are detected. Block indexes are only stable within one docVersion.",
+      inputSchema: { documentId }
+    },
+    async ({ documentId: id }) => withSession(id, async (s) => json(await s.snapshot()))
+  );
+  server.registerTool(
+    "find_text",
+    {
+      title: "Find text",
+      description: "Find every occurrence of a text in the document. Matches are within one paragraph (they never span paragraphs or inline objects). Returns each match with its block index, 1-based occurrence number, and surrounding context.",
+      inputSchema: { documentId, query: import_zod.z.string().min(1).describe("Exact text to find (case-sensitive).") }
+    },
+    async ({ documentId: id, query }) => withSession(id, async (s) => json({ matches: await s.find(query) }))
+  );
+  server.registerTool(
+    "replace_text",
+    {
+      title: "Replace text",
+      description: "Replace one occurrence of exact text. old_text must match exactly once in the document \u2014 if it matches more, either pass occurrence or use a longer, unique anchor (include surrounding words). Formatting of the replaced range is kept.",
+      inputSchema: {
+        documentId,
+        old_text: import_zod.z.string().min(1).describe("Exact existing text (must match uniquely, or pass occurrence)."),
+        new_text: import_zod.z.string().describe("Replacement text (empty string deletes)."),
+        occurrence,
+        expectedVersion
+      }
+    },
+    async ({ documentId: id, old_text, new_text, occurrence: occ, expectedVersion: ver }) => withSession(id, async (s) => json(await s.replaceText(old_text, new_text, { occurrence: occ, expectedVersion: ver })))
+  );
+  server.registerTool(
+    "insert_content",
+    {
+      title: "Insert content",
+      description: "Insert new paragraphs. Each line of `content` becomes one paragraph. Anchor by exact text with position before/after (the paragraph containing the anchor), or position document_end to append.",
+      inputSchema: {
+        documentId,
+        content: import_zod.z.string().min(1).describe("Plain text; every line becomes a paragraph."),
+        position: import_zod.z.enum(["before", "after", "document_end"]),
+        anchor_text: import_zod.z.string().optional().describe("Required for before/after: exact text inside the anchor paragraph."),
+        occurrence,
+        expectedVersion
+      }
+    },
+    async ({ documentId: id, content, position, anchor_text, occurrence: occ, expectedVersion: ver }) => withSession(id, async (s) => {
+      if (position === "document_end") {
+        return json(await s.insertContent(content, { position: "document_end" }, { expectedVersion: ver }));
+      }
+      if (!anchor_text) return errorText("anchor_text is required when position is before/after.");
+      return json(
+        await s.insertContent(content, { position, text: anchor_text, occurrence: occ }, { expectedVersion: ver })
+      );
+    })
+  );
+  server.registerTool(
+    "apply_formatting",
+    {
+      title: "Apply formatting",
+      description: "Format one occurrence of exact text: character marks (bold/italic/underline/strike \u2014 true applies, false removes) and/or paragraph alignment of the containing paragraph. Same anchoring rules as replace_text.",
+      inputSchema: {
+        documentId,
+        target_text: import_zod.z.string().min(1).describe("Exact text to format (must match uniquely, or pass occurrence)."),
+        bold: import_zod.z.boolean().optional(),
+        italic: import_zod.z.boolean().optional(),
+        underline: import_zod.z.boolean().optional(),
+        strike: import_zod.z.boolean().optional(),
+        align: import_zod.z.enum(["left", "center", "right", "justify"]).optional(),
+        occurrence,
+        expectedVersion
+      }
+    },
+    async ({ documentId: id, target_text, occurrence: occ, expectedVersion: ver, ...format }) => withSession(id, async (s) => json(await s.applyFormatting(target_text, format, { occurrence: occ, expectedVersion: ver })))
+  );
+  server.registerTool(
+    "update_image",
+    {
+      title: "Resize / rotate an image",
+      description: "Resize and/or rotate one image. Read get_document first: blocks list their images, and (block_index, image_index) addresses one. Omitted fields keep their current value; width/height are CSS px, rotation is clockwise degrees around the image center (normalized to 0-360; 0 = upright). Block indexes change with every edit \u2014 pass expectedVersion from your last read.",
+      inputSchema: {
+        documentId,
+        block_index: import_zod.z.number().int().min(0).describe("Index of the block holding the image (from get_document)."),
+        image_index: import_zod.z.number().int().min(0).optional().describe("0-based image within the block (default 0, the first)."),
+        width: import_zod.z.number().positive().optional().describe("New width in CSS px."),
+        height: import_zod.z.number().positive().optional().describe("New height in CSS px."),
+        rotation: import_zod.z.number().optional().describe("Clockwise degrees around the center."),
+        expectedVersion
+      }
+    },
+    async ({ documentId: id, block_index, image_index, width, height, rotation, expectedVersion: ver }) => withSession(id, async (s) => {
+      if (width === void 0 && height === void 0 && rotation === void 0) {
+        return errorText("Pass at least one of width, height, rotation.");
+      }
+      return json(
+        await s.updateImage(block_index, image_index ?? 0, { width, height, rotation }, { expectedVersion: ver })
+      );
+    })
+  );
+  server.registerTool(
+    "save_document",
+    {
+      title: "Save the document",
+      description: "Persist the document to its backing store (file on desktop). Usually optional \u2014 the desktop autosaves.",
+      inputSchema: { documentId }
+    },
+    async ({ documentId: id }) => withSession(id, async (s) => {
+      await s.save();
+      return json({ saved: true });
+    })
+  );
+  if (opts.selection) {
+    server.registerTool(
+      "get_selection",
+      {
+        title: "Read the user's selection",
+        description: "The text the user currently has selected in the editor, or null when nothing is selected.",
+        inputSchema: { documentId }
+      },
+      async ({ documentId: id }) => withSession(id, async (s) => json(await s.getSelection?.() ?? { selection: null }))
+    );
+  }
+  server.registerResource(
+    "document",
+    "bapbong://document",
+    {
+      title: "Open document",
+      description: "The currently open document as plain text (one line per block).",
+      mimeType: "text/plain"
+    },
+    async (uri) => {
+      const session = await provider.get(void 0);
+      if (!session) return { contents: [{ uri: uri.href, text: "(no document open)" }] };
+      const snap = await session.snapshot();
+      return { contents: [{ uri: uri.href, text: snap.blocks.map((b) => b.text).join("\n") }] };
+    }
+  );
+  return server;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AnchorError,
+  NoDocumentError,
+  PmDocSession,
+  RemoteSession,
+  VersionConflictError,
+  createMcpServer,
+  executeOp,
+  reviveError
+});

package/dist/host.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Host-process surface: everything in ./session plus the MCP server factory
+ * (which brings the @modelcontextprotocol/sdk + zod runtime deps). The
+ * desktop Bun process imports THIS; it deliberately excludes HeadlessSession
+ * so a host that proxies to a live editor doesn't drag the docx pipeline in.
+ */
+export * from './session.js';
+export { createMcpServer, type CreateMcpServerOptions } from './lib/server.js';
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAC"}