Workflow to MCP

Record a permitted browser task, review it, replace samples with typed inputs, verify it in isolated Chromium, and expose the exact verified revision as an MCP tool. Local SQLite, stdio transport, no telemetry or generated-code execution.

The product lives in apps/, packages/, tests/ and scripts/. See implementation evidence for results and incomplete release gates. This is an MVP implementation, not a universally compatible or independently approved public release. Unrelated NNI sources and tooling have been removed; their original history and MIT attribution remain available.

Install from source

Use Node 24.21.0 (pinned in .node-version) or the tested Node 26 runtime, with pnpm 12.16.1:

npm install --global pnpm@12.16.1
pnpm install --frozen-lockfile
pnpm browser:install
pnpm build
pnpm typecheck
pnpm lint
pnpm test
node dist/cli.js doctor

Tests need local loopback sockets and sandboxed Chromium. Linux also needs pnpm exec playwright install --with-deps chromium and working Chromium sandbox support. Do not disable the browser sandbox. macOS ARM64 is validated locally; Linux/Windows jobs are configured but platform support awaits executed CI results.

For an end-user installation from the locally generated package:

pnpm release:artifacts
npm install --global ./artifacts/workflow-to-mcp-0.1.0.tgz
workflow-to-mcp doctor

Install its exact browser too: pnpm browser:install from source, or npm exec --package=playwright@1.64.1 -- playwright install chromium. The package has not been published to npm. pnpm package:smoke tests an actual clean tarball installation, CLI import/trust/verify/publish and MCP calls outside the checkout.

Related MCP server: webpilot

Record your own lookup

1. Run pnpm demo:serve; open http://127.0.0.1:4173/tickets in Chrome.

2. Open chrome://extensions, enable developer mode, and load dist/extension unpacked (or extract the release ZIP).

3. Open the extension from its toolbar button on the demo tab and press Permit this origin & record. This uses a temporary activeTab grant, not permanent access to all sites.

4. Press Choose an input to permit, dismiss the popup, then click Ticket ID. Enter synthetic TICKET-1001 and click Search. Unknown text fields are private by default, and sensitive fields remain excluded even if selected.

5. Reopen the popup and use Choose an output element to select the “Ticket found” heading. Repeat separately for status and summary. Select one more output with Shift-click on the summary to choose its surrounding stable results container. The container will be used only as a readiness condition.

6. Press Stop & review. Set the captured input parameter to ticket_id. Name the first three outputs found, status, summary; select Visible (boolean) for found. Keep Allow missing enabled.

7. On the fourth output (the results container), press Wait until visible and leave its field name empty. This waits for completed results including “No matching ticket.” Select Read only after reviewing that the flow has no side effects.

8. Review every step, sample, origin and output, check the confirmation and export .workflow.json. Export does not execute or publish.

The UI supports pause/resume, safe timeline rendering, step removal/reordering, value removal/redaction, typed parameterization, explicit extraction and visible assertions. No keyboard transcript, cookies or passwords are collected. One tab and one origin are supported. Opening popup.html directly does not grant activeTab; use the toolbar.

Import, review, verify, publish

Keep the demo server running. The bundled example reproduces runtime behavior independently of recording; replace its import path with your downloaded recording to use your own flow.

node dist/cli.js policy allow --origin http://127.0.0.1:4173 --fixture
node dist/cli.js workflow import examples/demo-crm-lookup/workflow.json
node dist/cli.js workflow inspect lookup_support_ticket

Review the full IR, literal samples, origins, risk and schemas, then copy its exact SHA-256 from inspect:

node dist/cli.js workflow trust lookup_support_ticket --hash REVIEWED_SHA256
node dist/cli.js workflow verify lookup_support_ticket --suite examples/demo-crm-lookup/cases.json
node dist/cli.js workflow publish lookup_support_ticket --version 1.0.0
node dist/cli.js workflow run lookup_support_ticket --input examples/demo-crm-lookup/input.json
node dist/cli.js serve --stdio

