@vectojs/numera-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.1.0 - 2026-07-11
+
+### Added
+
+- Initial root-confined stdio MCP server with bounded workbook inspection,
+  range reads, and hash-guarded atomic cell writes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VectoJS contributors
+
+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/README.md

@@ -0,0 +1,41 @@
+# Numera MCP
+
+`@vectojs/numera-mcp` is the safe local-first Model Context Protocol adapter for
+Numera workbooks. It lets an MCP client inspect workbooks, read bounded ranges,
+and write validated cell batches without launching a browser or subprocess.
+The published stdio executable requires Bun.
+
+The server supports `.numera.json`, `.json`, `.csv`, and `.xlsx` files through
+exact-pinned Numera Core and XLSX packages. It is intentionally local and does
+not provide collaboration, accounts, cloud storage, or remote network access.
+
+## Run
+
+```sh
+numera-mcp --root /absolute/path/to/workbooks
+```
+
+The server uses stdio. Paths passed to tools are relative to `--root`. Mutation
+tools require an expected input SHA-256 and a distinct, non-existing output
+path, so a stale Agent cannot silently overwrite newer work.
+
+## Tools
+
+- `numera_inspect_workbook`: return the format, SHA-256, active sheet, sheet
+  dimensions, populated-cell count, and used range.
+- `numera_read_range`: return raw and display values for at most 10,000 cells.
+- `numera_write_cells`: validate and atomically apply 1–1,000 typed cell writes
+  to a new output workbook.
+
+## Development
+
+```sh
+bun install
+bun run verify
+npm pack --dry-run
+```
+
+## Security
+
+See [SECURITY.md](./SECURITY.md). Numera MCP treats workbook bytes, formulas,
+paths, and MCP arguments as untrusted input.

package/dist/NumeraError.d.ts

@@ -0,0 +1,7 @@
+export type NumeraErrorCode = "INVALID_ARGUMENT" | "PATH_OUTSIDE_ROOT" | "INPUT_NOT_FOUND" | "OUTPUT_EXISTS" | "OUTPUT_EQUALS_INPUT" | "FORMAT_UNSUPPORTED" | "FORMAT_MISMATCH" | "STALE_INPUT" | "SHEET_NOT_FOUND" | "RANGE_OUT_OF_BOUNDS" | "RESOURCE_LIMIT";
+/** Stable diagnostic safe to return to an MCP caller. */
+export declare class NumeraError extends Error {
+    readonly code: NumeraErrorCode;
+    constructor(code: NumeraErrorCode, message: string);
+}
+//# sourceMappingURL=NumeraError.d.ts.map

package/dist/NumeraError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NumeraError.d.ts","sourceRoot":"","sources":["../src/NumeraError.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,mBAAmB,GACnB,iBAAiB,GACjB,eAAe,GACf,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,aAAa,GACb,iBAAiB,GACjB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,yDAAyD;AACzD,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,eAAe;IADhC,YACW,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM,EAIhB;CACF"}

package/dist/NumeraWorkspace.d.ts

@@ -0,0 +1,73 @@
+import { type WorkbookFormat } from "./workbookCodec";
+export type CellWrite = {
+    address: string;
+    type: "blank";
+} | {
+    address: string;
+    type: "text";
+    value: string;
+} | {
+    address: string;
+    type: "number";
+    value: number;
+} | {
+    address: string;
+    type: "boolean";
+    value: boolean;
+} | {
+    address: string;
+    type: "formula";
+    value: string;
+};
+/**
+ * Owns the filesystem security boundary and all workbook I/O for MCP tools.
+ * The adapter layer never receives an unchecked host path.
+ */
+export declare class NumeraWorkspace {
+    readonly root: string;
+    private constructor();
+    static create(root: string): Promise<NumeraWorkspace>;
+    inspect(path: string): Promise<{
+        path: string;
+        format: WorkbookFormat;
+        sha256: string;
+        activeSheet: string;
+        sheets: {
+            name: string;
+            rows: number;
+            cols: number;
+            populatedCells: number;
+            usedRange: import("@vectojs/numera-core").Rect | null;
+        }[];
+    }>;
+    readRange(path: string, sheetName: string, sourceRange: string): Promise<{
+        path: string;
+        sha256: string;
+        sheet: string;
+        range: string;
+        cells: {
+            address: string;
+            raw: string;
+            display: string;
+        }[];
+    }>;
+    writeCells(options: {
+        inputPath: string;
+        outputPath: string;
+        expectedInputSha256: string;
+        sheet: string;
+        writes: CellWrite[];
+    }): Promise<{
+        inputPath: string;
+        outputPath: string;
+        inputSha256: string;
+        outputSha256: string;
+        sheet: string;
+        writtenCells: number;
+    }>;
+    private load;
+    private validateRelative;
+    private resolveExisting;
+    private resolveNew;
+}
+//# sourceMappingURL=NumeraWorkspace.d.ts.map

