Workflow to MCP
by cassiomc1
README.md
# 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](docs/implementation-progress.md) 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.
## Architecture

Capture, verification, state, and execution stay local. MCP exposes only published workflow tools over stdio.
## Install from source
Use Node **24.21.0** (pinned in `.node-version`) or the tested Node 26 runtime, with pnpm **12.16.1**:
```sh
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. On Ubuntu 24.04 and newer, AppArmor restricts unprivileged user namespaces by default; Playwright's Chromium headless shell needs a narrowly scoped AppArmor profile that grants `userns` to that binary. Keep Chromium sandboxing enabled; see [Ubuntu's AppArmor guidance](https://documentation.ubuntu.com/security/security-features/privilege-restriction/apparmor/#apparmor-unprivileged-user-namespace-restrictions). 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:
```sh
pnpm release:artifacts
npm install --global ./artifacts/workflow-to-mcp-0.3.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.
## 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, per-step input conditions, semantic locator scopes, fixed typed transformations and explicit extraction. Waits can target visible, hidden, attached or detached elements. No keyboard transcript, cookies or passwords are collected. Recording stays on one tab and one origin per session; reviewed workflows can declare multiple separately approved origins. 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.
```sh
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`:
```sh
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:
```json
{"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.
## Authenticated websites
Version 0.2.0 added dedicated authentication profiles on macOS/Linux. Version 0.3.0 adds the 1.1.0 declarative workflow features above. Run `auth login NAME` in a local interactive terminal, complete login/MFA in its separate Chromium window, and bind the saved encrypted session with `auth bind WORKFLOW --profile NAME` before verification and publication. It never reads your primary browser profile. See the [complete authentication walkthrough](docs/authentication.md), including the synthetic authenticated CRM, renewal, expiry and revocation. The 0.3.0 source changes have not yet passed build/runtime validation; see [implementation evidence](docs/implementation-progress.md).
## Connect an MCP client
For a host using common `mcpServers` configuration, use absolute paths:
```json
{
"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](docs/mcp-integration.md) 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:
```sh
node dist/cli.js approval grant create_support_ticket --input examples/demo-crm-create-ticket/input.json
```
The local prompt shows the workflow hash, entry point, allowed origins, authentication identity, exact input values and a numbered action summary, including the values to fill. Read the summary and type the workflow slug to approve. This approval covers one exact invocation for 60 seconds; it is bound to the OS principal, policy, content hash, authentication generation and input digest, then consumed once. MCP callers cannot approve, and there is no `approved` argument. 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
- Version 1.1.0 adds per-step input/output conditions, bounded semantic locator scopes (one to four unique containers), state waits, and fixed scalar transforms (`trim`, case conversion, digits only, strict number/boolean parsing, and stringification). A false condition skips one step; there are no loops or arbitrary expressions. No locator can match more than one element; normal actions require one match, while hidden/detached waits and `allowMissing` extraction can accept zero. No scripts, shell steps, CSS programs, first-match fallback or automatic repair.
- Frames, popups, uploads/downloads, WebSockets and general credential providers are unsupported. Authentication profiles currently require POSIX owner-only file permissions; Windows rejects that feature explicitly. `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. `TRANSFORM_INPUT_INVALID`: provide a non-null value in the declared source format; parsing does not guess.
- 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](PRIVACY.md), [security](docs/security-model.md), [upstream audit](docs/upstream-audit.md), [workflow format](docs/workflow-format.md), [dependencies](docs/dependency-inventory.md) and [notices](docs/legal/third-party-notices.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data