Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@formpilot dry-run the signup form on myapp.test, show me the data, then submit it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your AI coding agent fills out and submits web forms for testing — by driving a real browser.
Ask Claude Code or Codex to test a form. formpilot reads the fields, generates realistic data, fills it in, uploads files, walks multi-step wizards, and submits — no database access, no app code changes. The browser opens visibly by default, so you watch it happen live instead of taking it on faith.
1. Clone
git clone https://github.com/MazenBorong/formpilot.git && cd formpilot && npm run setupInstalls everything (including a Chromium browser), builds, and registers formpilot as an MCP server with whichever of Claude Code / Codex is on your machine. Safe to re-run anytime.
2. Allow your host
Open formpilot.config.json and add the host you're testing to
allowedHosts:
{ "allowedHosts": ["myapp.test"] }formpilot refuses to touch any host not on this list — no accidental runs against production.
3. Use it
Open Claude Code or Codex and ask:
"use formpilot to dry-run the signup form on myapp.test, show me the data, then submit it"
Watch the browser do it live, then check ./formpilot-runs/<timestamp>/ for
the screenshot and payload.
Related MCP server: Aiqaramba
Three MCP tools, used in order:
inspect_form — loads the page, returns every field's name, type,
constraints, and options as a schema.
generate_test_data — turns that schema into realistic values (no
browser involved), so you can review or override before anything touches
the page.
fill_and_submit — fills the form, uploads generated fixture files,
walks multi-step wizards, and submits via the real submit button. Reports
final URL, validation errors, console/network errors, and a screenshot.
A formpilot fill <url> CLI does all three in one shot for humans.
Refuses to touch any host not in allowedHosts — production is never one
typo away.
Headed (visible) by default — set "headless": true in
formpilot.config.json for CI or quiet background runs.
dryRun: true fills and screenshots but never clicks submit.
Every run's payload and screenshot are saved to ./formpilot-runs/<timestamp>/.
Login-gated forms — define named profiles (loginUrl, fields,
submit) in formpilot.config.json; secrets are read from env vars
($MY_VAR), never stored or logged.
Manual setup / Codex config / piecemeal commands — see
scripts/ and package.json for npm run build, npm run claude, npm run codex.
Tests — npm test runs a full fill_and_submit pass against the
bundled sample form in test/fixtures/.
Known limits — regex pattern constraints aren't solved generically;
no LLM-assisted filling yet (deterministic rules + faker).
Fill a form with valid test data (generated from its schema if data is omitted) and submit it via the real submit button (not form.submit()), handling multi-step wizards and consent modals along the way. Reports final URL, HTTP status, redirect chain, a success/failure guess, every visible validation error mapped to its field, console errors, failed network requests, and a full-page screenshot path.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| data | No | Field values by name; missing fields are generated | |
| seed | No | Seed for any auto-generated field values | |
| dryRun | No | Fill and screenshot but do not click submit | |
| headed | No | Show the browser window (default: visible, unless formpilot.config.json sets "headless": true) | |
| formSelector | No | ||
| loginProfile | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses real-button submission, multi-step wizard and consent-modal handling, and enumerates what is returned (final URL, status, redirects, success guess, mapped validation errors, console errors, failed requests, screenshot). It does not mention permission/login requirements beyond the loginProfile param name or any side effects of submitting real data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One long but well-structured sentence: the core action is front-loaded, and the output enumeration follows. No filler, though the dense output list makes it heavier than needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description correctly enumerates return values, and it covers wizard/modal edge cases and the dryRun escape hatch. The main gaps are the undocumented parameters and lack of auth/side-effect guidance for a tool that submits real data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 57%. The description adds meaning for `data` (generated from the form's schema when omitted), reinforcing the schema note, but says nothing about seed, dryRun, headed, formSelector, or loginProfile. It partially compensates but leaves several parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (fill a form and submit it) plus the distinguishing mechanism — the real submit button rather than form.submit(). This clearly separates it from siblings generate_test_data (data only) and inspect_form (read-only inspection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description (fill a live form and submit), and it notes data is auto-generated when omitted, but it never says when to prefer inspect_form or generate_test_data, nor when not to submit on a live endpoint. No explicit alternatives or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate realistic, valid test data for a form schema (as returned by inspect_form) without touching the browser — lets the agent review/edit data before submitting.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Make faker-generated values repeatable across runs | |
| schema | Yes | A FormSchema object, as returned by inspect_form | |
| overrides | No | Field values to pin instead of generating |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It helpfully discloses that the tool has no browser side effects and that its output is editable data, but it says nothing about determinism guarantees, error behavior on invalid schemas, or the shape of the returned values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that pairs the action with its key constraint and benefit; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does explain what the agent gets back (reviewable/editable data) and where the input schema comes from. It is largely complete for this tool, though a note on output format or failure modes would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with seed, schema, and overrides all documented in the schema itself, so the baseline is 3. The description adds no parameter-level detail beyond what the schema already states (e.g., how seeds interact with overrides).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (generate) and resource (realistic, valid test data for a form schema), and scopes the data source as the output of inspect_form. It also implicitly separates itself from fill_and_submit by stressing that it works without touching the browser.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'without touching the browser — lets the agent review/edit data before submitting' clause gives a clear workflow context: use this to preview data ahead of fill_and_submit. It does not explicitly name fill_and_submit as the alternative or state exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a page (optionally logging in via a configured profile first) and return a JSON schema of every field in its form(s): name, type, label, placeholder, required, pattern/min/max/maxlength, select/radio/checkbox options, file accept types, hidden fields, and best-effort multi-step grouping.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Page URL to inspect | |
| headed | No | Show the browser window (default: visible, unless formpilot.config.json sets "headless": true) | |
| formSelector | No | CSS selector for the form; defaults to the first <form> | |
| loginProfile | No | Named profile from formpilot.config.json to log in with first |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses useful behavior: optional profile-based login, hidden fields being returned, and 'best-effort multi-step grouping'. However it never states that no submission/state mutation occurs, nor anything about navigation, timeouts, or failure modes on unloadable pages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the action and then the return payload. No wasted clauses, though the long comma-listed enumeration of field attributes is slightly heavy for one sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly compensates by enumerating the returned field metadata in detail, and it covers the login precondition. Error handling and page-load failure behavior remain unaddressed, which is the main gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents url, headed, formSelector, and loginProfile. The description adds only marginal value by restating the optional login step that maps to loginProfile; it adds no syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (load/inspect) and resource (form fields on a page) and enumerates exactly what is returned, making it clearly distinct from siblings fill_and_submit and generate_test_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance, and no alternatives named. The user must infer from the sibling names that this is the reconnaissance step before filling/submitting, but the description never says so.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0fill_and_submitgenerate_test_datainspect_formScored across 3 tools
Each tool has a clearly distinct pipeline role: inspect_form discovers form structure, generate_test_data produces data without browser interaction, and fill_and_submit performs the actual fill and submit action. The overlap in data generation is secondary and explicitly positioned for pre-submission review, so there is no meaningful ambiguity.
All tool names use snake_case and descriptive verbs, but the patterns are not perfectly uniform: generate_test_data includes an extra noun and fill_and_submit uses a conjunction. Still, the style is consistent and readable across the set.
Three tools are well-scoped for a focused form-testing server, covering the essential inspect-generate-submit workflow without redundancy. Each tool earns its place and the minimal set is appropriate.
The tools cover the core lifecycle: inspect form fields, generate valid data, and fill/submit with detailed reporting. A minor gap is the lack of a fill-without-submit operation, but agents can work around it by supplying invalid data to trigger validation errors.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Autonomous cloud agent tasks: real browser + your tools, structured evidence-backed results.