package/dist/NumeraWorkspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NumeraWorkspace.d.ts","sourceRoot":"","sources":["../src/NumeraWorkspace.ts"],"names":[],"mappings":"AAeA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAOzB,MAAM,MAAM,SAAS,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAQxD;;;GAGG;AACH,qBAAa,eAAe;IACN,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAzC,OAAO,eAAsC;IAE7C,OAAa,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAa1D;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM;;;;;;;;;;;;OAezB;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;;;;;;;;;;OAgCnE;IAEK,UAAU,CAAC,OAAO,EAAE;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,SAAS,EAAE,CAAC;KACrB;;;;;;;OAyCA;YAEa,IAAI;IAWlB,OAAO,CAAC,gBAAgB;YAYV,eAAe;YAgBf,UAAU;CAwBzB"}

package/dist/a1.d.ts

@@ -0,0 +1,7 @@
+import { type Rect } from "@vectojs/numera-core";
+export declare function parseCellAddress(source: string): {
+    row: number;
+    col: number;
+};
+export declare function parseCellRange(source: string): Rect;
+//# sourceMappingURL=a1.d.ts.map

package/dist/a1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a1.d.ts","sourceRoot":"","sources":["../src/a1.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAOtE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAa7E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAanD"}

package/dist/chunk-RD4J723A.js

