blockflow-mcp 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.mjs ADDED
@@ -0,0 +1,428 @@
1
+ // BlockFlow MCP server: tools that validate, import and run workflows in the user's real browser
2
+ // through the BlockFlow bridge, the guide as resources, and a write-and-repair prompt.
3
+ // `createBlockflowServer({ connect })` builds the server around an injected bridge connector, so tests
4
+ // drive it with a fake bridge over the SDK's in-memory transport; server.mjs wires stdio and the real client.
5
+ import { readFileSync } from 'node:fs';
6
+ import path from 'node:path';
7
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
8
+ import * as z from 'zod';
9
+ import { createBridgeSession, defaultConnector, describeError } from './bridgeSession.mjs';
10
+ import { formatIssues, formatRunText, formatSuiteText, summarizeRun } from './format.mjs';
11
+ import { PACKAGE_DIR, RESOURCES, readResource } from './resources.mjs';
12
+ import { RPC_ERRORS } from 'blockflow-bridge/protocol';
13
+
14
+ const VERSION = JSON.parse(readFileSync(path.join(PACKAGE_DIR, 'package.json'), 'utf8')).version;
15
+
16
+ /** Bridge-call limits. A run's own `timeoutSeconds` is enforced by the extension; this is a backstop. */
17
+ const RUN_DEFAULT_MS = 30 * 60_000;
18
+ const SUITE_MS = 4 * 60 * 60_000;
19
+ const SNAPSHOT_MS = 120_000;
20
+ /** How much of the step outputs the run summary text carries (structuredContent has all of them). */
21
+ const OUTPUT_TEXT_CHARS = 4_000;
22
+
23
+ export const INSTRUCTIONS = `BlockFlow runs browser automations and end-to-end tests inside the user's own browser (with their logins).
24
+ Workflows are JSON scripts ({"format":"blockflow-script","version":1,"name":…,"steps":[…]}); read the resource blockflow://guide ("Rules for AI tools" and "Script format") and blockflow://blocks before writing one.
25
+ Loop: snapshot_page (copy locators from it) → write the script → validate_workflow (fix every issue by its path and hint) → run_workflow → on failure read the failing step's code, message, locator and screenshot, fix that step, validate and run again.
26
+ The browser must be open with BlockFlow's "Allow outside control" switched on (Settings) and the bridge installed (npx blockflow-bridge install).`;
27
+
28
+ // ---------- input schemas ----------
29
+
30
+ const source = z
31
+ .union([z.string(), z.record(z.string(), z.unknown())])
32
+ .describe(
33
+ 'The workflow: a BlockFlow script ({"format":"blockflow-script","version":1,"name":"…","steps":[…]}), a graph file ({"format":"blockflow-workflows",…}) or one workflow, either as a JSON object or as JSON text. Prefer the script format. Pass JSON text when you want issue paths to match the text exactly.',
34
+ );
35
+ const secrets = z
36
+ .record(z.string(), z.string())
37
+ .describe('Values for {{secret.<name>}} in the workflow, for this run only (never stored). Keys are secret names, e.g. {"loginPassword": "…"}.');
38
+
39
+ // ---------- helpers ----------
40
+
41
+ const text = (value) => ({ type: /** @type {const} */ ('text'), text: value });
42
+
43
+ function isBlobRef(value) {
44
+ return Boolean(value) && typeof value === 'object' && typeof value.blobId === 'string' && typeof value.size === 'number' && Object.keys(value).length <= 3;
45
+ }
46
+
47
+ /** Reads every chunk of a blob (`blob.get`, base64 data) and returns the bytes and their type. */
48
+ export async function fetchBlob(session, blobId) {
49
+ const chunks = [];
50
+ let offset = 0;
51
+ let mime;
52
+ for (;;) {
53
+ const chunk = await session.call('blob.get', { blobId, offset });
54
+ const bytes = Buffer.from(chunk.data ?? '', 'base64');
55
+ chunks.push(bytes);
56
+ mime ??= chunk.mime;
57
+ offset = (typeof chunk.offset === 'number' ? chunk.offset : offset) + bytes.length;
58
+ if (chunk.done || (typeof chunk.size === 'number' && offset >= chunk.size)) break;
59
+ if (bytes.length === 0) throw new Error(`blob ${blobId} returned an empty chunk at ${offset} before it was done`);
60
+ }
61
+ return { bytes: Buffer.concat(chunks), mime };
62
+ }
63
+
64
+ /** A result that may have come back as a BlobRef: fetch and parse it. */
65
+ async function resolve(session, result) {
66
+ if (!isBlobRef(result)) return result;
67
+ const { bytes } = await fetchBlob(session, result.blobId);
68
+ return JSON.parse(bytes.toString('utf8'));
69
+ }
70
+
71
+ /** Turns any error into a tool result the model can act on (the server never throws out of a tool). */
72
+ function errorResult(error) {
73
+ const e = /** @type {any} */ (error);
74
+ const issues = e?.data?.issues;
75
+ if (e?.code === RPC_ERRORS.invalidWorkflow && Array.isArray(issues)) {
76
+ return {
77
+ isError: true,
78
+ content: [text(`The workflow did not validate, so nothing ran. Fix every issue at its path (see the Repair table in blockflow://guide), then call again.\n${formatIssues(issues)}`)],
79
+ structuredContent: { ok: false, issues },
80
+ };
81
+ }
82
+ return { isError: true, content: [text(`BlockFlow error: ${describeError(error)}`)] };
83
+ }
84
+
85
+ /** `notifications/progress` for this request, when the client asked for progress. */
86
+ function progressReporter(extra) {
87
+ const token = extra?._meta?.progressToken;
88
+ let progress = 0;
89
+ return (message, total) => {
90
+ if (token === undefined) return;
91
+ progress += 1;
92
+ /** @type {any} */
93
+ const params = { progressToken: token, progress, message };
94
+ if (typeof total === 'number') params.total = total;
95
+ void extra.sendNotification({ method: 'notifications/progress', params }).catch(() => {});
96
+ };
97
+ }
98
+
99
+ /** The client's notification callback may be (method, params) or ({method, params}); accept both. */
100
+ function readNotification(a, b) {
101
+ return typeof a === 'string' ? { method: a, params: b ?? {} } : { method: a?.method, params: a?.params ?? {} };
102
+ }
103
+
104
+ function outputsText(run) {
105
+ const outputs = (run.steps ?? []).filter((step) => step.output !== undefined).map((step) => `${step.sourceId ?? step.nodeId}: ${JSON.stringify(step.output)}`);
106
+ if (!outputs.length) return '';
107
+ const joined = outputs.join('\n');
108
+ return `Step outputs:\n${joined.length > OUTPUT_TEXT_CHARS ? `${joined.slice(0, OUTPUT_TEXT_CHARS)}… (cut; full outputs in structuredContent.steps)` : joined}`;
109
+ }
110
+
111
+ // ---------- server ----------
112
+
113
+ /**
114
+ * @param {{ connect?: () => Promise<any>, resourceDirs?: { packageDir: string, repoDir: string } }} [options]
115
+ */
116
+ export function createBlockflowServer(options = {}) {
117
+ const session = createBridgeSession(options.connect ?? defaultConnector());
118
+ const server = new McpServer({ name: 'blockflow', title: 'BlockFlow', version: VERSION }, { instructions: INSTRUCTIONS });
119
+
120
+ /** Wraps a handler so every failure becomes an isError result. */
121
+ const safe = (handler) => async (args, extra) => {
122
+ try {
123
+ return await handler(args ?? {}, extra);
124
+ } catch (error) {
125
+ return errorResult(error);
126
+ }
127
+ };
128
+
129
+ server.registerTool(
130
+ 'list_workflows',
131
+ {
132
+ title: 'List workflows',
133
+ description: 'Lists the workflows saved in BlockFlow (id, name, whether it is switched on, whether it was imported over the bridge). Use an id with run_workflow or get_report.',
134
+ inputSchema: {},
135
+ annotations: { readOnlyHint: true, openWorldHint: false },
136
+ },
137
+ safe(async () => {
138
+ const { workflows } = await resolve(session, await session.call('list', {}));
139
+ const lines = workflows.map((wf) => `- ${wf.id} "${wf.name}" ${wf.enabled ? 'on' : 'off'}${wf.viaBridge ? ' (via bridge)' : ''}`);
140
+ return { content: [text(workflows.length ? `${workflows.length} workflow(s):\n${lines.join('\n')}` : 'No workflows saved yet.')], structuredContent: { workflows } };
141
+ }),
142
+ );
143
+
144
+ server.registerTool(
145
+ 'validate_workflow',
146
+ {
147
+ title: 'Validate a workflow',
148
+ description:
149
+ 'Checks a workflow script or graph strictly, exactly as Import would, without saving or running it. Returns ok and a list of issues, each "<level> <code> at <JSON path>: <message> <hint>". Errors (unknown block type or config key, wrong value type, bad locator…) block import and running; warnings do not. To repair: change the key or value at each path as the hint says (the Repair table in blockflow://guide explains every code), then validate again until ok is true. Always validate before run_workflow.',
150
+ inputSchema: { source },
151
+ annotations: { readOnlyHint: true, openWorldHint: false },
152
+ },
153
+ safe(async ({ source: src }) => {
154
+ const result = await resolve(session, await session.call('validate', { source: src }));
155
+ const workflows = (result.workflows ?? []).map((wf) => `"${wf.name}" (${wf.nodes} blocks)`).join(', ');
156
+ const head = result.ok
157
+ ? `Valid${workflows ? `: ${workflows}` : ''}. Next: run_workflow with this source (or import_workflow to save it).`
158
+ : 'INVALID: nothing can be imported or run until every error is fixed. Fix each path below, then validate again.';
159
+ const body = result.issues?.length ? `\n${formatIssues(result.issues)}` : '';
160
+ return { content: [text(head + body)], structuredContent: { ok: result.ok, issues: result.issues ?? [], workflows: result.workflows ?? [] } };
161
+ }),
162
+ );
163
+
164
+ server.registerTool(
165
+ 'import_workflow',
166
+ {
167
+ title: 'Import a workflow',
168
+ description:
169
+ "Saves a workflow script or graph into the user's BlockFlow editor (tagged \"via bridge\", switched off), after the same strict check as validate_workflow. Returns the new workflow ids. replace: true replaces an earlier bridge-imported workflow with the same name instead of adding a copy. Only import when the user wants to keep the workflow; run_workflow can run a source without saving it.",
170
+ inputSchema: {
171
+ source,
172
+ replace: z.boolean().optional().describe('Replace a workflow previously imported over the bridge with the same name (default false: add a new one).'),
173
+ },
174
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
175
+ },
176
+ safe(async ({ source: src, replace }) => {
177
+ const params = /** @type {any} */ ({ source: src });
178
+ if (replace !== undefined) params.replace = replace;
179
+ const result = await resolve(session, await session.call('import', params));
180
+ const workflows = result.workflows ?? [];
181
+ const issues = result.issues ?? [];
182
+ const failed = workflows.length === 0 && issues.some((issue) => issue.level === 'error');
183
+ const lines = workflows.map((wf) => `- ${wf.id} "${wf.name}"`);
184
+ const head = failed ? 'Nothing was imported. Fix the issues and call again.' : `Imported ${workflows.length} workflow(s):\n${lines.join('\n')}`;
185
+ return {
186
+ isError: failed || undefined,
187
+ content: [text(`${head}${issues.length ? `\n${formatIssues(issues)}` : ''}`)],
188
+ structuredContent: { workflows, issues },
189
+ };
190
+ }),
191
+ );
192
+
193
+ server.registerTool(
194
+ 'run_workflow',
195
+ {
196
+ title: 'Run a workflow',
197
+ description:
198
+ "Runs a workflow once in the user's browser and waits until it finishes. Pass either workflowId (a saved workflow, from list_workflows) or source (a script or graph, run without saving; it is validated first and invalid sources come back with issues, nothing runs). Returns a summary first: status (passed/failed/cancelled), run id, duration, and for a failure the failing step's id (the step `id` in your script, else s<N> for the Nth step) and block type, error code, message, locator, page URL and matching elements, then every step's status and the step outputs, plus a screenshot of the page at the failure when one was taken. To repair: look up the error code in the guide's error-code table, use snapshot_page on the URL for correct locators, change that step, validate_workflow, run again.",
199
+ inputSchema: {
200
+ workflowId: z.string().optional().describe('Id of a saved workflow (from list_workflows or import_workflow).'),
201
+ source: source.optional(),
202
+ secrets: secrets.optional(),
203
+ timeoutSeconds: z.number().int().positive().max(3600).optional().describe('Stop the run after this many seconds (default: no overall limit; each step has its own timeout).'),
204
+ screenshot: z.boolean().optional().describe('Attach the failing step\'s screenshot as an image (default true).'),
205
+ },
206
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
207
+ },
208
+ safe(async (args, extra) => {
209
+ if ((args.workflowId === undefined) === (args.source === undefined)) {
210
+ return { isError: true, content: [text('Pass exactly one of workflowId (a saved workflow) or source (a script to run without saving).')] };
211
+ }
212
+ const params = /** @type {any} */ ({});
213
+ for (const key of ['workflowId', 'source', 'secrets', 'timeoutSeconds']) if (args[key] !== undefined) params[key] = args[key];
214
+ const report = progressReporter(extra);
215
+ let runId;
216
+ const onAbort = () => {
217
+ if (runId) void session.call('stop', { runId }).catch(() => {});
218
+ };
219
+ extra?.signal?.addEventListener('abort', onAbort, { once: true });
220
+ let result;
221
+ try {
222
+ result = await session.call('run', params, {
223
+ timeoutMs: args.timeoutSeconds ? (args.timeoutSeconds + 60) * 1000 : RUN_DEFAULT_MS,
224
+ onNotification: (a, b) => {
225
+ const { method, params: note } = readNotification(a, b);
226
+ if (method === 'run.started') {
227
+ runId = note.runId;
228
+ report(`started "${note.workflowName}" (run ${note.runId})`);
229
+ } else if (method === 'run.step' && note.step) {
230
+ const step = note.step;
231
+ report(`${step.sourceId ?? step.nodeId} ${step.blockType} ${step.status}${step.code ? ` ${step.code}` : ''}`);
232
+ }
233
+ },
234
+ });
235
+ } finally {
236
+ extra?.signal?.removeEventListener('abort', onAbort);
237
+ }
238
+ const { run } = await resolve(session, result);
239
+ const summary = summarizeRun(run);
240
+ /** @type {any[]} */
241
+ const content = [text(formatRunText(run))];
242
+ const outputs = outputsText(run);
243
+ if (outputs) content.push(text(outputs));
244
+ const shot = summary.failingStep?.screenshot;
245
+ if (shot && args.screenshot !== false) {
246
+ try {
247
+ const { bytes, mime } = await fetchBlob(session, `screenshot:${shot}`);
248
+ content.push(text(`Screenshot of the page when step "${summary.failingStep?.id}" failed:`));
249
+ content.push({ type: 'image', data: bytes.toString('base64'), mimeType: mime ?? 'image/png' });
250
+ } catch (error) {
251
+ content.push(text(`(The failure screenshot could not be fetched: ${describeError(error)})`));
252
+ }
253
+ }
254
+ return { content, structuredContent: summary };
255
+ }),
256
+ );
257
+
258
+ server.registerTool(
259
+ 'get_report',
260
+ {
261
+ title: 'Get a run report',
262
+ description:
263
+ 'Exports finished runs as a report: json (machine-readable, schema in docs/guide/report.schema.json: every step with input, output, error code, locator, URL), junit (XML for CI) or html (self-contained). Choose runs by runIds, or by workflowId (its latest runs, up to limit); with neither, the latest runs of all workflows.',
264
+ inputSchema: {
265
+ format: z.enum(['json', 'junit', 'html']).optional().describe('Report format (default json).'),
266
+ runIds: z.array(z.string()).optional().describe('Run ids (from run_workflow or run_suite).'),
267
+ workflowId: z.string().optional().describe('Report the latest runs of this workflow.'),
268
+ limit: z.number().int().positive().max(40).optional().describe('How many runs at most (default: the extension\'s default).'),
269
+ },
270
+ annotations: { readOnlyHint: true, openWorldHint: false },
271
+ },
272
+ safe(async (args) => {
273
+ const params = /** @type {any} */ ({ format: args.format ?? 'json' });
274
+ for (const key of ['runIds', 'workflowId', 'limit']) if (args[key] !== undefined) params[key] = args[key];
275
+ const result = await resolve(session, await session.call('report', params));
276
+ return { content: [text(result.content)], structuredContent: { format: result.format } };
277
+ }),
278
+ );
279
+
280
+ server.registerTool(
281
+ 'snapshot_page',
282
+ {
283
+ title: 'Snapshot a page',
284
+ description:
285
+ 'Returns an outline of a page as the browser sees it (with the user\'s logins): one line per element, `role "name" [state…] [ref] locator=…`. Copy the locator= part unchanged into click/fill/assert steps; never use the [ref=…] ids. Pass url (opened in a background tab, then closed) or tabId (an open tab). Take a snapshot before writing locators and again after a locator.not-found failure, on the failing step\'s page URL.',
286
+ inputSchema: {
287
+ url: z.string().optional().describe('An http(s) URL to open and outline.'),
288
+ tabId: z.number().int().optional().describe('Id of an already open browser tab to outline instead.'),
289
+ },
290
+ annotations: { readOnlyHint: true, openWorldHint: true },
291
+ },
292
+ safe(async (args) => {
293
+ if (args.url === undefined && args.tabId === undefined) return { isError: true, content: [text('Pass url (a page to open) or tabId.')] };
294
+ const params = /** @type {any} */ ({});
295
+ if (args.url !== undefined) params.url = args.url;
296
+ if (args.tabId !== undefined) params.tabId = args.tabId;
297
+ const result = await resolve(session, await session.call('snapshot', params, { timeoutMs: SNAPSHOT_MS }));
298
+ return { content: [text(result.outline)], structuredContent: { url: result.url, title: result.title } };
299
+ }),
300
+ );
301
+
302
+ server.registerTool(
303
+ 'stop_run',
304
+ {
305
+ title: 'Stop a run',
306
+ description: 'Stops a running workflow before its next block (the run ends as cancelled). runId comes from run_workflow progress messages or list results.',
307
+ inputSchema: { runId: z.string().describe('Id of the run to stop.') },
308
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
309
+ },
310
+ safe(async ({ runId }) => {
311
+ const result = await session.call('stop', { runId });
312
+ return { content: [text(result.stopped ? `Stopping run ${runId}.` : `Run ${runId} was not running.`)], structuredContent: { stopped: Boolean(result.stopped) } };
313
+ }),
314
+ );
315
+
316
+ server.registerTool(
317
+ 'list_suites',
318
+ {
319
+ title: 'List suites',
320
+ description: 'Lists the saved suites (named, ordered lists of workflows run together, like a test suite): id, name, workflow ids, stopOnFailure. Run one with run_suite.',
321
+ inputSchema: {},
322
+ annotations: { readOnlyHint: true, openWorldHint: false },
323
+ },
324
+ safe(async () => {
325
+ const { suites } = await resolve(session, await session.call('suite.list', {}));
326
+ const lines = suites.map((suite) => `- ${suite.id} "${suite.name}": ${suite.workflowIds.length} workflow(s)${suite.stopOnFailure ? ', stops on the first failure' : ''}`);
327
+ return { content: [text(suites.length ? `${suites.length} suite(s):\n${lines.join('\n')}` : 'No suites saved yet.')], structuredContent: { suites } };
328
+ }),
329
+ );
330
+
331
+ server.registerTool(
332
+ 'run_suite',
333
+ {
334
+ title: 'Run a suite',
335
+ description:
336
+ 'Runs several workflows one after another and waits for all of them. Pass one of: suiteId or name (a saved suite, see list_suites), or suite (an inline suite: {name, workflowIds?, sources?, stopOnFailure?}, where sources are scripts run without saving; an invalid source fails the suite before anything runs). Returns the overall status, one line per workflow with its failing step, and the reports asked for in formats (json, junit, html).',
337
+ inputSchema: {
338
+ suiteId: z.string().optional().describe('Id of a saved suite.'),
339
+ name: z.string().optional().describe('Name of a saved suite.'),
340
+ suite: z
341
+ .object({
342
+ name: z.string(),
343
+ workflowIds: z.array(z.string()).optional(),
344
+ sources: z.array(source).optional(),
345
+ stopOnFailure: z.boolean().optional(),
346
+ })
347
+ .optional()
348
+ .describe('An inline suite (not saved).'),
349
+ secrets: secrets.optional(),
350
+ formats: z.array(z.enum(['json', 'junit', 'html'])).optional().describe('Reports to return with the result.'),
351
+ },
352
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
353
+ },
354
+ safe(async (args, extra) => {
355
+ const chosen = ['suiteId', 'name', 'suite'].filter((key) => args[key] !== undefined);
356
+ if (chosen.length !== 1) return { isError: true, content: [text('Pass exactly one of suiteId, name (a saved suite) or suite (an inline one).')] };
357
+ const params = /** @type {any} */ ({});
358
+ for (const key of ['suiteId', 'name', 'suite', 'secrets', 'formats']) if (args[key] !== undefined) params[key] = args[key];
359
+ const report = progressReporter(extra);
360
+ const result = await resolve(
361
+ session,
362
+ await session.call('suite.run', params, {
363
+ timeoutMs: SUITE_MS,
364
+ onNotification: (a, b) => {
365
+ const { method, params: note } = readNotification(a, b);
366
+ if (method === 'suite.progress') report(`${note.index + 1}/${note.total} "${note.workflowName}" ${note.status}`, note.total);
367
+ else if (method === 'run.step' && note.step) report(`${note.step.sourceId ?? note.step.nodeId} ${note.step.blockType} ${note.step.status}`);
368
+ },
369
+ }),
370
+ );
371
+ const content = [text(formatSuiteText(result.result))];
372
+ for (const [format, body] of Object.entries(result.reports ?? {})) content.push(text(`${format} report:\n${body}`));
373
+ const { runs, ...rest } = result.result;
374
+ return { content, structuredContent: { ...rest, runs: runs.map(summarizeRun), reports: result.reports } };
375
+ }),
376
+ );
377
+
378
+ for (const resource of RESOURCES) {
379
+ server.registerResource(
380
+ resource.name,
381
+ resource.uri,
382
+ { title: resource.title, description: resource.description, mimeType: resource.mimeType },
383
+ async (uri) => ({ contents: [{ uri: uri.href, mimeType: resource.mimeType, text: readResource(resource, options.resourceDirs) }] }),
384
+ );
385
+ }
386
+
387
+ server.registerPrompt(
388
+ 'write-and-repair-test',
389
+ {
390
+ title: 'Write and repair a BlockFlow test',
391
+ description: 'Write a BlockFlow test for a page, then run it in the browser and repair it until it passes.',
392
+ argsSchema: {
393
+ url: z.string().describe('The page the test starts on.'),
394
+ goal: z.string().describe('What the test should do and check, in plain words.'),
395
+ },
396
+ },
397
+ ({ url, goal }) => ({
398
+ messages: [{ role: 'user', content: { type: 'text', text: repairPrompt(url, goal) } }],
399
+ }),
400
+ );
401
+
402
+ return {
403
+ server,
404
+ session,
405
+ async close() {
406
+ await server.close();
407
+ await session.close().catch(() => {});
408
+ },
409
+ };
410
+ }
411
+
412
+ export function repairPrompt(url, goal) {
413
+ return `Write a BlockFlow end-to-end test for ${url} that does this: ${goal}
414
+
415
+ Work in this loop, using the BlockFlow tools:
416
+
417
+ 1. Read the resources blockflow://guide (sections "Rules for AI tools" and "Script format") and blockflow://blocks (block types and their config keys). Use only block types and keys from there.
418
+ 2. Call snapshot_page with url ${url}. Copy locators from its locator= parts unchanged (role=…, label=…, text=…). Never invent locators and never use [ref=…] ids.
419
+ 3. Write the test as a script: {"format":"blockflow-script","version":1,"name":"…","steps":[{"open":"${url}"}, …]}. Give each important step an "id" so failures name it. Check results with "assert" steps. Put passwords and tokens in {{secret.name}} and pass their values in run_workflow's secrets. Do not add waits "just in case": actions wait for their element.
420
+ 4. Call validate_workflow with the script. If ok is false, fix every issue at the JSON path it names, following its hint (the Repair table in the guide explains each code), and validate again. Repeat until ok is true.
421
+ 5. Call run_workflow with the script as source. If it passed, you are done: show the final script.
422
+ 6. If it failed, read the summary: the failing step id and block type, error code, message, locator, page URL and the screenshot. Fix by the code (the guide's "Error codes" table): locator.not-found or locator.strict → snapshot_page on the failing page URL and use a locator from it (for strict, a more specific one); element.covered → close the overlay first; timeout or assert.failed → check what the page really shows in the screenshot and snapshot. Change only what the failure points at.
423
+ 7. Validate and run again. Stop after 5 failed runs and explain what is still failing and why.
424
+
425
+ Answer with the final script as a JSON code block, and say which secrets (if any) the user must create.`;
426
+ }
427
+
428
+ export { VERSION, defaultConnector };
package/package.json CHANGED
@@ -1,6 +1,54 @@
1
1
  {
2
2
  "name": "blockflow-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.1",
4
+ "description": "MCP server (stdio) for the BlockFlow browser extension: validate, run and repair workflows in your real browser.",
5
+ "keywords": [
6
+ "blockflow",
7
+ "mcp",
8
+ "model-context-protocol",
9
+ "browser-automation",
10
+ "testing",
11
+ "claude"
12
+ ],
13
+ "homepage": "https://github.com/akibh-dev/blockflow#readme",
14
+ "bugs": {
15
+ "url": "https://github.com/akibh-dev/blockflow/issues"
16
+ },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/akibh-dev/blockflow.git",
20
+ "directory": "packages/mcp"
21
+ },
22
+ "license": "MIT",
23
+ "type": "module",
24
+ "bin": {
25
+ "blockflow-mcp": "server.mjs"
26
+ },
27
+ "main": "./index.mjs",
28
+ "exports": {
29
+ ".": {
30
+ "types": "./index.d.mts",
31
+ "default": "./index.mjs"
32
+ }
33
+ },
34
+ "files": [
35
+ "*.d.mts",
36
+ "*.mjs",
37
+ "LICENSE",
38
+ "README.md",
39
+ "resources/",
40
+ "scripts/"
41
+ ],
42
+ "scripts": {
43
+ "prepack": "node scripts/pack.mjs copy",
44
+ "postpack": "node scripts/pack.mjs clean"
45
+ },
46
+ "engines": {
47
+ "node": ">=20"
48
+ },
49
+ "dependencies": {
50
+ "@modelcontextprotocol/sdk": "^1.32.2",
51
+ "blockflow-bridge": "1.0.1",
52
+ "zod": "^4.0.0"
53
+ }
54
+ }