{"_id":"@aetherya/mcp","name":"@aetherya/mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aetherya/mcp","version":"0.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.","license":"MIT","type":"module","main":"./dist/index.js","bin":{"aetherya-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx watch src/index.ts","typecheck":"tsc --noEmit","test":"node --import tsx --test test/*.test.ts","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit"],"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.0","tsx":"^4.19.2","typescript":"^5.7.2"},"_id":"@aetherya/mcp@0.1.0","types":"./dist/index.d.ts","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-1HzIaaIpm2K7l+UJC6FhDB1poD716cYXPkPrcPP9fOAMnCXg/05dXDAvmrvUu9CzGWew1FSvbZaYjcO30b1GMw==","shasum":"24cae3ec09e305c220000d0a52c57d253ad15c65","tarball":"https://registry.npmjs.org/@aetherya/mcp/-/mcp-0.1.0.tgz","fileCount":43,"unpackedSize":152982,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC40Q3qE8GiAQMHhktcvSwT5uXH5wJTVeKB0JdbdXLw+gIgcI7U8FtyYxB7URv1CNay1qG/sMldIJ2qBiOdldiBWb4="}]},"_npmUser":{"name":"aetherya","email":"andrei@aetherya.ai"},"directories":{},"maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.0_1783457290660_0.512052959966123"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-07T20:48:10.253Z","0.1.0":"2026-07-07T20:48:10.803Z","modified":"2026-07-07T20:48:11.096Z"},"maintainers":[{"name":"aetherya","email":"andrei@aetherya.ai"}],"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.","keywords":["mcp","model-context-protocol","aetherya","synthetic-audience","behavioral-simulation","ux-audit"],"license":"MIT","readme":"# Aetherya MCP server\n\nPoint any MCP-capable coding agent — Claude Code, Claude Desktop, Cursor, OpenAI Codex, VS Code (Copilot), Windsurf, Zed — at a site or a copy variant and get **behavioral feedback from a synthetic audience**: where users would hesitate, get confused, or drop off, plus messaging-clarity and UX friction findings with concrete fixes. Build → simulate → get behavioral signal → 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.** In the [Aetherya dashboard](https://aetherya.ai) go to **Settings → API Keys → Create key** and copy it (it starts with `aeth_live_`). You only see it once.\n2. **Add the server** to your agent (pick your client below). The whole config is one command plus the `AETHERYA_API_KEY` env var.\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_audit_site` | **(Hero)** 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. |\n| `aetherya_get_audit_result` | Fetches an audit's findings by `job_id` (audits are async; poll this if the hero tool returns `running`). |\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\"), returned with ids to target in the tools above. |\n| `aetherya_test_copy` | *(Secondary)* Tests a headline / value-prop / copy variant against a synthetic audience for predicted clarity and response. |\n| `aetherya_ask_audience` | *(Secondary)* Poses an open-ended question to a synthetic audience (\"would this confuse people?\") and returns a predicted, in‑character response. |\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## Configuration\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `AETHERYA_API_KEY` | yes | — | Your Aetherya API key (`aeth_live_...`). Sent as a Bearer token; never logged. |\n| `AETHERYA_API_BASE_URL` | no | `https://api.aetherya.ai` | Override the API base URL. **Required for self-hosted or local backends** — the default host is the Aetherya cloud API. If the server warns that it cannot reach the default host at startup, set this variable to your API root (e.g. `http://localhost:8080`). |\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## 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","_rev":"1-8d42e53ffaa5e760ed8965cc0f59eeb5"}