@alaarab/ogrid-mcp 2.16.0 → 2.17.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Ala Arab
+
+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/bundled-docs/api/headless-hooks.mdx

@@ -68,7 +68,7 @@ const grid = useHeadlessGrid({
 | Field | Description |
 |---|---|
 | `rows` | Current page rows after sort + filter |
-| `allFilteredRows` | Full filtered+sorted set (client mode) or current page (server mode) |
+| `allFilteredRows` | Every filtered+sorted row across pages (client mode), or the current page (server mode) |
 | `columns` | Resolved columns |
 | `totalCount` | Post-filter total |
 | `totalPages` | Total pages at current page size |
@@ -246,13 +246,14 @@ useEffect(() => {
 | `columns` | `IColumnDef<T>[]` |
 | `onCellEdit` | `(events: ICellValueChangedEvent<T>[]) => void` |
 | `clipboard?` | `{ readText, writeText }` override (defaults to `navigator.clipboard`) |
+| `onClipboardError?` | `(error: unknown) => void`, called when a clipboard read/write fails (e.g. permission denied) |
 
 ### Returns
 
 | Field | Description |
 |---|---|
-| `copyRange()`, `cutRange()`, `pasteRange()` | Async actions |
-| `canPaste` | `boolean` (feature detection) |
+| `copyRange()`, `cutRange()`, `pasteRange()` | Async actions. They resolve (never reject) when the clipboard is unavailable or denied; see `onClipboardError`. |
+| `canPaste` | `boolean` (feature detection). `false` until mounted, so server-rendered markup hydrates cleanly. |
 | `activeCutRange`, `activeCopyRange` | Marching-ants tracking |
 | `clearClipboard()` | Dismiss markers (bind to Escape) |
 

package/bundled-docs/features/csv-export.mdx

@@ -61,8 +61,9 @@ The `OGrid` component has the same props across all React UI packages. To switch
 exportToCsv<T>(
   items: T[],
   columns: CsvColumn[],
-  getValue: (item: T, columnId: string) => string,
-  filename?: string
+  getValue: (item: T, columnId: string) => unknown,
+  filename?: string,
+  formulaOptions?: FormulaExportOptions
 ): void
 ```
 
@@ -71,13 +72,15 @@ exportToCsv<T>(
 | `items` | `T[]` | The row data to export |
 | `columns` | `CsvColumn[]` | Array of `{ columnId, name }` defining which columns to include and their header names |
 | `getValue` | `(item, columnId) => string` | Function to extract the display value for each cell |
-| `filename` | `string` (optional) | Download filename (default: `'export.csv'`) |
+| `filename` | `string` (optional) | Download filename (default: `export_YYYY-MM-DD.csv`) |
+| `formulaOptions` | `FormulaExportOptions` (optional) | Formula export settings, plus `preventFormulaInjection` (default `true`) |
 
 The function:
 1. Builds a CSV header row from `columns[].name`.
 2. Iterates over each item and calls `getValue` for each column.
-3. Escapes values containing commas, quotes, or newlines.
-4. Triggers a browser download with the specified filename.
+3. Escapes values containing commas, quotes, or line breaks.
+4. Guards against CSV (formula) injection: text starting with `=`, `+`, `-`, `@`, a tab or a carriage return is prefixed with `'`, so a spreadsheet opening the file shows it as text instead of running it. Plain numbers such as `-5` are left alone. Pass `{ preventFormulaInjection: false }` to turn this off, for example when a trusted consumer needs the raw text. Formulas written with `exportMode: 'formulas'` are never prefixed.
+5. Triggers a browser download with the specified filename.
 
 ### Context Menu Integration
 

package/bundled-docs/features/xlsx-import.mdx

@@ -64,6 +64,13 @@ function SingleSheet({ file }: { file: Blob }) {
 | `density` | `'compact' \| 'normal' \| 'comfortable'` | `'compact'` | Row height. |
 | `onSheetChange` | `(name: string) => void` | — | Fired when the user clicks a sheet tab. |
 | `headerRow` | `'auto' \| 'header' \| 'none'` | `'auto'` | Whether to promote row 1 to the header. `'auto'` detects strings-only top rows; `'header'` forces it; `'none'` uses A/B/C letters. |
+| `limits` | `{ maxRows?, maxCols?, maxCells? }` | 1,048,576 rows / 1,000 cols / 5,000,000 cells | Load caps per sheet. A small file can declare a huge used range; anything past the caps is dropped and a notice is shown above the grid. |
+
+### Untrusted files
+
+Only populated cells are read, and each sheet is capped by `limits`. `sheetToGridData(sheet, { maxRows, maxCols, maxCells })` applies the same caps and returns `truncated: { rowCount, columnCount }` (the full size) when it cut the sheet.
+
+`@alaarab/ogrid-react-xlsx` requires React 18 or 19.
 
 ### Format support
 

package/dist/esm/bridge-client.d.ts

@@ -25,18 +25,18 @@
  *
  * This module contains NO Node.js-specific imports  -  safe to bundle in browsers.
  */
-interface BridgeColumnInfo {
+export interface BridgeColumnInfo {
     columnId: string;
     headerName?: string;
     type?: string;
 }
-interface BridgeCommand {
+export interface BridgeCommand {
     id: string;
     type: 'update_cell' | 'set_filter' | 'clear_filters' | 'set_sort' | 'go_to_page';
     payload: Record<string, unknown>;
 }
 /** Minimal subset of IOGridApi used by the bridge. */
-interface BridgeGridApi {
+export interface BridgeGridApi {
     updateSort?: (model: Array<{
         columnId: string;
         direction: 'asc' | 'desc';
@@ -46,7 +46,7 @@ interface BridgeGridApi {
     goToPage?: (page: number) => void;
     getSelectedRows?: () => unknown[];
 }
-interface ConnectGridOptions {
+export interface ConnectGridOptions {
     /** Unique identifier for this grid instance (shown in list_grids). */
     gridId: string;
     /** Returns the currently displayed rows. Called on every state push. */
@@ -76,12 +76,10 @@ interface ConnectGridOptions {
     /** How often to push state and poll commands (ms, default: 500). */
     pollIntervalMs?: number;
 }
-interface BridgeConnection {
+export interface BridgeConnection {
     /** Stop polling and disconnect. */
     disconnect: () => void;
     /** Manually push current state immediately. */
     push: () => Promise<void>;
 }
-declare function connectGridToBridge(options: ConnectGridOptions): BridgeConnection;
-
-export { type BridgeColumnInfo, type BridgeCommand, type BridgeConnection, type BridgeGridApi, type ConnectGridOptions, connectGridToBridge };
+export declare function connectGridToBridge(options: ConnectGridOptions): BridgeConnection;

package/dist/esm/bridge.d.ts

@@ -0,0 +1,83 @@
+/**
+ * OGrid Live Testing Bridge
+ *
+ * An HTTP server (default port 7890) that running OGrid instances connect to.
+ * The MCP server holds a BridgeStore in-process and queries it directly when
+ * tools like list_grids / get_grid_state / send_grid_command are invoked.
+ *
+ * Protocol (used by bridge-client.ts in the browser):
+ *   POST   /grids/connect                -  register / heartbeat
+ *   PUT    /grids/:id/state              -  push current grid state
+ *   GET    /grids/:id/commands           -  poll for pending commands
+ *   POST   /grids/:id/commands/:cmdId/result   -  post command result
+ *
+ * Internal (used by MCP tools via BridgeStore directly):
+ *   bridgeStore.listGrids()
+ *   bridgeStore.getState(gridId)
+ *   bridgeStore.enqueueCommand(gridId, cmd)
+ *   bridgeStore.waitForResult(cmdId, timeoutMs)
+ */
+import { type IncomingMessage } from 'node:http';
+export interface GridColumnInfo {
+    columnId: string;
+    headerName?: string;
+    type?: string;
+}
+export interface GridStateSnapshot {
+    gridId: string;
+    connectedAt: number;
+    lastSeen: number;
+    rowCount: number;
+    totalCount: number;
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    data: unknown[];
+    columns: GridColumnInfo[];
+    sortModel: Array<{
+        columnId: string;
+        direction: 'asc' | 'desc';
+    }>;
+    filterModel: Record<string, unknown>;
+    selectedRowIndices: number[];
+}
+export type GridCommandType = 'update_cell' | 'set_filter' | 'clear_filters' | 'set_sort' | 'go_to_page';
+export interface GridCommand {
+    id: string;
+    type: GridCommandType;
+    payload: Record<string, unknown>;
+    createdAt: number;
+    status: 'pending' | 'completed' | 'error';
+    result?: unknown;
+    error?: string;
+}
+export declare class BridgeStore {
+    private readonly grids;
+    private readonly commandQueues;
+    private readonly commandResults;
+    private cmdSeq;
+    /** Drop stale grids, commands and results so a long-running bridge doesn't grow without bound. */
+    prune(now?: number): void;
+    upsertGrid(gridId: string, partial: Partial<GridStateSnapshot>): void;
+    popPendingCommands(gridId: string): GridCommand[];
+    resolveCommand(cmdId: string, result: unknown, error?: string): void;
+    listGrids(): GridStateSnapshot[];
+    getState(gridId: string): GridStateSnapshot | undefined;
+    enqueueCommand(gridId: string, type: GridCommandType, payload: Record<string, unknown>): GridCommand | null;
+    waitForResult(cmdId: string, timeoutMs?: number): Promise<GridCommand>;
+}
+/** Grid snapshots include row data, so allow a generous but finite body. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * Why a request must be refused, or null if it may proceed.
+ *
+ * CORS alone doesn't protect the bridge: "simple" requests (GET, or POST with
+ * a text/plain body) reach the server without a preflight, and their side
+ * effects happen even though the page can't read the response. So:
+ *  - any Origin that isn't localhost is refused outright;
+ *  - the Host must be loopback (blocks DNS rebinding, where a public name
+ *    resolves to 127.0.0.1);
+ *  - writes must be application/json, which forces a browser preflight.
+ */
+export declare function rejectReason(req: IncomingMessage): string | null;
+export declare function startBridgeServer(store: BridgeStore, port?: number): Promise<() => Promise<void>>;

package/dist/esm/docsLoader.d.ts

@@ -0,0 +1,24 @@
+export interface CodeBlock {
+    language: string;
+    code: string;
+    framework?: string;
+}
+export interface DocEntry {
+    path: string;
+    title: string;
+    description: string;
+    category: string;
+    content: string;
+    codeBlocks: CodeBlock[];
+}
+export interface DocsIndex {
+    entries: DocEntry[];
+    search(query: string, limit?: number): DocEntry[];
+    getByPath(path: string): DocEntry | undefined;
+    getByCategory(category: string): DocEntry[];
+    getCodeExamples(query: string, framework?: string): Array<{
+        entry: DocEntry;
+        block: CodeBlock;
+    }>;
+}
+export declare function loadDocsIndex(docsDir: string): DocsIndex;

package/dist/esm/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.js

@@ -858,6 +858,8 @@ Command: ${JSON.stringify({ type, payload }, null, 2)}`
   }
   return server2;
 }
+var GRID_TTL_MS = 10 * 6e4;
+var COMMAND_TTL_MS = 5 * 6e4;
 var BridgeStore = class {
   constructor() {
     this.grids = /* @__PURE__ */ new Map();
@@ -865,6 +867,22 @@ var BridgeStore = class {
     this.commandResults = /* @__PURE__ */ new Map();
     this.cmdSeq = 0;
   }
+  /** Drop stale grids, commands and results so a long-running bridge doesn't grow without bound. */
+  prune(now = Date.now()) {
+    for (const [id, grid] of this.grids) {
+      if (now - grid.lastSeen > GRID_TTL_MS) {
+        this.grids.delete(id);
+        this.commandQueues.delete(id);
+      }
+    }
+    for (const [id, queue] of this.commandQueues) {
+      const live = queue.filter((c) => now - c.createdAt <= COMMAND_TTL_MS);
+      if (live.length !== queue.length) this.commandQueues.set(id, live);
+    }
+    for (const [id, cmd] of this.commandResults) {
+      if (now - cmd.createdAt > COMMAND_TTL_MS) this.commandResults.delete(id);
+    }
+  }
   // ---- Called by HTTP handler ----
   upsertGrid(gridId, partial) {
     const existing = this.grids.get(gridId);
@@ -908,6 +926,7 @@ var BridgeStore = class {
         cmd.result = result;
         cmd.error = error;
         this.commandResults.set(cmdId, { ...cmd });
+        queue.splice(queue.indexOf(cmd), 1);
         return;
       }
     }
@@ -940,6 +959,7 @@ var BridgeStore = class {
       const poll = () => {
         const cmd = this.commandResults.get(cmdId);
         if (cmd) {
+          this.commandResults.delete(cmdId);
           resolve(cmd);
           return;
         }
@@ -953,10 +973,22 @@ var BridgeStore = class {
     });
   }
 };
+var MAX_BODY_BYTES = 10 * 1024 * 1024;
+var PayloadTooLargeError = class extends Error {
+};
 function readBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
-    req.on("data", (c) => chunks.push(c));
+    let size = 0;
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > MAX_BODY_BYTES) {
+        req.destroy();
+        reject(new PayloadTooLargeError(`Body exceeds ${MAX_BODY_BYTES} bytes`));
+        return;
+      }
+      chunks.push(c);
+    });
     req.on("end", () => {
       try {
         resolve(JSON.parse(Buffer.concat(chunks).toString("utf-8") || "null"));
@@ -968,10 +1000,22 @@ function readBody(req) {
   });
 }
 var LOCALHOST_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
+var LOCALHOST_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
 function corsOrigin(req) {
   const origin = req.headers.origin;
   return origin && LOCALHOST_ORIGIN.test(origin) ? origin : "";
 }
+function rejectReason(req) {
+  const host = req.headers.host ?? "";
+  if (!LOCALHOST_HOST.test(host)) return "Host must be localhost";
+  const origin = req.headers.origin;
+  if (origin && !LOCALHOST_ORIGIN.test(origin)) return "Origin not allowed";
+  if (req.method === "POST" || req.method === "PUT") {
+    const type = (req.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase();
+    if (type !== "application/json") return "Content-Type must be application/json";
+  }
+  return null;
+}
 function send(req, res, status, body) {
   const json = JSON.stringify(body);
   const headers = {
@@ -1001,6 +1045,12 @@ function startBridgeServer(store, port = 7890) {
         res.end();
         return;
       }
+      const refused = rejectReason(req);
+      if (refused) {
+        send(req, res, 403, { error: refused });
+        return;
+      }
+      store.prune();
       const url = new URL(req.url ?? "/", `http://localhost:${port}`);
       const parts = url.pathname.replace(/^\//, "").split("/");
       try {
@@ -1043,6 +1093,10 @@ function startBridgeServer(store, port = 7890) {
         }
         send(req, res, 404, { error: "Not found" });
       } catch (err) {
+        if (err instanceof PayloadTooLargeError) {
+          send(req, res, 413, { error: err.message });
+          return;
+        }
         send(req, res, 500, { error: String(err) });
       }
     });

package/dist/esm/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DocsIndex } from './docsLoader.js';
+import type { BridgeStore } from './bridge.js';
+export declare function createOGridMcpServer(index: DocsIndex, bridge?: BridgeStore): McpServer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-mcp",
-  "version": "2.16.0",
+  "version": "2.17.1",
   "description": "MCP server for OGrid documentation",
   "type": "module",
   "repository": {
@@ -12,12 +12,22 @@
     "ogrid-mcp": "./dist/esm/index.js"
   },
   "main": "./dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "bridge-client": [
+        "dist/esm/bridge-client.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
+      "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js",
       "default": "./dist/esm/index.js"
     },
     "./bridge-client": {
+      "types": "./dist/esm/bridge-client.d.ts",
       "import": "./dist/esm/bridge-client.js",
       "default": "./dist/esm/bridge-client.js"
     }
@@ -28,18 +38,18 @@
   ],
   "scripts": {
     "prebuild": "node scripts/bundle-docs.mjs",
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.json --emitDeclarationOnly --outDir dist/esm && node ../../scripts/fix-dts-extensions.mjs dist/esm",
     "dev": "tsup --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test --preload ../../bun-test.setup.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.3"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=18"