{"_id":"@airux/mcp","name":"@airux/mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@airux/mcp","version":"0.1.0","description":"Local MCP server for recording localhost evidence and submitting AirUX reviews.","type":"module","bin":{"airux-mcp":"dist/stdio.js"},"engines":{"node":">=20"},"repository":{"type":"git","url":"git+https://github.com/DorianGulley/AirUX.git","directory":"packages/mcp"},"homepage":"https://github.com/DorianGulley/AirUX/tree/main/packages/mcp","keywords":["airux","mcp","playwright","video-evidence"],"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/server":"2.0.0","playwright":"1.62.1"},"devDependencies":{"@modelcontextprotocol/client":"2.0.0","@types/node":"26.2.0","esbuild":"0.28.2","tsx":"4.23.12","@airux/shared":"0.0.0"},"scripts":{"build":"esbuild src/stdio.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/stdio.js --external:@modelcontextprotocol/* --external:playwright --banner:js='#!/usr/bin/env node'","browser:install":"playwright install chromium","start":"tsx src/stdio.ts"},"_nodeVersion":"24.12.0","_id":"@airux/mcp@0.1.0","dist":{"integrity":"sha512-wCjQjWZDB7p4qcua+Cex6Gn3VetZO1V7axZSQkv4zo4HJ+d4/imNkC6RLj/wX73UGlgXYiWPqWCsNxpbIn36rg==","shasum":"342915ea1879467791cc9293595298686a393700","tarball":"https://registry.npmjs.org/@airux/mcp/-/mcp-0.1.0.tgz","fileCount":3,"unpackedSize":625918,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH1iEqeIq/CbuU9UwKxNE5+UrwQ5l9FWUwacVoIIY4HvAiB4WvaCNgsF/CQ7i/VE2vZUusPXOZ6DLReI2EU4bVwu3g=="}]},"_npmUser":{"name":"dgulley","email":"dgulley@stanford.edu"},"directories":{},"maintainers":[{"name":"dgulley","email":"dgulley@stanford.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.0_1788985110851_0.22943495881042253"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-09T20:18:30.648Z","0.1.0":"2026-09-09T20:18:31.006Z","modified":"2026-09-09T20:18:31.426Z"},"maintainers":[{"name":"dgulley","email":"dgulley@stanford.edu"}],"description":"Local MCP server for recording localhost evidence and submitting AirUX reviews.","homepage":"https://github.com/DorianGulley/AirUX/tree/main/packages/mcp","keywords":["airux","mcp","playwright","video-evidence"],"repository":{"type":"git","url":"git+https://github.com/DorianGulley/AirUX.git","directory":"packages/mcp"},"readme":"# AirUX MCP server\n\nThe local stdio server exposes `airux_create_review`, `airux_get_review`,\n`airux_list_open_reviews`, and `airux_cancel_review`. The create tool records a\nvalidated localhost browser flow, creates an AirUX Review, uploads the temporary\nWebM recording directly to Cloudflare Stream, waits for processing, removes the\nlocal recording, and returns the pending Review URL.\n\n## Customer installation\n\nInstall the matching Chromium build once, then run the published package from\nthe agent host's MCP configuration:\n\n```sh\nnpx -y playwright@1.62.1 install chromium\nnpx -y @airux/mcp@0.1.0\n```\n\nThe server requires `AIRUX_API_ORIGIN` and `AIRUX_AGENT_TOKEN` in its process\nenvironment. The complete Codex and Claude Code setup, first Review, and\ncredential revocation flow is documented in\n[the AirUX Review onboarding guide](https://github.com/DorianGulley/AirUX/tree/main/skills/airux-review#readme).\n\n## Developer setup\n\nInstall Chromium once:\n\n```sh\npnpm mcp:browser:install\n```\n\nConfigure the AirUX API origin and an agent credential, then start the stdio\nserver:\n\n```sh\nAIRUX_API_ORIGIN=https://airux.example \\\nAIRUX_AGENT_TOKEN=\"airux_agent_v1.CREDENTIAL_ID.SECRET\" \\\npnpm mcp:start\n```\n\n`AIRUX_API_ORIGIN` must be an HTTPS origin. HTTP is accepted only for localhost\nand loopback development origins. Stdout is reserved for MCP JSON-RPC messages;\ntransport diagnostics use stderr and never include API responses or credentials.\n\n## Agent workflow guidance\n\nThe server publishes MCP initialization instructions that describe when to use\nAirUX and how to sequence creation, polling, feedback, and recovery. MCP clients\nthat support server instructions receive that guidance when they connect.\n\nThe customer package lives at `skills/airux-review`, with its one host-neutral\nAgent Skills source nested at `skills/airux-review/skills/airux-review`.\nRepository discovery adapters expose that canonical skill to Codex through\n`.agents/skills/airux-review` and to Claude Code through\n`.claude/skills/airux-review`; both adapters are symlinks so the workflow cannot\ndrift between hosts. The skill activates for natural-language requests such as\n“record a video of this localhost page” and “provide video evidence of this\nbutton working,” derives the tool input from the request and inspected localhost\napplication, and immediately invokes `airux_get_review` after creation.\n\nThe outer package directory contains\n`.codex-plugin/plugin.json` for Codex and `.claude-plugin/plugin.json` for Claude\nCode while retaining one shared nested `SKILL.md`. Preserve the hidden manifest\ndirectories when archiving or publishing the package. The package declares the\nAirUX MCP server as a required Codex tool but does not bundle the server or any\ncredential; connect and configure the AirUX MCP server before activating the\nskill. Claude Code can load a source checkout for local validation with:\n\n```sh\nclaude --plugin-dir ./skills/airux-review\n```\n\nRepository marketplace catalogs publish the plugin for Codex and Claude Code.\nThe separately configured `@airux/mcp` package supplies its local MCP tools;\nneither the marketplace package nor the MCP npm package contains an agent\ncredential.\n\nThe skill and result poll coordinate an active agent task. They persist Review\nstate across interruption, but cannot wake a task after its agent host has\nterminated it.\n\n## Tool contract\n\n`airux_create_review` accepts:\n\n- `client_request_id`, `title`, `claim`, and `criteria`\n- `capture_plan`, using the constrained localhost-only AirUX capture schema\n\nOn success it returns `review_id`, `review_url`, and `status: \"pending\"` as\nstructured content. The tool captures once. Transient create calls reuse the\nsame idempotency key, and ambiguous uploads receive one bounded state-based\nrecovery attempt before the temporary recording is deleted and a sanitized tool\nerror is returned.\n\nCapture failures return `isError: true` with actionable text and safe structured\ncontent under `error`. The stable fields are `code: \"capture_failed\"`, `reason`,\nand `suggestion`; step failures also include `action`, zero-based `step_index`,\nand, when available, the safe `selector` and `match_count`. Raw browser traces,\nfill values, credentials, and provider responses are never returned. For\nexample, a selector strictness failure can return:\n\n```json\n{\n  \"error\": {\n    \"code\": \"capture_failed\",\n    \"reason\": \"selector_not_unique\",\n    \"action\": \"hover\",\n    \"step_index\": 2,\n    \"selector\": \".card\",\n    \"match_count\": 4,\n    \"suggestion\": \"Replace the selector with one that resolves to exactly one element, then retry.\"\n  }\n}\n```\n\n`airux_get_review` accepts a `review_id`, then waits locally for the Review to\nreach a terminal state. It polls the authenticated AirUX API with increasing\nintervals, honors server retry guidance, and returns the final status and human\nDecision. Cancelling the MCP request interrupts the wait without changing the\nremotely stored Review.\n\nAfter an agent or MCP process is interrupted, call `airux_list_open_reviews`\nwith no arguments. It returns compact `draft` and `pending` Review summaries\ncreated by the configured agent credential, ordered newest first. Match the\noriginal work using `client_request_id` or the Review title, then pass its `id`\nto `airux_get_review` to resume waiting for the terminal result. An empty list\nmeans that credential has no unresolved Reviews.\n\n`airux_cancel_review` accepts a `review_id` for a `draft` or `pending` Review.\nCancellation is idempotent: AirUX makes the Review terminal, revokes reviewer\nplayback, and schedules its Evidence for deletion. Repeating cancellation\nreturns the same cancelled Review without incrementing its version again.\n\n## Publishing `@airux/mcp`\n\nThe package is released publicly from this directory. Confirm the version is\nunused and the npm account can publish the `@airux` scope, then run from the\nrepository root:\n\n```sh\npnpm --filter @airux/mcp pack\npnpm --filter @airux/mcp publish --access public\n```\n\nThe `prepack` script creates the bundled executable. The bundle includes AirUX's\nworkspace-only shared contracts while keeping Playwright and the MCP SDK as\nnormal runtime dependencies.\n","readmeFilename":"","_rev":"1-6d41c4087041b29cab544a089af41a19"}