@opencraw/mcp 0.1.47 → 0.1.49

package/README.md

@@ -152,10 +152,11 @@ Drive the OpenCraw Studio the person has open, so they watch the recipe being bu
 | 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_open_recipe` | `path` (a recipe file, a folder or a document), `workspace?` | `{ opened, message }` once the page has done it the way a Studio link does (or says why it could not); `{ opened: false, hint }` when Studio runs but no page is open. |
+| `studio_pick` | `recipeId`, `selector?` or `text?`, `add?` | Picks a value on the recipe's web page as a click would: by CSS selector, or by the text the element shows. Answers `{ picked, message, text, selector, matches, alternatives }` (the selector chosen and the others offered, each with how many elements it matches). Left staged for the person to choose and press *Add to recipe*, or added to the recipe with `add`. Open the recipe first. |
 | `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.
+`studio_pick` is for web pages. For a PDF, a spreadsheet or a deck the person still clicks, and the agent tells them where.
 
 ## Building
 

package/dist/index.esm.js

@@ -588,6 +588,13 @@ 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_pick`. */
+const studioPickInputShape = {
+  recipeId: z.string().min(1).describe('The id of an input recipe whose start point is a web page, in the folder Studio has open.'),
+  selector: z.string().optional().describe('A CSS selector of the element to pick on the page of the recipe. Give this or `text`.'),
+  text: z.string().optional().describe('The text the element shows, when you do not know a selector: the smallest element showing it is picked.'),
+  add: z.boolean().optional().describe('Add the pick to the recipe straight away (default: leave it staged, for the person to choose a selector and press Add to recipe).')
+};
 /** 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.'),
@@ -596,6 +603,8 @@ const studioRunSampleInputShape = {
 };
 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;
+/** How long a page gets to say how a request went. */
+const REPORT_WAIT_MS = 30_000;
 function text(value, isError = false) {
   return {
     content: [{
@@ -642,6 +651,45 @@ async function studioStatusTool(directory) {
     return text(`Studio did not answer: ${messageOf(error)}`, true);
   }
 }
+function sleep(ms) {
+  return new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+}
+/** Asks the open page to do something and waits for what it reports. */
+async function askPage(studio, request, waitMs = REPORT_WAIT_MS) {
+  const {
+    pages,
+    requestId
+  } = await sendStudioCommand(studio, {
+    type: 'ask-ui',
+    request
+  });
+  if (pages === 0) return {
+    pages
+  };
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    const outcome = await sendStudioCommand(studio, {
+      type: 'ui-outcome',
+      requestId
+    });
+    if (outcome.state === 'done') return {
+      pages,
+      outcome: {
+        ok: outcome.ok === true,
+        message: outcome.message ?? '',
+        detail: outcome.detail
+      }
+    };
+    await sleep(POLL_MS / 5);
+  }
+  return {
+    pages
+  };
+}
+const NO_PAGE = 'Studio is running but no page is open on it. Ask the person to open Studio in their browser.';
+const NO_REPORT = 'The page did not answer in time. Is the recipe in the folder Studio has open?';
 /**
  * `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.
  *
@@ -653,25 +701,62 @@ 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
-      }
+    const answer = await askPage(studio, {
+      kind: 'open',
+      path: args.path,
+      workspace: args.workspace
     });
-    if (pages === 0) return text({
+    if (answer.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.',
+      hint: NO_PAGE,
       url: studio.url
     });
+    if (answer.outcome === undefined) return text({
+      opened: false,
+      hint: NO_REPORT
+    });
     return text({
-      opened: true,
-      pages
+      opened: answer.outcome.ok,
+      message: answer.outcome.message
+    }, !answer.outcome.ok);
+  } catch (error) {
+    return text(`Studio refused: ${messageOf(error)}`, true);
+  }
+}
+/**
+ * `studio_pick`: picks a value on a recipe's web page in the Studio the person is looking at, as a click would: they see it selected and the
+ * ways to reach it. With `add` it is added to the recipe. Answers with the selector Studio chose and the others it offers.
+ *
+ * @param args - The recipe and what to pick (a selector or the text shown), and whether to add it.
+ * @param directory - Where Studios announce themselves.
+ * @returns The MCP tool result.
+ */
+async function studioPickTool(args, directory) {
+  if (args.selector === undefined && args.text === undefined) return text('Give a CSS selector or the text the element shows.', true);
+  const studio = await studioOf(directory);
+  if (studio === undefined) return text(NO_STUDIO, true);
+  try {
+    const answer = await askPage(studio, {
+      kind: 'pick',
+      recipeId: args.recipeId,
+      selector: args.selector,
+      text: args.text,
+      add: args.add
     });
+    if (answer.pages === 0) return text({
+      picked: false,
+      hint: NO_PAGE,
+      url: studio.url
+    }, true);
+    if (answer.outcome === undefined) return text({
+      picked: false,
+      hint: NO_REPORT
+    }, true);
+    return text({
+      picked: answer.outcome.ok,
+      message: answer.outcome.message,
+      ...answer.outcome.detail
+    }, !answer.outcome.ok);
   } catch (error) {
     return text(`Studio refused: ${messageOf(error)}`, true);
   }
@@ -712,9 +797,7 @@ async function studioRunSampleTool(args, directory) {
         ...status,
         hint: 'Still running; ask again with studio_run_sample or look in Studio.'
       });
-      await new Promise(resolve => {
-        setTimeout(resolve, POLL_MS);
-      });
+      await sleep(POLL_MS);
     }
   } catch (error) {
     return text(`Studio could not run it: ${messageOf(error)}`, true);
@@ -861,6 +944,10 @@ function createServer() {
     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_pick', {
+    description: 'Pick a value on the web page of an input recipe in Studio, as a click would: give a CSS selector or the text the element shows. The person sees it selected and the ways to reach it; with add it is added to the recipe. Returns the selector chosen and the alternatives, with how many elements each matches. Open the recipe first with studio_open_recipe.',
+    inputSchema: studioPickInputShape
+  }, args => studioPickTool(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

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

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

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

@@ -7,6 +7,13 @@ export declare const studioOpenRecipeInputShape: {
     path: z.ZodString;
     workspace: z.ZodOptional<z.ZodString>;
 };
+/** Input schema for `studio_pick`. */
+export declare const studioPickInputShape: {
+    recipeId: z.ZodString;
+    selector: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    add: z.ZodOptional<z.ZodBoolean>;
+};
 /** Input schema for `studio_run_sample`. */
 export declare const studioRunSampleInputShape: {
     recipeId: z.ZodString;
@@ -31,6 +38,20 @@ export declare function studioOpenRecipeTool(args: {
     path: string;
     workspace?: string;
 }, directory?: string): Promise<CallToolResult>;
+/**
+ * `studio_pick`: picks a value on a recipe's web page in the Studio the person is looking at, as a click would: they see it selected and the
+ * ways to reach it. With `add` it is added to the recipe. Answers with the selector Studio chose and the others it offers.
+ *
+ * @param args - The recipe and what to pick (a selector or the text shown), and whether to add it.
+ * @param directory - Where Studios announce themselves.
+ * @returns The MCP tool result.
+ */
+export declare function studioPickTool(args: {
+    recipeId: string;
+    selector?: string;
+    text?: string;
+    add?: boolean;
+}, 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.

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

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

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

@@ -7,6 +7,13 @@ export declare const studioOpenRecipeInputShape: {
     path: z.ZodString;
     workspace: z.ZodOptional<z.ZodString>;
 };
+/** Input schema for `studio_pick`. */
+export declare const studioPickInputShape: {
+    recipeId: z.ZodString;
+    selector: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    add: z.ZodOptional<z.ZodBoolean>;
+};
 /** Input schema for `studio_run_sample`. */
 export declare const studioRunSampleInputShape: {
     recipeId: z.ZodString;
@@ -31,6 +38,20 @@ export declare function studioOpenRecipeTool(args: {
     path: string;
     workspace?: string;
 }, directory?: string): Promise<CallToolResult>;
+/**
+ * `studio_pick`: picks a value on a recipe's web page in the Studio the person is looking at, as a click would: they see it selected and the
+ * ways to reach it. With `add` it is added to the recipe. Answers with the selector Studio chose and the others it offers.
+ *
+ * @param args - The recipe and what to pick (a selector or the text shown), and whether to add it.
+ * @param directory - Where Studios announce themselves.
+ * @returns The MCP tool result.
+ */
+export declare function studioPickTool(args: {
+    recipeId: string;
+    selector?: string;
+    text?: string;
+    add?: boolean;
+}, 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.

package/docs/recipes/authoring.md

@@ -735,7 +735,7 @@ local `file:…xlsx` / `…xlsm`) reads every worksheet with
 `2026-06-01T09:30:00`), errors their text (`#DIV/0!`), and empty cells `''`. Formulas give their cached
 value; nothing is evaluated, and display formats are not applied (a percentage stays `0.125`). Hidden sheets
 and rows are read, and `table` skips them unless `includeHidden`. Merged ranges are recorded, and `table`
-fills them. A legacy `.xls`, a password-protected file or an `.ods` fails the step, with what to do.
+fills them. An OpenDocument spreadsheet (`.ods`) reads exactly like an `.xlsx`, by its extension, its content type or the `mimetype` the file declares. A legacy `.xls` or a password-protected file fails the step, with what to do.
 
 **CSV.** `request` with `as: "csv"` (or a response served as `text/csv`, `application/csv` or
 `text/tab-separated-values`, or a local `file:…csv` / `…tsv`) reads the file into a **workbook**: a CSV is a

package/docs/studio/manual.md

@@ -305,8 +305,10 @@ happen instead of reading a report:
 
 - **`studio_status`** tells it whether Studio is running, which folder it has open and what it is sampling.
 - **`studio_open_recipe`** opens a recipe, a folder or a document in your Studio, as if you had followed a link to it.
+- **`studio_pick`** picks a value on a web page for you to see: by CSS selector or by the text it shows. It is staged the way your own click is, with the
+  ways to find it to choose from, and the agent can add it to the recipe.
 - **`studio_run_sample`** runs an input recipe as a sample: the records arrive in your Records tab, and the agent gets the counts and the first
   records back.
 
 Nothing needs setting up: a running Studio announces itself in `~/.opencraw/studio` (its address and its access token, readable only by you), and the
-agent finds it there. Studio still listens on this machine only. Clicking a value on a page or document stays your click: the agent tells you where.
+agent finds it there. Studio still listens on this machine only. On a PDF, a spreadsheet or a deck the picking is still your click: the agent tells you where.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/mcp",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",
@@ -25,8 +25,8 @@
     "!**/*.js.map"
   ],
   "dependencies": {
-    "@opencraw/core": "^0.1.42",
-    "@opencraw/cli": "^0.1.47",
+    "@opencraw/core": "^0.1.43",
+    "@opencraw/cli": "^0.1.49",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "playwright": "^1.63.0",
     "zod": "^4.6.5"