{"_id":"@aetherya/mcp","_rev":"6-bef419a26d57def311019734d31a7c2e","name":"@aetherya/mcp","dist-tags":{"latest":"1.0.5"},"versions":{"0.1.0":{"name":"@aetherya/mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit"],"license":"MIT","_id":"@aetherya/mcp@0.1.0","maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"bin":{"aetherya-mcp":"dist/index.js"},"dist":{"shasum":"24cae3ec09e305c220000d0a52c57d253ad15c65","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-0.1.0.tgz","fileCount":43,"integrity":"sha512-1HzIaaIpm2K7l+UJC6FhDB1poD716cYXPkPrcPP9fOAMnCXg/05dXDAvmrvUu9CzGWew1FSvbZaYjcO30b1GMw==","signatures":[{"sig":"MEUCIQC40Q3qE8GiAQMHhktcvSwT5uXH5wJTVeKB0JdbdXLw+gIgcI7U8FtyYxB7URv1CNay1qG/sMldIJ2qBiOdldiBWb4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":152982},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai"},"_npmVersion":"10.9.7","description":"Aetherya MCP server — point any MCP-capable coding agent at a site or copy variant and get behavioral feedback from a synthetic audience (predicted friction, hesitation, and messaging-clarity issues). Results are simulated, not from real users.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.0_1783457290660_0.512052959966123","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aetherya/mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit"],"license":"MIT","_id":"@aetherya/mcp@1.0.0","maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"bin":{"aetherya-mcp":"dist/index.js"},"dist":{"shasum":"4a2bff334a1b5524b39c52ffa3fc660f49a8380c","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-1.0.0.tgz","fileCount":103,"integrity":"sha512-F4wLV5liMh7vkaF2jC/1OyTMsN8r/QUqb6nU3FcLCTyE0eG262kKVZLk+P851FP0oeVJMVUb9pYLhByNyJyXCg==","signatures":[{"sig":"MEQCIC1QCun/4jUnxtQeadRKuM3E2VQa9Y+82jouY5NklN2TAiA81wDDIgMWOKfyr0h9nEvfRI6AbUEpkzuC3A/tIfgVYg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":560018},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"0e16f76f8f239756c0db11ec9ff38e50d7bf2448","scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node dist/index.js","test:e2e":"npm run build && node test/e2e-stdio.mjs","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai","approver":{"name":"aetherya","email":"andrei@aetherya.ai"}},"_npmVersion":"12.1.0","description":"Aetherya MCP server — point any MCP-capable coding agent at a site or copy variant and get behavioral feedback from a synthetic audience (predicted friction, hesitation, and messaging-clarity issues). Results are simulated, not from real users.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.0_1790761126827_0.6357987203090443","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aetherya/mcp","version":"1.0.1","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit","market-research","copy-testing","ai-agents"],"license":"MIT","_id":"@aetherya/mcp@1.0.1","maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"bin":{"aetherya-mcp":"dist/index.js"},"dist":{"shasum":"f575a9f7812c9e2978a579e075da4f351abcb0ff","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-1.0.1.tgz","fileCount":103,"integrity":"sha512-WqCaTIYA8XwOE0iSQ74/VnR0RCp03fLvNJmIeIVMiObNV1/frYxDKlFjYms5zjMfxXMRWeCUkAP/QN9aQkeP0Q==","signatures":[{"sig":"MEUCIEZ8c/Srqc/HDeyLMwqu00eiRuSgOym0/fHtBDI/zYXYAiEA87xgzt3nUb8DrsxPw+0P/ytYds7zLipvs8PmRQD5/cQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":560109},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"0e16f76f8f239756c0db11ec9ff38e50d7bf2448","scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node dist/index.js","test:e2e":"npm run build && node test/e2e-stdio.mjs","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai","approver":{"name":"aetherya","email":"andrei@aetherya.ai"}},"_npmVersion":"12.1.0","description":"Aetherya MCP server: let any MCP-capable agent test decisions on a synthetic audience before shipping. Plan and run research studies, audit sites, compare copy, get instant market reads, simulate social posts and emails, and turn results into decision bri","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.1_1790761611277_0.7131163902770086","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aetherya/mcp","version":"1.0.3","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit","market-research","copy-testing","ai-agents"],"license":"MIT","_id":"@aetherya/mcp@1.0.3","maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"homepage":"https://aetherya.ai","bin":{"aetherya-mcp":"dist/index.js"},"dist":{"shasum":"0c4d617ca8da8adce54d744af8714096d59de8d0","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-1.0.3.tgz","fileCount":130,"integrity":"sha512-I/zTWa/hCobW/HB0H9x+Rls9NGom2Cg47YIPyZSSgtBC1v9mddYz5zlYGhuz8QqR9vtDDD1NcvnHlNX4Y5CA1A==","signatures":[{"sig":"MEUCIQC7tK+YqrvV4vo9n40vv1eZAg/cIPdGfujNimupJRkvyAIgc8UolMUPLam7T+ePmGY/0M66iX+BbDVFZQJu7RhKibQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":826573},"main":"./dist/index.js","type":"module","_from":"file:/home/andrew/dev/Aetherya/aetherya-mcp/release/aetherya-mcp-1.0.3.tgz","types":"./dist/index.d.ts","engines":{"node":">=18"},"mcpName":"ai.aetherya/mcp","scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node dist/index.js","test:e2e":"npm run build && node test/e2e-stdio.mjs","typecheck":"tsc --noEmit","start:http":"node dist/http.js","test:e2e:http":"npm run build && node test/e2e-http.mjs","prepublishOnly":"npm run build"},"_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai","approver":{"name":"aetherya","email":"andrei@aetherya.ai"}},"_resolved":"/home/andrew/dev/Aetherya/aetherya-mcp/release/aetherya-mcp-1.0.3.tgz","_integrity":"sha512-I/zTWa/hCobW/HB0H9x+Rls9NGom2Cg47YIPyZSSgtBC1v9mddYz5zlYGhuz8QqR9vtDDD1NcvnHlNX4Y5CA1A==","_npmVersion":"12.2.0","description":"Aetherya MCP server: test decisions on a synthetic audience from any MCP agent. Run research studies, site audits, copy tests, instant market reads and post or email simulations, then get a decision brief. Simulated, not real-user data.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.3_1792401352322_0.7202996907368107","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@aetherya/mcp","version":"1.0.4","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit","market-research","copy-testing","ai-agents"],"license":"MIT","_id":"@aetherya/mcp@1.0.4","maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"homepage":"https://aetherya.ai","bin":{"aetherya-mcp":"dist/index.js"},"dist":{"shasum":"b1077d1e2ab064828d6ada5037e42cdcbe21b1e3","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-1.0.4.tgz","fileCount":133,"integrity":"sha512-BtOqbcWLyDAGPp4snMIati4UDr/PiSV6bZIOaJ0WVxzeUClY1EVueijptRNX0SzzdxNJOTf+k+R1WTA+TydxLg==","signatures":[{"sig":"MEQCIFmjdEN6CvTAjGL+CFe9+VD28jotRxsBM1ldJg41fgDDAiAwUHekT+Xv7wo63xxZkNlYnX1cJNDQv56mjzj5wu/MwQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":852587},"main":"./dist/index.js","type":"module","_from":"file:/home/andrew/dev/Aetherya/aetherya-mcp/release/aetherya-mcp-1.0.4.tgz","types":"./dist/index.d.ts","engines":{"node":">=18"},"mcpName":"ai.aetherya/mcp","scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node dist/index.js","test:e2e":"npm run build && node test/e2e-stdio.mjs","typecheck":"tsc --noEmit","start:http":"node dist/http.js","test:e2e:http":"npm run build && node test/e2e-http.mjs","prepublishOnly":"npm run build"},"_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai","approver":{"name":"aetherya","email":"andrei@aetherya.ai"}},"_resolved":"/home/andrew/dev/Aetherya/aetherya-mcp/release/aetherya-mcp-1.0.4.tgz","_integrity":"sha512-BtOqbcWLyDAGPp4snMIati4UDr/PiSV6bZIOaJ0WVxzeUClY1EVueijptRNX0SzzdxNJOTf+k+R1WTA+TydxLg==","_npmVersion":"12.2.0","description":"Aetherya MCP server: test decisions on a synthetic audience from any MCP agent. Run research studies, site audits, copy tests, instant market reads and post or email simulations, then get a decision brief. Simulated, not real-user data.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.4_1792403711030_0.22133043635447724","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"_id":"@aetherya/mcp@1.0.5","bin":{"aetherya-mcp":"dist/index.js"},"dist":{"shasum":"9b292e9b45f03eac5887f0ce0cfbbb27b2cfb3ad","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-1.0.5.tgz","integrity":"sha512-uGE1iFoLJJ4vTWyYNRLGSzvEvmShOgQrWW3wAiO9+1nm7FPhA9ohbc/Qyma6+0Z6+KG0mxBOgWqzz4fweJgtGA==","fileCount":136,"unpackedSize":858631,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDawni8cquE58aGyz111TkCTa7oipLZoW5u/4hR7bG5XAIhAOPzn/OSuYZcKGh5qR+W3UCXrkUzvi5IWw83SsmRxXOG"}]},"main":"./dist/index.js","name":"@aetherya/mcp","type":"module","_from":"file:/home/andrew/dev/Aetherya/aetherya-mcp/release/aetherya-mcp-1.0.5.tgz","types":"./dist/index.d.ts","engines":{"node":">=18"},"license":"MIT","mcpName":"ai.aetherya/mcp","scripts":{"dev":"tsx watch src/index.ts","test":"node --import tsx --test test/*.test.ts","build":"tsc","start":"node dist/index.js","test:e2e":"npm run build && node test/e2e-stdio.mjs","typecheck":"tsc --noEmit","start:http":"node dist/http.js","test:e2e:http":"npm run build && node test/e2e-http.mjs","prepublishOnly":"npm run build"},"version":"1.0.5","_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai","approver":{"name":"aetherya","email":"andrei@aetherya.ai"}},"homepage":"https://aetherya.ai","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit","market-research","copy-testing","ai-agents"],"_resolved":"/home/andrew/dev/Aetherya/aetherya-mcp/release/aetherya-mcp-1.0.5.tgz","_integrity":"sha512-uGE1iFoLJJ4vTWyYNRLGSzvEvmShOgQrWW3wAiO9+1nm7FPhA9ohbc/Qyma6+0Z6+KG0mxBOgWqzz4fweJgtGA==","_npmVersion":"12.2.0","description":"Aetherya MCP server: test decisions on a synthetic audience from any MCP agent. Run research studies, site audits, copy tests, instant market reads and post or email simulations, then get a decision brief. Simulated, not real-user data.","directories":{},"maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.8","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_1.0.5_1792413723134_0.9363856020083248"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-07T20:48:10.253Z","modified":"2026-10-19T12:42:05.929Z","0.1.0":"2026-07-07T20:48:10.803Z","1.0.0":"2026-09-30T09:38:46.899Z","1.0.1":"2026-09-30T09:46:51.429Z","1.0.3":"2026-10-19T09:15:52.460Z","1.0.4":"2026-10-19T09:55:11.135Z","1.0.5":"2026-10-19T12:42:03.200Z"},"license":"MIT","homepage":"https://aetherya.ai","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit","market-research","copy-testing","ai-agents"],"description":"Aetherya MCP server: test decisions on a synthetic audience from any MCP agent. Run research studies, site audits, copy tests, instant market reads and post or email simulations, then get a decision brief. Simulated, not real-user data.","maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"readme":"# Aetherya MCP server\n\nPoint any MCP-capable agent (Claude Code, Claude Desktop, Cursor, OpenAI Codex, VS Code with Copilot, Windsurf, Zed) at a decision and test it on a **synthetic audience** before you ship. Your agent can plan and run research studies (pricing, concepts, messaging, focus groups, interviews), audit a page or flow, compare copy variants, get an instant read against a market, simulate a social post or email, and turn any result into a short decision brief you can share.\n\nBuild → simulate → read the findings → fix → repeat, without leaving your editor.\n\n> **Everything Aetherya returns is a simulation of a synthetic audience — predicted behavior, not feedback from real users.**\n\n## 60‑second quickstart\n\n1. **Get an API key** from the Aetherya dashboard: [app.aetherya.ai](https://app.aetherya.ai) → Settings → API keys. It looks like `aeth_live_...`.\n2. **Add the server** to your agent (pick your client below) with `AETHERYA_API_KEY` set to that key.\n3. **Ask your agent**, e.g.:\n   > \"Audit https://example.com with Aetherya and suggest UX and messaging fixes.\"\n\n   Your agent calls `aetherya_audit_site`, gets back synthetic behavioral findings (inline, or via one poll for longer audits), and proposes concrete improvements.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `aetherya_plan_study` | **(Start here if you have a decision, not a study design)** Give it an objective in plain English and Aetherya designs the study, picks or builds the audience, prices it and runs it. Stops for approval before spending. |\n| `aetherya_confirm_study` | Approves the quoted cost (`accept_sessions`), answers a clarifying question, cancels, or retries a plan. The only place an agent authorizes spend. |\n| `aetherya_list_capabilities` | **(Start here if you already know the method)** Lists the research methods this workspace can run, the exact stimulus fields each one needs, and the plan headroom left. Registry-driven, so it stays accurate as methods are added. |\n| `aetherya_estimate` | Quotes the simulation-session cost of a run before you commit to it. Free — runs nothing, charges nothing. |\n| `aetherya_run_study` | Runs a Research Lab study — pricing sensitivity, concept test, message test, focus group, 1:1 interviews, open decision — and returns a verdict with segment breakdowns, objections and representative reactions. |\n| `aetherya_read` | Myrias instant read: 2–5 copy variants read against a census-weighted population for a market, in seconds. Predicted action propensity per variant, lift over the control, and which demographic archetypes favour each. Counts against the monthly read allowance. |\n| `aetherya_test_copy` | Compares 2–5 copy variants and ranks them on predicted action propensity, comprehension and trust, with the objections each raises. |\n| `aetherya_audit_site` | Runs a behavioral simulation of a URL: predicted friction, hesitation, drop-off and messaging-clarity issues with fixes. Ideal right after building or changing a page. Pass `tasks` and `start_url` for a flow test (sign-up, onboarding, checkout): simulated visitors walk the flow and report where they stall and how each step felt. Pass `credentials` (a dedicated test account) for pages behind a login. |\n| `aetherya_ask_audience` | Poses an open-ended question to a synthetic audience (\"would this confuse people?\") and returns a predicted, in-character response. |\n| `aetherya_simulate_post` | Runs an X, LinkedIn, Instagram or Facebook post (or an email) through a synthetic audience before it goes out: predicted engagement, sentiment and representative reactions. |\n| `aetherya_list_runs` | Lists recent runs across studies, reads, plans, audits and post simulations, newest first, with the `{kind, id}` to collect each. |\n| `aetherya_cancel` | Stops a study, read, plan, audit or post simulation that is still running. |\n| `aetherya_get_result` | Fetches the findings of any run by `{kind, id}` — study, read, audit, plan or post simulation. Simulations outlive a single tool call, so this is the normal way to collect results. |\n| `aetherya_get_audit_result` | Fetches an audit's findings by `job_id`, optionally with `include: [\"journeys\", \"heatmap\"]` for step-by-step detail. |\n| `aetherya_get_brief` | **(The deliverable)** Turns a finished study, read, audit or post simulation into a plain-language decision brief: the question, a direct answer, the reasoning with supporting reactions, the risks, and what to do next. Cached, so re-reading is free. |\n| `aetherya_share_result` | Mints a public link to a finished study, audit or creative comparison so someone without an Aetherya account can read the findings. Expires in 30 days by default; optional password. |\n| `aetherya_compare_creatives` | Compares 2+ image creatives (thumbnails, banners) end to end: creates the Ad Lab experiment, uploads the images (data URL or http(s) URL, png/jpeg/webp, 8 MB max), attaches an audience group or persona ids, drafts the comparison (free) and quotes the sessions. Runs only when called again with `accept_sessions` covering the quote. Collect with `aetherya_get_result` kind `creative_comparison`. |\n| `aetherya_pretest_video` | Pretests a video (mp4/mov/webm, 512 MB max, 10 min) end to end: uploads from `video_path` or `video_url`, splits it into scenes, then quotes the sessions (personas x 5 + scenes x 0.5, min 10) and runs only when called again with `accept_sessions` covering the quote. Preparing charges 0.25 to 6 sessions of speech-to-text unless you pass `transcript_srt`. Set `AETHERYA_MCP_ALLOW_LOCAL_FILES=0` to disable `video_path` (required if the server is ever hosted remotely). Collect with `aetherya_get_result` kind `video_analysis`. |\n| `aetherya_pretest_report` | Builds a deterministic markdown pretest report (RO or EN) from finished creative comparisons, video analyses and research runs, with claim-lint warnings. Fix recommendations are analyst placeholders unless `generateFixes` is set and enabled on the account (the response reports `fixesEnabled`). The branded PDF is downloaded from the app at `/dashboard/ad-lab/pretest`. |\n| `aetherya_seal_prediction` | Locks a prediction with a SHA-256 hash and timestamp before the real outcome is known. |\n| `aetherya_verify_prediction` | Recomputes a sealed prediction's hash and reports whether it still matches. |\n| `aetherya_record_outcome` | Attaches the real outcome to a sealed prediction (append-only) and returns the evaluation. |\n| `aetherya_create_intake_link` | Creates a secret client upload link (`label`, `expires_in_days` 1-30, `max_files`, `max_total_mb`) and returns its url and expiry. Off unless the workspace has the feature enabled. |\n| `aetherya_list_intake_files` | Lists the files a client uploaded through an intake link. |\n| `aetherya_list_audiences` | Lists your synthetic audiences (simulated personas) so you can target a relevant one. |\n| `aetherya_create_audience` | Generates new synthetic personas from a description (e.g. \"first-time SaaS buyers in Germany\"). |\n\n### Two ways in\n\n**Composed** — you have a decision, not a study design:\n`plan_study` → (approve the price) `confirm_study` → `get_brief` → `share_result`\n\n**Explicit** — you already know the method and its inputs:\n`list_capabilities` → `estimate` → `run_study` / `test_copy` / `audit_site` → `get_result` → `get_brief` → `share_result`\n\nA run over a real sample normally outlives the inline poll window, so a run returning `status: \"running\"` plus an id is the expected path, not an error. Pass `max_wait_seconds` to hand off sooner. Every metered tool reports the simulation sessions it consumed.\n\nThree results are states rather than failures, each naming its own next call: `needs_price_confirmation` (re-send accepting the quoted sessions), `needs_audience` (create an audience first), and `needs_clarification` (answer the question asked).\n\n### Prompts and resources\n\nThree canned workflows are exposed as MCP prompts — `validate_a_launch`, `test_messaging`, `audit_a_funnel` — each ending at the decision brief. Finished runs are also addressable as resources (`aetherya://run/{id}`, `aetherya://run/{id}/brief`, `aetherya://audit/{id}`); the resource list covers what the current session produced, not the whole workspace.\n\nAll tool outputs are **synthetic-audience simulations** (predicted behavior), never real-user data.\n\n## Install\n\nEvery client reduces to the same command — `npx -y @aetherya/mcp` — plus the `AETHERYA_API_KEY` environment variable. Replace `aeth_live_xxx` with your key.\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add aetherya --env AETHERYA_API_KEY=aeth_live_xxx -- npx -y @aetherya/mcp\n```\n\nAdd `--scope user` to make it available across all your projects, or `--scope project` to share it with your team via a checked-in `.mcp.json`. Restart Claude Code, then ask it to audit a URL.\n\n### Claude Desktop / Cursor / Windsurf (and most `mcpServers` clients)\n\nAdd this to the client's MCP config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"aetherya\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aetherya/mcp\"],\n      \"env\": { \"AETHERYA_API_KEY\": \"aeth_live_xxx\" }\n    }\n  }\n}\n```\n\nConfig file locations:\n\n- **Claude Desktop** — `claude_desktop_config.json`\n  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n  - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project)\n- **Windsurf** — `~/.codeium/windsurf/mcp_config.json`\n\nRestart the app after editing.\n\n### VS Code (GitHub Copilot)\n\nVS Code uses the key **`servers`** (not `mcpServers`). Put this in `.vscode/mcp.json` (workspace) or your user MCP config (run **MCP: Open User Configuration** from the Command Palette):\n\n```json\n{\n  \"servers\": {\n    \"aetherya\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aetherya/mcp\"],\n      \"env\": { \"AETHERYA_API_KEY\": \"aeth_live_xxx\" }\n    }\n  }\n}\n```\n\n### OpenAI Codex (CLI)\n\nEither run:\n\n```bash\ncodex mcp add aetherya --env AETHERYA_API_KEY=aeth_live_xxx -- npx -y @aetherya/mcp\n```\n\n…or add this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.aetherya]\ncommand = \"npx\"\nargs = [\"-y\", \"@aetherya/mcp\"]\n\n[mcp_servers.aetherya.env]\nAETHERYA_API_KEY = \"aeth_live_xxx\"\n```\n\n> Client config formats drift — if a snippet doesn't load, check your client's current MCP docs. The shape is always: command `npx`, args `[\"-y\", \"@aetherya/mcp\"]`, and `AETHERYA_API_KEY` in the environment.\n\n### auth.md onboarding (not yet enabled)\n\nThe package also ships an `auth` command for key-less onboarding through a browser claim page:\n\n```bash\nnpx -y @aetherya/mcp auth --email you@example.com\n```\n\nThe hosted Aetherya API does not advertise auth.md onboarding yet, so this command currently fails with an HTTP 404. Use an API key for now. When it is enabled, the command saves a service-signed assertion locally with mode `0600` (override with `--credential-file` or `AETHERYA_MCP_CREDENTIALS_FILE`), and an explicit `AETHERYA_API_KEY` still takes precedence over it.\n\n## Configuration\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `AETHERYA_API_KEY` | **yes** | — | Your API key (`aeth_live_...`), from Settings → API keys. Never logged. |\n| `AETHERYA_IDENTITY_ASSERTION` | no | — | Optional auth.md assertion override. Normally use the local credential file created by `aetherya-mcp auth`. |\n| `AETHERYA_MCP_CREDENTIALS_FILE` | no | `$XDG_CONFIG_HOME/aetherya/credentials.json` | Override the local assertion file. Files are written with mode `0600`. |\n| `AETHERYA_API_BASE_URL` | no | `https://api.aetherya.ai` | Override the API root. Only needed for a self-hosted or local backend (e.g. `http://localhost:8080`). |\n| `AETHERYA_APP_BASE_URL` | no | `https://app.aetherya.ai` | Dashboard origin. Used only to turn a share token into a link a human can open; never used for API calls. |\n\nUsage is metered per **simulation session** against your Aetherya plan (not per seat). If you hit your plan's limit, tools return a clean \"you've reached your plan's simulation limit\" message.\n\n## How audits work (async)\n\nAudits are real behavioral simulations and can take a while. `aetherya_audit_site` starts the job and polls inline for up to ~45 seconds (deliberately under the typical MCP client request timeout):\n\n- finishes in time → you get the full structured findings inline;\n- still running → you get a `job_id`; call `aetherya_get_audit_result` with it to fetch the findings when ready.\n\nMost real audits take longer than the inline window, so the usual flow is: `aetherya_audit_site` returns a `job_id`, then one `aetherya_get_audit_result` call fetches the findings.\n\n### Flow tests\n\nTo learn how people experience a flow rather than get a page score, pass `tasks` (up to 5, each with a `title`, optional `instructions` and `expected_outcome`) and `start_url` (where the flow begins, on the same site as `url`). Optional `objective` carries your question in your own words, and `scope` limits where visitors may go. The audit then runs as `ux_journey`: each simulated visitor walks the flow step by step instead of touring the site.\n\n- The visitors are simulated, not real users.\n- By default they **stop before the final submit**, so no account is created and no order is placed.\n- `allow_test_signups: true` lets them submit a sign-up with a synthetic test identity. Use it only with the site owner's explicit permission.\n- Payment is never submitted, whatever the setting.\n\n### Pages behind a login\n\nPass `credentials` to audit pages that need a sign-in:\n\n```json\n\"credentials\": {\n  \"mode\": \"form\",\n  \"login_url\": \"https://example.com/login\",\n  \"username\": \"qa+aetherya@example.com\",\n  \"password\": \"…\",\n  \"persona_login\": \"prelogin\",\n  \"allowed_hosts\": [\"auth.example.com\"]\n}\n```\n\n- **Use a dedicated test account.** Never a real customer or admin account.\n- `mode` is `form` (a login page, needs `login_url`) or `basic` (HTTP basic auth).\n- `persona_login`: `prelogin` (default) signs in once and every visitor starts logged in; `persona` has each visitor log in itself, which tests the login page too.\n- `allowed_hosts` (up to 5) lists the hosts a single sign-on login passes through.\n- The credentials are sent once, stored encrypted for that run only, and deleted when it ends. They never reach a model prompt or the report.\n- Credentialed audits are switched on per deployment. Where they are off, the call fails with \"credentialed audits are not enabled\".\n- Only `aetherya_audit_site` takes credentials. `aetherya_plan_study` does not, because its objective goes through language-model planning.\n\n`aetherya_plan_study` sends `market` and `language` to the API as structured fields next to your objective, which is passed through as written.\n\n## Install from source (development / contributing)\n\nThis section is for contributors working on the server itself, not for normal use — if you just want to use the tools, use [Install](#install) above (`npx -y @aetherya/mcp`).\n\nTo build and run a local checkout instead of the published package:\n\n```bash\ngit clone <this repo>          # clones the full Aetherya repo (e.g. into ./Aetherya)\ncd <cloned-dir>/aetherya-mcp  # aetherya-mcp is a subdirectory of the repo\nnpm install\nnpm run build                  # compiles TypeScript to dist/\n```\n\nThen point your MCP client at the built file instead of `npx -y @aetherya/mcp`:\n\n**Claude Code:**\n```bash\nclaude mcp add aetherya \\\n  --env AETHERYA_API_KEY=aeth_live_xxx \\\n  --env AETHERYA_API_BASE_URL=http://localhost:8080 \\\n  -- node /path/to/aetherya-mcp/dist/index.js\n```\n\n**Claude Desktop / Cursor / Windsurf:**\n```json\n{\n  \"mcpServers\": {\n    \"aetherya\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/aetherya-mcp/dist/index.js\"],\n      \"env\": {\n        \"AETHERYA_API_KEY\": \"aeth_live_xxx\",\n        \"AETHERYA_API_BASE_URL\": \"http://localhost:8080\"\n      }\n    }\n  }\n}\n```\n\nReplace `/path/to/aetherya-mcp` with the absolute path of your clone and `http://localhost:8080` with your API root.\n\n## Local development\n\n```bash\ngit clone <this repo>          # clones the full Aetherya repo (e.g. into ./Aetherya)\ncd <cloned-dir>/aetherya-mcp  # aetherya-mcp is a subdirectory of the repo\nnpm install\nAETHERYA_API_KEY=aeth_live_xxx npm run dev    # run against the live API\nnpm run build                                  # compile to dist/\nnpm test                                       # unit + tools smoke tests\n```\n\n## Roadmap (not in this MVP)\n\n- **Streamable HTTP transport** for a hosted, remote server (the tool logic is already transport-agnostic).\n- **OAuth 2.1** for that hosted server.\n- The MCP **Tasks primitive** for long-running audits, once client support is broad.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}