@alaarab/ogrid-mcp 2.15.1 → 2.15.2

package/README.md

@@ -1,6 +1,6 @@
 # @alaarab/ogrid-mcp
 
-MCP server that lets AI editors search and retrieve OGrid documentation across all supported frameworks.
+MCP server that lets AI editors (Claude Code, Cursor, VS Code Copilot, etc.) search and retrieve OGrid documentation — and, optionally, inspect and drive live OGrid instances in your running app through a local testing bridge.
 
 ## Install
 
@@ -17,7 +17,64 @@ Add to your editor's MCP configuration:
 Or run directly:
 
 ```bash
-npx @alaarab/ogrid-mcp
+npx @alaarab/ogrid-mcp            # docs server (stdio)
+npx @alaarab/ogrid-mcp --bridge   # docs server + live testing bridge on port 7890
+npx @alaarab/ogrid-mcp --version  # print version
 ```
 
-See the [OGrid docs](https://alaarab.github.io/ogrid/) for full documentation.
+## Tools
+
+Documentation tools (always available):
+
+| Tool | Description |
+| --- | --- |
+| `search_docs` | Search OGrid documentation by keyword. Returns matching docs with title, description, and content excerpt. |
+| `list_docs` | List available documentation pages, optionally filtered by category (`features`, `getting-started`, `guides`, `api`). |
+| `get_docs` | Get the full content of a documentation page by path (e.g. `features/sorting`, `api/column-def`). |
+| `get_code_example` | Find code examples from the docs matching a query, optionally filtered by framework. |
+| `detect_version` | Detect which OGrid version and framework a project uses by reading its `package.json`. |
+
+Live-bridge tools (available when the bridge is enabled):
+
+| Tool | Description |
+| --- | --- |
+| `list_grids` | List OGrid instances currently connected to the bridge: grid IDs, row counts, page info, last-seen timestamps. |
+| `get_grid_state` | Get a connected grid's current state: displayed rows, columns, sort, filters, pagination, and selection. |
+| `send_grid_command` | Send a command to a connected grid (sort, filter, paginate, edit a cell, …) and wait for the result. |
+
+## Resources
+
+| URI | Description |
+| --- | --- |
+| `ogrid://quick-reference` | Key props, install commands, and common patterns. |
+| `ogrid://migration-guide` | Full migration guide from AG Grid with side-by-side API mapping. |
+| `ogrid://docs/{path}` | Any documentation page by path. |
+
+## Live testing bridge
+
+The bridge lets an AI assistant observe and drive real OGrid instances in your running app — useful for agentic testing and debugging.
+
+1. Start the server with the bridge enabled: `npx @alaarab/ogrid-mcp --bridge` (or set `OGRID_BRIDGE_PORT` to pick a port; `--bridge` defaults to `7890`).
+2. In your app, connect a grid to the bridge:
+
+```tsx
+import { connectGridToBridge } from '@alaarab/ogrid-mcp/bridge-client';
+
+const connection = connectGridToBridge({
+  gridId: 'employees',
+  getData: () => rows,
+  getColumns: () => columns,
+  api: gridApiRef.current, // optional: enables send_grid_command actions
+  // bridgeUrl: 'http://localhost:7890' (default), pollIntervalMs: 500 (default)
+});
+
+// later: connection.disconnect();
+```
+
+3. The assistant can now call `list_grids`, `get_grid_state`, and `send_grid_command` against your live app.
+
+The bridge client polls the local bridge over HTTP and never talks to anything but `bridgeUrl`.
+
+## Documentation
+
+See the [OGrid docs](https://alaarab.github.io/ogrid/) — in particular the [MCP guide](https://alaarab.github.io/ogrid/docs/guides/mcp) and [MCP live testing guide](https://alaarab.github.io/ogrid/docs/guides/mcp-live-testing).

package/bundled-docs/api/headless-hooks.mdx

@@ -6,11 +6,10 @@ description: API reference for useHeadlessGrid + the spreadsheet hook set (useIn
 
 # Headless hooks
 
-OGrid 2.9 ships seven framework-native hooks that expose grid logic without
-imposing any chrome. Pair `useHeadlessGrid` with the spreadsheet hooks to
-add inline edit, range selection, fill handle, clipboard, undo/redo, and
-keyboard navigation to your own table markup (shadcn `<Table>`, plain HTML,
-Fluent `<DataGrid>`, anything).
+OGrid exposes hooks that provide the grid logic without imposing any UI.
+Pair `useHeadlessGrid` with the spreadsheet hooks to add inline edit, range
+selection, fill handle, clipboard, undo/redo, and keyboard navigation to your
+own table markup (shadcn `<Table>`, plain HTML, Fluent `<DataGrid>`, anything).
 
 All seven hooks ship as React hooks:
 

package/bundled-docs/api/ogrid-props.mdx

@@ -33,6 +33,7 @@ Complete reference for `IOGridProps<T>`, the props accepted by the `OGrid` compo
 | `onSortChange` | `(sort: { field: string; direction: 'asc' \| 'desc' }) => void` | `undefined` | Callback fired when the user changes the sort. Required for controlled sort mode. |
 | `defaultSortBy` | `string` | `undefined` | Column ID to sort by initially in uncontrolled mode. |
 | `defaultSortDirection` | `'asc' \| 'desc'` | `undefined` | Initial sort direction in uncontrolled mode. Used together with `defaultSortBy`. |
+| `workerSort` | `boolean \| 'auto'` | `false` | Offload sorting to a Web Worker to keep the main thread responsive. `true` always uses the worker; `'auto'` uses it past ~5000 rows. Columns with a custom `compare` fall back to synchronous sort. |
 
 ## Filtering
 
@@ -61,6 +62,7 @@ Complete reference for `IOGridProps<T>`, the props accepted by the `OGrid` compo
 | `columnOrder` | `string[]` | `undefined` | Controlled column order as an array of column IDs. |
 | `onColumnOrderChange` | `(order: string[]) => void` | `undefined` | Callback fired when the user reorders columns. |
 | `onColumnResized` | `(columnId: string, width: number) => void` | `undefined` | Callback fired when the user finishes resizing a column. |
+| `responsiveColumns` | `boolean \| IResponsiveColumnsConfig` | `false` | Auto-hide columns by their `responsivePriority` as the container narrows. `true` uses default breakpoints (576/768/992/1200px); pass a config object for custom thresholds. |
 
 ## Editing
 
@@ -128,12 +130,39 @@ Complete reference for `IOGridProps<T>`, the props accepted by the `OGrid` compo
 | `rowHeight` | `number` | `36` | Fixed row height in pixels. Affects layout and virtual scrolling row height calculation. |
 | `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Cell spacing preset. Controls cell padding throughout the grid. |
 | `showRowNumbers` | `boolean` | `false` | Show Excel-style row number column (1, 2, 3...) at the start of the grid. |
+| `cellReferences` | `boolean` | `false` | Excel-style cell references: column-letter headers (A, B, C…), a row-number gutter, and a name box showing the active cell (e.g. "A1"). Implies `showRowNumbers`. |
 | `className` | `string` | `undefined` | Additional CSS class name applied to the root grid element. |
 | `toolbar` | `ReactNode` | `undefined` | Custom toolbar content rendered in the left side of the primary toolbar strip. |
 | `toolbarBelow` | `ReactNode` | `undefined` | Secondary toolbar row rendered below the primary toolbar. Use for active filter chips, breadcrumbs, or other contextual controls. |
 | `entityLabelPlural` | `string` | `undefined` | Plural label for the entity type (e.g., `"projects"`, `"users"`). Used in status bar text and empty state messages. |
 | `emptyState` | `{ message?: ReactNode; render?: () => ReactNode }` | `undefined` | Custom empty state configuration. Provide `message` for a simple text override, or `render` for a fully custom empty state component. |
 
+## Formulas
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `formulas` | `boolean` | `false` | Enable Excel-like formulas. When on, cells starting with `=` are evaluated by the built-in formula engine. |
+| `initialFormulas` | `Array<{ col: number; row: number; formula: string }>` | `undefined` | Formulas to load when the engine initializes. |
+| `onFormulaRecalc` | `(result: IRecalcResult) => void` | `undefined` | Called when a recalculation updates cell values (e.g. a cascade from an edited cell). |
+| `formulaFunctions` | `Record<string, IFormulaFunction>` | `undefined` | Custom functions to register with the formula engine. |
+| `namedRanges` | `Record<string, string>` | `undefined` | Named ranges for formulas, mapping a name to a cell/range ref (e.g. `{ Revenue: 'A1:A10' }`). |
+| `sheets` | `Record<string, IGridDataAccessor>` | `undefined` | Accessors for cross-sheet formula references (e.g. `{ Sheet2: accessor }`). |
+
+See [Formulas](../features/formulas) for the full guide.
+
+## Multi-Sheet
+
+Excel-style sheet tabs along the bottom of the grid.
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `sheetDefs` | `ISheetDef[]` | `undefined` | Sheet definitions. When set, renders a bottom tab bar (the `SheetTabs` component). |
+| `activeSheet` | `string` | `undefined` | The currently active sheet id. |
+| `onSheetChange` | `(sheetId: string) => void` | `undefined` | Called when the user switches sheets. |
+| `onSheetAdd` | `() => void` | `undefined` | Called when the user clicks the add-sheet button. |
+
+See [Multi-Sheet](../features/multi-sheet).
+
 ## Callbacks
 
 | Name | Type | Default | Description |

package/bundled-docs/features/column-types.mdx

@@ -5,10 +5,13 @@ description: Built-in column types for common data patterns  -  text, numeric, d
 ---
 
 
+
 # Column Types
 
 OGrid provides built-in column types that automatically configure alignment, display formatting, cell editors, and filter types. Set `type` on a column definition to opt in.
 
+<ColumnTypesDemo />
+
 ## Available Types
 
 | Type | Alignment | Default Editor | Default Filter | Display Format |

package/bundled-docs/features/mobile-touch.mdx

@@ -5,10 +5,15 @@ description: Touch-friendly interactions using the Pointer Events API for cell s
 ---
 
 
+
 # Mobile Touch Support
 
 OGrid uses the [Pointer Events API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events) for all drag interactions, providing unified input handling across mouse, touch, and pen devices. All interactions  -  cell drag-selection, fill handle drag-to-fill, column resize, and column reorder  -  work on touch devices out of the box with no additional configuration.
 
+<MobileTouchDemo />
+
+The demo above uses the exact same pointer gestures on every device — try it with a mouse here, or open this page on a phone or tablet: the fill and resize handles automatically enlarge under `@media (pointer: coarse)` for finger-sized targets.
+
 ## How It Works
 
 ### Pointer Events API

package/bundled-docs/features/multi-sheet.mdx

@@ -0,0 +1,91 @@
+---
+sidebar_position: 6
+title: Multi-Sheet
+description: Excel-style sheet tabs — render a bottom tab bar and switch between multiple grids.
+---
+
+
+# Multi-Sheet
+
+OGrid can render an Excel-style **sheet tab bar** along the bottom of the grid so users can switch between multiple sheets. Provide `sheetDefs`, track the `activeSheet`, and swap the grid's `data` (and `columns`, if they differ) when the active sheet changes.
+
+<MultiSheetDemo />
+
+## Props
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sheetDefs` | `ISheetDef[]` | Sheet definitions. When set, the grid renders the bottom tab bar. |
+| `activeSheet` | `string` | The id of the currently active sheet. |
+| `onSheetChange` | `(sheetId: string) => void` | Called when the user clicks a different tab. |
+| `onSheetAdd` | `() => void` | Called when the user clicks the **+** button. Omit to hide it. |
+
+`ISheetDef` is a small shape from `@alaarab/ogrid-core`:
+
+```ts
+interface ISheetDef {
+  id: string;
+  name: string;
+  color?: string; // optional tab color (any CSS color)
+}
+```
+
+## Example
+
+The grid is controlled: you own `activeSheet` and pick which data to show.
+
+```tsx
+
+const sheets = [
+  { id: "q1", name: "Q1" },
+  { id: "q2", name: "Q2" },
+  { id: "fy", name: "Full Year", color: "#217346" },
+];
+
+const dataBySheet = {
+  q1: q1Rows,
+  q2: q2Rows,
+  fy: fyRows,
+};
+
+function Workbook() {
+  const [activeSheet, setActiveSheet] = useState("q1");
+  return (
+    <OGrid
+      columns={columns}
+      data={dataBySheet[activeSheet]}
+      getRowId={(r) => r.id}
+      sheetDefs={sheets}
+      activeSheet={activeSheet}
+      onSheetChange={setActiveSheet}
+      onSheetAdd={() => {/* add a sheet to your own state */}}
+    />
+  );
+}
+```
+
+## Cross-sheet formulas
+
+When [formulas](./formulas) are enabled, the `sheets` prop registers other sheets' data as accessors so a formula can reference another sheet (e.g. `=Q2!A1`):
+
+```tsx
+<OGrid
+  /* ...sheet props as above... */
+  formulas
+  sheets={{ Q2: q2Accessor, FY: fyAccessor }}
+/>
+```
+
+## Standalone tab bar
+
+The tab bar is also exported on its own as `SheetTabs` from `@alaarab/ogrid-react`, if you want to render it outside the grid:
+
+```tsx
+
+<SheetTabs
+  sheets={sheets}
+  activeSheet={activeSheet}
+  onSheetChange={setActiveSheet}
+  onSheetAdd={addSheet}
+/>;
+```

package/bundled-docs/features/performance.mdx

@@ -5,10 +5,13 @@ description: Automatic CSS containment, opt-in Web Worker sort/filter, and colum
 ---
 
 
+
 # Performance
 
 A grid that handles 100 rows fine but chokes at 50,000 isn't production-ready. OGrid ships with three complementary features to handle large datasets without framework-level heroics:
 
+<PerformanceDemo />
+
 | Feature | Opt-in? | What it does |
 |---------|---------|---------|
 | **CSS Containment** | No (automatic) | Browser skips layout and paint for off-screen cells |

package/bundled-docs/features/premium-inputs.mdx

@@ -5,10 +5,13 @@ description: Optional premium cell editors with zero bundle impact when not inst
 ---
 
 
+
 # Premium Inputs
 
 OGrid's premium inputs are optional cell editor components distributed in a separate package. They are fully tree-shakeable and have **zero bundle impact** when not installed -- your grid stays lightweight until you explicitly opt in.
 
+<PremiumInputsDemo />
+
 ## Installation
 
 <Tabs groupId="framework">

package/bundled-docs/features/responsive-columns.mdx

@@ -5,10 +5,13 @@ description: Automatically hide columns based on container width using responsiv
 ---
 
 
+
 # Responsive Columns
 
 OGrid can automatically hide lower-priority columns when the grid container becomes narrow, keeping the most important data visible on smaller screens. Columns are progressively hidden based on `responsivePriority` values and configurable width breakpoints.
 
+<ResponsiveColumnsDemo />
+
 ## How It Works
 
 1. Assign `responsivePriority` to columns (0 = highest priority, always visible).

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

@@ -1,13 +1,16 @@
 ---
 sidebar_position: 16
-title: XLSX Import
-description: Drop an .xlsx file into a fully featured OGrid — with multi-sheet tabs, formulas, and cell references on by default
+title: XLSX Import & Export
+description: Drop an .xlsx file into a fully featured OGrid — and export grid data back out as a real workbook
 ---
 
 
-# XLSX Import
 
-Render any `.xlsx`, CSV, or TSV blob as a fully featured OGrid. Multi-sheet workbooks get tabbed navigation, formulas evaluate live, and Excel-style cell references (A1, B2…) are on by default.
+# XLSX Import & Export
+
+Render any `.xlsx`, CSV, or TSV blob as a fully featured OGrid — and export grid data back out as a real `.xlsx` workbook. Multi-sheet workbooks get tabbed navigation, formulas evaluate live, and Excel-style cell references (A1, B2…) are on by default.
+
+<XlsxImportDemo />
 
 Two packages ship this:
 
@@ -64,7 +67,7 @@ function SingleSheet({ file }: { file: Blob }) {
 
 ### Format support
 
-ExcelJS-backed: `.xlsx`, `.csv`, `.tsv`. The `xlsx` package on npm (SheetJS) is currently stuck at the vulnerable 0.18.5, so support for `.xls`, `.xlsm`, `.xlsb`, and `.ods` was dropped in 2.12.0. See CHANGELOG for the swap rationale.
+Supported formats: `.xlsx`, `.csv`, `.tsv` (backed by ExcelJS).
 
 ## Browser bundle (no bundler)
 
@@ -117,6 +120,34 @@ Returns an unmount function. Always call it before removing the host node — Re
 | You want tree-shaking and a single dependency graph. | You don't have (and don't want) a JS bundler. |
 | You're integrating into an existing React tree. | You want one `<script type="module">` import. |
 
+## Exporting
+
+`exportToXlsx` mirrors [`exportToCsv`](./csv-export)'s call shape — pass rows, lightweight column defs, a value accessor, and a filename:
+
+```tsx
+
+await exportToXlsx(
+  rows,
+  [
+    { columnId: 'name', name: 'Name' },
+    { columnId: 'salary', name: 'Salary' },
+  ],
+  (item, columnId) => item[columnId],
+  'people.xlsx',
+);
+```
+
+Values export as native Excel types: numbers, dates, and booleans round-trip without stringification. To emit **live formulas** (Excel recalculates them on open), pass the same `{col, row, formula}` array `sheetToGridData` produced on import:
+
+```tsx
+await exportToXlsx(rows, columns, getValue, 'sheet.xlsx', {
+  sheetName: 'Data',
+  formulas: initialFormulas, // e.g. from the imported workbook
+});
+```
+
+For full control (multi-sheet assembly, styling), build the workbook yourself with `workbookFromGridData(rows, columns, getValue, options)` — it returns an `ExcelJS.Workbook` you can add sheets to before serializing with `xlsxBlobFromWorkbook(wb)`.
+
 ## Related
 
 - [Formulas](./formulas) — the engine that evaluates `=SUM(A1:A5)` cells lifted out of the workbook

package/bundled-docs/getting-started/headless-or-component.mdx

@@ -81,10 +81,10 @@ The full integration code is the
 
 ## Both at once — yes, in the same app
 
-Mix freely. A typical pattern:
+Mix freely. A common pattern:
 
-- 80% of admin / list pages → `<OGrid>` (fast to build, good enough chrome)
-- 20% of "the data table is the product" pages → headless hooks (custom chrome wins)
+- Standard admin / list pages → `<OGrid>` (fast to build, sensible default UI)
+- Pages where the table is the product → the hooks (full control over the markup)
 
 Same package import. Same theme tokens. Same TypeScript types. The
 spreadsheet features (inline edit, fill handle, clipboard, undo) work

package/bundled-docs/getting-started/installation.mdx

@@ -34,14 +34,9 @@ npm install @alaarab/ogrid-react-fluent @fluentui/react-components
 
 ---
 
-## Frozen adapters
+## Other adapters
 
-The following adapters remain on npm at their last shipped version but no longer receive feature work or framework-major upgrades. Existing installs continue to work unchanged. Source for each lives on the `legacy/multiframework` branch of the repo.
-
-- **`@alaarab/ogrid-react-material`** — frozen at v2.9.1. MUI v7 (skipped v8, broke in v9).
-- **`@alaarab/ogrid-js`** + **`@alaarab/ogrid-js-inputs`** — frozen at v2.9.1. The vanilla JS variant.
-- **`@alaarab/ogrid-angular*`** — frozen at v2.9.0.
-- **`@alaarab/ogrid-vue*`** — frozen at v2.9.0.
+OGrid is React-first (Radix or Fluent). Material UI, vanilla JS, Angular, and Vue adapters were published earlier and remain on npm for existing installs, but are no longer actively developed.
 
 ---
 

package/bundled-docs/getting-started/overview.mdx

@@ -8,7 +8,7 @@ description: What is OGrid and why use it
 
 OGrid is a lightweight, open-source React data grid library that delivers spreadsheet-grade features without the enterprise paywall. It ships React UI implementations for Radix and Fluent UI, all powered by a shared TypeScript core.
 
-> **Note:** Angular, Vue, vanilla JS, and Material UI adapters were available through earlier 2.9.x versions and remain on npm at those versions. New development is React-first (Radix / Fluent). See the project README's "Frozen adapters" section if you have an existing install on one of the frozen variants.
+> **Note:** OGrid is React-first (Radix or Fluent). Angular, Vue, vanilla JS, and Material UI adapters were published earlier and remain on npm for existing installs, but are no longer actively developed.
 
 ## Why OGrid?
 

package/bundled-docs/guides/theming.mdx

@@ -187,7 +187,7 @@ Users can resize columns by dragging the column border. Listen for resize events
 />
 ```
 
-## Theme presets (new in 2.9)
+## Theme presets
 
 Instead of mapping `--ogrid-*` variables to your design system one-by-one,
 shadcn/Tailwind v4 preset ships with `@alaarab/ogrid-react-radix`:
@@ -207,9 +207,9 @@ Both light and dark modes follow your shadcn theme automatically — no
 hand-authored `[data-theme="dark"]` override blocks needed. The `.dark`
 class on `<html>` (Tailwind v3+/shadcn convention) is fully supported.
 
-### New theming tokens (2.9)
+### Theming tokens
 
-In addition to the colors documented above, 2.8.0 added a radius/font/ring
+In addition to the colors documented above, a radius/font/ring
 scale that `preset-shadcn.css` bridges automatically:
 
 | Variable | Default | Description |

package/dist/esm/bridge-client.js

@@ -63,9 +63,9 @@ function connectGridToBridge(options) {
     try {
       switch (cmd.type) {
         case "update_cell": {
-          const rowIndex = cmd.payload["rowIndex"];
-          const columnId = cmd.payload["columnId"];
-          const value = cmd.payload["value"];
+          const rowIndex = cmd.payload.rowIndex;
+          const columnId = cmd.payload.columnId;
+          const value = cmd.payload.value;
           if (onCellUpdate) {
             onCellUpdate(rowIndex, columnId, value);
             result = { ok: true, rowIndex, columnId, value };
@@ -75,8 +75,8 @@ function connectGridToBridge(options) {
           break;
         }
         case "set_filter": {
-          const columnId = cmd.payload["columnId"];
-          const value = cmd.payload["value"];
+          const columnId = cmd.payload.columnId;
+          const value = cmd.payload.value;
           if (api?.updateFilter) {
             api.updateFilter(columnId, value);
             result = { ok: true };
@@ -95,7 +95,7 @@ function connectGridToBridge(options) {
           break;
         }
         case "set_sort": {
-          const sortModel = cmd.payload["sortModel"];
+          const sortModel = cmd.payload.sortModel;
           if (api?.updateSort) {
             api.updateSort(sortModel);
             result = { ok: true };
@@ -105,7 +105,7 @@ function connectGridToBridge(options) {
           break;
         }
         case "go_to_page": {
-          const page = cmd.payload["page"];
+          const page = cmd.payload.page;
           if (api?.goToPage) {
             api.goToPage(page);
             result = { ok: true };

package/dist/esm/index.js

@@ -27,7 +27,7 @@ var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
 function parseFrontmatter(raw) {
   const match = FRONTMATTER_RE.exec(raw);
   if (!match) return { title: "", description: "" };
-  const block = match[1];
+  const block = match[1] ?? "";
   let title = "";
   let description = "";
   for (const line of block.split("\n")) {
@@ -56,7 +56,7 @@ function extractCodeBlocks(raw) {
   CODE_BLOCK_RE.lastIndex = 0;
   while ((match = CODE_BLOCK_RE.exec(raw)) !== null) {
     const language = match[1] || "text";
-    const code = match[2].trim();
+    const code = (match[2] ?? "").trim();
     const precedingStart = Math.max(0, match.index - 300);
     const surroundingContext = raw.slice(precedingStart, match.index);
     const framework = detectFramework(language, code, surroundingContext);
@@ -218,14 +218,15 @@ function detectOGridVersion(searchPath) {
         const raw = readFileSync(pkgPath, "utf-8");
         const pkg = JSON.parse(raw);
         const allDeps = {
-          ...pkg["dependencies"] ?? {},
-          ...pkg["devDependencies"] ?? {},
-          ...pkg["peerDependencies"] ?? {}
+          ...pkg.dependencies ?? {},
+          ...pkg.devDependencies ?? {},
+          ...pkg.peerDependencies ?? {}
         };
         const ogridPkgs = Object.entries(allDeps).filter(([name]) => name.startsWith("@alaarab/ogrid-")).map(([name, version]) => ({ name, version: String(version) }));
-        if (ogridPkgs.length > 0) {
+        const firstPkg = ogridPkgs[0];
+        if (firstPkg) {
           const framework = detectFramework2(ogridPkgs.map((p) => p.name));
-          const version = ogridPkgs[0].version.replace(/^[\^~>=<]+/, "");
+          const version = firstPkg.version.replace(/^[\^~>=<]+/, "");
           return { found: true, version, framework, packages: ogridPkgs, packageJsonPath: pkgPath };
         }
       } catch {
@@ -280,9 +281,10 @@ Categories: features, getting-started, guides, api.`
       const formatted = results.map((entry, i) => {
         const excerpt = entry.content.length > 400 ? entry.content.slice(0, 400) + "..." : entry.content;
         const relevantCode = framework ? entry.codeBlocks.filter((b) => !b.framework || b.framework === framework).slice(0, 1) : [];
-        const codeSnippet = relevantCode.length > 0 ? `
-\`\`\`${relevantCode[0].language}
-${relevantCode[0].code.slice(0, 300)}
+        const firstCode = relevantCode[0];
+        const codeSnippet = firstCode ? `
+\`\`\`${firstCode.language}
+${firstCode.code.slice(0, 300)}
 \`\`\`` : "";
         return [
           `## ${i + 1}. ${entry.title}`,
@@ -537,6 +539,7 @@ Tip: use \`get_code_example\` with framework="${result.framework}" or \`search_d
             "```tsx",
             "const dataSource = {",
             "  fetchPage: async ({ page, pageSize, sort, filters, signal }) => {",
+            // biome-ignore lint/suspicious/noTemplateCurlyInString: intentional — this is documentation example code emitted as text; the ${} placeholders belong to the sample snippet
             "    const res = await fetch(`/api/data?page=${page}&size=${pageSize}`, { signal });",
             "    const json = await res.json();",
             "    return { items: json.data, totalCount: json.total };",
@@ -964,26 +967,37 @@ function readBody(req) {
     req.on("error", reject);
   });
 }
-function send(res, status, body) {
+var LOCALHOST_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
+function corsOrigin(req) {
+  const origin = req.headers.origin;
+  return origin && LOCALHOST_ORIGIN.test(origin) ? origin : "";
+}
+function send(req, res, status, body) {
   const json = JSON.stringify(body);
-  res.writeHead(status, {
+  const headers = {
     "Content-Type": "application/json",
     "Content-Length": Buffer.byteLength(json),
-    "Access-Control-Allow-Origin": "*",
+    Vary: "Origin",
     "Access-Control-Allow-Methods": "GET, POST, PUT, OPTIONS",
     "Access-Control-Allow-Headers": "Content-Type"
-  });
+  };
+  const allow = corsOrigin(req);
+  if (allow) headers["Access-Control-Allow-Origin"] = allow;
+  res.writeHead(status, headers);
   res.end(json);
 }
 function startBridgeServer(store, port = 7890) {
   return new Promise((resolve, reject) => {
     const httpServer = createServer(async (req, res) => {
       if (req.method === "OPTIONS") {
-        res.writeHead(204, {
-          "Access-Control-Allow-Origin": "*",
+        const headers = {
           "Access-Control-Allow-Methods": "GET, POST, PUT, OPTIONS",
-          "Access-Control-Allow-Headers": "Content-Type"
-        });
+          "Access-Control-Allow-Headers": "Content-Type",
+          Vary: "Origin"
+        };
+        const allow = corsOrigin(req);
+        if (allow) headers["Access-Control-Allow-Origin"] = allow;
+        res.writeHead(204, headers);
         res.end();
         return;
       }
@@ -991,45 +1005,45 @@ function startBridgeServer(store, port = 7890) {
       const parts = url.pathname.replace(/^\//, "").split("/");
       try {
         if (req.method === "GET" && parts[0] === "health") {
-          send(res, 200, { ok: true, grids: store.listGrids().length });
+          send(req, res, 200, { ok: true, grids: store.listGrids().length });
           return;
         }
         if (req.method === "POST" && parts[0] === "grids" && parts[1] === "connect") {
           const body = await readBody(req);
-          const gridId = String(body?.["gridId"] ?? "");
+          const gridId = String(body?.gridId ?? "");
           if (!gridId) {
-            send(res, 400, { error: "gridId required" });
+            send(req, res, 400, { error: "gridId required" });
             return;
           }
           store.upsertGrid(gridId, body);
-          send(res, 200, { ok: true });
+          send(req, res, 200, { ok: true });
           return;
         }
-        if (req.method === "PUT" && parts[0] === "grids" && parts[2] === "state") {
+        if (req.method === "PUT" && parts[0] === "grids" && parts[1] != null && parts[2] === "state") {
           const gridId = parts[1];
           const body = await readBody(req);
           store.upsertGrid(gridId, body);
-          send(res, 200, { ok: true });
+          send(req, res, 200, { ok: true });
           return;
         }
-        if (req.method === "GET" && parts[0] === "grids" && parts[2] === "commands") {
+        if (req.method === "GET" && parts[0] === "grids" && parts[1] != null && parts[2] === "commands") {
           const gridId = parts[1];
           const state = store.getState(gridId);
           if (state) store.upsertGrid(gridId, {});
           const cmds = store.popPendingCommands(gridId);
-          send(res, 200, cmds);
+          send(req, res, 200, cmds);
           return;
         }
-        if (req.method === "POST" && parts[0] === "grids" && parts[2] === "commands" && parts[4] === "result") {
+        if (req.method === "POST" && parts[0] === "grids" && parts[2] === "commands" && parts[3] != null && parts[4] === "result") {
           const cmdId = parts[3];
           const body = await readBody(req);
-          store.resolveCommand(cmdId, body?.["result"], body?.["error"]);
-          send(res, 200, { ok: true });
+          store.resolveCommand(cmdId, body?.result, body?.error);
+          send(req, res, 200, { ok: true });
           return;
         }
-        send(res, 404, { error: "Not found" });
+        send(req, res, 404, { error: "Not found" });
       } catch (err) {
-        send(res, 500, { error: String(err) });
+        send(req, res, 500, { error: String(err) });
       }
     });
     httpServer.on("error", reject);
@@ -1053,10 +1067,10 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 var __dirname$1 = dirname(fileURLToPath(import.meta.url));
 var monorepoDocs = join(__dirname$1, "../../../docs/docs");
 var bundledDocs = join(__dirname$1, "../../bundled-docs");
-var docsDir = process.env["OGRID_DOCS_PATH"] ?? (existsSync(monorepoDocs) ? monorepoDocs : bundledDocs);
+var docsDir = process.env.OGRID_DOCS_PATH ?? (existsSync(monorepoDocs) ? monorepoDocs : bundledDocs);
 var index = loadDocsIndex(docsDir);
 var bridgeStore = new BridgeStore();
-var bridgePort = process.env["OGRID_BRIDGE_PORT"] ? parseInt(process.env["OGRID_BRIDGE_PORT"], 10) : process.argv.includes("--bridge") ? 7890 : null;
+var bridgePort = process.env.OGRID_BRIDGE_PORT ? parseInt(process.env.OGRID_BRIDGE_PORT, 10) : process.argv.includes("--bridge") ? 7890 : null;
 if (bridgePort !== null) {
   try {
     await startBridgeServer(bridgeStore, bridgePort);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-mcp",
-  "version": "2.15.1",
+  "version": "2.15.2",
   "description": "MCP server for OGrid documentation",
   "type": "module",
   "repository": {