@opencraw/mcp 0.1.44 → 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