@tday-com/mcp 0.3.1 → 0.4.2

package/README.md

@@ -1,94 +1,100 @@
 # @tday-com/mcp
 
-Official local MCP server and installer for [tday.com](https://tday.com). Connect Claude Code, Cursor, VS Code, Gemini CLI, Codex, and any MCP-compatible AI agent to your tday.com account so you can generate designs, make launch videos, manage brands, and query your workspace directly from chat.
+Record narrated product demos with your coding agent. This is [tday](https://tday.com)'s MCP server and CLI for Claude Code, Cursor, Codex, VS Code, Gemini CLI and any other MCP client.
+
+Ask your agent for a demo of a feature. It starts a separate demo copy of the app in your repo, on your machine, with throwaway data, and records one beat for each narrated line as it uses the app. It works with web apps, Electron apps and terminal tools. Before anything is uploaded it shows you a review page. Once you say yes, tday adds the voice, cursor, camera and style, and the demo arrives in tday ready to edit.
+
+**Only rendered UI and metadata leave your machine.** Source code, scripts, `.env` files and their values, cookies, local storage and network traffic never do. Every upload is scanned for secrets and for the values in your `.env` files first, and anything it finds blocks the upload until it is removed. Details: [What leaves your machine](https://docs.tday.com/capture-privacy).
 
 ## Install
 
+With a tday account, sign in once:
+
 ```bash
-npx -y @tday-com/mcp install
+curl -fsSL https://tday.com/install.sh | bash
+# or
+npx -y @tday-com/mcp@latest install
 ```
 
-Alternatives:
+The installer opens your browser, lets you sign in or sign up on tday.com, and asks you to authorize this machine. It then adds the `tday` server to Claude Code, Cursor, Gemini CLI and VS Code (stable and Insiders, user `mcp.json`). For Codex it prints a TOML block to paste; the Codex app reads the same file. There is no key to copy. The server works on the brand connected to your repo's git remote, and asks which one when you work on several.
+
+With a capture prompt from a teammate (no tday account needed), run the line it gives you:
 
 ```bash
-bunx @tday-com/mcp install
-pnpm dlx @tday-com/mcp install
-curl -fsSL https://tday.com/install.sh | bash
+TDAY_CAPTURE_TOKEN=<token from the prompt> npx --prefix ~ -y @tday-com/mcp@latest install
 ```
 
-The installer opens your browser, lets you sign in or sign up on tday.com, asks you to authorize this machine, then automatically configures supported agents. Claude Code, Cursor, Gemini CLI and VS Code (stable and Insiders, user `mcp.json`) get MCP config entries; Codex gets a TOML block to paste (the Codex app reads the same file). No manual key copying is needed.
+This adds `tday` to Claude Code at user scope (nothing is written into your repo) and installs the agent's skill. For other clients it prints the config to paste.
 
-One install sets up everything your account can use, with one sign-in:
+Then check everything:
 
-- `tday`: this server (your account, brands, designs, launch videos).
-- `tday-capture`: [`@tday-com/capture`](https://www.npmjs.com/package/@tday-com/capture), which captures real UI from the app running on your machine for tday. Added when your account can capture. It reads the same `~/.tday/config.json`, so it needs no token of its own.
+```bash
+npx -y @tday-com/mcp@latest doctor
+```
 
-Run `install` again whenever you want to update either, or after your account gains access to something new.
+It checks the browser, ffmpeg (used for demos), your sign-in and the connection to tday. It needs Node 18.17 or later, and Google Chrome or Playwright's Chromium.
 
-## Slash commands
+Earlier installs added a second server, `tday-capture`. Running `install` again replaces it with `tday`, which has the same tools.
 
-Claude Code users get:
+## What your agent gets
 
-- `/tday` - general tday.com assistant
-- `/tday-design` - generate a design
-- `/tday-brand` - create/list/view brands
-- `/tday-credits` - check your plan and credit balance
-- `/tday-ideas` - brainstorm brand-specific design ideas
-- `/tday-launch-video` - make a launch video of a feature: the one you name, or the newest one without a launch video (when your plan includes launch videos)
+One server, `tday`. Each time it starts it asks tday what your account can use, and lists only those tools.
 
-## MCP tools
+**Demos** (`demo_*`):
 
-- `tday_whoami` - current user, plan and credit balance
-- `tday_list_brands` / `tday_get_brand` - lightweight list summaries with API-backed `limit`/`offset`
-- `tday_create_brand` - create a brand from a website
-- `tday_list_designs` / `tday_get_design` - lightweight list summaries with API-backed `limit`/`offset`
-- `tday_generate_design` - prompt + brandId
-- `tday_poll_generation` - poll until completed/failed
-- `tday_download_image` - save a completed image locally
-- `tday_list_features` - a brand's features, newest first, with the launch videos each already has (`without: "launch_video"` lists the ones with none)
-- `tday_create_launch_video` - make a launch video of a feature (`featureId` from `tday_list_features`) or of a new subject (brandId, title, description)
-- `tday_poll_launch_video` / `tday_get_launch_video_mp4` / `tday_revise_launch_video` - follow a film until it is ready, get its MP4, or make a new cut from notes
+- `demo_features` / `demo_docs` - your features (newest first) and the docs pages that still need a demo.
+- `demo_guide` - how tday wants a demo made.
+- `demo_app_notes` - how your apps were started before. A note that is new on this machine, or changed since you approved it, is shown to you before your agent may use it.
+- `demo_check` - before recording, a read-only look at where the demo's data would live and what it could reach.
+- `demo_start`, then `demo_beat` for each narrated line.
+- `demo_review` - the review page. Your agent uploads with `demo_upload` only after you confirm with the code it shows you.
+- `demo_finish`.
+- `demo_embed_docs` - puts finished demos into the docs in your repo.
 
-Generating a design spends credits from your organisation's balance, at the same price as in the app, and a failed generation gives them back. When the balance cannot cover a request, tday answers with a 402 and spends nothing; `tday_whoami` shows the balance and when it refreshes.
+**Captures** (`capture_*`): real screens, components and flows of a feature, for its product screens in tday. They are reviewed and confirmed the same way before upload.
 
-Making a launch video spends credits the same way; `tday_get_credit_prices` lists every price.
+**Your account:** `tday_whoami`, `tday_list_brands`, `tday_get_brand`, `tday_create_brand`, `tday_get_credit_prices` and `tday_get_usage`.
 
-## MCP prompts
+**Where your plan includes them:** designs (`tday_generate_design`, `tday_poll_generation`, `tday_list_designs`, `tday_get_design`, `tday_download_image`) and launch videos (`tday_list_features`, `tday_create_launch_video`, `tday_poll_launch_video`, `tday_get_launch_video_mp4`, `tday_revise_launch_video`).
 
-Clients that list MCP prompts (Claude Code as `/mcp__tday__<name>`, VS Code as `/mcp.tday.<name>`) get:
+Anything that spends credits is charged to your organisation's balance at the same price as in the app. When the balance cannot cover a request, tday answers with a 402 and spends nothing. `tday_get_credit_prices` lists every price.
 
-- `launch-video` - a launch video of the feature you name, or of the newest feature without one, quoted before it starts
-- `features` - the newest features and which already have a launch video
+## Commands in your agent
 
-All tools return structured content for modern MCP clients. They also accept optional `response_format: "json" | "markdown"` for the text payload; JSON remains the default for backward compatibility.
+Clients that list MCP prompts show them as commands: Claude Code as `/mcp__tday__<name>`, VS Code as `/mcp.tday.<name>`.
 
-## One-shot CLI calls
+- `demo` - record a demo of the feature you name, or of the newest one without a demo.
+- `demos-needed` - the features and docs pages with no demo yet.
+- `docs-demos` - demos for your docs.
+- `docs-embeds` - put finished demos into your docs.
+- `latest-feature` - your newest feature.
+- `capture` - capture a feature's screens.
 
-Non-MCP integrations can call the same tool handlers directly:
+Where your plan includes launch videos, you also get `launch-video` and `features`.
 
-```bash
-npx -y @tday-com/mcp call tday_whoami '{}'
-npx -y @tday-com/mcp call tday_list_brands '{"limit":10,"response_format":"markdown"}'
-```
+The installer also writes Claude Code slash commands to `~/.claude/commands`:
 
-This is useful for smoke tests and scripted integrations.
+- `/tday-demo` and `/tday-demos-needed`.
+- `/tday-credits`.
+- `/tday-launch-video`, where your plan includes launch videos.
+- `/tday`, `/tday-design`, `/tday-brand` and `/tday-ideas`, where it includes designs.
 
-## Claude connector
+A command your account no longer has is removed the next time you run `install`.
 
-For Claude's remote connector/custom connector flow, use the hosted MCP endpoint:
+## CLI
 
 ```text
-https://tday.com/api/mcp
+tday install            Sign in and add tday to your coding agents
+tday serve              Run the MCP server over stdio (what your agent launches)
+tday doctor             Check the browser, ffmpeg, your sign-in and the connection
+tday skill              Print the agent's instructions, for agents without skills
+tday run <plan.json>    Run a list of demo or capture tool calls without an agent
+tday recapture --app <url> [--feature <id>] [--reset "<seed command>"]
+                        Capture saved screens and flows again after a UI change
+tday call <tool> [json] Call one account tool once and print JSON
 ```
 
-The hosted connector uses OAuth + PKCE with refresh-token rotation. Users sign in on tday.com, Claude receives a scoped bearer token, and the connection can be revoked from tday Settings - Integrations.
-
-## Security and privacy
-
-- **What a connection can do.** The token an MCP connection holds only reaches the routes the tools above use. It cannot delete or transfer a brand, manage members, or see payment details.
-- **Links expire.** A link made by `install` lasts 90 days; run `install` again to renew it. A hosted connector's access token lasts an hour and renews itself for as long as the connection is used; one left unused for 30 days disconnects.
-- **Disconnect** any connection from tday Settings - Integrations.
-- **No telemetry.** The server talks only to tday, and to tday's file storage when you ask it to download an image or video.
+Run any of them with `npx -y @tday-com/mcp@latest <command>`.
 
 ## Manual MCP config
 
@@ -97,28 +103,34 @@ The hosted connector uses OAuth + PKCE with refresh-token rotation. Users sign i
   "mcpServers": {
     "tday": {
       "command": "npx",
-      "args": ["-y", "@tday-com/mcp", "serve"]
+      "args": ["--prefix", "<your home directory>", "-y", "@tday-com/mcp@<version>", "serve"]
     }
   }
 }
 ```
 
-If you add this block yourself, run `npx -y @tday-com/mcp install` once afterward so the browser sign-in flow can link the server to your tday account automatically. `install` writes the entry pinned to its own version (`@tday-com/mcp@<version>`), so an agent never picks up a new release on its own; run `install` again to update. Pin the version in a block you write by hand too.
+`--prefix` keeps npx from reading the repo's `package.json`: the agent starts the server in your repo, and a repo whose `overrides` pin one of this package's dependencies would otherwise fail the start (`EOVERRIDE`). `install` writes this entry pinned to its own version, so your agent never picks up a new release on its own. Run `install` again to update. Pin the version in an entry you write by hand too. If you add the entry yourself, run `npx -y @tday-com/mcp@latest install` once afterwards, so the browser sign-in can link the server to your tday account.
+
+For Gemini CLI, put the same `mcpServers.tday` object in `~/.gemini/settings.json`. VS Code's user `mcp.json` keys entries by `servers` and names the transport: `{ "servers": { "tday": { "type": "stdio", "command": "npx", "args": ["--prefix", "<your home directory>", "-y", "@tday-com/mcp@<version>", "serve"] } } }`.
 
-For Gemini CLI, put the same `mcpServers.tday` object in `~/.gemini/settings.json`. VS Code's user `mcp.json` keys entries by `servers` and names the transport: `{ "servers": { "tday": { "type": "stdio", "command": "npx", "args": ["-y", "@tday-com/mcp", "serve"] } } }`.
+## Claude and ChatGPT connectors
 
-## Claude Code slash commands
+For Claude's or ChatGPT's custom connector, use the hosted endpoint. It has the account, design and launch-video tools, but no demo tools, since demos are recorded on your machine.
 
-The installer writes user-level Claude Code slash commands to `~/.claude/commands`. After restarting Claude Code, typing `/` shows `/tday`, `/tday-design`, `/tday-brand`, `/tday-credits`, `/tday-ideas` and, where your plan includes launch videos, `/tday-launch-video` in the slash-command autocomplete list. A command your account no longer has is removed the next time you run `install`.
+```text
+https://tday.com/api/mcp
+```
 
-## Security model
+The hosted connector uses OAuth with PKCE and rotating refresh tokens. You sign in on tday.com, your assistant gets a scoped bearer token, and you can revoke the connection from tday Settings - Integrations.
+
+## Security and privacy
 
-- Uses local stdio transport; the MCP server runs on your machine.
-- Browser authorization requires signing in or signing up on tday.com.
-- The installer uses a loopback callback bound to `127.0.0.1` plus a random `state` nonce.
-- The local connection is revocable from tday.com settings.
-- Local config is written to `~/.tday/config.json` with `0600` permissions.
-- File downloads are restricted to HTTPS image URLs on an allowlist, re-check redirect targets, cap size at 50MB, and write only inside the current working directory.
+- **You see what uploads.** Every upload is reviewed first: every file and string, with a secret scan that blocks it. A demo uploads once its review is clean, and the review page stays on your machine. A capture of your screens also waits for your yes: tday opens its review in your browser, and your agent's app asks you or you read it the confirmation code shown there.
+- **Your repo stays as it was.** Demos run in a separate demo instance, and anything the agent creates is deleted when it finishes.
+- **What a connection can do.** The token only reaches the routes these tools use. It cannot delete or transfer a brand, manage members, or see payment details.
+- **Links expire.** A link made by `install` lasts 90 days; run `install` again to renew it. A capture prompt's token lasts 7 days, a demo prompt's one day. You can disconnect any connection from tday Settings - Integrations.
+- **Local only.** The server runs on your machine over stdio. The installer's sign-in uses a loopback callback on `127.0.0.1` with a random `state` value. Your login is written to `~/.tday/config.json` with `0600` permissions.
+- **No telemetry.** The server talks only to tday, and to tday's file storage for uploads and the downloads you ask for. Downloads are limited to HTTPS image URLs on an allowlist, re-check redirects, are capped at 50MB, and are written only inside the current working directory.
 
 ## License