diff --git a/dist/claude-code/replayio/skills/replayio/SKILL.md b/dist/claude-code/replayio/skills/replayio/SKILL.md index a014d8a..39d9c0d 100644 --- a/dist/claude-code/replayio/skills/replayio/SKILL.md +++ b/dist/claude-code/replayio/skills/replayio/SKILL.md @@ -173,6 +173,12 @@ If the browser is already running: First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the `replay` MCP server tools only when you need deeper Replay-specific debugging beyond direct CLI output. Claude Code connects to the Replay HTTP MCP server configured in `.mcp.json`. +## Replay MCP widgets + +Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks. + +When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection. + ## Recording uploads are automatic You do **not** need to run `replayio list` or `replayio upload ` manually. The plugin's hooks handle uploads: diff --git a/dist/codex/replayio/.codex-plugin/plugin.json b/dist/codex/replayio/.codex-plugin/plugin.json index c9ddb38..296c647 100644 --- a/dist/codex/replayio/.codex-plugin/plugin.json +++ b/dist/codex/replayio/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "replayio", "version": "0.1.0", - "description": "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through the connected Replay ChatGPT app, and auto-upload recordings when the browser closes or the turn ends.", + "description": "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through Replay MCP tools with rich inspector widgets, and auto-upload recordings when the browser closes or the turn ends.", "author": { "name": "Replay", "url": "https://replay.io" @@ -19,11 +19,12 @@ ], "skills": "./skills/", "apps": "./.app.json", + "mcpServers": "./.mcp.json", "hooks": "./hooks.json", "interface": { "displayName": "Replay.io", - "shortDescription": "Record browser sessions and analyze recordings", - "longDescription": "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through the connected Replay ChatGPT app.", + "shortDescription": "Record browser sessions and inspect Replay recordings", + "longDescription": "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through Replay MCP tools. In MCP Apps-aware hosts, Replay tool results can render rich debugging widgets for logpoints, console output, React trees, Redux state, network requests, screenshots, source code, profiles, and exception stacks.", "developerName": "Replay", "category": "Coding", "capabilities": [ diff --git a/dist/codex/replayio/.mcp.json b/dist/codex/replayio/.mcp.json new file mode 100644 index 0000000..98a3bdd --- /dev/null +++ b/dist/codex/replayio/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "replay": { + "type": "http", + "url": "https://dispatch.replay.io/mcp" + } + } +} diff --git a/dist/codex/replayio/README.md b/dist/codex/replayio/README.md index 871a147..46e0e5f 100644 --- a/dist/codex/replayio/README.md +++ b/dist/codex/replayio/README.md @@ -1,5 +1,27 @@ -# Replay.io Plugin +# Replay.io (Codex) -Generated from `src/` in the Replay.io agent plugins repo. +Record browser sessions with the **Replay Browser** via Playwright CLI, inspect runs from the terminal, and use the **Replay MCP** server (`.mcp.json`) after a recording uploads. Hooks upload pending recordings when Playwright closes a session and when the Codex turn stops. + +## MCP widgets + +The Codex plugin exposes Replay MCP directly through `https://dispatch.replay.io/mcp`. That server can attach MCP Apps widget metadata to tool descriptors: + +- `_meta.ui.resourceUri` for MCP Apps-compatible hosts. +- `_meta["openai/outputTemplate"]` as the ChatGPT/OpenAI compatibility alias. +- `structuredContent` for widget rendering while preserving text `content` for model narration. -This bundle includes the Replay browser skill, upload/cleanup scripts, and the platform-specific integration config for this target. +When the backend returns Replay widget results, Codex can render inspector-style cards for logpoints, console messages, React trees, Redux state, network requests, screenshots, source views, profiles, and exception stacks. + +## What ships in this bundle + +| Component | Path | +|-----------|------| +| Plugin manifest | `.codex-plugin/plugin.json` | +| Connected Replay app | `.app.json` | +| Replay HTTP MCP server | `.mcp.json` | +| Agent skill | `skills/replayio/SKILL.md` (+ `references/`) | +| Hooks | `hooks.json` | +| Scripts | `scripts/post_bash_upload.sh`, `scripts/stop_close_and_upload.sh`, `skills/replayio/scripts/playwright_cli.sh` | +| Logo | `assets/replayio.svg` | + +Generated from `src/` in the Replay.io agent plugins repo. diff --git a/dist/codex/replayio/skills/replayio/SKILL.md b/dist/codex/replayio/skills/replayio/SKILL.md index d1446c7..228ecc1 100644 --- a/dist/codex/replayio/skills/replayio/SKILL.md +++ b/dist/codex/replayio/skills/replayio/SKILL.md @@ -1,9 +1,9 @@ --- name: "replayio" -description: "Use when you need to record or inspect a Playwright CLI browser run in Replay, test a local app directly with Playwright CLI, or use the connected Replay app for deeper debugging of an uploaded recording." +description: "Use when you need to record or inspect a Playwright CLI browser run in Replay, test a local app directly with Playwright CLI, or use the Replay MCP server for deeper debugging of an uploaded recording." --- -# Replay Browser + Playwright CLI + Replay App +# Replay Browser + Playwright CLI + Replay MCP Use `playwright-cli` with the Replay Browser whenever you need a recorded browser session. Recordings upload automatically — you do **not** need to run `replayio upload` yourself. Your only responsibility is to **close the browser when the test is complete**. The plugin's hooks handle the rest: @@ -14,9 +14,9 @@ Always prefer closing explicitly — it gives faster feedback and ensures record ## Direct CLI first -Use `playwright-cli` directly for live browser control and first-pass inspection. Do not reach for the connected Replay app just to click, type, snapshot, read console output, inspect network requests, take screenshots, read storage, or check cookies. +Use `playwright-cli` directly for live browser control and first-pass inspection. Do not reach for the Replay MCP server just to click, type, snapshot, read console output, inspect network requests, take screenshots, read storage, or check cookies. -Use the connected Replay app only after a recording has uploaded and you need deeper Replay-specific debugging, such as inspecting execution history, narrowing a time-travel debugging problem, or investigating details that the live CLI cannot answer. +Use the Replay MCP server only after a recording has uploaded and you need deeper Replay-specific debugging, such as inspecting execution history, narrowing a time-travel debugging problem, or investigating details that the live CLI cannot answer. Useful direct commands: @@ -171,7 +171,13 @@ If the browser is already running: ## Analyzing uploaded recordings -First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the connected Replay app tools only when you need deeper Replay-specific debugging beyond direct CLI output. This plugin does not launch a local MCP server; app authentication and tool exposure are handled by the connected Replay app. +First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the `replay` MCP server tools only when you need deeper Replay-specific debugging beyond direct CLI output. Codex connects to the Replay HTTP MCP server configured in `.mcp.json`; the connected Replay app id remains available in `.app.json` for app-level authentication and compatibility. + +## Replay MCP widgets + +Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks. + +When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection. ## Recording uploads are automatic @@ -195,7 +201,7 @@ replayio list - If the requested port was busy, use the actual port printed by the dev server. - If a browser exists but your commands are detached, use `list` then `attach`. - Prefer explicit commands like `fill`, `click`, `check`, and `press` over `eval` or `run-code`. -- Prefer direct CLI inspection (`console`, `network`, `screenshot`, storage, cookies, `eval`) before using the connected Replay app. +- Prefer direct CLI inspection (`console`, `network`, `screenshot`, storage, cookies, `eval`) before using the Replay MCP server. - If Replay authentication fails, run `replayio login` or reconnect the relevant Replay app/integration. ## References diff --git a/dist/cursor/replayio/skills/replayio/SKILL.md b/dist/cursor/replayio/skills/replayio/SKILL.md index eedab17..76764fd 100644 --- a/dist/cursor/replayio/skills/replayio/SKILL.md +++ b/dist/cursor/replayio/skills/replayio/SKILL.md @@ -179,6 +179,12 @@ If the browser is already running: First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the `replay` MCP server tools only when you need deeper Replay-specific debugging beyond direct CLI output. Cursor connects to the Replay HTTP MCP server configured in `mcp.json`. +## Replay MCP widgets + +Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks. + +When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection. + ## Recording uploads are automatic You do **not** need to run `replayio list` or `replayio upload ` manually. The plugin's hooks handle uploads: diff --git a/dist/opencode/replayio/AGENTS.md b/dist/opencode/replayio/AGENTS.md index b7caa92..b3042f7 100644 --- a/dist/opencode/replayio/AGENTS.md +++ b/dist/opencode/replayio/AGENTS.md @@ -6,4 +6,5 @@ Use the Replay browser workflow when a task needs a recorded browser session. - Set `PWCLI` from the plugin-provided shell environment or skill instructions and use `"$PWCLI"` for browser commands. - Close the browser before reporting results: `"$PWCLI" --session="$SESSION" close`. - Use Replay analysis tools only after a recording has uploaded and direct CLI output is not enough. +- If Replay MCP renders an inspector widget, use the widget as the primary debugging view and follow its point/source/component/request actions when useful. - If Replay MCP authentication fails, reconnect or sign in through the agent host and retry. diff --git a/lib/connectors.ts b/lib/connectors.ts index c8cad90..10e934d 100644 --- a/lib/connectors.ts +++ b/lib/connectors.ts @@ -15,7 +15,10 @@ export const connectors = { codex: { id: "codex", output: "dist/codex/replayio", - artifacts: [{ source: ".app.json", destination: ".app.json" }], + artifacts: [ + { source: ".app.json", destination: ".app.json" }, + { source: ".mcp.json", destination: ".mcp.json" }, + ], }, cursor: { id: "cursor", diff --git a/lib/strategies/codex.ts b/lib/strategies/codex.ts index cd688fe..282eb54 100644 --- a/lib/strategies/codex.ts +++ b/lib/strategies/codex.ts @@ -13,7 +13,7 @@ async function build(context: BuildContext, connector: Connector): Promise name: plugin.name, version: plugin.version, description: - "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through the connected Replay ChatGPT app, and auto-upload recordings when the browser closes or the turn ends.", + "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through Replay MCP tools with rich inspector widgets, and auto-upload recordings when the browser closes or the turn ends.", author: { name: plugin.developerName, url: plugin.homepage, @@ -24,12 +24,13 @@ async function build(context: BuildContext, connector: Connector): Promise keywords: replaceKeyword(plugin.keywords, "chatgpt-app"), skills: "./skills/", apps: "./.app.json", + mcpServers: "./.mcp.json", hooks: "./hooks.json", interface: { displayName: plugin.displayName, - shortDescription: "Record browser sessions and analyze recordings", + shortDescription: "Record browser sessions and inspect Replay recordings", longDescription: - "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through the connected Replay ChatGPT app.", + "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through Replay MCP tools. In MCP Apps-aware hosts, Replay tool results can render rich debugging widgets for logpoints, console output, React trees, Redux state, network requests, screenshots, source code, profiles, and exception stacks.", developerName: plugin.developerName, category: "Coding", capabilities: ["Interactive", "Read", "Write"], @@ -50,11 +51,39 @@ async function build(context: BuildContext, connector: Connector): Promise await context.writeJson(path.join(out, "hooks.json"), claudeStyleHooks("${CLAUDE_PLUGIN_ROOT:-.}")); await context.writeSharedPluginFiles(out, { pwcliExport: '${CLAUDE_PLUGIN_ROOT:-$PWD/dist/codex/replayio}/skills/replayio/scripts/playwright_cli.sh', - titleSuffix: "Replay App", - analysisSurface: "the connected Replay app", - analysisTools: "the connected Replay app tools", + titleSuffix: "Replay MCP", + analysisSurface: "the Replay MCP server", + analysisTools: "the `replay` MCP server tools", authNote: - "This plugin does not launch a local MCP server; app authentication and tool exposure are handled by the connected Replay app.", + "Codex connects to the Replay HTTP MCP server configured in `.mcp.json`; the connected Replay app id remains available in `.app.json` for app-level authentication and compatibility.", + readme: `# ${plugin.displayName} (Codex) + +Record browser sessions with the **Replay Browser** via Playwright CLI, inspect runs from the terminal, and use the **Replay MCP** server (\`.mcp.json\`) after a recording uploads. Hooks upload pending recordings when Playwright closes a session and when the Codex turn stops. + +## MCP widgets + +The Codex plugin exposes Replay MCP directly through \`https://dispatch.replay.io/mcp\`. That server can attach MCP Apps widget metadata to tool descriptors: + +- \`_meta.ui.resourceUri\` for MCP Apps-compatible hosts. +- \`_meta["openai/outputTemplate"]\` as the ChatGPT/OpenAI compatibility alias. +- \`structuredContent\` for widget rendering while preserving text \`content\` for model narration. + +When the backend returns Replay widget results, Codex can render inspector-style cards for logpoints, console messages, React trees, Redux state, network requests, screenshots, source views, profiles, and exception stacks. + +## What ships in this bundle + +| Component | Path | +|-----------|------| +| Plugin manifest | \`.codex-plugin/plugin.json\` | +| Connected Replay app | \`.app.json\` | +| Replay HTTP MCP server | \`.mcp.json\` | +| Agent skill | \`skills/replayio/SKILL.md\` (+ \`references/\`) | +| Hooks | \`hooks.json\` | +| Scripts | \`scripts/post_bash_upload.sh\`, \`scripts/stop_close_and_upload.sh\`, \`skills/replayio/scripts/playwright_cli.sh\` | +| Logo | \`assets/replayio.svg\` | + +Generated from \`src/\` in the Replay.io agent plugins repo. +`, }); } diff --git a/src/assets/mcp-widgets-demo.png b/src/assets/mcp-widgets-demo.png new file mode 100644 index 0000000..dd5ea3c Binary files /dev/null and b/src/assets/mcp-widgets-demo.png differ diff --git a/src/content/agents.md b/src/content/agents.md index b7caa92..b3042f7 100644 --- a/src/content/agents.md +++ b/src/content/agents.md @@ -6,4 +6,5 @@ Use the Replay browser workflow when a task needs a recorded browser session. - Set `PWCLI` from the plugin-provided shell environment or skill instructions and use `"$PWCLI"` for browser commands. - Close the browser before reporting results: `"$PWCLI" --session="$SESSION" close`. - Use Replay analysis tools only after a recording has uploaded and direct CLI output is not enough. +- If Replay MCP renders an inspector widget, use the widget as the primary debugging view and follow its point/source/component/request actions when useful. - If Replay MCP authentication fails, reconnect or sign in through the agent host and retry. diff --git a/src/content/skill.md b/src/content/skill.md index 57df05f..8a9fb88 100644 --- a/src/content/skill.md +++ b/src/content/skill.md @@ -173,6 +173,12 @@ If the browser is already running: First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use {{ANALYSIS_TOOLS}} only when you need deeper Replay-specific debugging beyond direct CLI output. {{AUTH_NOTE}} +## Replay MCP widgets + +Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks. + +When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection. + ## Recording uploads are automatic You do **not** need to run `replayio list` or `replayio upload ` manually. The plugin's hooks handle uploads: