@alaarab/ogrid-mcp 2.4.0

package/dist/esm/index.js

@@ -0,0 +1,1060 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync, existsSync, statSync, readdirSync } from 'fs';
+import { join, dirname, extname, relative } from 'path';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createServer } from 'http';
+import { fileURLToPath } from 'url';
+
+function collectFiles(dir) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(full));
+    } else if (entry.isFile() && (extname(entry.name) === ".mdx" || extname(entry.name) === ".md")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+function deriveCategory(relPath) {
+  const first = relPath.split("/")[0];
+  return first ?? "uncategorized";
+}
+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];
+  let title = "";
+  let description = "";
+  for (const line of block.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("title:")) {
+      title = trimmed.slice("title:".length).trim().replace(/^['"]|['"]$/g, "");
+    } else if (trimmed.startsWith("description:")) {
+      description = trimmed.slice("description:".length).trim().replace(/^['"]|['"]$/g, "");
+    }
+  }
+  return { title, description };
+}
+var CODE_BLOCK_RE = /```(\w*)\n([\s\S]*?)```/g;
+function detectFramework(language, code, surroundingContext) {
+  if (language === "tsx" || language === "jsx") return "react";
+  if (language === "vue") return "vue";
+  const ctxLower = surroundingContext.toLowerCase();
+  if (ctxLower.includes('value="react"') || ctxLower.includes('label="react"'))
+    return "react";
+  if (ctxLower.includes('value="angular"') || ctxLower.includes('label="angular"'))
+    return "angular";
+  if (ctxLower.includes('value="vue"') || ctxLower.includes('label="vue"'))
+    return "vue";
+  if (ctxLower.includes('value="js"') || ctxLower.includes('label="vanilla js"') || ctxLower.includes("vanilla js"))
+    return "js";
+  if (code.includes("@angular/") || code.includes("@Component")) return "angular";
+  if (code.includes("ogrid-vue") || code.includes("<template>")) return "vue";
+  if (code.includes("ogrid-react") || code.includes("from 'react'"))
+    return "react";
+  if (code.includes("ogrid-js") || code.includes("new OGrid(")) return "js";
+  return void 0;
+}
+function extractCodeBlocks(raw) {
+  const blocks = [];
+  let match;
+  CODE_BLOCK_RE.lastIndex = 0;
+  while ((match = CODE_BLOCK_RE.exec(raw)) !== null) {
+    const language = match[1] || "text";
+    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);
+    blocks.push({ language, code, framework });
+  }
+  return blocks;
+}
+function stripMdxContent(raw) {
+  let text = raw;
+  text = text.replace(FRONTMATTER_RE, "");
+  text = text.replace(/^import\s+.*?;\s*$/gm, "");
+  text = text.replace(/```\w*\n[\s\S]*?```/g, "");
+  text = text.replace(/<[A-Z]\w*\s*\/>/g, "");
+  text = text.replace(/<\/?[A-Z][\w.]*(?:\s[^>]*)?>/g, "");
+  text = text.replace(/<\/?[a-z][\w-]*(?:\s[^>]*)?\/?\s*>/g, "");
+  text = text.replace(/^:::\w+.*$/gm, "");
+  text = text.replace(/^:::$/gm, "");
+  text = text.replace(/\n{3,}/g, "\n\n");
+  return text.trim();
+}
+function parseDocFile(filePath, docsDir2) {
+  const raw = readFileSync(filePath, "utf-8");
+  const relPath = relative(docsDir2, filePath);
+  const { title, description } = parseFrontmatter(raw);
+  const category = deriveCategory(relPath);
+  const content = stripMdxContent(raw);
+  const codeBlocks = extractCodeBlocks(raw);
+  return {
+    path: relPath,
+    title: title || relPath,
+    description: description || "",
+    category,
+    content,
+    codeBlocks
+  };
+}
+function scoreEntry(entry, queryLower) {
+  let score = 0;
+  const titleLower = entry.title.toLowerCase();
+  const descLower = entry.description.toLowerCase();
+  const contentLower = entry.content.toLowerCase();
+  if (titleLower.includes(queryLower)) {
+    score += 100;
+    if (titleLower === queryLower) score += 50;
+    if (titleLower.startsWith(queryLower)) score += 25;
+  }
+  if (descLower.includes(queryLower)) {
+    score += 50;
+  }
+  if (contentLower.includes(queryLower)) {
+    score += 10;
+    let idx = 0;
+    let count = 0;
+    while (count < 10) {
+      idx = contentLower.indexOf(queryLower, idx);
+      if (idx === -1) break;
+      count++;
+      idx += queryLower.length;
+    }
+    score += count * 2;
+  }
+  if (entry.category === "features") score += 3;
+  if (entry.category === "getting-started") score += 2;
+  return score;
+}
+function scoreCodeBlock(entry, block, queryLower, framework) {
+  let score = 0;
+  if (framework && block.framework !== framework) return -1;
+  if (entry.title.toLowerCase().includes(queryLower)) score += 50;
+  if (entry.description.toLowerCase().includes(queryLower)) score += 25;
+  if (block.code.toLowerCase().includes(queryLower)) score += 30;
+  return score;
+}
+function loadDocsIndex(docsDir2) {
+  try {
+    statSync(docsDir2);
+  } catch {
+    throw new Error(`Docs directory not found: ${docsDir2}`);
+  }
+  const files = collectFiles(docsDir2);
+  const entries = files.map((f) => parseDocFile(f, docsDir2));
+  const pathMap = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    pathMap.set(entry.path, entry);
+  }
+  return {
+    entries,
+    search(query, limit = 5) {
+      const q = query.toLowerCase().trim();
+      if (!q) return [];
+      const scored = entries.map((entry) => ({ entry, score: scoreEntry(entry, q) })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score);
+      return scored.slice(0, limit).map((r) => r.entry);
+    },
+    getByPath(path) {
+      return pathMap.get(path);
+    },
+    getByCategory(category) {
+      return entries.filter((e) => e.category === category);
+    },
+    getCodeExamples(query, framework) {
+      const q = query.toLowerCase().trim();
+      if (!q) return [];
+      const results = [];
+      for (const entry of entries) {
+        for (const block of entry.codeBlocks) {
+          const s = scoreCodeBlock(entry, block, q, framework);
+          if (s > 0) {
+            results.push({ entry, block, score: s });
+          }
+        }
+      }
+      results.sort((a, b) => b.score - a.score);
+      return results.slice(0, 10).map(({ entry, block }) => ({ entry, block }));
+    }
+  };
+}
+function detectFramework2(packageNames) {
+  if (packageNames.some((n) => n.includes("-react"))) return "react";
+  if (packageNames.some((n) => n.includes("-angular"))) return "angular";
+  if (packageNames.some((n) => n.includes("-vue"))) return "vue";
+  if (packageNames.some((n) => n.endsWith("-js"))) return "js";
+  return "unknown";
+}
+function detectOGridVersion(searchPath) {
+  let dir = searchPath;
+  for (let i = 0; i < 10; i++) {
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const raw = readFileSync(pkgPath, "utf-8");
+        const pkg = JSON.parse(raw);
+        const allDeps = {
+          ...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 framework = detectFramework2(ogridPkgs.map((p) => p.name));
+          const version = ogridPkgs[0].version.replace(/^[\^~>=<]+/, "");
+          return { found: true, version, framework, packages: ogridPkgs, packageJsonPath: pkgPath };
+        }
+      } catch {
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { found: false };
+}
+function toResourcePath(docPath) {
+  return docPath.replace(/\.(mdx|md)$/, "");
+}
+function fromResourcePath(resourcePath, index2) {
+  return index2.getByPath(resourcePath + ".mdx") ?? index2.getByPath(resourcePath + ".md") ?? index2.getByPath(resourcePath);
+}
+function createOGridMcpServer(index2, bridge) {
+  const server2 = new McpServer({
+    name: "ogrid-docs",
+    version: "2.3.0",
+    instructions: `OGrid documentation server. OGrid is a lightweight multi-framework data grid for React, Angular, Vue, and vanilla JS.
+
+Tools: search_docs (keyword search), list_docs (browse by category), get_docs (full page), get_code_example (code snippets), detect_version (detect OGrid version in your project).
+Resources: ogrid://quick-reference (key API overview), ogrid://docs/{path} (any doc page by path).
+Categories: features, getting-started, guides, api.`
+  });
+  server2.tool(
+    "search_docs",
+    "Search OGrid documentation by keyword. Returns matching docs with title, description, and content excerpt.",
+    {
+      query: z.string().describe("Search query string"),
+      limit: z.number().int().min(1).max(20).optional().describe("Max results to return (default 5)"),
+      framework: z.enum(["react", "angular", "vue", "js"]).optional().describe("Filter code examples to this framework")
+    },
+    async ({ query, limit, framework }) => {
+      const results = index2.search(query, limit ?? 5);
+      if (results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No documentation found for "${query}". Try a different search term or use list_docs to browse available docs.`
+            }
+          ]
+        };
+      }
+      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)}
+\`\`\`` : "";
+        return [
+          `## ${i + 1}. ${entry.title}`,
+          `**Path:** ${entry.path}  |  **Category:** ${entry.category}`,
+          `**Description:** ${entry.description}`,
+          "",
+          excerpt,
+          codeSnippet
+        ].filter(Boolean).join("\n");
+      }).join("\n\n---\n\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${results.length} result(s) for "${query}":
+
+${formatted}`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "list_docs",
+    "List available OGrid documentation pages, optionally filtered by category (features, getting-started, guides, api).",
+    {
+      category: z.string().optional().describe("Filter by category: features, getting-started, guides, api")
+    },
+    async ({ category }) => {
+      const entries = category ? index2.getByCategory(category) : index2.entries;
+      if (entries.length === 0) {
+        const available = [...new Set(index2.entries.map((e) => e.category))];
+        return {
+          content: [
+            {
+              type: "text",
+              text: category ? `No docs found in category "${category}". Available categories: ${available.join(", ")}` : "No documentation entries found."
+            }
+          ]
+        };
+      }
+      const formatted = entries.map(
+        (entry) => `- **${entry.title}** \u2014 ${entry.description}
+  Path: \`${entry.path}\` | Resource: \`ogrid://docs/${toResourcePath(entry.path)}\``
+      ).join("\n");
+      const header = category ? `Documentation in "${category}" (${entries.length} pages):` : `All documentation (${entries.length} pages):`;
+      return {
+        content: [{ type: "text", text: `${header}
+
+${formatted}` }]
+      };
+    }
+  );
+  server2.tool(
+    "get_docs",
+    "Get the full content of an OGrid documentation page by its path.",
+    {
+      path: z.string().describe('Document path (e.g. "features/sorting" or "api/column-def")')
+    },
+    async ({ path }) => {
+      const entry = fromResourcePath(path, index2);
+      if (!entry) {
+        const available = index2.entries.map((e) => `  - ${toResourcePath(e.path)}`).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Document not found: "${path}"
+
+Available paths:
+${available}`
+            }
+          ]
+        };
+      }
+      const header = [
+        `# ${entry.title}`,
+        `**Category:** ${entry.category}`,
+        `**Description:** ${entry.description}`,
+        "",
+        "---",
+        ""
+      ].join("\n");
+      return {
+        content: [{ type: "text", text: header + entry.content }]
+      };
+    }
+  );
+  server2.tool(
+    "get_code_example",
+    "Find code examples from OGrid docs matching a query, optionally filtered by framework.",
+    {
+      query: z.string().describe("Search query for code examples"),
+      framework: z.enum(["react", "angular", "vue", "js"]).optional().describe("Filter by framework: react, angular, vue, js")
+    },
+    async ({ query, framework }) => {
+      const examples = index2.getCodeExamples(query, framework);
+      if (examples.length === 0) {
+        const hint = framework ? ` for framework "${framework}"` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No code examples found matching "${query}"${hint}. Try a broader search term or remove the framework filter.`
+            }
+          ]
+        };
+      }
+      const limited = examples.slice(0, 5);
+      const formatted = limited.map((example, i) => {
+        const frameworkLabel = example.block.framework ? ` (${example.block.framework})` : "";
+        return [
+          `### Example ${i + 1}: ${example.entry.title}${frameworkLabel}`,
+          "",
+          "```" + example.block.language,
+          example.block.code,
+          "```"
+        ].join("\n");
+      }).join("\n\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${examples.length} code example(s) for "${query}"${framework ? ` (${framework})` : ""}:
+
+${formatted}`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "detect_version",
+    "Detect which OGrid version and framework is installed in the user's project by reading their package.json.",
+    {
+      path: z.string().optional().describe(
+        "Directory to search from (defaults to current working directory). The tool walks up the directory tree to find the nearest package.json with OGrid dependencies."
+      )
+    },
+    async ({ path }) => {
+      const searchPath = path ?? process.cwd();
+      const result = detectOGridVersion(searchPath);
+      if (!result.found) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `No OGrid packages found in package.json (searched from: ${searchPath}).`,
+                "",
+                "Install OGrid for your framework:",
+                "  React (Radix):    npm install @alaarab/ogrid-react-radix",
+                "  React (Material): npm install @alaarab/ogrid-react-material",
+                "  React (Fluent):   npm install @alaarab/ogrid-react-fluent",
+                "  Angular Material: npm install @alaarab/ogrid-angular-material",
+                "  Angular PrimeNG:  npm install @alaarab/ogrid-angular-primeng",
+                "  Vue Vuetify:      npm install @alaarab/ogrid-vue-vuetify",
+                "  Vue PrimeVue:     npm install @alaarab/ogrid-vue-primevue",
+                "  Vanilla JS:       npm install @alaarab/ogrid-js"
+              ].join("\n")
+            }
+          ]
+        };
+      }
+      const pkgList = (result.packages ?? []).map((p) => `  - ${p.name}: ${p.version}`).join("\n");
+      const frameworkTip = result.framework !== "unknown" ? `
+
+Tip: use \`get_code_example\` with framework="${result.framework}" or \`search_docs\` with framework="${result.framework}" to get framework-specific results.` : "";
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `\u2705 OGrid detected in ${result.packageJsonPath}`,
+              "",
+              `Version:   ${result.version}`,
+              `Framework: ${result.framework}`,
+              "",
+              "Packages installed:",
+              pkgList,
+              frameworkTip
+            ].filter((l) => l !== void 0).join("\n")
+          }
+        ]
+      };
+    }
+  );
+  server2.resource(
+    "quick-reference",
+    "ogrid://quick-reference",
+    { description: "OGrid quick-reference: key props, install commands, and common patterns", mimeType: "text/markdown" },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "text/markdown",
+          text: [
+            "# OGrid Quick Reference",
+            "",
+            "## Install",
+            "```bash",
+            "# React (choose one)",
+            "npm install @alaarab/ogrid-react-radix",
+            "npm install @alaarab/ogrid-react-material",
+            "npm install @alaarab/ogrid-react-fluent",
+            "",
+            "# Angular (choose one)",
+            "npm install @alaarab/ogrid-angular-material",
+            "npm install @alaarab/ogrid-angular-primeng",
+            "npm install @alaarab/ogrid-angular-radix",
+            "",
+            "# Vue (choose one)",
+            "npm install @alaarab/ogrid-vue-vuetify",
+            "npm install @alaarab/ogrid-vue-primevue",
+            "npm install @alaarab/ogrid-vue-radix",
+            "",
+            "# Vanilla JS",
+            "npm install @alaarab/ogrid-js",
+            "```",
+            "",
+            "## Core Props (IOGridProps)",
+            "| Prop | Type | Description |",
+            "|------|------|-------------|",
+            "| `data` | `T[]` | Client-side row data |",
+            "| `columns` | `IColumnDef<T>[]` | Column definitions |",
+            "| `dataSource` | `IDataSource<T>` | Server-side data source |",
+            "| `pagination` | `boolean \\| number` | Enable pagination (number = page size) |",
+            '| `rowSelection` | `"single" \\| "multiple"` | Row selection mode |',
+            "| `formulas` | `boolean` | Enable formula engine (=SUM, =IF, etc.) |",
+            "| `cellReferences` | `boolean` | Excel-style A1 column headers + name box |",
+            '| `workerSort` | `boolean \\| "auto"` | Web Worker sort/filter |',
+            '| `columnChooser` | `boolean \\| "toolbar" \\| "sidebar"` | Column visibility control |',
+            "| `sideBar` | `boolean \\| ISideBarDef` | Sidebar panel |",
+            "| `toolbar` | `ReactNode` | Custom toolbar content |",
+            "| `onRowSelectionChanged` | `(rows: T[]) => void` | Row selection callback |",
+            "| `onCellValueChanged` | `(e: ICellValueChangedEvent) => void` | Cell edit callback |",
+            "",
+            "## IColumnDef Key Fields",
+            "| Field | Type | Description |",
+            "|-------|------|-------------|",
+            "| `columnId` | `string` | Unique column ID (maps to data key) |",
+            "| `headerName` | `string` | Column header label |",
+            '| `type` | `"text" \\| "numeric" \\| "date" \\| "boolean"` | Data type |',
+            '| `filter` | `"none" \\| "text" \\| "multiSelect" \\| "date"` | Filter type |',
+            "| `editable` | `boolean \\| (row) => boolean` | Enable inline editing |",
+            "| `width` | `number` | Column width in px |",
+            '| `pinned` | `"left" \\| "right"` | Pin column |',
+            "| `sortable` | `boolean` | Enable sorting |",
+            "| `hidden` | `boolean` | Hide column by default |",
+            "| `valueGetter` | `(row: T) => unknown` | Custom value extractor |",
+            "| `renderCell` | `(value, row) => ReactNode` | Custom cell renderer (React) |",
+            "",
+            "## Common Patterns",
+            "",
+            "### Client-side data",
+            "```tsx",
+            'import { OGrid } from "@alaarab/ogrid-react-radix";',
+            "const columns = [",
+            '  { columnId: "name", headerName: "Name", type: "text", filter: "text" },',
+            '  { columnId: "age",  headerName: "Age",  type: "numeric", sortable: true },',
+            "];",
+            "<OGrid data={rows} columns={columns} pagination={50} />",
+            "```",
+            "",
+            "### Server-side data",
+            "```tsx",
+            "const dataSource = {",
+            "  fetchPage: async ({ page, pageSize, sortModel, filterModel }) => {",
+            "    const res = await fetch(`/api/data?page=${page}&size=${pageSize}`);",
+            "    const json = await res.json();",
+            "    return { rows: json.data, totalCount: json.total };",
+            "  }",
+            "};",
+            "<OGrid dataSource={dataSource} columns={columns} pagination={50} />",
+            "```",
+            "",
+            "### Formula support",
+            "```tsx",
+            "<OGrid data={rows} columns={columns} formulas cellReferences />",
+            '// Users can type =SUM(A1:C3), =IF(A1>0,"yes","no"), etc.',
+            "```"
+          ].join("\n")
+        }
+      ]
+    })
+  );
+  server2.resource(
+    "migration-guide",
+    "ogrid://migration-guide",
+    { description: "Full migration guide from AG Grid to OGrid with side-by-side API mapping", mimeType: "text/markdown" },
+    async (uri) => {
+      const entry = index2.getByPath("guides/migration-from-ag-grid.mdx") ?? index2.getByPath("guides/migration-from-ag-grid.md") ?? index2.getByPath("guides/migration-from-ag-grid");
+      const text = entry ? `# ${entry.title}
+> ${entry.description}
+
+${entry.content}` : '# Migration from AG Grid\n\nMigration guide not found in docs index. Use `search_docs` with query "migration" to find available migration content.';
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text
+          }
+        ]
+      };
+    }
+  );
+  server2.prompt(
+    "migrate-from-ag-grid",
+    "Step-by-step guide to migrate from AG Grid to OGrid",
+    async () => {
+      const entry = index2.getByPath("guides/migration-from-ag-grid.mdx") ?? index2.getByPath("guides/migration-from-ag-grid.md") ?? index2.getByPath("guides/migration-from-ag-grid");
+      const guideContent = entry ? entry.content : 'Migration guide not found. Please use `search_docs` with query "migration" to find available content.';
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                "I want to migrate my project from AG Grid to OGrid. Use the following migration guide to help me step by step.",
+                "",
+                "---",
+                "",
+                guideContent,
+                "",
+                "---",
+                "",
+                "Please analyze my current AG Grid usage and provide specific migration steps. For each AG Grid API, prop, or pattern I use, show me the OGrid equivalent with a code example."
+              ].join("\n")
+            }
+          }
+        ]
+      };
+    }
+  );
+  server2.resource(
+    "doc-page",
+    new ResourceTemplate("ogrid://docs/{path}", {
+      list: async () => ({
+        resources: index2.entries.map((entry) => ({
+          uri: `ogrid://docs/${toResourcePath(entry.path)}`,
+          name: entry.title,
+          description: entry.description,
+          mimeType: "text/markdown"
+        }))
+      })
+    }),
+    { description: 'OGrid documentation page. Use path like "features/filtering" or "api/column-def".', mimeType: "text/markdown" },
+    async (uri, { path }) => {
+      const entry = fromResourcePath(path, index2);
+      if (!entry) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "text/markdown",
+              text: `# Not Found
+
+No documentation found at path: "${path}"
+
+Use \`list_docs\` tool or \`resources/list\` to see available paths.`
+            }
+          ]
+        };
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: [
+              `# ${entry.title}`,
+              `> ${entry.description}`,
+              "",
+              entry.content
+            ].join("\n")
+          }
+        ]
+      };
+    }
+  );
+  if (bridge) {
+    server2.tool(
+      "list_grids",
+      "List OGrid instances currently connected to the live testing bridge. Returns grid IDs, row counts, page info, and last-seen timestamps.",
+      {},
+      async () => {
+        const grids = bridge.listGrids();
+        if (grids.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  "No OGrid instances connected.",
+                  "",
+                  "To connect your app, add the bridge client:",
+                  "```js",
+                  "import { connectGridToBridge } from '@alaarab/ogrid-mcp/bridge-client';",
+                  "const bridge = connectGridToBridge({ gridId: 'my-grid', getData: () => rows, getColumns: () => columns });",
+                  "```",
+                  "",
+                  "Then start the MCP server with bridge enabled:",
+                  "  OGRID_BRIDGE_PORT=7890 npx @alaarab/ogrid-mcp",
+                  "  \u2014 or \u2014",
+                  "  npx @alaarab/ogrid-mcp --bridge"
+                ].join("\n")
+              }
+            ]
+          };
+        }
+        const formatted = grids.map((g) => {
+          const age = Math.round((Date.now() - g.lastSeen) / 1e3);
+          return [
+            `**${g.gridId}**`,
+            `  Rows: ${g.rowCount} displayed / ${g.totalCount} total`,
+            `  Page: ${g.page} / ${g.pageCount} (${g.pageSize} per page)`,
+            `  Columns: ${g.columns.map((c) => c.columnId).join(", ")}`,
+            `  Active filters: ${Object.keys(g.filterModel).length}`,
+            `  Last seen: ${age}s ago`
+          ].join("\n");
+        }).join("\n\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${grids.length} connected grid(s):
+
+${formatted}`
+            }
+          ]
+        };
+      }
+    );
+    server2.tool(
+      "get_grid_state",
+      "Get the current state of a connected OGrid instance: displayed rows, columns, sort, filters, pagination, and selection.",
+      {
+        gridId: z.string().describe("Grid ID as registered by connectGridToBridge()"),
+        includeData: z.boolean().optional().describe("Whether to include the full row data (default: false \u2014 shows only summary)"),
+        maxRows: z.number().int().min(1).max(200).optional().describe("Max rows to include when includeData=true (default: 20)")
+      },
+      async ({ gridId, includeData, maxRows }) => {
+        const state = bridge.getState(gridId);
+        if (!state) {
+          const available = bridge.listGrids().map((g) => g.gridId);
+          return {
+            content: [
+              {
+                type: "text",
+                text: available.length > 0 ? `Grid "${gridId}" not found. Available grids: ${available.join(", ")}` : `Grid "${gridId}" not found. No grids are currently connected.`
+              }
+            ]
+          };
+        }
+        const age = Math.round((Date.now() - state.lastSeen) / 1e3);
+        const colNames = state.columns.map((c) => `${c.columnId}${c.type ? ` (${c.type})` : ""}`).join(", ");
+        const sortDesc = state.sortModel.length > 0 ? state.sortModel.map((s) => `${s.columnId} ${s.direction}`).join(", ") : "none";
+        const filterDesc = Object.keys(state.filterModel).length > 0 ? JSON.stringify(state.filterModel) : "none";
+        const sections = [
+          `# Grid: ${gridId}`,
+          `Last seen: ${age}s ago`,
+          "",
+          `## Pagination`,
+          `Page ${state.page} of ${state.pageCount} | ${state.rowCount} rows displayed | ${state.totalCount} total`,
+          `Page size: ${state.pageSize}`,
+          "",
+          `## Columns (${state.columns.length})`,
+          colNames,
+          "",
+          `## Sort`,
+          sortDesc,
+          "",
+          `## Filters`,
+          filterDesc,
+          "",
+          `## Selection`,
+          state.selectedRowIndices.length > 0 ? `${state.selectedRowIndices.length} row(s) selected: indices [${state.selectedRowIndices.slice(0, 10).join(", ")}${state.selectedRowIndices.length > 10 ? ", ..." : ""}]` : "None"
+        ];
+        if (includeData) {
+          const limit = maxRows ?? 20;
+          const rows = state.data.slice(0, limit);
+          sections.push("", `## Data (first ${rows.length} of ${state.rowCount} rows)`);
+          sections.push("```json");
+          sections.push(JSON.stringify(rows, null, 2));
+          sections.push("```");
+          if (state.rowCount > limit) {
+            sections.push(`
+_${state.rowCount - limit} more rows not shown. Increase maxRows to see more._`);
+          }
+        }
+        return {
+          content: [{ type: "text", text: sections.join("\n") }]
+        };
+      }
+    );
+    server2.tool(
+      "send_grid_command",
+      [
+        "Send a command to a connected OGrid instance and wait for the result.",
+        "",
+        "Command types:",
+        "  update_cell   \u2014 { rowIndex: number, columnId: string, value: unknown }",
+        "  set_filter    \u2014 { columnId: string, value: string | string[] }",
+        "  clear_filters \u2014 {}",
+        '  set_sort      \u2014 { sortModel: [{ columnId, direction: "asc"|"desc" }] }',
+        "  go_to_page    \u2014 { page: number }"
+      ].join("\n"),
+      {
+        gridId: z.string().describe("Grid ID as registered by connectGridToBridge()"),
+        type: z.enum(["update_cell", "set_filter", "clear_filters", "set_sort", "go_to_page"]).describe("Command type"),
+        payload: z.record(z.unknown()).describe("Command-specific payload (see tool description for fields per type)"),
+        timeoutMs: z.number().int().min(100).max(3e4).optional().describe("How long to wait for the app to execute the command (default: 5000ms)")
+      },
+      async ({ gridId, type, payload, timeoutMs }) => {
+        const state = bridge.getState(gridId);
+        if (!state) {
+          const available = bridge.listGrids().map((g) => g.gridId);
+          return {
+            content: [
+              {
+                type: "text",
+                text: available.length > 0 ? `Grid "${gridId}" not found. Available: ${available.join(", ")}` : `Grid "${gridId}" not found. No grids are currently connected.`
+              }
+            ]
+          };
+        }
+        const cmd = bridge.enqueueCommand(gridId, type, payload);
+        if (!cmd) {
+          return {
+            content: [{ type: "text", text: `Failed to enqueue command for grid "${gridId}".` }]
+          };
+        }
+        try {
+          const result = await bridge.waitForResult(cmd.id, timeoutMs ?? 5e3);
+          if (result.status === "error") {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Command failed: ${result.error ?? "unknown error"}
+
+Command: ${JSON.stringify({ type, payload }, null, 2)}`
+                }
+              ]
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `\u2705 Command executed successfully`,
+                  "",
+                  `Type: ${type}`,
+                  `Payload: ${JSON.stringify(payload)}`,
+                  `Result: ${JSON.stringify(result.result)}`,
+                  "",
+                  `Call get_grid_state to see the updated grid state.`
+                ].join("\n")
+              }
+            ]
+          };
+        } catch {
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  `\u23F1\uFE0F Command timed out after ${timeoutMs ?? 5e3}ms.`,
+                  "",
+                  "The OGrid app may not be polling for commands. Check that:",
+                  "1. connectGridToBridge() is active in your app",
+                  "2. The pollIntervalMs is not too large (default: 500ms)",
+                  `3. The grid ID matches: "${gridId}"`
+                ].join("\n")
+              }
+            ]
+          };
+        }
+      }
+    );
+  }
+  return server2;
+}
+var BridgeStore = class {
+  constructor() {
+    this.grids = /* @__PURE__ */ new Map();
+    this.commandQueues = /* @__PURE__ */ new Map();
+    this.commandResults = /* @__PURE__ */ new Map();
+    this.cmdSeq = 0;
+  }
+  // ---- Called by HTTP handler ----
+  upsertGrid(gridId, partial) {
+    const existing = this.grids.get(gridId);
+    const now = Date.now();
+    this.grids.set(gridId, {
+      connectedAt: existing?.connectedAt ?? now,
+      lastSeen: now,
+      rowCount: 0,
+      totalCount: 0,
+      page: 1,
+      pageSize: 50,
+      pageCount: 1,
+      data: [],
+      columns: [],
+      sortModel: [],
+      filterModel: {},
+      selectedRowIndices: [],
+      ...existing,
+      ...partial,
+      // gridId must always be the canonical value — set last so partial can't override it
+      gridId
+    });
+    if (!this.commandQueues.has(gridId)) {
+      this.commandQueues.set(gridId, []);
+    }
+  }
+  popPendingCommands(gridId) {
+    const queue = this.commandQueues.get(gridId) ?? [];
+    const pending = queue.filter((c) => c.status === "pending");
+    const unsent = pending.filter((c) => !c.sent);
+    for (const cmd of unsent) {
+      cmd.sent = true;
+    }
+    return unsent;
+  }
+  resolveCommand(cmdId, result, error) {
+    for (const queue of this.commandQueues.values()) {
+      const cmd = queue.find((c) => c.id === cmdId);
+      if (cmd) {
+        cmd.status = error ? "error" : "completed";
+        cmd.result = result;
+        cmd.error = error;
+        this.commandResults.set(cmdId, { ...cmd });
+        return;
+      }
+    }
+  }
+  // ---- Called by MCP tools ----
+  listGrids() {
+    const cutoff = Date.now() - 3e4;
+    return [...this.grids.values()].filter((g) => g.lastSeen > cutoff);
+  }
+  getState(gridId) {
+    return this.grids.get(gridId);
+  }
+  enqueueCommand(gridId, type, payload) {
+    if (!this.grids.has(gridId)) return null;
+    const cmd = {
+      id: `cmd-${++this.cmdSeq}-${Date.now()}`,
+      type,
+      payload,
+      createdAt: Date.now(),
+      status: "pending"
+    };
+    const queue = this.commandQueues.get(gridId) ?? [];
+    queue.push(cmd);
+    this.commandQueues.set(gridId, queue);
+    return cmd;
+  }
+  waitForResult(cmdId, timeoutMs = 5e3) {
+    return new Promise((resolve, reject) => {
+      const deadline = Date.now() + timeoutMs;
+      const poll = () => {
+        const cmd = this.commandResults.get(cmdId);
+        if (cmd) {
+          resolve(cmd);
+          return;
+        }
+        if (Date.now() > deadline) {
+          reject(new Error(`Command ${cmdId} timed out after ${timeoutMs}ms`));
+          return;
+        }
+        setTimeout(poll, 100);
+      };
+      poll();
+    });
+  }
+};
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf-8") || "null"));
+      } catch {
+        resolve(null);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function send(res, status, body) {
+  const json = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(json),
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type"
+  });
+  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": "*",
+          "Access-Control-Allow-Methods": "GET, POST, PUT, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type"
+        });
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+      const parts = url.pathname.replace(/^\//, "").split("/");
+      try {
+        if (req.method === "GET" && parts[0] === "health") {
+          send(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"] ?? "");
+          if (!gridId) {
+            send(res, 400, { error: "gridId required" });
+            return;
+          }
+          store.upsertGrid(gridId, body);
+          send(res, 200, { ok: true });
+          return;
+        }
+        if (req.method === "PUT" && parts[0] === "grids" && parts[2] === "state") {
+          const gridId = parts[1];
+          const body = await readBody(req);
+          store.upsertGrid(gridId, body);
+          send(res, 200, { ok: true });
+          return;
+        }
+        if (req.method === "GET" && parts[0] === "grids" && 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);
+          return;
+        }
+        if (req.method === "POST" && parts[0] === "grids" && parts[2] === "commands" && parts[4] === "result") {
+          const cmdId = parts[3];
+          const body = await readBody(req);
+          store.resolveCommand(cmdId, body?.["result"], body?.["error"]);
+          send(res, 200, { ok: true });
+          return;
+        }
+        send(res, 404, { error: "Not found" });
+      } catch (err) {
+        send(res, 500, { error: String(err) });
+      }
+    });
+    httpServer.on("error", reject);
+    httpServer.listen(port, "127.0.0.1", () => {
+      console.error(`[ogrid-mcp] Bridge server listening on http://localhost:${port}`);
+      resolve(
+        () => new Promise((res) => {
+          httpServer.close(() => res());
+        })
+      );
+    });
+  });
+}
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  process.stdout.write(`${pkg.version}
+`);
+  process.exit(0);
+}
+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 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;
+if (bridgePort !== null) {
+  try {
+    await startBridgeServer(bridgeStore, bridgePort);
+  } catch (err) {
+    console.error(`[ogrid-mcp] Failed to start bridge server on port ${bridgePort}: ${String(err)}`);
+  }
+}
+var server = createOGridMcpServer(index, bridgeStore);
+var transport = new StdioServerTransport();
+await server.connect(transport);