@opencraw/mcp 0.1.45 → 0.1.47

package/dist/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/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/probe-tool/index.d.ts

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

package/dist/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/recipe-source/index.d.ts

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

package/dist/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/run-tool/index.d.ts

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

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

@@ -0,0 +1,51 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CrawlReport } from '@opencraw/core';
+import { z } from 'zod';
+import type { RecipeSourceArgs } from '../recipe-source';
+/** Input schema for the `run` tool. */
+export declare const runInputShape: {
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
+    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>;
+    parallel: z.ZodOptional<z.ZodInt>;
+};
+interface RunArgs extends RecipeSourceArgs {
+    out?: string;
+    append?: boolean;
+    resume?: boolean;
+    only?: string[];
+    dryRun?: boolean;
+    headed?: boolean;
+    browserPath?: string;
+    insecureTls?: boolean;
+    userAgent?: string;
+    access?: string;
+    parallel?: number;
+}
+/** 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/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`, `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.
+ *
+ * @returns The server, ready to `connect`.
+ */
+export declare function createServer(): McpServer;
+//# sourceMappingURL=create-server.use-case.d.ts.map

package/dist/server/index.d.ts

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

package/dist/src/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/src/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/src/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/src/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/src/docs-tool/index.d.ts

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

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

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
  * 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.
  *

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

@@ -0,0 +1,2 @@
+export { studioOpenRecipeInputShape, studioOpenRecipeTool, studioRunSampleInputShape, studioRunSampleTool, studioStatusInputShape, studioStatusTool } from './studio-tools.handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/studio-tool/studio-command.client.d.ts

@@ -0,0 +1,11 @@
+import type { StudioInstance } from './studio-instance.repository.js';
+/**
+ * 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.
+ */
+export declare function sendStudioCommand<T>(instance: StudioInstance, command: Record<string, unknown>): Promise<T>;
+//# sourceMappingURL=studio-command.client.d.ts.map

package/dist/src/studio-tool/studio-instance.repository.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A running Studio, as it announced itself in `~/.opencraw/studio/<pid>-<port>.json` (`@opencraw/studio`'s
+ * `studio-instance`; this is the same shape, change both together).
+ */
+export interface StudioInstance {
+    pid: number;
+    url: string;
+    token: string;
+    folder?: string;
+    startedAt: string;
+}
+/** Where running Studios announce themselves. */
+export declare function instancesDirectory(): string;
+/**
+ * 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.
+ */
+export declare function runningStudios(directory?: string): Promise<StudioInstance[]>;
+//# sourceMappingURL=studio-instance.repository.d.ts.map

package/dist/src/studio-tool/studio-tools.handler.d.ts

@@ -0,0 +1,47 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/** Input schema for `studio_status`: nothing. */
+export declare const studioStatusInputShape: {};
+/** Input schema for `studio_open_recipe`. */
+export declare const studioOpenRecipeInputShape: {
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
+};
+/** Input schema for `studio_run_sample`. */
+export declare const studioRunSampleInputShape: {
+    recipeId: z.ZodString;
+    maxRecords: z.ZodOptional<z.ZodNumber>;
+    waitSeconds: z.ZodOptional<z.ZodNumber>;
+};
+/**
+ * `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.
+ */
+export declare function studioStatusTool(directory?: string): Promise<CallToolResult>;
+/**
+ * `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.
+ */
+export declare function studioOpenRecipeTool(args: {
+    path: string;
+    workspace?: string;
+}, directory?: string): Promise<CallToolResult>;
+/**
+ * `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.
+ */
+export declare function studioRunSampleTool(args: {
+    recipeId: string;
+    maxRecords?: number;
+    waitSeconds?: number;
+}, directory?: string): Promise<CallToolResult>;
+//# sourceMappingURL=studio-tools.handler.d.ts.map

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

@@ -0,0 +1,2 @@
+export { studioOpenRecipeInputShape, studioOpenRecipeTool, studioRunSampleInputShape, studioRunSampleTool, studioStatusInputShape, studioStatusTool } from './studio-tools.handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/studio-tool/studio-command.client.d.ts

@@ -0,0 +1,11 @@
+import type { StudioInstance } from './studio-instance.repository';
+/**
+ * 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.
+ */
+export declare function sendStudioCommand<T>(instance: StudioInstance, command: Record<string, unknown>): Promise<T>;
+//# sourceMappingURL=studio-command.client.d.ts.map

package/dist/studio-tool/studio-instance.repository.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A running Studio, as it announced itself in `~/.opencraw/studio/<pid>-<port>.json` (`@opencraw/studio`'s
+ * `studio-instance`; this is the same shape, change both together).
+ */
+export interface StudioInstance {
+    pid: number;
+    url: string;
+    token: string;
+    folder?: string;
+    startedAt: string;
+}
+/** Where running Studios announce themselves. */
+export declare function instancesDirectory(): string;
+/**
+ * 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.
+ */
+export declare function runningStudios(directory?: string): Promise<StudioInstance[]>;
+//# sourceMappingURL=studio-instance.repository.d.ts.map

package/dist/studio-tool/studio-tools.handler.d.ts

@@ -0,0 +1,47 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+/** Input schema for `studio_status`: nothing. */
+export declare const studioStatusInputShape: {};
+/** Input schema for `studio_open_recipe`. */
+export declare const studioOpenRecipeInputShape: {
+    path: z.ZodString;
+    workspace: z.ZodOptional<z.ZodString>;
+};
+/** Input schema for `studio_run_sample`. */
+export declare const studioRunSampleInputShape: {
+    recipeId: z.ZodString;
+    maxRecords: z.ZodOptional<z.ZodNumber>;
+    waitSeconds: z.ZodOptional<z.ZodNumber>;
+};
+/**
+ * `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.
+ */
+export declare function studioStatusTool(directory?: string): Promise<CallToolResult>;
+/**
+ * `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.
+ */
+export declare function studioOpenRecipeTool(args: {
+    path: string;
+    workspace?: string;
+}, directory?: string): Promise<CallToolResult>;
+/**
+ * `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.
+ */
+export declare function studioRunSampleTool(args: {
+    recipeId: string;
+    maxRecords?: number;
+    waitSeconds?: number;
+}, directory?: string): Promise<CallToolResult>;
+//# sourceMappingURL=studio-tools.handler.d.ts.map

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

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

package/dist/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';
+/** 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