Skip to content

docs(ui-capture): agent quickstart and walkthrough, and REST, MCP and CLI references - #991

Merged
slayerjain merged 1 commit into
mainfrom
docs/ui-capture-agent-references
Nov 20, 2026
Merged

slayerjain merged 1 commit into
mainfrom
docs/ui-capture-agent-references

Conversation

@slayerjain

@slayerjain slayerjain commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

What this does

The UI Testing section gets its agent path, end to end: an AI agent can set up UI capture in a web app and read what it records, through the Keploy MCP server or the REST API. Six new pages, and the REST and MCP setup the overview has carried until now moves into them.

New:

  • /docs/ui-capture/quickstart-agent/ (AI agent quickstart, under Quickstarts). Connect Claude Code, Cursor, Codex or another MCP client to the Keploy MCP server three ways (OAuth sign-in; a personal access token, with the command and a screenshot of the setup card's agent callout; keploy login and keploy mcp-install), ask the agent, what it does, using the app, reading the flows, the same steps with curl, what the agent sees, clean-up.
  • /docs/ui-capture/walkthrough-agent/ (An agent onboards a web app, under Walkthroughs). Twelve steps, each with the real invoke_tool call and its answer: find the tools, createApp, uiCaptureSetup, the SDK in the sample shop, uiCaptureStatus at NO_SESSIONS, RECORDING and FLOWS_READY, /complete, listUIFlows, getUIFlow, uiJourneys, uiJourneyImpact (with a comma-joined journeyIds and a refused one), listUITestRuns, revokeUIIngestKey, deleteApp; then the waits and what an agent cannot do yet.
  • /docs/ui-capture/agents/ (Operate from an AI agent, under Guides). Credentials (OAuth, PAT, keploy mcp-install and its 90-day token, KEPLOY_API_KEY, a UI_READER service-account key on a paid plan) and what each can do; tool-search mode; the lifecycle as MCP tool and REST route; waiting and polling; the errors to branch on; what an agent sees; what agents cannot do yet.
  • Reference: /docs/ui-capture/rest-api/ (every UI Capture operation, scope and permission, parameters, a real answer, plus the ingest endpoints and /complete), /docs/ui-capture/mcp-tools/ (the server, the 15 tools with their inputs and scopes, a JSON-RPC call, input types, OAuth or API key) and /docs/ui-capture/cli/ (keploy login and keploy mcp-install as the released binary has them; keploy ui is not in a release build).

Changed:

  • Overview (running-keploy/ui-capture): "With the REST API" and "From an AI agent (MCP)" are now short sections that link the new pages; their old sub-sections (create an ingest key, check that capture is working, read the flows, manage ingest keys, what an agent sees) moved, and a Where did a section go? table at the bottom points to each one's new place. #set-up-ui-capture-with-the-rest-api and #set-up-ui-capture-from-an-ai-agent-mcp are kept.
  • ui-capture/errors.md: the "mint a key" link points to the REST reference; "Handle errors from the Keploy UI tools" no longer lists keploy ui run's flags as commands of the binary, and says keploy ui --help and keploy ui run are not in a release build yet (founder ruling D2: replay is beta, not runnable yet). No {#kui-e-…} section is touched.
  • walkthrough-dashboard.md, privacy.md, sessions-and-sampling.md: links follow the moved sections.
  • NO_FLOWS: the overview and the REST state table said a page that is only loaded makes no flow, repeating api-server's own hint. The extractor turns every page's load into a navigate action (api-server pkg/service/uicapture/flowengine/extract.go:440-466) and skips only empty sequences (flowengine/dedup.go:214-216), so an untouched page makes a one-step Navigate on /about flow, as on staging. Both now say so.
  • Sidebar: one item each in Quickstarts and Walkthroughs, the agents page at the end of Guides, three items in Reference.
  • llms.txt: the six pages.

Replay stays "beta, not runnable yet" everywhere: no page gives a step to generate or run a test, and every page that mentions runs says a run today comes only from the dashboard's Generate Test and stays pending.

Screenshot

One, ui-capture-agent-callout.webp (76 KB): the setup card's "Setting this up with an AI agent or a script?" callout, an element shot. Taken by a Playwright script on a build box against Keploy's staging dashboard, for a throwaway app (docs-demo-agent) the script created and deleted; the staging host is written as api.keploy.io; no key is in the shot.

How the examples were made

The same box job drove the lifecycle as an agent does, through the staging MCP server (invoke_tool over JSON-RPC) and the REST API, against the throwaway app: six visits to the React sample shop (samples-typescript main, SDK 3.1.0) in headless Chromium, each ended with /complete. Every JSON answer on the pages is from that run, with IDs replaced by fresh UUIDs, the staging host written as api.keploy.io, the key blanked, and lists shortened. A few REST-page answers were captured through the MCP server (which dispatches the same handler in-process) and are printed in the REST API's field order. Clean-up: the keys revoked, deleteApp, and GET of the app answered 404. Before the run, the script checked that staging serves api-server main's UI Capture operations: the served openapi.yaml's UI Capture paths are byte-identical to main's.

The CLI page was checked against the released binary itself (Keploy 3.9.4, the latest release; asset checksum verified): its help tree, keploy login --help, keploy mcp-install --help, and keploy ui --help, which answers unknown command "ui".

Sources checked

Sources: keploy/api-server main 7d97ad0db (api:), keploy/enterprise-ui main 4a5d8c5d (eui:), keploy/enterprise v3.9.4 cbd2ee776b, the released keploy binary (ent:), keploy/ui-capture v3.1.0 9bae8002 (uic:), keploy/samples-typescript main 6231b4e (samples:). Staging serves api-server main's UI Capture operations: the served openapi.yaml's UI Capture paths are byte-identical to main's.

ui-capture/cli

  • The released binary's command tree, run on a build box (3.9.4, checksum checked): keploy --help lists login, logout, mcp-install, skill, … and no ui; keploy ui --help answers Error: unknown command "ui" for "keploy".
  • ent:cmd/enterprise/cli/ui.go:1-9 (the keploy ui tree builds only under the uicapture tag); ent:goreleaser.yaml:116-120, 165-169, 196-197, 226-227, 280-281 (no release build sets it).
  • ent:cmd/enterprise/cli/provider/cmd.go:483-505 (login's flags and exclusions); ent:pkg/tokenmanager/device_login.go:167 (--finish waits 70 s).
  • ent:cmd/enterprise/cli/login.go:37 (examples), 82-99 (--no-wait, --finish, --json), 882-921 (an accepted API key answers signed in, no device code).
  • ent:pkg/tokenmanager/token.go:330-347 (--manual-login asks for an API key), 350-365 (KEPLOY_API_KEY), 366-380 (a stored session, then the browser sign-in).
  • ent:cmd/enterprise/cli/mcp_install.go:137-260 (the agents and their config files), 446-447, 919-932 (flags), 1645 (the server entry keploy).
  • api:pkg/http/mcp.go:22 (the token's name), 57-99 (its scopes follow the caller's permissions), 128-200 (revokes the caller's earlier ones), 306-337 (mcp_url).

ui-capture/mcp-tools

  • api:pkg/http/apiv1/mcp.go:51 (keploy-atg), 282-285 (one tool per OpenAPI operation), 304-315 (tool-search listing, lean instructions, streamable HTTP, stateless).
  • api:pkg/mcp/meta_tools.go:72-102 (the instructions' UI CAPTURE section), 110-118 (the seven tools on tools/list), 158-268 (search_tools: names and a summary, 10 by default, keyword-scored), 270-322 (get_tool_schema), 326-360 (invoke_tool).
  • api:pkg/mcp/spec_sync.go:29-200 (tool = operationId; inputs from path, query and body), 219-245 (typedParam: number, boolean, else string, so journeyIds is a string), 306-358, 374-387 (annotations).
  • api:pkg/mcp/executor.go:190-310 (in-process dispatch with the caller's key, the envelope plus status_code, 4xx/5xx as errors); api:pkg/mcp/proxy.go:141-188 (isError).
  • api:pkg/http/apiv1/router.go:122, 217-218 (100 a minute per key; 60 a minute per IP only without a key), 259-265.
  • api:pkg/http/apiv1/mcp_auth.go:42-80 (401 challenge; ingest key refused), 87-121; api:pkg/models/oauth.go:24-40 (OAuth scopes read and write, never admin); api:pkg/service/oauth/apikeystore.go:62-69 (an OAuth token works only through the MCP server); api:server/server.go:3074-3103.
  • api:pkg/http/apiv1/openapi.yaml x-required-scope of each operation (45-180, 2418-2793).
  • api:pkg/http/apiv1/service_account_operation_gate.go:44-50, 143-161; api:pkg/models/roles.go:57-59, 93-104; api:pkg/models/permissions.go:517-612 (no runner role holds testgen:run).
  • Staging: tools/list, get_tool_schema of the 15 tools (names, required inputs, types), a refused getUITestRun.

ui-capture/rest-api

  • api:pkg/http/apiv1/openapi.yaml:1-24, 42-180, 2418-2793, 2884-2936; router.go:245-246 (/client/v1/docs, /client/v1/openapi.yaml).
  • api:pkg/http/apiv1/middleware.go:56-58, 371-373 (Bearer or X-API-Key), 109-112 (an ingest key is 403), 627-650 (rate-limit headers, Retry-After); response.go:21-46 (envelope, pagination); errors.go:30-115 (codes).
  • api:pkg/http/apiv1/uicapture_agent.go:139-150 (limits), 160-208 (views, snippet), 216-308 (mint: name, ttlDays, reserved name, 409, no-store, next, empty endpoint), 313-360 (list, revoke), 362-449 (status), 454-483 (flows, no pagination meta), 491-610 (flow graph bounds), 620-635 (limit 1-200), 1018-1086 (one flow); api:pkg/models/uicapture.go:17-32 (session and flow statuses), 572-594 (flow graph fields).
  • api:pkg/service/uicapture/capture_status.go:97-147 (states and their next).
  • api:pkg/http/apiv1/uicapture_journeys.go:73-104 (freshness), 117-139 (429 RATE_LIMITED, Retry-After: 10), 189-224 (refresh needs testgen:run), 226-249 (impact); api:pkg/service/uicapture/journeyplan/service.go:268-290 (impact IDs from the plan's journeys).
  • api:pkg/http/apiv1/uicapture_test_runs.go:80-160 (views), 198-247 (summary line), 312-327 (next), 347-410 (list, paged; one run).
  • api:pkg/http/apiv1/uiingest.go:23-58 (ingest answers), 66-107 (6,000 a minute, CORS), 330-360 (complete); api:pkg/service/uicapture/sdk_ingest.go:308-334 (completing again answers the session as it is); api:pkg/uicapture/sdkwire/sdkwire.go:41-47 (10 MiB); api:pkg/http/apiv1/uiingest_auth.go:39-46 (30 s cache).
  • Staging: every example answer; field order of answers captured through MCP from the views above.

ui-capture/agents

  • The cites of the REST and MCP pages; eui:components/authorized-apps/AuthorizedApps.tsx:30-36, 231-251 and eui:components/app-sidebar.tsx:721 (Settings → Authorized apps); eui:components/api-keys/CreateTokenDialog.tsx:34-36, 130 (Generate new token, Read, Write, Admin); eui:app/settings/service-accounts/page.tsx:11-13 (admins create service accounts).
  • api:pkg/http/apiv1/uicapture_agent.go:637-990 ("What an agent sees", moved from the overview unchanged).
  • uic:packages/sdk/README.md:190 (privacy modes; strict for public sites), 211 (getSessionId); eui:app/ui-testing/[flowId]/page.tsx:552-567 (Generate Test's pending run).

ui-capture/quickstart-agent

  • eui:components/ui-testing/CaptureSetupCard.tsx:78-92 (the callout's commands), 467-488 (the callout); the cites above; samples:ui-capture-react-shop/src/keploy.ts, .env.example, scripts/visits.mjs.

ui-capture/walkthrough-agent

  • Every call and answer from the staging run; the cites above; api:pkg/service/uicapture/journeys/plan.go (selection).

running-keploy/ui-capture, errors.md, walkthrough-dashboard.md, llms-root, sidebar

  • The moved text keeps batch 1's cites. errors.md: the line on what a remedy names now says keploy ui --help and keploy ui run are not in a release build (the binary's tree above).

Checks

On a build box, with CI's commands (node 22, yarn 1.22), on this commit (on main 9cc6d36):

  • prettier@2.8.8 --check on the changed .md files
  • the asset budget: the one new image is 76 KB, and its src="/docs/…" resolves under static/
  • yarn install --frozen-lockfile and the yarn.lock check
  • yarn build on main and on this branch: neither prints a warning or error line, so the branch adds none (onBrokenLinks and onBrokenAnchors are throw)
  • verify-linkedin-tag, verify-schema, verify-lastmod, verify-moved-urls and verify-ui-capture-sdk-links (49 error sections, 5 refused verbs, 4 README links)
  • yarn build with onBrokenAnchors: throw also covers the moved sections: nothing on the site links an overview heading this change removes

In the built site: every heading id the pages link to exists (the overview's kept ones and #where-did-a-section-go, and each new page's sections); the image is in the build; llms.txt and the sitemap list the six new pages; both task pages carry their HowTo; a rendered-text comparison of each page's source with its HTML differs only at the JSX components and code-block titles, and errors.md differs nowhere.

… CLI references

The UI Testing section's agent path: an AI agent sets up UI capture and reads
flows and journeys through the Keploy MCP server or the REST API.

- ui-capture/quickstart-agent: connect an agent (OAuth, a personal access
  token, keploy login + keploy mcp-install), what it does, curl without MCP.
- ui-capture/walkthrough-agent: every tool call and its answer, from a
  staging run against a throwaway app, IDs replaced.
- ui-capture/agents: credentials, the lifecycle as MCP tools and REST routes,
  waits, errors, what an agent sees, what it cannot do yet.
- ui-capture/rest-api, mcp-tools, cli: references, checked against
  api-server main and the released keploy binary.
- running-keploy/ui-capture: the REST and MCP setup moves to those pages,
  with a "Where did a section go?" table.
- ui-capture/errors: keploy ui --help and keploy ui run are not in a release
  build yet; the flags of keploy ui run are no longer listed.
- NO_FLOWS: a page opened and left untouched still makes a one-step
  Navigate flow (flowengine extract.go, dedup.go); the overview and the
  REST state table no longer say it makes none.
- Sidebar (agents joins the Guides category), llms.txt, and links in the
  dashboard walkthrough, privacy and sessions pages to the moved sections.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
@slayerjain
slayerjain force-pushed the docs/ui-capture-agent-references branch from ab95c32 to 5719b74 Compare November 20, 2026 08:14
@slayerjain slayerjain changed the title docs(ui-capture): AI agent quickstart and walkthrough, and REST, MCP and CLI references docs(ui-capture): agent quickstart and walkthrough, and REST, MCP and CLI references Nov 20, 2026
@slayerjain
slayerjain merged commit 676fa6e into main Nov 20, 2026
6 checks passed
@slayerjain
slayerjain deleted the docs/ui-capture-agent-references branch November 20, 2026 08:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant