@wevo-ai/pulse-mcp 0.0.0-stage → 0.1.0-test.0

package/README.md

@@ -1,3 +1,458 @@
-# Temporary Holding Version
+# Local Pulse public API MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local stdio MCP server → WEVO Pulse public API (`/api/public/v1`), **prod**
+by default (`https://platform.wevo.ai`); WEVO developers opt into dev or
+staging explicitly (see [Environments](#environments)). Claude Code, Claude Desktop,
+Cursor, and VS Code launch it as a child process. No local Pulse backend,
+Docker, or deployment is required; the only listener is the short-lived
+`127.0.0.1` callback used while you sign in.
+
+## Prior design documents
+
+- [MCP Auth, Credits & Distribution Plan (Oct 8 draft)](https://app.notion.com/p/3f3bf908bd6881ea8f19fc34d3f0010f)
+- [Pulse Public API MVP spec](https://app.notion.com/p/3edbf908bd68819bb7afe2ee9a66a333)
+- [WEV-4086: private MCP server](https://linear.app/wevo/issue/WEV-4086)
+
+This implements the plan's **local development** option: public v1 tools
+acting as one signed-in user. Sign-in runs Authorization Code + PKCE in your
+browser, started by the server itself on the first tool call (or by the
+`login` CLI command), and stores a refreshable token; the server refreshes it
+without re-approval. The older ticket proposes Device Code, but WEVO's Auth0 tenant
+does not offer Device Code to third-party (developer portal) apps.
+
+## Install and sign in
+
+Requires **Node.js 22 or newer** on `PATH`. The package `@wevo-ai/pulse-mcp`
+is one bundled file with no runtime dependencies; its command is
+`wevo-pulse-public-mcp`. MCP clients launch it with `npx`. No clone, build,
+or CodeArtifact access is needed.
+
+> **Restricted package.** `@wevo-ai/pulse-mcp` is planned as a **restricted**
+> (private) npm package for now; see [Package and publish](#package-and-publish).
+> `npx -y @wevo-ai/pulse-mcp` then works only for npm users who belong to the
+> `@wevo-ai` npm organization, sit on a team with read access to the package,
+> and are authenticated to `registry.npmjs.org` (`npm login`, or an `.npmrc`
+> line `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`). Everyone else gets a 404. **Customers should use the [Claude Desktop bundle](#connect-clients)
+> (`wevo-pulse.mcpb`)**: it is self-contained and needs no npm account.
+>
+> **Not published yet.** Until it is, run `npm pack` in this package and
+> replace `-y @wevo-ai/pulse-mcp` below with
+> `-y --package /ABS/PATH/TO/wevo-ai-pulse-mcp-0.1.0.tgz wevo-pulse-public-mcp`.
+
+### Environments
+
+With no `WEVO_PULSE_BASE_URL`, the server and `login` use **prod**. Each
+environment has its own Auth0 tenant; `login` picks the matching defaults:
+
+| Environment    | `WEVO_PULSE_BASE_URL`            | Auth0 domain           | Audience      |
+| -------------- | -------------------------------- | ---------------------- | ------------- |
+| prod (default) | `https://platform.wevo.ai`       | `auth.wevo.ai`         | `persona-api` |
+| staging        | `https://platform-stage.wevo.ai` | `auth-staging.wevo.ai` | `persona-api` |
+| dev            | `https://platform-dev.wevo.ai`   | `auth-dev.wevo.ai`     | `persona-api` |
+
+WEVO developers set `WEVO_PULSE_BASE_URL=https://platform-dev.wevo.ai` (or
+the staging origin) themselves, in `mcp.env` or the client's `env`. Logins are
+stored per origin, so switching environments needs one `login` per origin.
+
+> **Prod launch pending.** `https://platform.wevo.ai` serves
+> `/api/public/v1` only after the prod public API host launches (WEV-4085);
+> until then prod calls fail there. `https://personas-api.wevo.ai` reaches the
+> same prod API and uses the same prod Auth0 defaults in the meantime.
+
+### Sign in
+
+1. **Client ID.** **Dev** (`https://platform-dev.wevo.ai`) and **staging**
+   (`https://platform-stage.wevo.ai`) have WEVO's own MCP login client built
+   in: skip to step 3 (WEVO developers only need `WEVO_PULSE_BASE_URL` from
+   step 2). Prod has no default login client yet, so `login` there needs
+   `WEVO_PULSE_CLIENT_ID`. Open the developer portal (`<origin>/developer`)
+   and create a **Public** app in your own organization (an app registered in
+   another organization returns `403 api_client_org_mismatch`; Public apps
+   created before October 7, 2026 have no refresh tokens, so create a new
+   one). Callback URL, exactly: `http://127.0.0.1:47615/callback`. Select the
+   scopes below. Setting `WEVO_PULSE_CLIENT_ID` on dev or staging overrides
+   the built-in client.
+2. Save settings in the per-user config file, which every run loads
+   automatically:
+
+   ```bash
+   mkdir -p ~/.config/wevo-pulse-mcp
+   (umask 077 && cat > ~/.config/wevo-pulse-mcp/mcp.env <<'EOF'
+   # Prod only, until WEVO's own login client ships there:
+   # WEVO_PULSE_CLIENT_ID=your_public_app_client_id
+   # WEVO developers only (default is prod):
+   # WEVO_PULSE_BASE_URL=https://platform-dev.wevo.ai
+   EOF
+   )
+   ```
+
+3. Sign in. **No terminal needed:** in your MCP client, call any WEVO tool or
+   just say "log in to WEVO". When nobody is signed in, the server opens your
+   browser at WEVO sign-in and the tool returns `login_started` at once with
+   the sign-in link (`authorize_url`) as a fallback; it does not wait for you.
+   Sign in, then retry the request: the next call uses the new login. A
+   sign-in stays open for 5 minutes; a later call after that starts a fresh
+   one. Clients that support MCP URL elicitation are asked to show the
+   sign-in page themselves instead of the server opening a browser.
+
+   From a terminal instead (or on a machine without a desktop browser):
+
+   ```bash
+   npx -y @wevo-ai/pulse-mcp login
+   ```
+
+   On your **first** login a one-time **consent screen** lists the requested
+   scopes: approve it. Auth0 always asks once for an app with a loopback
+   (`127.0.0.1`) callback; silent refreshes never prompt, and later logins ask
+   again only if the requested scopes change. `--no-browser` (or
+   `WEVO_PULSE_NO_BROWSER=1`, which also applies to server-started sign-in)
+   prints the URL instead of opening a browser. The command confirms the
+   signed-in user, org, app, and scopes. `npx -y @wevo-ai/pulse-mcp status`
+   shows the API origin and active credential later; `logout` revokes and
+   deletes it; `help` lists commands and settings. The MCP tools `login`,
+   `auth_status`, and `logout` do the same from inside a client.
+
+For all tools: `pulse:read pulse:write personas:read personas:write
+personas:outputs:read assets:read assets:write`. Read-only use needs only the
+corresponding read scopes. The API still checks user permissions, app grants,
+org membership, resource ownership/sharing, and credits. Call `whoami` first
+and confirm user, org, app, scopes, and expiry.
+
+### Stored login
+
+The token is stored per user at `~/.config/wevo-pulse-mcp/credentials.json`
+(`$XDG_CONFIG_HOME/wevo-pulse-mcp`, or `%APPDATA%\wevo-pulse-mcp` on Windows;
+`WEVO_PULSE_CONFIG_DIR` overrides), owner-only `0600`, keyed by API origin.
+Every client on the machine shares it, and running servers pick it up on their
+next call; no restart is needed. They refresh the access token shortly before
+expiry and once after a `401`, persisting Auth0's rotated refresh token
+atomically under a lock file so several MCP clients can share one login. When
+the refresh token expires or is revoked, the next tool call starts browser
+sign-in again (`login_started`). Tokens are never printed or logged.
+
+Sign-in uses the fixed callback port `47615`. One sign-in runs per server
+process; while it is open, further calls reuse it and return the same link.
+If another process (a second MCP client or a terminal `login`) holds the port
+mid-sign-in, tools return `login_port_busy`: finish that sign-in and retry.
+On prod without a client ID (see step 1) they return `login_unavailable`,
+naming `WEVO_PULSE_CLIENT_ID`. Stopping the server
+cancels its open sign-in.
+
+### Configuration files
+
+Settings come from process variables plus at most one env file, chosen in
+this order:
+
+1. `WEVO_PULSE_ENV_FILE`, if set. Use an absolute path; a missing file fails
+   startup.
+2. The package-root `.env` (monorepo checkouts only; installed packages have
+   none).
+3. `mcp.env` in the config directory above (`~/.config/wevo-pulse-mcp/mcp.env`
+   by default).
+
+Missing implicit files are ignored. Process variables win over file values.
+`WEVO_PULSE_BASE_URL` is an **origin only**, without `/api` or
+`/api/public/v1`, and defaults to prod (`https://platform.wevo.ai`); HTTPS is required except for loopback
+test APIs. Timeout (`WEVO_PULSE_TIMEOUT_MS`): 1–300000 ms. See
+[`.env.example`](.env.example) for every setting.
+
+Login options: `WEVO_PULSE_CALLBACK_PORT` (must match a registered callback),
+`WEVO_PULSE_CLIENT_ID` (built in for dev and staging; required on prod until
+WEVO's own login client ships there),
+`WEVO_PULSE_AUTH0_DOMAIN` / `WEVO_PULSE_AUTH0_AUDIENCE` (required only for
+origins outside [Environments](#environments)),
+`WEVO_PULSE_AUTH0_ORGANIZATION` (users in several orgs), and
+`WEVO_PULSE_SCOPES` (subset of the app's scopes; `offline_access` is always
+added), and `WEVO_PULSE_NO_BROWSER=1` (return the sign-in link without opening
+a browser).
+
+### Fixed token override (CI/tests)
+
+`WEVO_PULSE_TOKEN` (process env or env file) overrides the stored login and is
+never refreshed; while it is set the server never starts browser sign-in. Use a user-delegated **access token**, without `Bearer `, from
+a developer portal app (for example via the
+[API docs test client](https://github.com/wevo-conversion/pulse-api-docs-test-client)).
+Do not use an ID token, client secret, or client-credentials/M2M token. A
+normal Pulse web-app token is insufficient unless its client is registered for
+public API use. Keep tokens out of client JSON, shell history, and commits.
+
+## Connect clients
+
+Clients need only the command: the server reads
+`~/.config/wevo-pulse-mcp/mcp.env` and the stored login itself, and starts
+browser sign-in on the first tool call when nobody is signed in. MCP reserves
+stdout for JSON-RPC; `npx -y` installs quietly, and the server logs only to
+stderr.
+
+**Claude Code** — register once:
+
+```bash
+claude mcp add --transport stdio --scope user \
+  wevo-pulse-public -- npx -y @wevo-ai/pulse-mcp
+```
+
+Run `/mcp`, then ask: “Use wevo-pulse-public to check my identity and list my
+Personas.”
+
+**Cursor** — merge into `~/.cursor/mcp.json` (user) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "wevo-pulse-public": {
+      "command": "npx",
+      "args": ["-y", "@wevo-ai/pulse-mcp"]
+    }
+  }
+}
+```
+
+Enable it in Cursor's MCP settings; refresh/restart after configuration changes.
+
+**Claude Desktop** — either:
+
+- **One-click bundle** (recommended for customers while the npm package is
+  restricted): open `wevo-pulse.mcpb` (Settings → Extensions → Install
+  Extension). The bundle embeds the server, so it needs no npm account,
+  registry access, Node install, or env file; Desktop runs it on its built-in
+  Node.js. It prompts for the API origin (prefilled with prod,
+  `https://platform.wevo.ai`) plus two optional fields. Leave the **access
+  token** empty, then ask Claude anything that uses WEVO (or "log in to
+  WEVO"): a browser window opens to sign in, and the next request works. No
+  terminal is needed. On prod, until WEVO's own login client ships there,
+  fill in the **client ID** field (`WEVO_PULSE_CLIENT_ID`, step 1 above);
+  dev and staging need none. The login lives in the same credentials file as a
+  terminal `login`, so both share it and its refresh. Pasting an access token instead stores it in the OS keychain and
+  disables browser sign-in; it is never refreshed, so replace it when it
+  expires. If you set `XDG_CONFIG_HOME` or `WEVO_PULSE_CONFIG_DIR` only in
+  your shell, Desktop will not see a terminal login. Build the bundle with `npm run mcpb`
+  (output: `dist/wevo-pulse.mcpb`) and share the file directly.
+- **JSON config**: the Cursor `mcpServers` JSON in
+  `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS
+  (Settings → Developer → Edit Config), then restart Claude Desktop.
+
+Neither makes the server reachable from the claude.ai website.
+
+**VS Code / GitHub Copilot** — `.vscode/mcp.json` uses `servers`:
+
+```json
+{
+  "servers": {
+    "wevo-pulse-public": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@wevo-ai/pulse-mcp"]
+    }
+  }
+}
+```
+
+Other stdio clients use the same command and arguments. To keep settings
+elsewhere, add `"env": { "WEVO_PULSE_ENV_FILE": "/Users/YOU/path/mcp.env" }`
+(JSON configs do not expand `~`). GUI apps may not inherit a shell-managed
+`PATH` (nvm, fnm, Volta): if the client cannot find `npx`, use its absolute
+path from `which npx`. On Windows clients that cannot launch `npx` directly,
+use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@wevo-ai/pulse-mcp"]`.
+
+### From a monorepo checkout (WEVO developers)
+
+From the `wevo-pulse` repository root, using Node 25 from `.nvmrc`:
+
+```bash
+make install-api-client install-mcp
+make build-api-client build-mcp
+cp -n packages/wevo-pulse-mcp/.env.example packages/wevo-pulse-mcp/.env
+chmod 600 packages/wevo-pulse-mcp/.env   # then set WEVO_PULSE_BASE_URL (dev and staging need no WEVO_PULSE_CLIENT_ID)
+./scripts/with-node.sh node packages/wevo-pulse-mcp/dist/public-index.js login
+claude mcp add --transport stdio --scope user wevo-pulse-public -- \
+  /ABS/PATH/TO/wevo-pulse/scripts/with-node.sh node \
+  /ABS/PATH/TO/wevo-pulse/packages/wevo-pulse-mcp/dist/public-index.js
+```
+
+The gitignored package `.env` loads automatically, regardless of the client's
+working directory, and takes the place of `mcp.env`. Login uses the same
+per-user credentials file as the npm package. Other clients use
+`/ABS/PATH/TO/wevo-pulse/scripts/with-node.sh` as `command` and
+`["node", "/ABS/PATH/TO/wevo-pulse/packages/wevo-pulse-mcp/dist/public-index.js"]`
+as `args`. The wrapper selects Node 25 without writing to stdout.
+
+## Run and develop
+
+No shared daemon needs starting first: each MCP client starts its own process.
+To run manually from the repository root:
+
+```bash
+./scripts/with-node.sh node packages/wevo-pulse-mcp/dist/public-index.js
+```
+
+A quiet process waiting on stdin is expected. Ctrl-C stops it. For interactive
+protocol inspection after signing in:
+
+```bash
+./scripts/with-node.sh npx @modelcontextprotocol/inspector \
+  ./scripts/with-node.sh node packages/wevo-pulse-mcp/dist/public-index.js
+```
+
+For source iteration, run `npm run dev:public` inside this package. Reconnect
+after watch-process restarts. Compiled clients need `make build-mcp` followed
+by restart/reconnect. `npm start` also runs the compiled public server.
+
+```bash
+make test-mcp typecheck-mcp lint-mcp
+make code-quality
+```
+
+Tests cover MCP discovery/calls, all route mappings and request schemas,
+configuration validation, auth/error propagation, 204 deletes, idempotency,
+timeouts, redirects, and a real stdio child process against a loopback fixture
+API. Login tests cover PKCE, callback state handling, credential file
+permissions/locking, refresh-token rotation, single 401 retry, env-token
+precedence, and in-server sign-in (auto-start, reuse, success, timeout,
+busy port, URL elicitation, logout, and a stdio child whose stdout carries only
+JSON-RPC) against a loopback fake Auth0; they never contact real Auth0. Tests
+never launch real billable Pulses.
+
+## Package and publish
+
+`npm run build` uses esbuild to bundle `src/public-index.ts` and the legacy
+`src/index.ts` into self-contained ESM files in `dist/` (local sourcemaps),
+plus `dist/THIRD_PARTY_NOTICES.txt` for the inlined dependencies. Runtime
+libraries, including `@wevo/pulse-api-client`, are `devDependencies` on
+purpose: they are inlined, so the published package installs nothing else. Add
+new runtime libraries the same way.
+
+`npm pack` builds first, then ships only the `wevo-pulse-public-mcp` bin,
+notices, README, and `package.json` (about 150 kB). The legacy
+`wevo-pulse-mcp` server targets internal Persona/Audience APIs, so it stays
+monorepo-only (`node dist/index.js`). `npm run mcpb` writes
+`dist/wevo-pulse.mcpb` for Claude Desktop with a pinned `@anthropic-ai/mcpb`.
+
+The package publishes as `@wevo-ai/pulse-mcp` in WEVO's `@wevo-ai` npm org,
+with **restricted** access for now (public later).
+The `@wevo` scope on public npm belongs to an unrelated owner: never publish
+or document install commands under it. Internal packages such as
+`@wevo/pulse-api-client` stay on private CodeArtifact and are only inlined
+into the bundle.
+
+Publishing is gated by `"private": true`. `publishConfig` pins
+`registry.npmjs.org` with `"access": "restricted"`, so a CodeArtifact login
+that rewrites the default registry cannot capture the publish and the first
+publish cannot go public by accident.
+
+Restricted access means (per npm docs:
+[private packages](https://docs.npmjs.com/about-private-packages),
+[paid organization plan](https://docs.npmjs.com/upgrading-to-a-paid-organization-plan),
+[visibility](https://docs.npmjs.com/package-scope-access-level-and-visibility),
+[CI auth](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow)):
+
+- The `@wevo-ai` org must be on the paid **npm Teams** plan, billed per org
+  member (every member, not just publishers).
+- Only org members on a team granted read access can view or install it.
+  Each installer needs their own npm account in the org and must authenticate
+  to `registry.npmjs.org` (`npm login`, or a read-only granular token via
+  `.npmrc`). Anonymous `npx` gets a 404.
+- The [MCP Registry](https://modelcontextprotocol.io/registry/package-types)
+  lists npm servers only from the public npm registry and verifies `mcpName`
+  from the published `package.json`, so no MCP Registry listing is possible
+  while restricted.
+- Customers outside the org use the `.mcpb` bundle, which embeds the server.
+
+To publish:
+
+1. Confirm the `@wevo-ai` org is on npm Teams, then remove `"private": true`.
+2. Publish from CI, not a laptop: a `workflow_dispatch` job modeled on
+   `.github/workflows/api-client.yml` (Node from `.nvmrc`,
+   `make install-api-client install-mcp test-mcp`, `npm version`,
+   `npm publish` with `id-token: write`, using npm trusted publishing
+   configured for `@wevo-ai/pulse-mcp`). Do not pass `--provenance`: npm
+   generates [provenance](https://docs.npmjs.com/trusted-publishers) only for
+   public packages published from public repositories, and both are private
+   here. Attach `dist/wevo-pulse.mcpb` to the GitHub release.
+3. Going public later: set `publishConfig.access` to `"public"` (or
+   `npm access set status=public @wevo-ai/pulse-mcp`), then add `mcpName` and
+   a `server.json` for an MCP Registry listing.
+
+The server version reported at MCP `initialize` comes from `package.json`:
+`scripts/build.mjs` injects it with esbuild `define` (unbundled `tsx` runs
+report `0.0.0-dev`).
+
+## Tools and workflow
+
+Routes below are relative to `/api/public/v1`.
+
+| Tools                                                             | API                                                                             | Scope                                    |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- |
+| `login`, `auth_status`, `logout`                                  | Browser sign-in; local credential status; sign out (no `/api` call)             | None                                     |
+| `whoami`                                                          | `GET /me`                                                                       | Valid user token                         |
+| `list_personas`, `get_persona`                                    | `GET /personas`, `GET /personas/{id}`                                           | `personas:read`                          |
+| `get_persona_research_profile`, `get_persona_personality_profile` | `GET /personas/{id}/research-profile`, `GET /personas/{id}/personality-profile` | `personas:outputs:read`                  |
+| `create_persona`, `update_persona`, `delete_persona`              | `POST /personas`, `PATCH/DELETE /personas/{id}`                                 | `personas:write`                         |
+| `generate_persona`, `get_persona_generation`                      | `POST /personas/generations`, `GET /personas/generations/{id}`                  | write / read                             |
+| `create_url_asset`, `list_assets`, `get_asset`, `delete_asset`    | `POST/GET /assets`, `GET/DELETE /assets/{id}`                                   | `assets:write` / `assets:read`           |
+| `list_pulses`, `get_pulse`, `get_pulse_results`                   | `GET /pulses`, `GET /pulses/{id}`, `GET /pulses/{id}/results`                   | `pulse:read`                             |
+| `launch_pulse`                                                    | `POST /pulses`                                                                  | `pulse:write` + Pulse product permission |
+| `launch_compare`, `get_compare`, `get_compare_results`            | `POST /compares`, `GET /compares/{id}`, `GET /compares/{id}/results`            | write + Compare permission / read        |
+
+`create_persona` (structured fields) and `generate_persona` (description) both
+return a full generation payload: `generation_id`, overall `status`, optional
+`persona_id`, and states for `core`, `research_profile`, `personality`,
+`demographics`, `image`, and `grounding`. Keep the generation ID. Poll
+`get_persona_generation` no more often than every **10 seconds**, narrating
+component progress to the user. Report completion only when every component is
+`completed` or `skipped`; if any component or overall generation is `failed`,
+name the component and stop. Read research/personality output only after their
+components finish.
+
+Flow: `whoami` → select/create and fully complete Persona → `create_url_asset`
+→ poll `get_asset` until `ready` → `launch_pulse` → poll `get_pulse` →
+`get_pulse_results` after `completed` or `partial`. Partial Pulses expose
+successful sections. Stop on failure. Compare 2–6 completed Pulses, then
+retrieve status/results. Tool callers should send an arguments object (`{}` for
+no filters).
+
+Generation, Pulse launch, and Compare launch require `idempotency_key`. Use a
+unique key per intended operation; retain it and identical inputs when retrying
+an uncertain response. API retention is 24 hours; failed Persona generations
+can restart with the same key under the API's documented semantics. The server
+never retries writes automatically. Asset/manual Persona creation lack public
+API idempotency: inspect existing resources before repeating uncertain creates.
+Writes can spend credits. Effect annotations do not replace client approval
+or API authorization.
+
+Errors set MCP `isError: true`. HTTP failures preserve `{status, body,
+retry_after}`; `body` is the public error envelope, including request ID.
+`401`: invalid/expired token; `login_started` (sign-in opened: finish it at
+`authorize_url`, then retry); `login_port_busy` or `login_unavailable` (see
+[Stored login](#stored-login)). `403`:
+scopes, app registration, membership, or permissions. `402`: insufficient credits. `429`: follow retry guidance when
+provided. Network errors report an unknown outcome without raw transport errors.
+
+## Boundaries and hosted migration
+
+`public-server.ts` owns tools and turns `login_required` into a background
+sign-in; `public-client.ts` owns HTTP transport and the 401 retry; `src/auth/`
+owns login, the per-process sign-in session (`session.ts`), the credential
+file, and refresh;
+`public-index.ts` dispatches CLI subcommands or connects stdio. Typed requests use
+`createPublicPulseClient` in `@wevo/pulse-api-client`, generated from
+`contracts/openapi-public-v1.json`. Regenerate with `make api-contract`; verify
+with `make api-contract-check`. The broad internal contract remains separate
+because it accepts launch fields absent from public v1.
+
+The planned hosted endpoint uses **Streamable HTTP**. Before exposing it,
+implement per-user OAuth authorization code + PKCE, resource metadata,
+audience validation, refresh/revocation, rate limits, and the agreed downstream
+authorization design. Never expose this single-user local credential setup
+through a shared network listener. Credit attribution and launch billing readiness remain
+prerequisites from the design plan. No Auth0, AWS, Terraform, or deployment
+changes are included here.
+
+Image upload and SSE-to-MCP progress are deferred. URL
+Assets, full tracked Persona generation, output reads, polling, and public
+results support the local end-to-end workflow.
+
+The existing `dist/index.js` and `npm run dev` remain available in the
+monorepo for internal Persona/Audience integrations; see
+[legacy setup](docs/internal-server.md). The published package omits them.
+Use **`dist/public-index.js`**, **`wevo-pulse-public-mcp`**, or **`npm start`** for
+this public API server. It registers no internal Audience/chat tools.