@react-querybuilder/mcp 0.0.0-stage → 8.24.4

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @react-querybuilder/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local (stdio) [Model Context Protocol](https://modelcontextprotocol.io) server for [React Query Builder](https://react-querybuilder.js.org/). Gives coding agents the library's real query tooling and version-pinned docs.
+
+## Tools
+
+| Tool               | Purpose                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| `format_query`     | RQB query → any `formatQuery` format (SQL, parameterized, MongoDB, CEL, JsonLogic, natural language, …) |
+| `parse_query`      | SQL/CEL/MongoDB/JsonLogic/SpEL/JSONata/Cypher/GQL/Gremlin/SPARQL → RQB query                            |
+| `convert_query`    | Parse + format in one step (e.g. SQL → MongoDB); returns the intermediate RQB query too                 |
+| `validate_query`   | Check a query against a `fields` config (shape, IC alternation, operators, value arity/types, …)        |
+| `get_query_schema` | JSON Schema for valid queries (`getQueryJsonSchema`)                                                    |
+| `search_docs`      | Full-text search of the docs (matching this package's version)                                          |
+| `get_doc`          | A docs page (or `#anchor` section) as markdown                                                          |
+
+ORM formats (`drizzle`, `prisma`, `sequelize`, `tanstack_db`) need live ORM objects and aren't available over MCP. `fields` input accepts the JSON-serializable subset of `Field` (no function props such as `validator`).
+
+Also provides:
+
+- **Resources**: `rqb://docs/{slug}` (every docs page) and `rqb://types/{name}` (key type declarations, e.g. `RuleGroupType`, `FormatQueryOptions`, `QueryBuilderProps`).
+- **Prompts**: `setup_query_builder` (`uiLibrary`, `fields`) and `convert_filter` (`input`, `from`, `to`).
+
+## Configuration
+
+Requires Node.js 20+.
+
+**Claude Code**
+
+```bash
+claude mcp add rqb -- npx -y @react-querybuilder/mcp
+```
+
+**opencode** (`opencode.json`)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "rqb": {
+      "type": "local",
+      "command": ["npx", "-y", "@react-querybuilder/mcp"]
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "rqb": { "command": "npx", "args": ["-y", "@react-querybuilder/mcp"] }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "rqb": { "type": "stdio", "command": "npx", "args": ["-y", "@react-querybuilder/mcp"] }
+  }
+}
+```
+
+`bunx @react-querybuilder/mcp` also works.
+
+## Programmatic use
+
+```ts
+import { createServer, handleConvertQuery } from '@react-querybuilder/mcp';
+
+// Tool handlers are plain async functions
+const result = await handleConvertQuery({ input: 'age > 30', from: 'sql', to: 'mongodb_query' });
+
+// Or connect the server to any MCP transport
+const server = createServer();
+```
+
+## Development
+
+```bash
+bun run build:mcp   # builds the docs index (src/generated/, gitignored) + dist
+bun test packages/mcp
+bun run test:mcp    # Vitest w/ coverage
+```
+
+Smoke test with the MCP Inspector (after building):
+
+```bash
+bunx @modelcontextprotocol/inspector node packages/mcp/dist/cli.mjs
+```

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { n as serverName, t as createServer } from "./server-ClTRN2X5.mjs";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+//#region src/cli.ts
+const handle = serveStdio(createServer);
+console.error(`${serverName} MCP server listening on stdio`);
+for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => void handle.close().then(() => process.exit(0)));
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { serveStdio } from '@modelcontextprotocol/server/stdio';\nimport { createServer, serverName } from './server';\n\n// stdout is the JSON-RPC channel; log to stderr only\nconst handle = serveStdio(createServer);\nconsole.error(`${serverName} MCP server listening on stdio`);\n\nfor (const signal of ['SIGINT', 'SIGTERM'] as const) {\n  process.on(signal, () => void handle.close().then(() => process.exit(0)));\n}\n"],"mappings":";;;;AAKA,MAAM,SAAS,WAAW,YAAY;AACtC,QAAQ,MAAM,GAAG,WAAW,+BAA+B;AAE3D,KAAK,MAAM,UAAU,CAAC,UAAU,SAAS,GACvC,QAAQ,GAAG,cAAc,KAAK,OAAO,MAAM,CAAC,CAAC,WAAW,QAAQ,KAAK,CAAC,CAAC,CAAC"}

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import { ExportFormat, FormatQueryOptions, GetQueryJsonSchemaOptions } from "@react-querybuilder/core";
+import { McpServer } from "@modelcontextprotocol/server";
+//#region src/types.d.ts
+/** Docs page metadata. */
+interface DocsPage {
+  /** Path under `/docs/`, e.g. `utils/export`. */
+  slug: string;
+  title: string;
+  description: string;
+  url: string;
+}
+/** Docs chunk: page preamble (empty `heading`) or one `##` section. */
+interface DocsSection {
+  /** Index into {@link DocsIndex.pages}. */
+  page: number;
+  heading: string;
+  anchor: string;
+  /** Cleaned markdown. */
+  text: string;
+}
+/** Build-time docs/types snapshot (`src/generated/docs-index.json`). */
+interface DocsIndex {
+  /** RQB version the docs were built from. */
+  version: string;
+  pages: DocsPage[];
+  sections: DocsSection[];
+  /** Type name → declaration source (with JSDoc). */
+  types: Record<string, string>;
+}
+/** Tool handler result (subset of MCP `CallToolResult`). Type alias (not interface) so it's
+ * assignable to the SDK's index-signature result type. */
+type ToolResult = {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+};
+//#endregion
+//#region src/docs.d.ts
+/** Build-time docs snapshot. */
+export declare const docsIndex: DocsIndex;
+/** Search hit. */
+export interface DocsSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+  score: number;
+}
+export declare const sectionUrl: (s: DocsSection) => string;
+export declare const sectionTitle: (s: DocsSection) => string;
+/** ~`len`-char plain-ish excerpt around the first matched term. */
+export declare const makeSnippet: (text: string, terms: string[], len?: number) => string;
+/** Full-text docs search (BM25+ via MiniSearch; title/heading boosted). */
+export declare const searchDocs: (query: string, limit?: number) => DocsSearchResult[];
+/** Resolves a docs URL/slug (optionally with `#anchor`) to a page index + anchor. */
+export declare const resolveDocRef: (ref: string) => {
+  page: DocsPage;
+  anchor: string;
+} | undefined;
+/** Full page markdown (title, description, all sections). */
+export declare const getPageMarkdown: (page: DocsPage) => string;
+/** One section's markdown (+ subsections if `##`), or `undefined` for unknown anchor. */
+export declare const getSectionMarkdown: (page: DocsPage, anchor: string) => string | undefined;
+/** Page markdown, or one section's when `anchor` is non-empty. */
+export declare const getDocMarkdown: (page: DocsPage, anchor?: string) => string | undefined;
+//#endregion
+//#region src/formats.d.ts
+/** ORM formats: need live ORM objects (columns, `Op`, etc.); unsupported over JSON. */
+export type OrmFormat = "drizzle" | "prisma" | "sequelize" | "tanstack_db";
+/** `format_query` formats (every {@link ExportFormat} except {@link OrmFormat}s). */
+export type McpExportFormat = Exclude<ExportFormat, OrmFormat>;
+/** `parse_query` source formats. */
+export type McpImportFormat = "sql" | "cel" | "mongodb" | "jsonlogic" | "spel" | "jsonata" | "cypher" | "gql" | "gremlin" | "sparql";
+export declare const ormFormats: readonly OrmFormat[];
+export declare const exportFormats: readonly McpExportFormat[];
+export declare const importFormats: readonly McpImportFormat[];
+//#endregion
+//#region src/handlers.d.ts
+/** JSON-serializable `fields` (array, option groups, or object map). */
+export type FieldsInput = unknown[] | Record<string, unknown>;
+/** JSON-serializable subset of {@link FormatQueryOptions}. */
+export type FormatOptionsInput = Omit<FormatQueryOptions, "format" | "fields" | "validator" | "getOperators" | "getParameters" | "operatorProcessor" | "valueProcessor" | "ruleProcessor" | "ruleGroupProcessor"> & {
+  fields?: FieldsInput;
+};
+/** JSON-serializable parser options. */
+export interface ParseOptionsInput {
+  fields?: FieldsInput;
+  independentCombinators?: boolean;
+  listsAsArrays?: boolean;
+  generateIDs?: boolean;
+  paramPrefix?: string;
+  params?: unknown[] | Record<string, unknown>;
+}
+export interface FormatQueryArgs {
+  query: unknown;
+  format: string;
+  options?: FormatOptionsInput;
+}
+export interface ParseQueryArgs {
+  input: unknown;
+  sourceFormat: string;
+  options?: ParseOptionsInput;
+}
+export interface ConvertQueryArgs {
+  input: unknown;
+  from: string;
+  to: string;
+  fields?: FieldsInput;
+  parseOptions?: ParseOptionsInput;
+  formatOptions?: FormatOptionsInput;
+}
+export interface ValidateQueryArgs {
+  query: unknown;
+  fields: FieldsInput;
+  queryType?: "standard" | "ic";
+}
+export interface GetQuerySchemaArgs {
+  fields: FieldsInput;
+  options?: GetQueryJsonSchemaOptions;
+}
+export interface SearchDocsArgs {
+  query: string;
+  limit?: number;
+}
+export interface GetDocArgs {
+  page: string;
+}
+/** Validation issue reported by `validate_query`. */
+export interface ValidationIssue {
+  code: string;
+  message: string;
+  path: number[];
+}
+export declare const ok: (structured: Record<string, unknown>, text?: string) => ToolResult;
+export declare const fail: (message: string) => ToolResult;
+/** Parses `query` input (object or JSON string). Throws {@link InputError}. */
+export declare const parseQueryInput: (query: unknown) => unknown;
+/** Structural checks `diagnostics` assumes (group `rules` array, rule `field`/`operator`). */
+export declare const checkShape: (q: unknown, path?: number[]) => ValidationIssue[];
+export declare const handleFormatQuery: (args: FormatQueryArgs) => Promise<ToolResult>;
+export declare const handleParseQuery: (args: ParseQueryArgs) => Promise<ToolResult>;
+export declare const handleConvertQuery: (args: ConvertQueryArgs) => Promise<ToolResult>;
+export declare const handleValidateQuery: (args: ValidateQueryArgs) => Promise<ToolResult>;
+export declare const handleGetQuerySchema: (args: GetQuerySchemaArgs) => Promise<ToolResult>;
+export declare const handleSearchDocs: (args: SearchDocsArgs) => Promise<ToolResult>;
+export declare const handleGetDoc: (args: GetDocArgs) => Promise<ToolResult>;
+//#endregion
+//#region src/prompts.d.ts
+/** MCP `GetPromptResult` subset. */
+export type PromptResult = {
+  description?: string;
+  messages: {
+    role: "user";
+    content: {
+      type: "text";
+      text: string;
+    };
+  }[];
+};
+/** `setup_query_builder` prompt. */
+export declare const setupQueryBuilderPrompt: (uiLibrary?: string, fields?: string) => PromptResult;
+/** `convert_filter` prompt. */
+export declare const convertFilterPrompt: (input: string, from?: string, to?: string) => PromptResult;
+//#endregion
+//#region src/server.d.ts
+/** Server name advertised to clients. */
+export declare const serverName = "react-querybuilder";
+/**
+ * Creates the React Query Builder MCP server (tools, resources, prompts). Transport-agnostic;
+ * see `cli.ts` for stdio.
+ */
+export declare const createServer: () => McpServer;
+//#endregion
+export type { DocsIndex, DocsPage, DocsSection, ToolResult };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1 @@
+export { a as checkShape, r as convertFilterPrompt, t as createServer, y as docsIndex, g as exportFormats, o as fail, b as getDocMarkdown, x as getPageMarkdown, S as getSectionMarkdown, s as handleConvertQuery, c as handleFormatQuery, l as handleGetDoc, u as handleGetQuerySchema, d as handleParseQuery, f as handleSearchDocs, p as handleValidateQuery, _ as importFormats, C as makeSnippet, m as ok, v as ormFormats, h as parseQueryInput, w as resolveDocRef, T as searchDocs, E as sectionTitle, D as sectionUrl, n as serverName, i as setupQueryBuilderPrompt } from "./server-ClTRN2X5.mjs";