@opencraw/mcp 0.1.45 → 0.1.47

package/README.md

@@ -11,7 +11,7 @@ directly: probe a page, validate recipes, run a crawl, list what's already autho
 For a shared, remote endpoint that authors recipes where they will run (and publishes them to a crawl host), see
 [`@opencraw/azure-durable`](https://github.com/Open-Craw/OpenCraw/blob/main/packages/azure-durable/README.md#write-recipes-over-mcp)'s `/mcp`.
 
-This does **not** auto-author recipes from a sentence. The five tools are, `list_recipes` aside, the same
+This does **not** auto-author recipes from a sentence. The crawl tools are, `list_recipes` and `docs` aside, 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.
@@ -116,6 +116,19 @@ call, for checking what already exists before writing a new recipe.
 
 Returns `{ outputs: [{ path, id }], inputs: [{ path, id, output, mode }], others: string[] }`.
 
+### `docs`
+
+OpenCraw's own documentation, for an agent that has to write recipes right: the authoring guide (every step, selector, transform and policy), the
+how-it-works chapters, the examples and the Studio manual. They ship inside the package.
+
+| Input | Meaning |
+|---|---|
+| `topic?` | A document id (`recipes/authoring`, `how-it-works/06-documents`, `studio/manual`…). Leave out to list every document, with its title and size. |
+| `section?` | A heading (or part of one) of that document: only that section comes back, subsections included. A long document answers with its outline until a section is asked for. |
+
+Returns `{ topics, hint }` without a topic, `{ topic, text }` (or `{ topic, outline, note }` for a long document) with one, and `{ topic, section, text }`
+with a section.
+
 ### `diff`
 
 Compares two runs' JSON Lines files by record key: what was added, what was removed, and which fields changed,
@@ -131,6 +144,19 @@ Returns `{ added, removed, changed, unchanged, shrunk?, summary, changes }`: `su
 reads, `changes` the first 200 changes (`removed`, `changed` with `fields: [{ field, before, after }]`, `added`),
 and `shrunk` is set when the current run holds under half the records the previous one did.
 
+### `studio_status`, `studio_open_recipe`, `studio_run_sample`
+
+Drive the OpenCraw Studio the person has open, so they watch the recipe being built. A running Studio announces itself in `~/.opencraw/studio/<pid>-<port>.json`
+(its address and its access token, readable by its owner only); these tools find it there, so nothing needs configuring. If several run, the newest is used.
+
+| Tool | Input | Returns |
+|---|---|---|
+| `studio_status` | none | `{ running, url, folder?, pages, running? }`: whether Studio is up, the folder it has open, how many connections are listening (an open page holds a couple), the recipe being sampled. Without a Studio: `{ running: false, hint }`. |
+| `studio_open_recipe` | `path` (a recipe file, a folder or a document), `workspace?` | `{ opened: true, pages }`, or `{ opened: false, hint }` when Studio runs but no page is open. The open page does it the way a Studio link does. |
+| `studio_run_sample` | `recipeId`, `maxRecords?` (10), `waitSeconds?` (60) | `{ recipeId, state, result? }`: the counts, the first 20 records and rejections once finished. Studio must have the recipe's folder open (`studio_open_recipe` first). |
+
+Picking a value on a page (`studio_pick`) is not here yet: it is still the person's click.
+
 ## Building
 
 `nx build @opencraw/mcp`, `nx test @opencraw/mcp` (unit tests per tool), `nx run @opencraw/mcp:e2e`

package/dist/diff-tool/diff-tool.handler.d.ts

@@ -0,0 +1,42 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { RecordChange } from '@opencraw/core';
+import { z } from 'zod';
+/** Input schema for the `diff` tool. */
+export declare const diffInputShape: {
+    previous: z.ZodString;
+    current: z.ZodString;
+    key: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+};
+interface DiffArgs {
+    previous: string;
+    current: string;
+    key?: string[];
+    ignore?: string[];
+}
+/** What the `diff` tool returns. */
+export interface DiffResult {
+    added: number;
+    removed: number;
+    changed: number;
+    unchanged: number;
+    /** Set when the current run lost most of the previous run's records. */
+    shrunk?: {
+        previous: number;
+        current: number;
+    };
+    /** The report a person reads, one line per change. */
+    summary: string[];
+    /** The changes, up to 200: removed, changed (with each field's before and after), added. */
+    changes: RecordChange[];
+}
+/**
+ * The `diff` tool: compares two runs' records by key, so an agent watching a
+ * source can say what changed since last time instead of re-reading it all.
+ *
+ * @param args - The tool's parsed input.
+ * @returns The MCP tool result.
+ */
+export declare function diffTool(args: DiffArgs): Promise<CallToolResult>;
+export {};
+//# sourceMappingURL=diff-tool.handler.d.ts.map

package/dist/diff-tool/index.d.ts

@@ -0,0 +1,3 @@
+export { diffTool, diffInputShape } from './diff-tool.handler';
+export type { DiffResult } from './diff-tool.handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs-tool/docs-folder.repository.d.ts

@@ -0,0 +1,24 @@
+/** One document the server can show. */
+export interface DocTopic {
+    id: string;
+    title: string;
+    /** Its size in characters, so an agent knows to ask for a section of a long one. */
+    size: number;
+}
+/**
+ * The documents under a docs folder: the Markdown files directly inside `recipes`, `how-it-works` and `studio` (their pictures and capture scripts are
+ * not documentation to read).
+ *
+ * @param root - The docs folder.
+ * @returns The topics, ordered by id.
+ */
+export declare function listTopics(root: string): Promise<DocTopic[]>;
+/**
+ * One document's text.
+ *
+ * @param root - The docs folder.
+ * @param id - The topic id from `listTopics` (never a path: nothing outside the listed folders is read).
+ * @returns The Markdown, or `undefined` when there is no such topic.
+ */
+export declare function readTopic(root: string, id: string): Promise<string | undefined>;
+//# sourceMappingURL=docs-folder.repository.d.ts.map

package/dist/docs-tool/docs-root.client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where the documentation is: a `docs` folder beside `dist` in the installed package (copied there at build), or the repository's own `docs` when the server runs
+ * from a checkout.
+ *
+ * @returns The docs folder.
+ */
+export declare function docsRoot(): string;
+//# sourceMappingURL=docs-root.client.d.ts.map

package/dist/docs-tool/docs-tool.handler.d.ts

@@ -0,0 +1,21 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/** Input schema for the `docs` tool. */
+export declare const docsInputShape: {
+    topic: z.ZodOptional<z.ZodString>;
+    section: z.ZodOptional<z.ZodString>;
+};
+/**
+ * The `docs` tool: OpenCraw's own documentation, for an agent that has to write recipes right: the authoring guide (every step, selector, transform
+ * and policy), how it all works, the examples and the Studio manual. Without a topic it lists what there is; with one it gives the document, or just
+ * the section asked for, so a long guide costs only what is read.
+ *
+ * @param args - The tool's parsed input.
+ * @param root - The docs folder (the packaged copy, or the repository's).
+ * @returns The MCP tool result.
+ */
+export declare function docsTool(args: {
+    topic?: string;
+    section?: string;
+}, root: string): Promise<CallToolResult>;
+//# sourceMappingURL=docs-tool.handler.d.ts.map

package/dist/docs-tool/docs-topics.algorithm.d.ts

@@ -0,0 +1,39 @@
+/** One heading of a document: how deep it is, its text and where its line is. */
+export interface DocHeading {
+    level: number;
+    text: string;
+    line: number;
+}
+/**
+ * The topic id of a documentation file: its path under the docs folder, without the extension and with forward slashes, so `recipes/authoring.md` is
+ * `recipes/authoring`.
+ *
+ * @param relativePath - The file's path under the docs folder.
+ * @returns The id.
+ */
+export declare function topicIdOf(relativePath: string): string;
+/**
+ * The title of a document: its first top-level heading, else its id.
+ *
+ * @param markdown - The document.
+ * @param fallback - The id, when there is no heading.
+ * @returns The title.
+ */
+export declare function titleOf(markdown: string, fallback: string): string;
+/**
+ * Every heading of a Markdown document, in order. A line inside a fenced code block is not a heading (a shell comment starts with `#` too).
+ *
+ * @param markdown - The document.
+ * @returns The headings.
+ */
+export declare function outlineOf(markdown: string): DocHeading[];
+/**
+ * One section of a document: from the heading whose text contains `heading` (case-insensitive; an exact match wins over a partial one) to the next
+ * heading of the same or a higher level, so its subsections come with it.
+ *
+ * @param markdown - The document.
+ * @param heading - What the heading says, or part of it.
+ * @returns The section's text, or `undefined` when no heading matches.
+ */
+export declare function sectionOf(markdown: string, heading: string): string | undefined;
+//# sourceMappingURL=docs-topics.algorithm.d.ts.map

package/dist/docs-tool/index.d.ts

@@ -0,0 +1,3 @@
+export { docsTool, docsInputShape } from './docs-tool.handler';
+export { docsRoot } from './docs-root.client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

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

package/dist/index.esm.js

@@ -3,6 +3,11 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readRecordsFile, diffRecords, memorySink, fileSink, createCrawler, RecipeSet, RecipeValidationError, RecipeBindingError, parseOutputRecipe, parseInputRecipe, bindRecipeSet } from '@opencraw/core';
 import { diffReport, readRecipeFiles, probeUrl, loadForRun, loadPlugins, resolveAccess } from '@opencraw/cli';
 import { z } from 'zod';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 
 /** Changes returned at most; the counts cover all of them. */
 const CHANGE_LIMIT = 200;