@@ -0,0 +1,483 @@
+// src/NumeraError.ts
+var NumeraError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "NumeraError";
+  }
+  code;
+};
+
+// src/cliArguments.ts
+function parseRoot(arguments_) {
+  if (arguments_.length !== 2 || arguments_[0] !== "--root" || !arguments_[1])
+    throw new NumeraError(
+      "INVALID_ARGUMENT",
+      "Usage: numera-mcp --root <absolute-directory>"
+    );
+  return arguments_[1];
+}
+
+// src/NumeraWorkspace.ts
+import { toA1 } from "@vectojs/numera-core";
+import { createHash, randomUUID } from "crypto";
+import {
+  link,
+  lstat,
+  open,
+  realpath,
+  rm,
+  stat,
+  writeFile
+} from "fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "path";
+
+// src/a1.ts
+import { parseA1, parseRange } from "@vectojs/numera-core";
+var MAX_WORKSHEET_ROWS = 1048576;
+var MAX_WORKSHEET_COLUMNS = 16384;
+function parseCellAddress(source) {
+  const cell = parseA1(source.toUpperCase());
+  if (!cell)
+    throw new NumeraError(
+      "INVALID_ARGUMENT",
+      `Invalid cell address: ${source}`
+    );
+  if (cell.row >= MAX_WORKSHEET_ROWS || cell.col >= MAX_WORKSHEET_COLUMNS)
+    throw new NumeraError(
+      "RESOURCE_LIMIT",
+      `Cell exceeds worksheet limits: ${source}`
+    );
+  return cell;
+}
+function parseCellRange(source) {
+  const normalized = source.toUpperCase();
+  const range = normalized.includes(":") ? parseRange(normalized) : (() => {
+    const cell = parseA1(normalized);
+    return cell ? { r1: cell.row, c1: cell.col, r2: cell.row, c2: cell.col } : null;
+  })();
+  if (!range)
+    throw new NumeraError("INVALID_ARGUMENT", `Invalid range: ${source}`);
+  return range;
+}
+
+// src/workbookCodec.ts
+import {
+  fromCsv,
+  parseWorkbookJson,
+  toCsv,
+  toWorkbookJson,
+  Workbook
+} from "@vectojs/numera-core";
+import { decodeXlsx, encodeXlsx } from "@vectojs/numera-xlsx";
+function detectWorkbookFormat(path) {
+  const normalized = path.toLowerCase();
+  if (normalized.endsWith(".xlsx")) return "xlsx";
+  if (normalized.endsWith(".csv")) return "csv";
+  if (normalized.endsWith(".numera.json") || normalized.endsWith(".json"))
+    return "json";
+  throw new NumeraError(
+    "FORMAT_UNSUPPORTED",
+    `Unsupported workbook format: ${path}`
+  );
+}
+async function decodeWorkbook(bytes, format) {
+  if (format === "xlsx") return decodeXlsx(bytes);
+  const source = new TextDecoder().decode(bytes);
+  if (format === "json") return parseWorkbookJson(source);
+  const workbook = new Workbook();
+  const sheet = workbook.activeSheet.model;
+  for (const write of fromCsv(
+    source,
+    { row: 0, col: 0 },
+    { rows: sheet.rows, cols: sheet.cols }
+  ))
+    sheet.setCell(write.row, write.col, write.raw);
+  return workbook;
+}
+async function encodeWorkbook(workbook, format) {
+  if (format === "xlsx") return encodeXlsx(workbook);
+  if (format === "json")
+    return new TextEncoder().encode(toWorkbookJson(workbook));
+  const sheet = workbook.activeSheet.model;
+  const used = sheet.getUsedRange();
+  const range = used ?? { r1: 0, c1: 0, r2: 0, c2: 0 };
+  return new TextEncoder().encode(toCsv(sheet, range));
+}
+
+// src/NumeraWorkspace.ts
+var MAX_READ_CELLS = 1e4;
+var MAX_WRITES = 1e3;
+var MAX_INPUT_BYTES = 50 * 1024 * 1024;
+var MAX_CELL_TEXT_LENGTH = 32767;
+var NumeraWorkspace = class _NumeraWorkspace {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  static async create(root) {
+    if (!isAbsolute(root))
+      throw new NumeraError("INVALID_ARGUMENT", "--root must be absolute");
+    const canonical = await realpath(root).catch(() => {
+      throw new NumeraError(
+        "INVALID_ARGUMENT",
+        "--root must be an existing directory"
+      );
+    });
+    const metadata = await stat(canonical);
+    if (!metadata.isDirectory())
+      throw new NumeraError("INVALID_ARGUMENT", "--root must be a directory");
+    return new _NumeraWorkspace(canonical);
+  }
+  async inspect(path) {
+    const loaded = await this.load(path);
+    return {
+      path,
+      format: loaded.format,
+      sha256: loaded.sha256,
+      activeSheet: loaded.workbook.activeSheet.name,
+      sheets: loaded.workbook.sheets.map((sheet) => ({
+        name: sheet.name,
+        rows: sheet.model.rows,
+        cols: sheet.model.cols,
+        populatedCells: sheet.model.cellCount,
+        usedRange: sheet.model.getUsedRange()
+      }))
+    };
+  }
+  async readRange(path, sheetName, sourceRange) {
+    const loaded = await this.load(path);
+    const sheet = findSheet(loaded.workbook, sheetName).model;
+    const range = parseCellRange(sourceRange);
+    if (range.r2 >= sheet.rows || range.c2 >= sheet.cols)
+      throw new NumeraError(
+        "RANGE_OUT_OF_BOUNDS",
+        `Range is outside sheet bounds: ${sourceRange}`
+      );
+    const cellCount = (range.r2 - range.r1 + 1) * (range.c2 - range.c1 + 1);
+    if (cellCount > MAX_READ_CELLS)
+      throw new NumeraError(
+        "RESOURCE_LIMIT",
+        `Range exceeds ${MAX_READ_CELLS} cells`
+      );
+    const cells = [];
+    for (let row = range.r1; row <= range.r2; row++) {
+      for (let col = range.c1; col <= range.c2; col++) {
+        cells.push({
+          address: toA1({ row, col }),
+          raw: sheet.getRaw(row, col),
+          display: sheet.getDisplay(row, col)
+        });
+      }
+    }
+    return {
+      path,
+      sha256: loaded.sha256,
+      sheet: sheetName,
+      range: sourceRange.toUpperCase(),
+      cells
+    };
+  }
+  async writeCells(options) {
+    validateWriteCount(options.writes);
+    const input = await this.resolveExisting(options.inputPath);
+    const outputCandidate = this.validateRelative(options.outputPath);
+    if (input === outputCandidate)
+      throw new NumeraError(
+        "OUTPUT_EQUALS_INPUT",
+        "Output path must differ from input path"
+      );
+    const output = await this.resolveNew(options.outputPath);
+    const inputFormat = detectWorkbookFormat(input);
+    const outputFormat = detectWorkbookFormat(output);
+    if (inputFormat !== outputFormat)
+      throw new NumeraError(
+        "FORMAT_MISMATCH",
+        "Input and output workbook formats must match"
+      );
+    const bytes = await readBounded(input);
+    const sha256 = hash(bytes);
+    if (sha256 !== options.expectedInputSha256.toLowerCase())
+      throw new NumeraError(
+        "STALE_INPUT",
+        "Input SHA-256 does not match expected_input_sha256"
+      );
+    const workbook = await decodeWorkbook(bytes, inputFormat);
+    const sheet = findSheet(workbook, options.sheet).model;
+    const normalized = normalizeWrites(options.writes);
+    for (const write of normalized) {
+      expandSheetToCell(sheet, write.row, write.col);
+      sheet.setCell(write.row, write.col, write.raw);
+    }
+    const outputBytes = await encodeWorkbook(workbook, outputFormat);
+    await writeNewAtomically(output, outputBytes);
+    return {
+      inputPath: options.inputPath,
+      outputPath: options.outputPath,
+      inputSha256: sha256,
+      outputSha256: hash(outputBytes),
+      sheet: options.sheet,
+      writtenCells: normalized.length
+    };
+  }
+  async load(path) {
+    const resolved = await this.resolveExisting(path);
+    const format = detectWorkbookFormat(resolved);
+    const bytes = await readBounded(resolved);
+    return {
+      format,
+      sha256: hash(bytes),
+      workbook: await decodeWorkbook(bytes, format)
+    };
+  }
+  validateRelative(path) {
+    if (path.includes("\0") || path === "" || isAbsolute(path))
+      throw new NumeraError(
+        "PATH_OUTSIDE_ROOT",
+        `Invalid relative path: ${path}`
+      );
+    const candidate = resolve(this.root, path);
+    if (!isWithin(this.root, candidate))
+      throw new NumeraError("PATH_OUTSIDE_ROOT", `Path escapes root: ${path}`);
+    return candidate;
+  }
+  async resolveExisting(path) {
+    const candidate = this.validateRelative(path);
+    let canonical;
+    try {
+      canonical = await realpath(candidate);
+    } catch {
+      throw new NumeraError("INPUT_NOT_FOUND", `Input not found: ${path}`);
+    }
+    if (!isWithin(this.root, canonical))
+      throw new NumeraError("PATH_OUTSIDE_ROOT", `Path escapes root: ${path}`);
+    const metadata = await stat(canonical);
+    if (!metadata.isFile())
+      throw new NumeraError("INPUT_NOT_FOUND", `Input is not a file: ${path}`);
+    return canonical;
+  }
+  async resolveNew(path) {
+    const candidate = this.validateRelative(path);
+    const canonicalParent = await realpath(dirname(candidate)).catch(() => {
+      throw new NumeraError(
+        "PATH_OUTSIDE_ROOT",
+        `Output parent does not exist: ${path}`
+      );
+    });
+    if (!isWithin(this.root, canonicalParent))
+      throw new NumeraError("PATH_OUTSIDE_ROOT", `Path escapes root: ${path}`);
+    const resolved = resolve(canonicalParent, basename(candidate));
+    try {
+      await lstat(resolved);
+      throw new NumeraError("OUTPUT_EXISTS", `Output already exists: ${path}`);
+    } catch (error) {
+      if (error instanceof NumeraError) throw error;
+      if (error.code !== "ENOENT")
+        throw new NumeraError(
+          "INVALID_ARGUMENT",
+          `Cannot inspect output path: ${path}`
+        );
+    }
+    return resolved;
+  }
+};
+function isWithin(root, candidate) {
+  const path = relative(root, candidate);
+  return path === "" || !path.startsWith("..") && !isAbsolute(path);
+}
+function hash(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+async function readBounded(path) {
+  const handle = await open(path, "r");
+  try {
+    const metadata = await handle.stat();
+    if (metadata.size > MAX_INPUT_BYTES)
+      throw new NumeraError(
+        "RESOURCE_LIMIT",
+        `Workbook exceeds ${MAX_INPUT_BYTES} bytes`
+      );
+    return new Uint8Array(await handle.readFile());
+  } finally {
+    await handle.close();
+  }
+}
+function findSheet(workbook, name) {
+  const sheet = workbook.sheets.find((candidate) => candidate.name === name);
+  if (!sheet)
+    throw new NumeraError("SHEET_NOT_FOUND", `Sheet not found: ${name}`);
+  return sheet;
+}
+function validateWriteCount(writes) {
+  if (writes.length < 1 || writes.length > MAX_WRITES)
+    throw new NumeraError(
+      "RESOURCE_LIMIT",
+      `writes must contain between 1 and ${MAX_WRITES} cells`
+    );
+}
+function normalizeWrites(writes) {
+  const seen = /* @__PURE__ */ new Set();
+  return writes.map((write) => {
+    const cell = parseCellAddress(write.address);
+    const key = `${cell.row}:${cell.col}`;
+    if (seen.has(key))
+      throw new NumeraError(
+        "INVALID_ARGUMENT",
+        `Duplicate write address: ${write.address}`
+      );
+    seen.add(key);
+    let raw;
+    if (write.type === "blank") raw = "";
+    else if (write.type === "boolean") raw = write.value ? "TRUE" : "FALSE";
+    else if (write.type === "number") {
+      if (!Number.isFinite(write.value))
+        throw new NumeraError(
+          "INVALID_ARGUMENT",
+          `Number must be finite: ${write.address}`
+        );
+      raw = String(write.value);
+    } else if (write.type === "formula")
+      raw = write.value.startsWith("=") ? write.value : `=${write.value}`;
+    else raw = write.value;
+    if (raw.length > MAX_CELL_TEXT_LENGTH)
+      throw new NumeraError(
+        "RESOURCE_LIMIT",
+        `Cell content exceeds ${MAX_CELL_TEXT_LENGTH} characters: ${write.address}`
+      );
+    return { ...cell, raw };
+  });
+}
+function expandSheetToCell(sheet, row, col) {
+  if (row < sheet.rows && col < sheet.cols) return;
+  const snapshot = sheet.toSnapshot();
+  sheet.restoreSnapshot({
+    ...snapshot,
+    rows: Math.max(sheet.rows, row + 1),
+    cols: Math.max(sheet.cols, col + 1)
+  });
+}
+async function writeNewAtomically(outputPath, content) {
+  const temporaryPath = `${outputPath}.numera-${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, content, { flag: "wx" });
+    await link(temporaryPath, outputPath).catch((error) => {
+      const code = error.code;
+      if (code === "EEXIST")
+        throw new NumeraError("OUTPUT_EXISTS", "Output already exists");
+      throw error;
+    });
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod/v4";
+var writeSchema = z.discriminatedUnion("type", [
+  z.object({ address: z.string(), type: z.literal("blank") }),
+  z.object({ address: z.string(), type: z.literal("text"), value: z.string() }),
+  z.object({
+    address: z.string(),
+    type: z.literal("number"),
+    value: z.number()
+  }),
+  z.object({
+    address: z.string(),
+    type: z.literal("boolean"),
+    value: z.boolean()
+  }),
+  z.object({
+    address: z.string(),
+    type: z.literal("formula"),
+    value: z.string()
+  })
+]);
+function createNumeraServer(workspace) {
+  const server = new McpServer({ name: "numera-mcp", version: "0.1.0" });
+  server.registerTool(
+    "numera_inspect_workbook",
+    {
+      title: "Inspect Numera workbook",
+      description: "Inspect a root-relative Numera JSON, CSV, or XLSX workbook and return its SHA-256 and sheet metadata.",
+      inputSchema: { path: z.string() },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ path }) => toolResult(() => workspace.inspect(path))
+  );
+  server.registerTool(
+    "numera_read_range",
+    {
+      title: "Read Numera range",
+      description: "Read raw and displayed cell values from a bounded A1 range in a root-relative workbook.",
+      inputSchema: {
+        path: z.string(),
+        sheet: z.string(),
+        range: z.string()
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ path, sheet, range }) => toolResult(() => workspace.readRange(path, sheet, range))
+  );
+  server.registerTool(
+    "numera_write_cells",
+    {
+      title: "Write Numera cells",
+      description: "Apply a validated typed cell batch to a new output workbook. Requires the current input SHA-256 and never overwrites either file.",
+      inputSchema: {
+        input_path: z.string(),
+        output_path: z.string(),
+        expected_input_sha256: z.string().regex(/^[a-fA-F0-9]{64}$/),
+        sheet: z.string(),
+        writes: z.array(writeSchema).min(1).max(1e3)
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    async (arguments_) => toolResult(
+      () => workspace.writeCells({
+        inputPath: arguments_.input_path,
+        outputPath: arguments_.output_path,
+        expectedInputSha256: arguments_.expected_input_sha256,
+        sheet: arguments_.sheet,
+        writes: arguments_.writes
+      })
+    )
+  );
+  return server;
+}
+async function toolResult(operation) {
+  try {
+    const value = await operation();
+    return {
+      content: [{ type: "text", text: JSON.stringify(value) }]
+    };
+  } catch (error) {
+    const diagnostic = error instanceof NumeraError ? { code: error.code, message: error.message } : { code: "UNEXPECTED", message: "Unexpected workbook failure" };
+    return {
+      isError: true,
+      content: [{ type: "text", text: JSON.stringify(diagnostic) }]
+    };
+  }
+}
+
+export {
+  NumeraError,
+  parseRoot,
+  NumeraWorkspace,
+  createNumeraServer
+};

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+import {
+  NumeraError,
+  NumeraWorkspace,
+  createNumeraServer,
+  parseRoot
+} from "./chunk-RD4J723A.js";
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function main() {
+  const workspace = await NumeraWorkspace.create(
+    parseRoot(process.argv.slice(2))
+  );
+  const transport = new StdioServerTransport();
+  await createNumeraServer(workspace).connect(transport);
+  process.stdin.resume();
+  process.stdin.ref?.();
+}
+void main().catch((error) => {
+  const diagnostic = error instanceof NumeraError ? `${error.code}: ${error.message}` : `UNEXPECTED: ${String(error)}`;
+  process.stderr.write(`${diagnostic}
+`);
+  process.exitCode = 1;
+});

package/dist/cliArguments.d.ts

@@ -0,0 +1,2 @@
+export declare function parseRoot(arguments_: string[]): string;
+//# sourceMappingURL=cliArguments.d.ts.map

package/dist/cliArguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliArguments.d.ts","sourceRoot":"","sources":["../src/cliArguments.ts"],"names":[],"mappings":"AAEA,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAOtD"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { NumeraError, type NumeraErrorCode } from "./NumeraError";
+export { NumeraWorkspace, type CellWrite } from "./NumeraWorkspace";
+export { parseRoot } from "./cliArguments";
+export { createNumeraServer } from "./server";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  NumeraError,
+  NumeraWorkspace,
+  createNumeraServer,
+  parseRoot
+} from "./chunk-RD4J723A.js";
+export {
+  NumeraError,
+  NumeraWorkspace,
+  createNumeraServer,
+  parseRoot
+};

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { NumeraWorkspace } from "./NumeraWorkspace";
+export declare function createNumeraServer(workspace: NumeraWorkspace): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAsBpD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,CA2ExE"}

package/dist/workbookCodec.d.ts

@@ -0,0 +1,6 @@
+import { Workbook } from "@vectojs/numera-core";
+export type WorkbookFormat = "csv" | "json" | "xlsx";
+export declare function detectWorkbookFormat(path: string): WorkbookFormat;
+export declare function decodeWorkbook(bytes: Uint8Array, format: WorkbookFormat): Promise<Workbook>;
+export declare function encodeWorkbook(workbook: Workbook, format: WorkbookFormat): Promise<Uint8Array>;
+//# sourceMappingURL=workbookCodec.d.ts.map

package/dist/workbookCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbookCodec.d.ts","sourceRoot":"","sources":["../src/workbookCodec.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAK9B,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAUjE;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,QAAQ,CAAC,CAanB;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,UAAU,CAAC,CAQrB"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@vectojs/numera-mcp",
+  "version": "0.1.0",
+  "description": "Safe local-first MCP server for Numera workbooks.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vectojs/numera-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vectojs/numera-mcp/issues"
+  },
+  "homepage": "https://github.com/vectojs/numera-mcp#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "numera-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --clean && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "test": "bun test",
+    "format:check": "prettier --check .",
+    "lint": "oxlint --deny-warnings src test scripts",
+    "verify": "bun run format:check && bun run lint && bun test && bun run build && node scripts/stdio-smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@vectojs/numera-core": "0.4.0",
+    "@vectojs/numera-xlsx": "0.1.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "2.31.0",
+    "@types/bun": "1.3.14",
+    "oxlint": "1.73.0",
+    "prettier": "3.9.5",
+    "tsup": "8.5.1",
+    "typescript": "7.0.2"
+  }
+}