Your recording must use the suite's input/output names. The suite checks two ticket IDs and a missing ticket. TICKET-1001 returns:

{"found":true,"status":"open","summary":"A synthetic example ticket"}

Every command accepts --home DIRECTORY (or WORKFLOW_MCP_HOME) and --json. State defaults to ~/.workflow-to-mcp. Import never executes or grants permission. Origin grants and workflow review are separate. Changing installation policy invalidates prior verification/publication. Edits require a new immutable workflow version and re-verification.

Connect an MCP client

For a host using common mcpServers configuration, use absolute paths:

{
  "mcpServers": {
    "workflow-to-mcp": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": ["/ABSOLUTE/PATH/TO/Workflow-to-MCP/dist/cli.js", "serve", "--stdio"]
    }
  }
}

The tool is wf_lookup_support_ticket, with required ticket_id: string and no extra properties. Call {"ticket_id":"TICKET-1002"} to get {"found":true,"status":"closed","summary":"A second synthetic ticket"}. Outputs are untrusted application data. Tool-list additions/updates require a server restart; disabling or revoking policy blocks new calls immediately. pnpm test:mcp uses the actual official SDK v2 client, child-process stdio, real Chromium and invalid arguments. MCP integration records host-validation boundaries. There is no HTTP MCP listener.

Writes and approvals

The synthetic write example is in examples/demo-crm-create-ticket/. Import and review its hash as above. Verification requests a local terminal approval per case; restart the disposable demo before verifying its suite (which expects CREATED-1). After verification/publication, approve one exact invocation in a trusted interactive local terminal:

node dist/cli.js approval grant create_support_ticket --input examples/demo-crm-create-ticket/input.json

Review the displayed workflow hash, origins and inputs; type the workflow slug. Invoke the matching MCP tool or workflow run within 60 seconds using the exact input. Approval is server-side, bound to the OS principal, policy, content hash and input digest, and consumed once. No approved argument exists. Missing/reused/expired approval fails before browser allocation. Unknown/destructive workflows are disabled.

Failure after a potentially mutating interaction yields OUTCOME_UNKNOWN. Inspect the application and run inspect RUN_ID; no automatic retry occurs. Browser automation is not a rollback-capable database transaction.

Limits, errors and removal

• Actions: navigate, click, fill, select, check, allowlisted keys, visibility/exact-URL waits, visible/text assertions, explicit text/visibility/count extraction. Locators must match exactly one element. No scripts, shell steps, CSS programs or automatic repair.

• Frames, popups, uploads/downloads, WebSockets, authenticated profiles and secret storage are unsupported. secretRef validates as a future reference but execution explicitly returns SECRET_NOT_CONFIGURED. The runner never uses a primary Chrome profile.

• Recorded IR URLs exclude query, fragment and credentials to avoid URL-secret capture. Runtime app requests may have queries. Remote sites require approved HTTPS origins and public IPv4 answers. IPv6/private networks are blocked; --fixture grants only the exact HTTP IPv4 loopback origin/port.

• Missing browser: run the pinned installation command and use the same PLAYWRIGHT_BROWSERS_PATH, if set, during install, verification and MCP serving.

• PERMISSION_DENIED: authorize the origin and trust the reviewed hash separately. WORKFLOW_NOT_VERIFIED: reverify after a content/policy/runtime change. LOCATOR_AMBIGUOUS: select a unique semantic target; there is no first-match fallback.

• Use Delete recording to clear the draft. Drafts expire on the next extension interaction after 24 hours. workflow delete SLUG removes revisions/approvals/runs; privacy erase-audit deletes audit entries with SQLite secure deletion/checkpointing.

• Remove the extension in Chrome and run npm uninstall --global workflow-to-mcp. Stop the server before deleting the entire selected application data directory. User-managed downloads/backups remain separate.

Read privacy, security, upstream audit, workflow format, dependencies and notices.