### Quick start commands for self-hosting Source: https://github.com/albretsen/mcpemails/blob/main/self-host/README.md Run these commands in order to set up and start the self-hosted stack. `make setup` generates secrets and writes .env; `make up` builds and starts the stack; `make provision` connects a mailbox using the IMAP_PASSWORD env var; `make key` mints an MCP API key. Requires Docker and Docker Compose. ```bash cd self-host # 1. Generate secrets (encryption key, DB passwords, signed PostgREST tokens). # Writes .env. Run once, keep it private. make setup # 2. Build and start the stack. make up # 3. Connect a mailbox (app password, never your main account password). # The password is read from the IMAP_PASSWORD env var so it stays out of shell history. export IMAP_PASSWORD='your-app-specific-password' make provision \ EMAIL=you@example.com \ IMAP_HOST=imap.fastmail.com SMTP_HOST=smtp.fastmail.com \ IMAP_PORT=993 SMTP_PORT=465 \ SERVICE=fastmail # 4. Mint an MCP API key (printed once, copy it now). make key NAME="my agent" ``` -------------------------------- ### Install snapcn Remotion components Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/DEVELOPMENT-GUIDE.md Install the snapcn components from inside tools/video-studio. Treat them as owned source: read each file after installing and adjust to src/theme.ts. Do not add snapcn as a dependency and do not npm update it. ```bash npx shadcn@latest add @snapcn/answer-stream @snapcn/prompt-send @snapcn/terminal-simulator @snapcn/word-captions ``` -------------------------------- ### Install video-studio package Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/PROMPT-demo-video.md Run from the repo root. Installs the separate video-studio package; a root install does not cover it. ```bash cd tools/video-studio && npm install ``` -------------------------------- ### OAuth client configuration example (claude.ai) Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/built-output/snapshots/docs.txt Example configuration for OAuth-capable clients like claude.ai, Claude Desktop, and Cursor. Paste the MCP endpoint URL and authorize; no API key is required. ```text # OAuth-capable clients (claude.ai, Claude Desktop, Cursor…) # No API key required. Paste the URL, click Connect, authorize. # # Example: claude.ai # 1. Go to claude.ai β†’ Customize β†’ Connectors # 2. Click "Add connector" and paste this URL: # # https://mcpemails.com/api/mcp # # 3. Click Connect and sign in with your MCPEmails account. # 4. Every tool your approved scopes allow is live immediately. # # Claude Desktop and Cursor follow the same OAuth flow when # the server URL is configured in their MCP settings. ``` -------------------------------- ### Make a test video: cd, npm install, npm run demo Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/README.md Run from tools/video-studio. npm install is required once and is not covered by a root install because the directory is outside the repo's workspace. The demo records the public marketing site, composites with title and outro, renders, verifies, and prints the output path. First run downloads Chromium (~95 MB). Result is out/demo.mp4 plus a poster and contact sheet; re-recording is automatic after a day, and --fresh forces it. ```bash cd tools/video-studio npm install # once. This package is separate from the repo's own. npm run demo ``` -------------------------------- ### Setup for a real cut: cp .env.example .env, npm run doctor Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/README.md Copy the environment template and fill it in, then run npm run doctor to validate setup. npm run auth opens a headed browser for manual sign-in as the demo account; nothing will type a password. ```bash cp .env.example .env # then fill it in npm run doctor ``` -------------------------------- ### Navigate to tools/video-studio and install dependencies Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/AGENTS.md Run from tools/video-studio/, never the repo root. The repo's own install does not cover this directory; running from the root gives 'npm error Missing script: "auth"'. ```bash cd tools/video-studio npm install # once per clone; the repo's own install does not cover this ``` -------------------------------- ### Transcript plan JSON example Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/AGENTS.md Example of a `.plan.json` file that declares chat scene calls as data. It defines user, tool, and assistant turns with references and pipes. References must point backwards and resolve to existing values; otherwise the turn fails and rendering is refused. ```json { "turns": [ { "role": "user", "text": "Is there anything in here I actually have to pay?" }, { "role": "tool", "as": "demo", "name": "email_read", "args": { "action": "list", "folder": "Demo" }, "summary": "{{demo.messages | count}} messages" }, { "role": "tool", "as": "bill", "name": "email_read", "args": { "action": "read", "message_id": "{{demo.messages | where:subject~/overdue/i | first | get:id}}" }, "summary": "opened \"{{bill.subject}}\"" }, { "role": "assistant", "requires": "demo.messages | where:subject~/overdue/i | count", "text": "Found it: \"{{bill.subject}}\", from {{bill.from.name}}.", "otherwise": "Nothing in here is overdue." } ] } ``` -------------------------------- ### Start local database and run RLS tests Source: https://github.com/albretsen/mcpemails/blob/main/CLAUDE.md Applies every migration and runs the RLS tests against the local Supabase instance. ```bash supabase db start && supabase test db ``` -------------------------------- ### Start Supabase and source environment Source: https://github.com/albretsen/mcpemails/blob/main/scripts/stripe-test/README.md Starts the local Supabase stack and sources scripts/stripe-test/env.sh to override .env.local and prevent writing to the production database. ```bash npx supabase start source scripts/stripe-test/env.sh ``` -------------------------------- ### Start session with extension environment variables Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Include environment variables in the extension command when starting a session. Requires Node.js for npx-based commands. ```bash goose session --with-extension "VAR=value command arg1 arg2" ``` ```bash goose session --with-extension "GITHUB_PERSONAL_ACCESS_TOKEN= npx -y @modelcontextprotocol/server-github" ``` -------------------------------- ### Install, configure, and run the web app Source: https://github.com/albretsen/mcpemails/blob/main/README.md Run from the repo root. Requires Node.js 20+, npm, and the Supabase CLI. Generates ENCRYPTION_KEY and CSRF_SECRET with openssl. next.config.js validates required env vars at build/start and rejects weak ENCRYPTION_KEY values. ```bash # 1. Install (npm workspaces β€” run from the repo root) npm install # 2. Configure environment cp .env.example apps/web/.env.local # then fill in the values (see below) and generate the two secrets: openssl rand -hex 32 # ENCRYPTION_KEY openssl rand -hex 32 # CSRF_SECRET # 3. Run the web app (http://localhost:3000) npm run dev # 4. Production build npm run build ``` -------------------------------- ### Example mcp_config.json with GitHub server Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/devin-desktop-mcp.txt Example configuration that sets up a single server for GitHub using npx. Requires providing the GITHUB_PERSONAL_ACCESS_TOKEN environment variable. ```json "mcpServers" : { "github" : { "command" : "npx" , "args" : [ "-y" , "@modelcontextprotocol/server-github" ], "env" : { "GITHUB_PERSONAL_ACCESS_TOKEN" : "" } ``` -------------------------------- ### Example /mcp output Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/gemini-cli-mcp.txt Sample output from the /mcp command showing connection statuses, commands, working directories, timeouts, tools, and discovery state for multiple servers. ```text MCP Servers Status: πŸ“‘ pythonTools (CONNECTED) Command: python -m my_mcp_server --port 8080 Working Directory: ./mcp-servers/python Timeout: 15000ms Tools: calculate_sum, file_analyzer, data_processor πŸ”Œ nodeServer (DISCONNECTED) Command: node dist/server.js --verbose Error: Connection refused 🐳 dockerizedServer (CONNECTED) Command: docker run -i --rm -e API_KEY my-mcp-server:latest Tools: mcp_dockerizedServer_docker_deploy, mcp_dockerizedServer_docker_status Discovery State: COMPLETED ``` -------------------------------- ### Start Caddy HTTPS proxy for remote access Source: https://github.com/albretsen/mcpemails/blob/main/self-host/README.md Run this command from the self-host directory to start the stack with the Caddy HTTPS proxy. Set MCP_PUBLIC_HOST and APP_URL to your public hostname, and ensure ports 80 and 443 are reachable. Caddy uses port 80 for ACME validation and redirects HTTP to HTTPS. ```bash cd self-host MCP_PUBLIC_HOST=mcp.example.com \ APP_URL=https://mcp.example.com \ docker compose -f docker-compose.yml -f docker-compose.tls.yml up -d --build ``` -------------------------------- ### Start session with external extensions using --with-extension Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Enable external extensions when starting a goose session. The extension is not installed and only enabled for the current session. ```bash goose session --with-extension "{extension command}" --with-extension "{another extension command}" ``` ```bash goose session --with-extension "uvx mcp-server-fetch" ``` -------------------------------- ### Install and run seed-demo-mailbox.mjs (install, dry-run, check, reset) Source: https://github.com/albretsen/mcpemails/blob/main/tools/openai-review/README.md Install dependencies with npm and run the CLI in three modes: --dry-run (offline, no password), --check (read-only, exit 0 if clean, 1 if differs), and reset (deletes and re-appends fixtures, exit 0 only if mailbox matches). DEMO_IMAP_PASSWORD is required for --check and reset. ```sh npm install --prefix tools/openai-review # once: installs imapflow (+ mailparser for tests) ``` ```sh # 1. Offline: see the plan and every fixture. No password, no network. node tools/openai-review/seed-demo-mailbox.mjs --dry-run ``` ```sh # 2. Read-only: print the current state of every folder and diff it # against the fixtures. Exit 0 = clean, 1 = differs. DEMO_IMAP_PASSWORD='...' node tools/openai-review/seed-demo-mailbox.mjs --check ``` ```sh # 3. Reset. Prints what it deletes, re-appends the fixtures, then re-runs # the check. Exit 0 only if the mailbox now matches. DEMO_IMAP_PASSWORD='...' node tools/openai-review/seed-demo-mailbox.mjs ``` -------------------------------- ### Start session with built-in extensions using --with-builtin Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Enable built-in extensions when starting a goose session. The extension is not installed and only enabled for the current session. ```bash goose session --with-builtin "{extension_id}" ``` ```bash goose session --with-builtin "developer,computercontroller" ``` ```bash goose session --with-builtin developer --with-builtin computercontroller ``` -------------------------------- ### Create an MCP installation URL with vscode:mcp/install Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/vscode-install-url.txt Builds a vscode:mcp/install URL from a JSON server configuration object. Use vscode-insiders instead of code for Insiders builds. The link can be opened in a browser or via xdg-open on Linux. ```javascript // For Insiders, use `vscode-insiders` instead of `code` const link = `vscode:mcp/install? ${ encodeURIComponent ( JSON . stringify ( obj )) } ` ; ``` -------------------------------- ### gemini mcp list - Command and example output Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/gemini-cli-mcp.txt Lists all configured MCP servers with their name, configuration details, and connection status. The command has no flags. Example output shows connected and disconnected servers. ```bash gemini mcp list ``` ```bash βœ“ stdio-server: command: python3 server.py (stdio) - Connected βœ“ http-server: https://api.example.com/mcp (http) - Connected βœ— sse-server: https://api.example.com/sse (sse) - Disconnected ``` -------------------------------- ### Example deeplink for npx command Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Example deeplink for a command like 'npx -y @modelcontextprotocol/server-github'. Each parameter to the npx command is passed as a separate arg parameter. ```text goose://extension?cmd=npx&arg=-y&arg=%40modelcontextprotocol/server-github&timeout=&id=&name=&description= ``` -------------------------------- ### Set webhook secret and start app Source: https://github.com/albretsen/mcpemails/blob/main/scripts/stripe-test/README.md Exports the whsec_... secret printed by stripe listen, then starts the dev server. ```bash export STRIPE_WEBHOOK_SECRET=whsec_... npm run dev ``` -------------------------------- ### Example MCP Client Config with Bearer Token Source: https://github.com/albretsen/mcpemails/blob/main/README.md JSONC configuration for any MCP client using an API key. Send the key as a bearer token in the Authorization header. ```jsonc // Example MCP client config { "mcpServers": { "mcpemails": { "url": "https://mcpemails.com/api/mcp", "headers": { "Authorization": "Bearer mcpe_your_key_here" } } } } ``` -------------------------------- ### System prompt for multi-inbox setups Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/built-output/snapshots/docs.txt Optional system prompt instructing the agent to call inbox_list first to discover available inboxes, avoiding hardcoded UUIDs. ```text # The agent calls inbox_list first, so no hardcoded UUIDs. # System prompt (optional, for multi-inbox setups): You have access to email via MCPEmails. Start by calling inbox_list to discover available inboxes. ``` -------------------------------- ### Query B: Ads against organic Google baseline over the same window Source: https://github.com/albretsen/mcpemails/blob/main/docs/PLAN-google-ads-test-20260929.md Read-out query comparing Google Ads signups and activation against the organic Google baseline over the same window. Set the start parameter to the day the first ad ran. Counts signups, activated signups (first tool call within 7 days), and paid conversions. ```sql with params as (select timestamptz '2026-10-01' as start) select w.acquisition_source as source, count(*) as signups, count(*) filter (where exists (select 1 from product_funnel_events e where e.workspace_id = w.id and e.stage = 'first_tool_call' and e.occurred_at < w.created_at + interval '7 days')) as activated_7d, count(b.paid_at) as paid from workspaces w join auth.users u on u.id = w.owner_id left join billing_funnel_by_workspace b on b.workspace_id = w.id, params p where w.deleted_at is null and not public.growth_is_internal_email(u.email) and w.acquisition_source in ('google_ads', 'organic_google') and w.created_at >= p.start group by 1; ``` -------------------------------- ### Enable PostgreSQL extension via goose CLI Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Use the 'goose' CLI to enable an extension by name. The output shows the approval prompt and confirmation that the extension is installed and ready. ```text goose └─ action enable extension_name postgresql The extension 'postgresql' has been installed successfully The PostgreSQL extension is now ready to use. What would you like to do with it? ``` -------------------------------- ### Register MCP server definitions with API key prompt (vscode.lm.registerMcpServerDefinitionProvider) Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/vscode-install-url.txt Registers stdio and HTTP MCP server definitions in an extension and resolves them to prompt for an API key. Uses vscode.lm.registerMcpServerDefinitionProvider with an onDidChangeMcpServerDefinitions event and provideMcpServerDefinitions/resolveMcpServerDefinition callbacks. The resolveMcpServerDefinition returns undefined to indicate the server should not be started, and pending tool calls are cancelled with an error message. ```typescript import * as vscode from 'vscode' ; export function activate ( context : vscode . ExtensionContext ) { const didChangeEmitter = new vscode . EventEmitter < void >(); context . subscriptions . push ( vscode . lm . registerMcpServerDefinitionProvider ( 'exampleProvider' , { onDidChangeMcpServerDefinitions: didChangeEmitter . event , provideMcpServerDefinitions : async () => { let servers : vscode . McpServerDefinition [] = []; // Example of a simple stdio server definition servers . push ( new vscode . McpStdioServerDefinition ( label: 'myServer' , command: 'node' , args: [ 'server.js' ], cwd: vscode . Uri . file ( '/path/to/server' ), env: { API_KEY: '' }, version: '1.0.0' }); // Example of an HTTP server definition servers . push ( new vscode . McpHttpServerDefinition ( label: 'myRemoteServer' , uri: 'http://localhost:3000' , headers: { 'API_VERSION' : '1.0.0' }, version: '1.0.0' })); return servers ; }, resolveMcpServerDefinition : async ( server : vscode . McpServerDefinition ) => { if ( server . label === 'myServer' ) { // Get the API key from the user, e.g. using vscode.window.showInputBox // Update the server definition with the API key // Return undefined to indicate that the server should not be started or throw an error // If there is a pending tool call, the editor will cancel it and return an error message // to the language model. return server ; })); ``` -------------------------------- ### Query A: Ad signups, activation and sales per landing page Source: https://github.com/albretsen/mcpemails/blob/main/docs/PLAN-google-ads-test-20260929.md Read-out query for Google Ads performance by landing page. Set the start parameter to the day the first ad ran. Counts signups, activated signups (first tool call within 7 days), workspaces with two or more inboxes, paid conversions, and business-domain signups. ```sql with params as (select timestamptz '2026-10-01' as start) select w.acquisition_landing_path as landing, count(*) as signups, count(*) filter (where exists (select 1 from product_funnel_events e where e.workspace_id = w.id and e.stage = 'first_tool_call' and e.occurred_at < w.created_at + interval '7 days')) as activated_7d, count(*) filter (where (select count(*) from inboxes i where i.workspace_id = w.id) >= 2) as two_plus_inboxes, count(b.paid_at) as paid, count(*) filter (where w.acquisition_email_segment = 'business') as business_domain from workspaces w join auth.users u on u.id = w.owner_id left join billing_funnel_by_workspace b on b.workspace_id = w.id, params p where w.deleted_at is null and not public.growth_is_internal_email(u.email) and w.acquisition_source = 'google_ads' and w.created_at >= p.start group by 1 order by signups desc; ``` -------------------------------- ### Start Stripe webhook forwarder Source: https://github.com/albretsen/mcpemails/blob/main/scripts/stripe-test/README.md Runs stripe listen to forward webhooks to localhost:3000/api/stripe/webhook. It mints a fresh signing secret per session. ```bash stripe listen --forward-to localhost:3000/api/stripe/webhook ``` -------------------------------- ### Environment variable expansion example in env block Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/gemini-cli-mcp.txt Shows how environment variables are expanded in the env block of an MCP server configuration. Supports POSIX/Bash syntax ($VAR or ${VAR}) on all platforms and Windows syntax (%VAR%) only on Windows. Undefined variables resolve to an empty string. ```json "env" : { "API_KEY" : "$MY_EXTERNAL_TOKEN" , "LOG_LEVEL" : "$LOG_LEVEL" , "TEMP_DIR" : "%TEMP%" } ``` -------------------------------- ### Storyboard JSON example: add-inbox-then-chat.json Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/DEVELOPMENT-GUIDE.md Defines a complete video storyboard with scenes for title, capture, chat, and outro. Uses seconds for durations, references external assets and transcripts, and includes callouts for annotations. This is the primary authoring format for agents. ```json { "id": "add-inbox-then-chat", "width": 1920, "height": 1080, "fps": 30, "theme": "dark", "voiceover": "assets/vo/add-inbox-then-chat.mp3", "captions": true, "scenes": [ { "type": "title", "durationInSeconds": 2.5, "headline": "Connect a mailbox", "sub": "IMAP and an app password. No OAuth review." }, { "type": "capture", "shot": "add-inbox", "clip": { "from": 1.2, "to": 34.0 }, "speed": 1.0, "autoZoom": true, "callouts": [ { "at": 11.4, "for": 2.2, "text": "An app password, never your login password" } ] }, { "type": "chat", "transcript": "transcripts/add-inbox-then-chat.json", "durationInSeconds": 14 }, { "type": "outro", "durationInSeconds": 3, "cta": "mcpemails.com" } ] } ``` -------------------------------- ### Self-host the MCP server stack Source: https://github.com/albretsen/mcpemails/blob/main/README.md Runs the same MCP server locally using a containerized stack (Postgres + PostgREST + Deno server). Generates secrets, builds and starts the stack, provisions an email account with an app password, and mints an mcpe_ key for client access at http://localhost:8787. ```bash cd self-host make setup # generate secrets (.env) make up # build + start the stack export IMAP_PASSWORD='your-app-password' make provision EMAIL=you@example.com IMAP_HOST=imap.fastmail.com SMTP_HOST=smtp.fastmail.com SERVICE=fastmail make key NAME="my agent" # mint an mcpe_ key, then point your client at http://localhost:8787 ``` -------------------------------- ### Example: Adding Built-in Extension Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Shows the interactive goose configure output when adding the Auto Visualiser built-in extension with a 300-second timeout. The final line confirms the extension was enabled. ```text β”Œ goose-configure β—‡ What would you like to configure? β”‚ Add Extension β—‡ What type of extension would you like to add? β”‚ Built-in Extension β—‡ Which built-in extension would you like to enable? β”‚ Auto Visualiser β—‡ Please set the timeout for this tool (in secs): β”‚ 300 β”” Enabled Auto Visualiser extension ``` -------------------------------- ### Spike re-run commands Source: https://github.com/albretsen/mcpemails/blob/main/docs/mcp-apps/phase-0-protocol-findings.md Commands to re-run the spike: start the hand-rolled Deno MCP server, build the card bundle, run the basic-host harness, probe the protocol-version matrix, and run the size sweep. Environment variables control protocol version, big-KB padding, and resource capabilities. ```bash cd /private/tmp/claude-501/-Users-asgeiralbretsen-Repositories-MCPEmails/31ec7162-7a08-4a71-b024-c68e652c810d/scratchpad # 1. spike MCP server (hand-rolled Deno, mirrors production shape) cd apps-spike deno run -A server.ts # :3001/mcp, logs to spike.log.jsonl and GET /log # env: SPIKE_PROTOCOL_VERSION (default 2025-06-18) # SPIKE_BIG_KB (padding for ui://spike/big) # SPIKE_NO_RESOURCES_CAP=1 reproduce today's production capabilities # SPIKE_PORT # 2. the card bundle (only needed if card/main.ts changed) cd card && npm install && npx vite build # -> card/dist/index.html # 3. ext-apps basic-host reference harness (already built) ./run-host.sh # :8080 host, :8091 sandbox proxy # NOTE: sandbox was moved off the default :8081 (occupied on this machine); # SANDBOX_PROXY_BASE_URL in ext-apps/examples/basic-host/src/implementation.ts:10 # was edited to :8091 and the host re-bundled. # 4. protocol-version matrix (needs spike servers on :3001-:3004) node probe.mjs # 5. size sweep ./size-probe.sh 8000 # restarts server with 8 MB padding ``` -------------------------------- ### Install tokenizer for measurement harness Source: https://github.com/albretsen/mcpemails/blob/main/docs/token-cost/research-responses.md Install either the npm gpt-tokenizer package or Python tiktoken to get accurate token counts. Without one, the harness falls back to a bytes/3.7 estimate labelled [ESTIMATE]. ```bash npm i gpt-tokenizer # or: pip install tiktoken ``` -------------------------------- ### StandardIO deeplink URL format Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt URL format for installing StandardIO extensions via goose's deep link protocol. Required parameters: cmd, arg (repeatable), timeout, id, name, description. All parameters must be URL-encoded. ```text goose://extension?cmd=&arg=&id=&name=&description= ``` -------------------------------- ### capture scene JSON configuration Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/AGENTS.md Composites a real recording with a drawn cursor, auto zoom, and callouts from `captures/.timeline.json`. `shot` must match `shots/.shot.mjs` and a completed capture. `clip.from` defaults to measured first paint, `clip.to` to the end; callout `at` is measured from clip start. `verify` fails if `clip.from` is not about a second. ```json { "type": "capture", "shot": "add-inbox", "clip": { "from": 1.2, "to": 34.0 }, "speed": 1.0, "autoZoom": true, "maxZoom": 1.8, "frame": "browser", "callouts": [ { "at": 11.4, "for": 2.2, "text": "An app password, never your login password" } ] } ``` -------------------------------- ### Start session with remote Streamable HTTP extension Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Enable a remote extension over Streamable HTTP when starting a session. ```bash goose session --with-streamable-http-extension "{extension URL}" --with-streamable-http-extension "{another extension URL}" ``` ```bash goose session --with-streamable-http-extension "https://example.com/streamable" ``` -------------------------------- ### Base predicate for workspace client attribution queries Source: https://github.com/albretsen/mcpemails/blob/main/docs/RESEARCH-directory-onboarding-ux.md SQL query used with `npx supabase db query --linked` to reproduce the figures. Filters workspaces to those with non-internal owner emails, not deleted, and created on or after 2026-08-13, when mcp_client_capabilities starts. The date cutoff is essential; earlier workspaces may appear to have no client connection. ```sql select w.* from public.workspaces w join public.users u on u.id = w.owner_id where not public.growth_is_internal_email(u.email) and w.deleted_at is null and w.created_at >= '2026-08-13' -- mcp_client_capabilities starts here ``` -------------------------------- ### Example deeplink for Streamable HTTP URL Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Example deeplink for a URL like https://example.com/streamable, URL-encoded. All parameters must be URL-encoded. ```text goose://extension?url=https%3A%2F%2Fexample.com%2Fstreamable&type=streamable_http&timeout=&id=&name=&description= ``` -------------------------------- ### Run demo to make a test video Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/AGENTS.md One command, no configuration, no account. Records the public site, composites it with a title and outro, renders, verifies, and prints the path. Use --fresh to force a re-record, --storyboard and --url to override defaults. ```bash npm run demo ``` -------------------------------- ### Initialize request from basic-host (no extensions capability) Source: https://github.com/albretsen/mcpemails/blob/main/docs/mcp-apps/phase-0-protocol-findings.md Captured verbatim from spike.log.jsonl entry initialize.params. Shows the official reference host sends an empty capabilities object, so servers must not gate _meta.ui metadata on the extension capability. ```json { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "MCP Apps Host", "version": "1.0.0" } } ``` -------------------------------- ### initialize Source: https://github.com/albretsen/mcpemails/blob/main/docs/mcp-apps/phase-0-protocol-findings.md Initializes the MCP connection and returns server capabilities, including the required resources capability with subscribe set to false. ```APIDOC ## initialize ### Description Initializes the MCP connection and returns server capabilities, including the required resources capability with subscribe set to false. ### Method initialize ### Response #### Success Response - **protocolVersion** (string) - The protocol version supported by the server. - **capabilities** (object) - Server capabilities, including tools, prompts, and resources. - **serverInfo** (object) - Server name and version. - **instructions** (string) - Optional instructions for the client. #### Response Example ```json { "jsonrpc": "2.0", "id": 0, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false }, "prompts": { "listChanged": false }, "resources": { "listChanged": false, "subscribe": false } }, "serverInfo": { "name": "mcp-emails", "version": "1.x.x" }, "instructions": "..." } } ``` ``` -------------------------------- ### Web client typecheck, test, and build Source: https://github.com/albretsen/mcpemails/blob/main/CLAUDE.md Run from the apps/client directory to validate the web client package. ```bash cd apps/client && npm run typecheck && npm test && npm run build ``` -------------------------------- ### Render storyboard with npm run render Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/DEVELOPMENT-GUIDE.md Renders the storyboard 'add-inbox-then-chat' to out/. Output includes an MP4 (H.264/AAC, 1920x1080, yuv420p), a poster JPG, WebVTT captions, and a JSON manifest with duration, scene boundaries, checksums, source capture ids, and transcript verifiedAt. ```bash npm run render -- --storyboard add-inbox-then-chat ``` -------------------------------- ### Check current date (UTC) Source: https://github.com/albretsen/mcpemails/blob/main/docs/runbooks/pro-price-19-flip.md Run this to get the current UTC time. If it is earlier than 2026-12-07T23:00:00Z, do not merge; only prepare and get CI green. ```bash date -u ``` -------------------------------- ### Making a video: capture, transcript, render, verify Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/README.md Four commands to produce a video for a storyboard. A new video requires a new storyboards/.json plus these commands; writing React is reserved for genuinely new scene types. The transcript command runs calls against the real MCP server, and a transcript with any failed tool call or older than 14 days blocks the render. ```bash npm run capture -- --shot add-inbox npm run transcript -- --storyboard add-inbox-then-chat npm run render -- --storyboard add-inbox-then-chat npm run verify -- --storyboard add-inbox-then-chat ``` -------------------------------- ### Run lint and build for web app Source: https://github.com/albretsen/mcpemails/blob/main/docs/personal-tier-rollout.md Run lint and build checks for the web app before deployment. ```bash npm run lint -w apps/web && npm run build -w apps/web ``` -------------------------------- ### signature_get Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/built-output/snapshots/docs.txt Gets the email signature. Requires read:email scope. ```APIDOC ## signature_get ### Description Gets the email signature. Requires read:email scope. ``` -------------------------------- ### Host tool picker options (combobox) Source: https://github.com/albretsen/mcpemails/blob/main/docs/mcp-apps/phase-0-protocol-findings.md Shows the tool picker options when all three tools are returned over the wire. The app-only tool is absent because the host filters it out. ```text combobox "spike_big" option "spike_big" (selected) option "spike_show" ``` -------------------------------- ### Query B: Which plan business workspaces bought first Source: https://github.com/albretsen/mcpemails/blob/main/docs/MEASURE-business-domain-segment-20260929.md Run with `npx supabase db query --linked -f .sql` from the repo root. `--linked` is mandatory; without it the CLI queries an empty local database. Replace `2026-10-01` with the real deploy date. Run one at a time, never in parallel. ```sql with params as (select timestamptz '2026-10-01' as ship, interval '28 days' as win) select case when e.occurred_at >= p.ship then 'post' else 'pre' end as period, w.acquisition_email_segment as seg, split_part(e.category, '_', 1) as plan, -- solo = Pro, personal = Personal, pro = Team count(distinct e.workspace_id) as workspaces from product_funnel_events e join workspaces w on w.id = e.workspace_id join auth.users u on u.id = w.owner_id, params p where e.stage = 'checkout_completed' and not public.growth_is_internal_email(u.email) and e.occurred_at >= p.ship - p.win and e.occurred_at < p.ship + p.win group by 1, 2, 3 order by 2, 1 desc, 3; ``` -------------------------------- ### Apply support tickets migration to production Source: https://github.com/albretsen/mcpemails/blob/main/docs/RELEASE-help-and-support.md Apply the migration file one at a time, never with the bulk push command. Run the query first, then mark it as applied. Merge only after it is applied; until then the form answers server_error when it tries to insert a row. ```bash npx supabase db query --linked -f supabase/migrations/20261016090000_support_tickets.sql ``` ```bash npx supabase migration repair --status applied 20261016090000 --linked ``` -------------------------------- ### Run test suites for web app Source: https://github.com/albretsen/mcpemails/blob/main/docs/personal-tier-rollout.md Execute the test suites for plans, inbox limit, billing, and growth features. ```bash npm run test:plans -w apps/web && npm run test:inbox-limit -w apps/web && npm run test:billing -w apps/web && npm run test:growth -w apps/web ``` -------------------------------- ### gemini mcp remove - Command and example Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/gemini-cli-mcp.txt Deletes a server from the configuration. The command takes the server's name. The `-s, --scope` flag sets the configuration scope (user or project), defaulting to 'project'. The example removes 'my-server' from the mcpServers object in the appropriate settings.json file. ```bash gemini mcp remove ``` ```bash gemini mcp remove my-server ``` -------------------------------- ### Web app typecheck, lint, test, and build commands Source: https://github.com/albretsen/mcpemails/blob/main/CLAUDE.md Run these from the apps/web directory. The test command ends with an N/N suites passed line; read that line and the exit code, not the scrollback. Build with npm run build, never bare npx next build, which can pick up a different Next version in a worktree. ```bash cd apps/web && npx tsc --noEmit ``` ```bash npm run lint ``` ```bash npm test ``` ```bash npm run build ``` -------------------------------- ### Direct Request - goose Prompt Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Prompt used in the direct request example to enable an extension. ```text Use PostgreSQL extension ``` -------------------------------- ### Query A: Conversion by segment, pre vs post Source: https://github.com/albretsen/mcpemails/blob/main/docs/MEASURE-business-domain-segment-20260929.md Run with `npx supabase db query --linked -f .sql` from the repo root. `--linked` is mandatory; without it the CLI queries an empty local database. Replace `2026-10-01` with the real deploy date. Run one at a time, never in parallel. ```sql with params as (select timestamptz '2026-10-01' as ship, interval '28 days' as win), w as ( select w.id, w.created_at, w.acquisition_email_segment as seg, case when w.created_at >= p.ship then 'post' else 'pre' end as period from workspaces w join auth.users u on u.id = w.owner_id, params p where w.deleted_at is null and not public.growth_is_internal_email(u.email) and w.created_at >= p.ship - p.win and w.created_at < p.ship + p.win ) select period, seg, count(*) as signups, count(*) filter (where b.paid_at < w.created_at + interval '14 days') as paid_14d, round(100.0 * count(*) filter (where b.paid_at < w.created_at + interval '14 days') / nullif(count(*), 0), 1) as pct from w left join billing_funnel_by_workspace b on b.workspace_id = w.id group by 1, 2 order by 2, 1 desc; ``` -------------------------------- ### draft_read Source: https://github.com/albretsen/mcpemails/blob/main/packages/mcpemails/README.md Reads one unsent draft in full, for example after the user edited it in the draft editor card. Read-only. ```APIDOC ## draft_read ### Description Reads one unsent draft in full, for example after the user edited it in the draft editor card. Read-only. ### Method MCP Tool ### Endpoint draft_read ### Parameters #### Request Body - **draft_id** (string) - Required - The ID of the draft to read. ### Response #### Success Response - **draft** (object) - The full draft content. ``` -------------------------------- ### Automatic Detection - goose Prompt (Desktop) Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Prompt used in the automatic detection example for the goose Desktop interface. ```text Find all orders with pending status from our production database ``` -------------------------------- ### Acceptance test for isolation Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/DEVELOPMENT-GUIDE.md Run this command from the repository root to verify isolation constraints. It checks git status, workspace dependencies, and the web build. The output must show no changes under apps/, packages/, supabase/, or scripts/, no video-studio in the workspace listing, and a passing web build. ```bash cd /Users/asgeiralbretsen/Repositories/MCPEmails && git status --short && npm ls --workspaces --depth=0 && cd apps/web && npm run build ``` -------------------------------- ### Read the AGENTS.md contract Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/PROMPT-demo-video.md After installing, read AGENTS.md which defines the commands, scene types with props, and guard rails. ```bash cat AGENTS.md ``` -------------------------------- ### Reset dummy-account created_at Source: https://github.com/albretsen/mcpemails/blob/main/docs/PLAN-free-action-cap-150.md Updates the workspace created_at to now, which resets the monthly allowance. Leave created_at unchanged to keep the account metered. ```sql update workspaces set created_at = now() ``` -------------------------------- ### automation_read Source: https://github.com/albretsen/mcpemails/blob/main/packages/mcpemails/README.md Lists triage rules, reads one, shows run history, dry-runs a filter. Actions: list, get, runs, preview. Read-only. ```APIDOC ## automation_read ### Description Lists triage rules, reads one, shows run history, dry-runs a filter. Actions: list, get, runs, preview. Read-only. ### Method MCP Tool ### Endpoint automation_read ### Parameters #### Request Body - **action** (string) - Required - The operation to perform: list, get, runs, preview. ### Response #### Success Response - **rules** (array) - List of triage rules or rule details. ``` -------------------------------- ### Check demo account and inboxes Source: https://github.com/albretsen/mcpemails/blob/main/tools/video-studio/PROMPT-demo-video.md Read-only command that prints the demo account, workspace id, and connected inboxes as pasteable .env lines. Required before touching the dashboard. ```bash npm run whoami ``` -------------------------------- ### Query C: Two or more inboxes by day 7 Source: https://github.com/albretsen/mcpemails/blob/main/docs/MEASURE-business-domain-segment-20260929.md Run with `npx supabase db query --linked -f .sql` from the repo root. `--linked` is mandatory; without it the CLI queries an empty local database. Replace `2026-10-01` with the real deploy date. Run one at a time, never in parallel. ```sql with params as (select timestamptz '2026-10-01' as ship, interval '28 days' as win) select case when w.created_at >= p.ship then 'post' else 'pre' end as period, w.acquisition_email_segment as seg, count(*) as signups, count(*) filter (where (select count(*) from inboxes i where i.workspace_id = w.id and i.created_at < w.created_at + interval '7 days') >= 2) as two_plus_by_d7 from workspaces w join auth.users u on u.id = w.owner_id, params p where w.deleted_at is null and not public.growth_is_internal_email(u.email) and w.created_at >= p.ship - p.win and w.created_at < p.ship + p.win group by 1, 2 order by 2, 1 desc; ``` -------------------------------- ### Configure goose extensions interactively Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/goose-extensions.txt Starts the interactive configuration menu to add, remove, or manage extensions. Use arrow keys to navigate and Enter to select. ```bash goose configure ``` -------------------------------- ### Initialize handshake with cURL Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/built-output/snapshots/docs.txt Example cURL command to perform the MCP initialize handshake against the endpoint. Uses a bearer token and JSON-RPC 2.0 request body with protocol version 2025-06-18. ```bash curl -X POST https://mcpemails.com/api/mcp \ -H "Authorization: Bearer mcpe_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "clientInfo": { "name": "my-agent", "version": "1.0" }, "capabilities": {} } }' ``` -------------------------------- ### tools/list tool with UI (default visibility) Source: https://github.com/albretsen/mcpemails/blob/main/docs/mcp-apps/phase-0-protocol-findings.md A tool with a UI, visible to both model and app by default. Omit `visibility` to mean `["model","app"]`; do not emit `_meta["ui/resourceUri"]`. ```json { "name": "email_read", "title": "Read email", "description": "...", "inputSchema": { "type": "object", "properties": { "...": {} } }, "_meta": { "ui": { "resourceUri": "ui://mcpemails/inbox" } } } ``` -------------------------------- ### Check workspaces_acquisition_source_check constraint includes google_ads Source: https://github.com/albretsen/mcpemails/blob/main/docs/PLAN-google-ads-test-20260929.md Run this SQL query after applying the migration to verify the constraint allows the google_ads acquisition source. The result must list google_ads. ```sql select pg_get_constraintdef(oid) from pg_constraint where conname = 'workspaces_acquisition_source_check'; ``` -------------------------------- ### Config interpolation with environment variable Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/devin-desktop-mcp.txt Example of using ${env:VAR_NAME} interpolation in headers to avoid hardcoding secrets. If the variable is not set, it resolves to an empty string. ```json "mcpServers" : { "remote-http-mcp" : { "serverUrl" : "/mcp" , "headers" : { "API_KEY" : "Bearer ${env:AUTH_TOKEN}" } ``` -------------------------------- ### API key format example Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/built-output/snapshots/docs.txt Shows the format of an MCPEmails API key: 'mcpe_' followed by 64 hex characters. This key is used for authentication in clients without OAuth support and for scripted access. ```text mcpe_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef ``` -------------------------------- ### Check llms.txt for Pro price Source: https://github.com/albretsen/mcpemails/blob/main/docs/runbooks/pro-price-19-flip.md Confirm the llms.txt file quotes $19 for Pro. ```bash curl -s https://mcpemails.com/llms.txt ``` -------------------------------- ### Config interpolation from file Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/client-docs-drift/devin-desktop-mcp.txt Example of using ${file:/path/to/file} interpolation to read an API key from a file. Tilde paths are supported; if the file cannot be read, the pattern is left unchanged. ```json "mcpServers" : { "my-server" : { "command" : "node" , "args" : [ "server.js" ], "env" : { "API_KEY" : "${file:~/.secrets/api_key.txt}" } ``` -------------------------------- ### Switch GitHub auth if needed Source: https://github.com/albretsen/mcpemails/blob/main/docs/runbooks/pro-price-19-flip.md If `gh` refuses due to permissions, switch to the Albretsen user. ```bash gh auth switch --user Albretsen ``` -------------------------------- ### Clone and run the self-hosted MCPEmails server Source: https://github.com/albretsen/mcpemails/blob/main/apps/web/scripts/built-output/snapshots/self-hosting.txt Run the open-source MCPEmails server on your own infrastructure. Requires git and make. Starts four containers: Postgres, PostgREST, nginx, and the Deno server. ```bash git clone https://github.com/Albretsen/MCPEmails cd MCPEmails/self-host make setup && make up ``` -------------------------------- ### Run EUR launch preflight manually Source: https://github.com/albretsen/mcpemails/blob/main/docs/RUNBOOK-eur-launch.md Runs the read-only preflight checks for the EUR launch on any day. No --apply exists for this command. On 2026-10-24 live, payment_methods passed while tax_registrations, webhook_events, and prices failed. ```bash cd apps/web node scripts/stripe-eur/eur-launch-preflight.mjs --prices ../../Documents/stripe-eur/prices.live.json --live ``` -------------------------------- ### Run Supabase query from repo root Source: https://github.com/albretsen/mcpemails/blob/main/docs/PLAN-multi-mailbox-business-segment.md All queries are run from the repo root using this command. The `--linked` flag is mandatory; without it the CLI silently runs against an empty local database and returns confident wrong answers. ```bash npx supabase db query --linked -f .sql ```