@@ -56,6 +61,191 @@ async function diffTool(args) {
   }
 }
 
+/**
+ * The topic id of a documentation file: its path under the docs folder, without the extension and with forward slashes, so `recipes/authoring.md` is
+ * `recipes/authoring`.
+ *
+ * @param relativePath - The file's path under the docs folder.
+ * @returns The id.
+ */
+function topicIdOf(relativePath) {
+  return relativePath.replaceAll('\\', '/').replace(/\.md$/i, '');
+}
+/**
+ * The title of a document: its first top-level heading, else its id.
+ *
+ * @param markdown - The document.
+ * @param fallback - The id, when there is no heading.
+ * @returns The title.
+ */
+function titleOf(markdown, fallback) {
+  const heading = outlineOf(markdown).find(candidate => candidate.level === 1);
+  return heading?.text ?? fallback;
+}
+/**
+ * Every heading of a Markdown document, in order. A line inside a fenced code block is not a heading (a shell comment starts with `#` too).
+ *
+ * @param markdown - The document.
+ * @returns The headings.
+ */
+function outlineOf(markdown) {
+  const headings = [];
+  let fence;
+  for (const [line, text] of markdown.split(/\r?\n/).entries()) {
+    const marker = /^\s*(`{3,}|~{3,})/.exec(text)?.[1];
+    if (marker !== undefined) {
+      if (fence === undefined) fence = marker[0];else if (marker[0] === fence) fence = undefined;
+      continue;
+    }
+    if (fence !== undefined) continue;
+    const match = /^(#{1,6}) (.+)$/.exec(text);
+    if (match !== null) headings.push({
+      level: match[1].length,
+      text: match[2].trim().replace(/ #+$/, ''),
+      line
+    });
+  }
+  return headings;
+}
+/**
+ * One section of a document: from the heading whose text contains `heading` (case-insensitive; an exact match wins over a partial one) to the next
+ * heading of the same or a higher level, so its subsections come with it.
+ *
+ * @param markdown - The document.
+ * @param heading - What the heading says, or part of it.
+ * @returns The section's text, or `undefined` when no heading matches.
+ */
+function sectionOf(markdown, heading) {
+  const wanted = heading.trim().toLowerCase();
+  const headings = outlineOf(markdown);
+  const start = headings.find(candidate => candidate.text.toLowerCase() === wanted) ?? headings.find(candidate => candidate.text.toLowerCase().includes(wanted));
+  if (start === undefined) return undefined;
+  const end = headings.find(candidate => candidate.line > start.line && candidate.level <= start.level);
+  const lines = markdown.split(/\r?\n/);
+  return lines.slice(start.line, end?.line ?? lines.length).join('\n').trim();
+}
+
+/** The folders under the docs folder whose Markdown files are documentation for a person (or an agent) using OpenCraw. */
+const FOLDERS = ['recipes', 'how-it-works', 'studio'];
+/**
+ * The documents under a docs folder: the Markdown files directly inside `recipes`, `how-it-works` and `studio` (their pictures and capture scripts are
+ * not documentation to read).
+ *
+ * @param root - The docs folder.
+ * @returns The topics, ordered by id.
+ */
+async function listTopics(root) {
+  const topics = [];
+  for (const folder of FOLDERS) {
+    let names;
+    try {
+      names = await readdir(join(root, folder));
+    } catch {
+      continue;
+    }
+    const documents = names.filter(file => file.toLowerCase().endsWith('.md'));
+    for (const name of documents) {
+      const id = topicIdOf(`${folder}/${name}`);
+      const text = await readFile(join(root, folder, name), 'utf8');
+      topics.push({
+        id,
+        title: titleOf(text, id),
+        size: text.length
+      });
+    }
+  }
+  return topics.sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * One document's text.
+ *
+ * @param root - The docs folder.
+ * @param id - The topic id from `listTopics` (never a path: nothing outside the listed folders is read).
+ * @returns The Markdown, or `undefined` when there is no such topic.
+ */
+async function readTopic(root, id) {
+  const known = await listTopics(root);
+  if (known.every(topic => topic.id !== id)) return undefined;
+  return await readFile(join(root, `${id}.md`), 'utf8');
+}
+
+/** Input schema for the `docs` tool. */
+const docsInputShape = {
+  topic: z.string().optional().describe('A document id from the list this tool returns without a topic (`recipes/authoring`, `how-it-works/06-documents`, `studio/manual`…). Leave out to list every document.'),
+  section: z.string().optional().describe('A heading (or part of one) of that document: only that section comes back, subsections included. A long document answers with its outline until you ask for a section.')
+};
+/** A document longer than this many characters comes back as its outline, and the section asked for. */
+const WHOLE_DOCUMENT_LIMIT = 30_000;
+function text$1(value, isError = false) {
+  return {
+    content: [{
+      type: 'text',
+      text: typeof value === 'string' ? value : JSON.stringify(value)
+    }],
+    ...(isError && {
+      isError
+    }),
+    ...(typeof value === 'object' && value !== null && {
+      structuredContent: value
+    })
+  };
+}
+/**
+ * The `docs` tool: OpenCraw's own documentation, for an agent that has to write recipes right: the authoring guide (every step, selector, transform
+ * and policy), how it all works, the examples and the Studio manual. Without a topic it lists what there is; with one it gives the document, or just
+ * the section asked for, so a long guide costs only what is read.
+ *
+ * @param args - The tool's parsed input.
+ * @param root - The docs folder (the packaged copy, or the repository's).
+ * @returns The MCP tool result.
+ */
+async function docsTool(args, root) {
+  const topics = await listTopics(root);
+  if (topics.length === 0) return text$1('The documentation is not installed with this server.', true);
+  if (args.topic === undefined) return text$1({
+    topics,
+    hint: 'Ask for one with { topic }, and for part of a long one with { topic, section }.'
+  });
+  const document = await readTopic(root, args.topic);
+  if (document === undefined) {
+    const close = topics.filter(topic => topic.id.includes(args.topic?.toLowerCase() ?? '') || args.topic?.includes(topic.id) === true).map(topic => topic.id);
+    return text$1(`There is no document "${args.topic}". ${close.length > 0 ? `Did you mean: ${close.join(', ')}?` : `The documents are: ${topics.map(topic => topic.id).join(', ')}.`}`, true);
+  }
+  if (args.section !== undefined) {
+    const section = sectionOf(document, args.section);
+    return section === undefined ? text$1({
+      topic: args.topic,
+      error: `no heading contains "${args.section}"`,
+      outline: outlineOf(document).map(heading => `${'#'.repeat(heading.level)} ${heading.text}`)
+    }, true) : text$1({
+      topic: args.topic,
+      section: args.section,
+      text: section
+    });
+  }
+  if (document.length <= WHOLE_DOCUMENT_LIMIT) return text$1({
+    topic: args.topic,
+    text: document
+  });
+  return text$1({
+    topic: args.topic,
+    outline: outlineOf(document).map(heading => `${'#'.repeat(heading.level)} ${heading.text}`),
+    note: `This document is ${String(document.length)} characters: ask for a section with { topic, section } using a heading from the outline.`
+  });
+}
+
+/**
+ * Where the documentation is: a `docs` folder beside `dist` in the installed package (copied there at build), or the repository's own `docs` when the server runs
+ * from a checkout.
+ *
+ * @returns The docs folder.
+ */
+function docsRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [join(here, '..', 'docs'), join(here, '..', '..', '..', 'docs')];
+  return candidates.find(candidate => existsSync(join(candidate, 'recipes'))) ?? candidates[0];
+}
+
 /** Input schema for the `list_recipes` tool. */
 const listRecipesInputShape = {
   dir: z.string().describe('A directory of recipe files.')
@@ -308,6 +498,229 @@ function loadErrorText(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * Sends one command to a running Studio (`POST /api/command`, the same door its own page uses) and reads the answer.
+ *
+ * @param instance - The Studio to talk to.
+ * @param command - A command `@opencraw/studio`'s `studioCommandSchema` accepts.
+ * @returns The JSON the Studio answered.
+ * @throws Error with the Studio's own message when it refuses.
+ */
+async function sendStudioCommand(instance, command) {
+  const response = await fetch(`${instance.url}/api/command`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-opencraw-token': instance.token
+    },
+    body: JSON.stringify(command)
+  });
+  const body = await response.json();
+  if (!response.ok) throw new Error(body.error ?? `Studio answered ${String(response.status)}`);
+  return body;
+}
+
+/** Where running Studios announce themselves. */
+function instancesDirectory() {
+  return join(homedir(), '.opencraw', 'studio');
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but is not ours to signal.
+    return error.code === 'EPERM';
+  }
+}
+function instanceOf(text) {
+  try {
+    const value = JSON.parse(text);
+    return typeof value.pid === 'number' && typeof value.url === 'string' && typeof value.token === 'string' && typeof value.startedAt === 'string' ? {
+      pid: value.pid,
+      url: value.url,
+      token: value.token,
+      folder: value.folder,
+      startedAt: value.startedAt
+    } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+/** The announcement files in a directory; none when it does not exist yet. */
+async function namesIn(directory) {
+  try {
+    const names = await readdir(directory);
+    return names.filter(file => file.endsWith('.json'));
+  } catch {
+    return [];
+  }
+}
+/** A file's text; empty when it vanished (its Studio just stopped). */
+async function textOf(file) {
+  try {
+    return await readFile(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+/**
+ * The Studios running on this machine, the newest first. A file whose process is gone (Studio was killed
+ * and could not withdraw it) is left out.
+ *
+ * @param directory - Where Studios announce themselves.
+ * @returns The live Studios.
+ */
+async function runningStudios(directory = instancesDirectory()) {
+  const found = [];
+  const names = await namesIn(directory);
+  for (const name of names) {
+    const instance = instanceOf(await textOf(join(directory, name)));
+    if (instance !== undefined && isAlive(instance.pid)) found.push(instance);
+  }
+  return found.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+
+/** Input schema for `studio_status`: nothing. */
+const studioStatusInputShape = {};
+/** Input schema for `studio_open_recipe`. */
+const studioOpenRecipeInputShape = {
+  path: z.string().min(1).describe('A recipe file (`*.input.json` / `*.ocw-in.json`), a folder of recipes, or a document, as an absolute path.'),
+  workspace: z.string().optional().describe('The folder a document belongs to, when `path` is a document.')
+};
+/** Input schema for `studio_run_sample`. */
+const studioRunSampleInputShape = {
+  recipeId: z.string().min(1).describe('The id of an input recipe in the folder Studio has open.'),
+  maxRecords: z.number().int().positive().optional().describe('Stop after this many records. Default 10.'),
+  waitSeconds: z.number().int().positive().max(300).optional().describe('How long to wait for the run to finish before answering that it is still running. Default 60.')
+};
+const NO_STUDIO = 'No Studio is running. Start one with `opencraw studio <folder>`, or open a recipe from the OpenCraw view in VS Code ("Open in Studio"), then ask again.';
+const POLL_MS = 500;
+function text(value, isError = false) {
+  return {
+    content: [{
+      type: 'text',
+      text: typeof value === 'string' ? value : JSON.stringify(value)
+    }],
+    ...(isError && {
+      isError
+    }),
+    ...(typeof value === 'object' && value !== null && {
+      structuredContent: value
+    })
+  };
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function studioOf(directory) {
+  const [newest] = await runningStudios(directory);
+  return newest;
+}
+/**
+ * `studio_status`: whether a Studio is running, which folder it has open, how many pages are watching and what it is running.
+ *
+ * @param directory - Where Studios announce themselves; the default is the user's own.
+ * @returns The MCP tool result.
+ */
+async function studioStatusTool(directory) {
+  const studio = await studioOf(directory);
+  if (studio === undefined) return text({
+    running: false,
+    hint: NO_STUDIO
+  });
+  try {
+    const status = await sendStudioCommand(studio, {
+      type: 'studio-status'
+    });
+    return text({
+      running: true,
+      url: studio.url,
+      ...status
+    });
+  } catch (error) {
+    return text(`Studio did not answer: ${messageOf(error)}`, true);
+  }
+}
+/**
+ * `studio_open_recipe`: opens a recipe, a folder or a document in the Studio the person is looking at, so they watch the work happen.
+ *
+ * @param args - What to open.
+ * @param directory - Where Studios announce themselves.
+ * @returns The MCP tool result.
+ */
+async function studioOpenRecipeTool(args, directory) {
+  const studio = await studioOf(directory);
+  if (studio === undefined) return text(NO_STUDIO, true);
+  try {
+    const {
+      pages
+    } = await sendStudioCommand(studio, {
+      type: 'ask-ui',
+      request: {
+        kind: 'open',
+        path: args.path,
+        workspace: args.workspace
+      }
+    });
+    if (pages === 0) return text({
+      opened: false,
+      hint: 'Studio is running but no page is open on it. Ask the person to open Studio in their browser.',
+      url: studio.url
+    });
+    return text({
+      opened: true,
+      pages
+    });
+  } catch (error) {
+    return text(`Studio refused: ${messageOf(error)}`, true);
+  }
+}
+/**
+ * `studio_run_sample`: runs an input recipe as a sample in Studio (the person sees the records arrive), waits for it, and returns the
+ * counts and the first records.
+ *
+ * @param args - The recipe, how many records to stop at and how long to wait.
+ * @param directory - Where Studios announce themselves.
+ * @returns The MCP tool result.
+ */
+async function studioRunSampleTool(args, directory) {
+  const studio = await studioOf(directory);
+  if (studio === undefined) return text(NO_STUDIO, true);
+  try {
+    const {
+      folder
+    } = await sendStudioCommand(studio, {
+      type: 'studio-status'
+    });
+    if (folder === undefined) return text('Studio has no folder open yet. Call studio_open_recipe with a recipe file or a folder first.', true);
+    await sendStudioCommand(studio, {
+      type: 'run-sample',
+      recipeId: args.recipeId,
+      budget: {
+        maxRecords: args.maxRecords ?? 10
+      }
+    });
+    const deadline = Date.now() + (args.waitSeconds ?? 60) * 1000;
+    for (;;) {
+      const status = await sendStudioCommand(studio, {
+        type: 'run-status',
+        recipeId: args.recipeId
+      });
+      if (status.state !== 'running') return text(status);
+      if (Date.now() >= deadline) return text({
+        ...status,
+        hint: 'Still running; ask again with studio_run_sample or look in Studio.'
+      });
+      await new Promise(resolve => {
+        setTimeout(resolve, POLL_MS);
+      });
+    }
+  } catch (error) {
+    return text(`Studio could not run it: ${messageOf(error)}`, true);
+  }
+}
+
 /** Input schema for the `validate` tool. */
 const validateInputShape = recipeSourceShape;
 /**
@@ -408,7 +821,7 @@ const SERVER_INFO = {
 };
 /**
  * Builds the MCP server: one tool per crawl primitive (`probe`, `validate`,
- * `run`, `list_recipes`, `diff`), each a thin wrapper over `@opencraw/core` and
+ * `run`, `list_recipes`, `diff`), `docs` and the `studio_` tools that drive a running Studio, each a thin wrapper over `@opencraw/core` and
  * `@opencraw/cli`'s structured helpers. No transport is attached; `main`
  * connects it over stdio.
  *
@@ -436,6 +849,22 @@ function createServer() {
     description: 'Compare two runs\' JSON Lines files by record key: what was added, removed, and changed (each field before and after). Use to report what changed in a source since the last crawl.',
     inputSchema: diffInputShape
   }, args => diffTool(args));
+  server.registerTool('docs', {
+    description: 'OpenCraw\'s own documentation: the authoring guide (every step, selector, transform and policy), how it works, the examples and the Studio manual. Without a topic it lists the documents; with one it gives the document, or just a section of it. Read the guide before writing a recipe you are not sure of, instead of guessing.',
+    inputSchema: docsInputShape
+  }, args => docsTool(args, docsRoot()));
+  server.registerTool('studio_status', {
+    description: 'Whether OpenCraw Studio is running on this machine, which folder it has open, how many pages are watching and which recipe it is sampling. Call it before the other studio_ tools.',
+    inputSchema: studioStatusInputShape
+  }, () => studioStatusTool());
+  server.registerTool('studio_open_recipe', {
+    description: 'Open a recipe, a folder of recipes or a document in the Studio the person has open, so they watch the recipe being built. Does nothing to the files.',
+    inputSchema: studioOpenRecipeInputShape
+  }, args => studioOpenRecipeTool(args));
+  server.registerTool('studio_run_sample', {
+    description: 'Run an input recipe as a sample in Studio (the person sees the records arrive) and get back the counts, the first records and what was rejected. Studio must have the folder of that recipe open: call studio_open_recipe first.',
+    inputSchema: studioRunSampleInputShape
+  }, args => studioRunSampleTool(args));
   return server;
 }
 

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

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