@opencraw/mcp 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @opencraw/mcp
+
+An MCP (Model Context Protocol) server exposing [`@opencraw/core`](../core) as tools an agent can call
+directly: probe a page, validate recipes, run a crawl, list what's already authored. Local transport only
+(stdio) — the host launches it as a subprocess, the same shape as the [`opencraw` cli](../cli).
+
+This does **not** auto-author recipes from a sentence. The four tools are the same primitives the
+`opencraw` cli gives a terminal; the calling agent still writes the JSON recipes, using `probe` and
+`validate` to iterate, the same way this project's own example recipes were built by hand. An agent that
+can write files passes their `paths`; one that can't (a chat-only host) passes the `recipes` inline.
+
+## Register it
+
+```json
+{
+  "mcpServers": {
+    "opencraw": {
+      "command": "node",
+      "args": ["/absolute/path/to/opencraw/packages/mcp/bin/opencraw-mcp.mjs"],
+      "env": { "OPENCRAW_CHROMIUM": "/path/to/chrome" }
+    }
+  }
+}
+```
+
+`OPENCRAW_CHROMIUM` and `OPENCRAW_INSECURE_TLS=1` in the server's environment are the defaults for every
+`probe`/`run` call's `browserPath`/`insecureTls`, so a sandbox without Playwright's own bundled browser
+does not need every tool call to repeat them.
+
+`OPENCRAW_HOOKS` points at a JavaScript module whose default export is `{ name: function }`: the hooks the
+recipes call (`hook` steps and transforms). Only the server's environment names it, never a tool call, so an
+agent can run recipes that use your hooks but can't make the server load a module of its choosing.
+
+`OPENCRAW_ACCESS` points at an access config ([access.md](../../docs/recipes/access.md)): proxy profiles, with
+credentials as `{{env.NAME}}` read from the server's environment. The `probe` and `run` tools then take an
+`access` argument naming a profile. The file and the credentials never pass through a tool call.
+
+## Tools
+
+### `probe`
+
+Fetches a page and reports where its data lives: JSON-LD blocks, inline JSON objects above a size with
+their keys, `.json` URLs referenced in the markup, script hosts, and links that look like an API. With
+`browser: true` it also renders the page and lists the JSON responses observed while it settles, for
+endpoints only a script fetches after load.
+
+| Input | Meaning |
+|---|---|
+| `url` | The page to fetch. |
+| `browser?` | Also render it in a browser (slower, a few seconds). |
+| `browserPath?`, `insecureTls?`, `userAgent?` | As in the cli. |
+| `access?` | An access profile from the server's `OPENCRAW_ACCESS` config. |
+
+Returns `{ url, status, findings: { jsonLd, inlineJson, jsonUrls, scriptHosts, apiLinks }, observed }`.
+
+### `validate`
+
+Loads and binds recipes (an output recipe plus its input recipes), from files or passed inline: parses each
+against its schema, checks every mapping resolves, reports every problem with its JSON path.
+
+| Input | Meaning |
+|---|---|
+| `paths` | Recipe files (`.json`, `.jsonl`) or directories of them. |
+| `recipes` | Instead of `paths`: the recipes themselves, as an array of recipe objects or as JSON / JSON Lines text. For a host that can't write files. An inline recipe's issues name it by position: `recipes[1]`, or `recipes:2` for a line. |
+
+Give exactly one of `paths` and `recipes`.
+
+Returns `{ ok, output?, inputs: string[], issues: [{ path, message, source }] }`.
+
+### `run`
+
+Crawls the recipes at the given paths, or passed inline.
+
+| Input | Meaning |
+|---|---|
+| `paths` or `recipes` | As in `validate`: exactly one output recipe, any number of input recipes. |
+| `out?` | Write records to this JSON Lines file instead of returning them inline. Use this for anything beyond a handful of records — the tool result is not the place for a large crawl's output. |
+| `append?`, `resume?` | As in the cli (`resume` needs `append`). |
+| `only?` | Run only these input recipe ids. |
+| `dryRun?` | One record per input recipe instead of a full crawl — for checking a recipe under construction. |
+| `headed?`, `browserPath?`, `insecureTls?`, `userAgent?` | As in the cli. |
+| `access?` | The access profile for recipes that name none, from the server's `OPENCRAW_ACCESS` config. |
+
+Returns `{ report: CrawlReport, records?, truncated? }`. `records`/`truncated` are present only when `out`
+was not given, and `records` is capped at 50 even then.
+
+### `list_recipes`
+
+Lists the recipe files in a directory, split by kind, with their ids — cheaper than a full `validate`
+call, for checking what already exists before writing a new recipe.
+
+| Input | Meaning |
+|---|---|
+| `dir` | A directory of recipe files. |
+
+Returns `{ outputs: [{ path, id }], inputs: [{ path, id, output, mode }], others: string[] }`.
+
+## Building
+
+`nx build @opencraw/mcp`, `nx test @opencraw/mcp` (unit tests per tool), `nx run @opencraw/mcp:e2e`
+(spawns the built server and drives it with the MCP SDK's own `Client`/`StdioClientTransport`, against the
+fixture shop `@opencraw/core` ships; needs a browser — `npm run playwright:install` once, or
+`OPENCRAW_CHROMIUM=/path/to/chrome`).

package/bin/opencraw-mcp.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../dist/index.esm.js'
+
+await main()

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.js";

package/dist/index.esm.js

@@ -0,0 +1,373 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { readRecipeFiles, probeUrl, loadForRun, resolveAccess, loadHooks } from '@opencraw/cli';
+import { z } from 'zod';
+import { memorySink, jsonLinesSink, createCrawler, RecipeSet, RecipeValidationError, RecipeBindingError, parseOutputRecipe, parseInputRecipe, bindRecipeSet } from '@opencraw/core';
+
+/** Input schema for the `list_recipes` tool. */
+const listRecipesInputShape = {
+  dir: z.string().describe('A directory of recipe files.')
+};
+/**
+ * The `list_recipes` tool: what recipes already exist in a directory, cheaper
+ * than a full `validate` call, so an agent can check before writing a new one
+ * or find what an existing output recipe already covers.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+async function listRecipesTool(args) {
+  const files = await readRecipeFiles([args.dir]);
+  const result = {
+    outputs: files.outputs.map(file => ({
+      path: file.path,
+      id: idOf(file.recipe)
+    })),
+    inputs: files.inputs.map(file => ({
+      path: file.path,
+      id: idOf(file.recipe),
+      output: fieldOf(file.recipe, 'output'),
+      mode: fieldOf(file.recipe, 'mode')
+    })),
+    others: files.others
+  };
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(result)
+    }],
+    structuredContent: result
+  };
+}
+function idOf(recipe) {
+  return fieldOf(recipe, 'id');
+}
+function fieldOf(recipe, name) {
+  if (typeof recipe !== 'object' || recipe === null) return undefined;
+  const value = recipe[name];
+  return typeof value === 'string' ? value : undefined;
+}
+
+/** Input schema for the `probe` tool: a raw zod shape, as `McpServer.registerTool` expects. */
+const probeInputShape = {
+  url: z.string().describe('The page to fetch and inspect.'),
+  browser: z.boolean().optional().describe('Also render the page in a browser and list the JSON responses it fetches while settling. Slower (a few seconds); finds endpoints a plain fetch of the initial HTML cannot.'),
+  browserPath: z.string().optional().describe('A browser binary other than the one Playwright installed. Defaults to OPENCRAW_CHROMIUM in the server\'s environment.'),
+  insecureTls: z.boolean().optional().describe("Accept an intercepting proxy's certificate. Defaults to OPENCRAW_INSECURE_TLS=1 in the server's environment."),
+  userAgent: z.string().optional().describe('The user agent to send.'),
+  access: z.string().optional().describe('An access profile (a proxy) from the server\'s access config file, OPENCRAW_ACCESS.')
+};
+/**
+ * The `probe` tool: fetches a page and reports where its data lives, so an
+ * agent can write an extraction recipe without guessing selectors.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result: the probe findings as JSON text.
+ */
+async function probeTool(args) {
+  try {
+    const result = await probeUrl(args.url, {
+      browser: args.browser ?? false,
+      browserPath: args.browserPath ?? process.env.OPENCRAW_CHROMIUM,
+      insecureTls: args.insecureTls === true || process.env.OPENCRAW_INSECURE_TLS === '1',
+      userAgent: args.userAgent,
+      access: process.env.OPENCRAW_ACCESS === '' ? undefined : process.env.OPENCRAW_ACCESS,
+      accessProfile: args.access
+    });
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result)
+      }],
+      structuredContent: result
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text',
+        text: `probe failed: ${error instanceof Error ? error.message : String(error)}`
+      }],
+      isError: true
+    };
+  }
+}
+
+const recipeObject = z.record(z.string(), z.unknown());
+const recipeObjects = z.array(recipeObject).min(1);
+/** The two ways a tool takes recipes: files, or the recipes themselves. */
+const recipeSourceShape = {
+  paths: z.array(z.string()).min(1).optional().describe('Recipe files or directories (every .json and .jsonl file in a directory is read). Give this or "recipes".'),
+  recipes: z.union([z.string(), recipeObjects]).optional().describe('The recipes themselves instead of files: an array of recipe objects, or JSON / JSON Lines text (one recipe per line). For a host that cannot write files. Give this or "paths".')
+};
+/**
+ * The recipe source a tool call names.
+ *
+ * @param args - The tool's parsed input.
+ * @returns What core reads: the paths, or the inline recipes.
+ * @throws Error when the call gives both or neither.
+ */
+function recipeSourceOf(args) {
+  if (args.paths === undefined === (args.recipes === undefined)) throw new Error('give exactly one of "paths" or "recipes"');
+  if (args.paths !== undefined) return args.paths;
+  // Inline text is always recipes, never a path, whatever it starts with.
+  return typeof args.recipes === 'string' ? Buffer.from(args.recipes) : args.recipes ?? [];
+}
+
+const RECORD_CAP = 50;
+/** Input schema for the `run` tool. */
+const runInputShape = {
+  ...recipeSourceShape,
+  out: z.string().optional().describe('Write records to this JSON Lines file instead of returning them inline. Use for a crawl expected to produce more than a handful of records.'),
+  append: z.boolean().optional().describe('Keep what "out" holds and add to it; each line carries _key. Needs "out".'),
+  resume: z.boolean().optional().describe('Skip records "out" already has. Needs "append".'),
+  only: z.array(z.string()).optional().describe('Run only these input recipe ids.'),
+  dryRun: z.boolean().optional().describe('One record per input recipe, with the scope it was mapped from, instead of a full crawl. For checking a recipe under construction.'),
+  headed: z.boolean().optional().describe('Show the browser instead of running headless.'),
+  browserPath: z.string().optional().describe('A browser binary other than the one Playwright installed. Defaults to OPENCRAW_CHROMIUM in the server\'s environment.'),
+  insecureTls: z.boolean().optional().describe("Accept an intercepting proxy's certificate. Defaults to OPENCRAW_INSECURE_TLS=1 in the server's environment."),
+  userAgent: z.string().optional().describe('The user agent to send.'),
+  access: z.string().optional().describe('An access profile (a proxy) from the server\'s access config file, OPENCRAW_ACCESS, used by every recipe that names none. The error for an unknown name lists the profiles.')
+};
+/**
+ * The `run` tool: crawls the recipes in `paths` or `recipes` (exactly one
+ * output recipe, any number of inputs) and returns what happened,
+ * structured, instead of the cli's printed summary.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+async function runTool(args) {
+  let set;
+  try {
+    set = await loadForRun(recipeSourceOf(args), args.only ?? []);
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text',
+        text: loadErrorText(error)
+      }],
+      isError: true
+    };
+  }
+  if (set.inputs.length === 0) {
+    return {
+      content: [{
+        type: 'text',
+        text: args.only !== undefined && args.only.length > 0 ? `no input recipe matches "only": ${args.only.join(', ')}` : 'no input recipes found'
+      }],
+      isError: true
+    };
+  }
+  let crawler;
+  const sink = args.dryRun === true || args.out === undefined ? memorySink() : jsonLinesSink(args.out, {
+    append: args.append
+  });
+  try {
+    const hooksFile = serverFile('OPENCRAW_HOOKS');
+    crawler = createCrawler({
+      sink,
+      hooks: hooksFile === undefined ? undefined : await loadHooks(hooksFile),
+      access: await resolveAccess({
+        insecureTls: false,
+        access: serverFile('OPENCRAW_ACCESS'),
+        accessProfile: args.access
+      }),
+      resume: args.resume,
+      browser: {
+        headless: args.headed !== true,
+        executablePath: args.browserPath ?? process.env.OPENCRAW_CHROMIUM,
+        ignoreHTTPSErrors: args.insecureTls === true || process.env.OPENCRAW_INSECURE_TLS === '1'
+      }
+    });
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text',
+        text: error instanceof Error ? error.message : String(error)
+      }],
+      isError: true
+    };
+  }
+  try {
+    const inputs = args.dryRun === true ? set.inputs.map(input => ({
+      ...input,
+      limits: {
+        ...input.limits,
+        maxRecords: 1
+      }
+    })) : set.inputs;
+    const report = await crawler.run(new RecipeSet(set.output, inputs));
+    const result = {
+      report
+    };
+    if (args.out === undefined) {
+      const records = sink.records.map(record => record.data);
+      result.records = records.slice(0, RECORD_CAP);
+      result.truncated = records.length > RECORD_CAP;
+    }
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result)
+      }],
+      structuredContent: result,
+      isError: report.recipes.some(recipe => recipe.error !== undefined)
+    };
+  } finally {
+    await crawler.close();
+  }
+}
+/**
+ * A file the server was started with (`OPENCRAW_ACCESS`, `OPENCRAW_HOOKS`).
+ * Never a tool argument: a caller picks a profile, never a file, and never
+ * names a module for the server to run.
+ */
+function serverFile(name) {
+  const file = process.env[name];
+  return file === undefined || file === '' ? undefined : file;
+}
+function loadErrorText(error) {
+  if (error instanceof RecipeValidationError) return error.issues.map(issue => `${error.source}: ${issue.path === '' ? '(root)' : issue.path}: ${issue.message}`).join('\n');
+  if (error instanceof RecipeBindingError) return error.issues.map(issue => `${issue.recipeId}: ${issue.path}: ${issue.message}`).join('\n');
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Input schema for the `validate` tool. */
+const validateInputShape = recipeSourceShape;
+/**
+ * The `validate` tool: loads and binds recipes, returning every problem
+ * with its JSON path instead of a printed report, so an agent authoring a
+ * recipe can check it without a round trip through a terminal.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+async function validateTool(args) {
+  let files;
+  try {
+    files = await readRecipeFiles(recipeSourceOf(args));
+  } catch (error) {
+    return reply({
+      ok: false,
+      inputs: [],
+      issues: issuesOf(error, '')
+    });
+  }
+  const issues = files.others.map(path => ({
+    path: '',
+    message: '"kind" is missing or not "input"/"output"',
+    source: path
+  }));
+  if (files.outputs.length === 0) issues.push({
+    path: '',
+    message: 'no output recipe found',
+    source: ''
+  });
+  if (files.outputs.length > 1) issues.push({
+    path: '',
+    message: `more than one output recipe: ${files.outputs.map(file => file.path).join(', ')}`,
+    source: ''
+  });
+  const result = {
+    ok: issues.length === 0,
+    inputs: [],
+    issues
+  };
+  if (files.outputs.length === 1) {
+    try {
+      const output = parseOutputRecipe(files.outputs[0].recipe, files.outputs[0].path);
+      result.output = output.id;
+      const inputs = files.inputs.flatMap(file => {
+        try {
+          const input = parseInputRecipe(file.recipe, file.path);
+          result.inputs.push(input.id);
+          return [input];
+        } catch (error) {
+          issues.push(...issuesOf(error, file.path));
+          return [];
+        }
+      });
+      try {
+        bindRecipeSet(output, inputs);
+      } catch (error) {
+        issues.push(...issuesOf(error, output.id));
+      }
+    } catch (error) {
+      issues.push(...issuesOf(error, files.outputs[0].path));
+    }
+  }
+  result.ok = issues.length === 0;
+  return reply(result);
+}
+function reply(result) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(result)
+    }],
+    structuredContent: result
+  };
+}
+function issuesOf(error, source) {
+  if (error instanceof RecipeValidationError) return error.issues.map(issue => ({
+    path: issue.path,
+    message: issue.message,
+    source: error.source
+  }));
+  if (error instanceof RecipeBindingError) return error.issues.map(issue => ({
+    path: issue.path,
+    message: issue.message,
+    source: issue.recipeId
+  }));
+  return [{
+    path: '',
+    message: error instanceof Error ? error.message : String(error),
+    source
+  }];
+}
+
+const SERVER_INFO = {
+  name: 'opencraw',
+  version: '0.0.1'
+};
+/**
+ * Builds the MCP server: one tool per crawl primitive (`probe`, `validate`,
+ * `run`, `list_recipes`), each a thin wrapper over `@opencraw/core` and
+ * `@opencraw/cli`'s structured helpers. No transport is attached; `main`
+ * connects it over stdio.
+ *
+ * @returns The server, ready to `connect`.
+ */
+function createServer() {
+  const server = new McpServer(SERVER_INFO);
+  server.registerTool('probe', {
+    description: 'Fetch a page and report where its data lives: JSON-LD blocks, inline JSON objects, .json URLs, script hosts, API-looking links. Use before writing an input recipe, to see the shape a site\'s data actually takes.',
+    inputSchema: probeInputShape
+  }, args => probeTool(args));
+  server.registerTool('validate', {
+    description: 'Load and bind recipes (an output recipe plus its input recipes), from files or passed inline: parse each against its schema, check every mapping resolves, report every problem with its JSON path.',
+    inputSchema: validateInputShape
+  }, args => validateTool(args));
+  server.registerTool('run', {
+    description: 'Crawl the recipes at the given paths, or passed inline as "recipes". Use dryRun to check a recipe under construction (one record per input, returned inline); use "out" for anything beyond a handful of records.',
+    inputSchema: runInputShape
+  }, args => runTool(args));
+  server.registerTool('list_recipes', {
+    description: 'List the recipe files in a directory, split by kind, with their ids. Check before writing a new recipe, or to see what an existing output recipe covers.',
+    inputSchema: listRecipesInputShape
+  }, args => listRecipesTool(args));
+  return server;
+}
+
+/**
+ * Runs the server over stdio until the transport closes. This is what
+ * `bin/opencraw-mcp.mjs` calls; an MCP host launches it as a subprocess and
+ * talks JSON-RPC over stdin/stdout, so there is no argv to parse.
+ */
+async function main() {
+  const server = createServer();
+  await server.connect(new StdioServerTransport());
+}
+
+export { createServer, listRecipesInputShape, listRecipesTool, main, probeInputShape, probeTool, runInputShape, runTool, validateInputShape, validateTool };
+//# sourceMappingURL=index.esm.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export { main } from './main.js';
+export { createServer } from './server/index.js';
+export { probeTool, probeInputShape } from './probe-tool/index.js';
+export { validateTool, validateInputShape } from './validate-tool/index.js';
+export type { ValidateResult } from './validate-tool/index.js';
+export { runTool, runInputShape } from './run-tool/index.js';
+export type { RunResult } from './run-tool/index.js';
+export { listRecipesTool, listRecipesInputShape } from './list-tool/index.js';
+export type { ListRecipesResult } from './list-tool/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/list-tool/index.d.ts

@@ -0,0 +1,3 @@
+export { listRecipesTool, listRecipesInputShape } from './list-recipes-tool.handler.js';
+export type { ListRecipesResult } from './list-recipes-tool.handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/list-tool/list-recipes-tool.handler.d.ts

@@ -0,0 +1,32 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/** Input schema for the `list_recipes` tool. */
+export declare const listRecipesInputShape: {
+    dir: z.ZodString;
+};
+/** What the `list_recipes` tool returns. */
+export interface ListRecipesResult {
+    outputs: {
+        path: string;
+        id?: string;
+    }[];
+    inputs: {
+        path: string;
+        id?: string;
+        output?: string;
+        mode?: string;
+    }[];
+    others: string[];
+}
+/**
+ * The `list_recipes` tool: what recipes already exist in a directory, cheaper
+ * than a full `validate` call, so an agent can check before writing a new one
+ * or find what an existing output recipe already covers.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+export declare function listRecipesTool(args: {
+    dir: string;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=list-recipes-tool.handler.d.ts.map

package/dist/src/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Runs the server over stdio until the transport closes. This is what
+ * `bin/opencraw-mcp.mjs` calls; an MCP host launches it as a subprocess and
+ * talks JSON-RPC over stdin/stdout, so there is no argv to parse.
+ */
+export declare function main(): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/src/probe-tool/index.d.ts

@@ -0,0 +1,2 @@
+export { probeTool, probeInputShape } from './probe-tool.handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/probe-tool/probe-tool.handler.d.ts

@@ -0,0 +1,27 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/** Input schema for the `probe` tool: a raw zod shape, as `McpServer.registerTool` expects. */
+export declare const probeInputShape: {
+    url: z.ZodString;
+    browser: z.ZodOptional<z.ZodBoolean>;
+    browserPath: z.ZodOptional<z.ZodString>;
+    insecureTls: z.ZodOptional<z.ZodBoolean>;
+    userAgent: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodString>;
+};
+/**
+ * The `probe` tool: fetches a page and reports where its data lives, so an
+ * agent can write an extraction recipe without guessing selectors.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result: the probe findings as JSON text.
+ */
+export declare function probeTool(args: {
+    url: string;
+    browser?: boolean;
+    browserPath?: string;
+    insecureTls?: boolean;
+    userAgent?: string;
+    access?: string;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=probe-tool.handler.d.ts.map

package/dist/src/recipe-source/index.d.ts

@@ -0,0 +1,3 @@
+export { recipeSourceShape, recipeSourceOf } from './recipe-source.mapper.js';
+export type { RecipeSourceArgs } from './recipe-source.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/recipe-source/recipe-source.mapper.d.ts

@@ -0,0 +1,21 @@
+import type { RecipeSource } from '@opencraw/core';
+import { z } from 'zod';
+/** The two ways a tool takes recipes: files, or the recipes themselves. */
+export declare const recipeSourceShape: {
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
+};
+/** A tool's recipe arguments. */
+export interface RecipeSourceArgs {
+    paths?: string[];
+    recipes?: string | Record<string, unknown>[];
+}
+/**
+ * The recipe source a tool call names.
+ *
+ * @param args - The tool's parsed input.
+ * @returns What core reads: the paths, or the inline recipes.
+ * @throws Error when the call gives both or neither.
+ */
+export declare function recipeSourceOf(args: RecipeSourceArgs): RecipeSource;
+//# sourceMappingURL=recipe-source.mapper.d.ts.map

package/dist/src/run-tool/index.d.ts

@@ -0,0 +1,3 @@
+export { runTool, runInputShape } from './run-tool.handler.js';
+export type { RunResult } from './run-tool.handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/run-tool/run-tool.handler.d.ts

@@ -0,0 +1,49 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CrawlReport } from '@opencraw/core';
+import { z } from 'zod';
+import type { RecipeSourceArgs } from '../recipe-source/index.js';
+/** Input schema for the `run` tool. */
+export declare const runInputShape: {
+    out: z.ZodOptional<z.ZodString>;
+    append: z.ZodOptional<z.ZodBoolean>;
+    resume: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    headed: z.ZodOptional<z.ZodBoolean>;
+    browserPath: z.ZodOptional<z.ZodString>;
+    insecureTls: z.ZodOptional<z.ZodBoolean>;
+    userAgent: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
+};
+interface RunArgs extends RecipeSourceArgs {
+    out?: string;
+    append?: boolean;
+    resume?: boolean;
+    only?: string[];
+    dryRun?: boolean;
+    headed?: boolean;
+    browserPath?: string;
+    insecureTls?: boolean;
+    userAgent?: string;
+    access?: string;
+}
+/** What the `run` tool returns. */
+export interface RunResult {
+    report: CrawlReport;
+    /** Present when "out" was not given: the records this call produced, capped. */
+    records?: Record<string, unknown>[];
+    truncated?: boolean;
+}
+/**
+ * The `run` tool: crawls the recipes in `paths` or `recipes` (exactly one
+ * output recipe, any number of inputs) and returns what happened,
+ * structured, instead of the cli's printed summary.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+export declare function runTool(args: RunArgs): Promise<CallToolResult>;
+export {};
+//# sourceMappingURL=run-tool.handler.d.ts.map

package/dist/src/server/create-server.use-case.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Builds the MCP server: one tool per crawl primitive (`probe`, `validate`,
+ * `run`, `list_recipes`), each a thin wrapper over `@opencraw/core` and
+ * `@opencraw/cli`'s structured helpers. No transport is attached; `main`
+ * connects it over stdio.
+ *
+ * @returns The server, ready to `connect`.
+ */
+export declare function createServer(): McpServer;
+//# sourceMappingURL=create-server.use-case.d.ts.map

package/dist/src/server/index.d.ts

@@ -0,0 +1,2 @@
+export { createServer } from './create-server.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/validate-tool/index.d.ts

@@ -0,0 +1,3 @@
+export { validateTool, validateInputShape } from './validate-tool.handler.js';
+export type { ValidateResult } from './validate-tool.handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/validate-tool/validate-tool.handler.d.ts

@@ -0,0 +1,31 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { RecipeSourceArgs } from '../recipe-source/index.js';
+/** Input schema for the `validate` tool. */
+export declare const validateInputShape: {
+    paths: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    recipes: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodArray<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>]>>;
+};
+interface Issue {
+    path: string;
+    message: string;
+    /** The file (`path:line` in JSON Lines), `recipes[i]` / `recipes:line` for inline recipes, or the recipe id when the issue came from binding. */
+    source: string;
+}
+/** What the `validate` tool returns. */
+export interface ValidateResult {
+    ok: boolean;
+    output?: string;
+    inputs: string[];
+    issues: Issue[];
+}
+/**
+ * The `validate` tool: loads and binds recipes, returning every problem
+ * with its JSON path instead of a printed report, so an agent authoring a
+ * recipe can check it without a round trip through a terminal.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+export declare function validateTool(args: RecipeSourceArgs): Promise<CallToolResult>;
+export {};
+//# sourceMappingURL=validate-tool.handler.d.ts.map

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@opencraw/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.esm.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "opencraw-mcp": "./bin/opencraw-mcp.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "default": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "!**/*.tsbuildinfo",
+    "!**/*.d.ts.map",
+    "!**/*.js.map"
+  ],
+  "dependencies": {
+    "@opencraw/core": "^0.1.0",
+    "@opencraw/cli": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "playwright": "^1.63.0",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "An MCP server exposing OpenCraw's crawler as agent tools: probe a page, validate recipes, run a crawl, list recipes.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/russoedu/open.craw.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "crawler",
+    "scraper",
+    "mcp",
+    "model-context-protocol",
+    "recipe"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "nx": {
+    "targets": {
+      "typecheck": {
+        "dependsOn": [
+          "^build"
+        ]
+      },
+      "lint": {
+        "dependsOn": [
+          "^build"
+        ]
+      },
+      "e2e": {
+        "executor": "nx:run-commands",
+        "dependsOn": [
+          "build",
+          {
+            "projects": [
+              "@opencraw/core"
+            ],
+            "target": "e2e"
+          },
+          {
+            "projects": [
+              "@opencraw/cli"
+            ],
+            "target": "e2e"
+          }
+        ],
+        "inputs": [
+          "default",
+          "^production",
+          "{workspaceRoot}/packages/core/e2e/**"
+        ],
+        "options": {
+          "command": "tsc -p tsconfig.e2e.json && jest --config jest.e2e.config.cts",
+          "cwd": "packages/mcp"
+        }
+      }
+    }
+  }
+}