# TellWang — Full Agent Reference (MCP)

TellWang is an agent-native cloud. You build and operate a **Wok**: a team's complete live stack — Postgres, automatic REST (PostgREST), Auth (GoTrue), Storage, Realtime, Edge Functions (Deno), Redis cache + queues, Scheduler, Email (send + inbound), SMS, static Hosting, custom Domains, KMS, and an AI model gateway. Wang is the AI agent that builds Woks for non-technical users; technical agents drive the **same** Wok through MCP.

This file is the expanded reference for MCP clients (Cursor, Claude Code, Codex, VS Code, and any MCP-native agent). The short version is at https://tellwang.com/llms.txt.

## Connect

One hosted MCP server, Streamable HTTP:

    https://tellwang.com/v1/mcp

- **Auth, preferred:** OAuth 2.1 discovery. The server publishes `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`; clients that support it do Dynamic Client Registration + PKCE and the user logs in + picks an org in the browser. No key to paste.
- **Auth, fallback:** a bearer token (`Authorization: Bearer skl_…`) the user mints in the dashboard, for non-interactive clients.
- The JSON-RPC methods `initialize` and `tools/list` are open; `tools/call` is gated by your auth + org scope.
- Per-client install steps (exact config, Cursor's Command-Palette login, etc.): https://tellwang.com/install.txt
- **Before calling tools, load the operating discipline:** https://tellwang.com/SOUL.md

Everything you do is scoped to the caller's org and the Woks it owns; data boundaries are enforced server-side. Wang, the dashboard, REST, and MCP all act on the same resources.

## How to operate (the loop)

Provision → build → run → **verify** → say done. Build against the live Wok; never claim something works until a real probe confirms it (a row count, a 2xx from `invoke_function`, a clean `browser_check`). If a probe shows an error, the app is broken — fix the root cause and re-verify; do not dismiss it.

On a vague goal ("a landing page for my bakery"), first map it to the capabilities that fit and state a one-line plan, then run it. Step 1 is almost always `provision_wok`. Pull in domain, email, auth, storage, scheduler proactively when they serve the goal.

## Tool catalog

Names and exact argument schemas come from `tools/list` — treat that as canonical. Grouped overview:

- **Wok lifecycle:** `provision_wok`, `list_woks`, `get_connection` (urls + anon/service keys), `export_code`, `restart` (re-render the stack), `create_staging`, `promote`, `migrate`.
- **Database:** `exec_sql` (DDL + queries; auto-`NOTIFY pgrst`), `migrate` (named, replayable migrations).
- **Edge functions:** `deploy_function`, `list_functions`, `invoke_function`, `get_function_logs` (tail the runtime's logs — every `console.log`/`console.error` plus worker errors; check it when a deployed function fails in ways `invoke_function` doesn't reproduce).
- **Wok source + deploy:** every Wok repo has root `AGENTS.md` and `TELLWANG.md`; read both first. Inspect/open the authoritative Wok, edit it, and deploy frontend/functions through TellWang MCP (or push its authenticated TellWang Git remote), then verify release status plus browser/function/database checks. Do not guess Vercel, AWS, or generic cloud commands. `schema.sql` is reference-only; apply named DDL with `migrate`. If TellWang MCP is unavailable, ask the owner to connect it instead of claiming deployment.
- **Frontend:** `deploy_frontend` (deploy a small/single-file page), a tarball upload at `POST /v1/woks/{id}/frontend/upload` (additive — overwrites matching files, keeps the rest) for agents with a real build dir, and `read_frontend_file` / `list_frontend_files` to inspect. To edit an existing site, use the git round-trip: `git_snapshot` for the clone URL → `git clone` → read `AGENTS.md` + `TELLWANG.md` → edit → `git push` (the push validates context and redeploys `frontend/` + `functions/`).
- **Site import (deep copy):** `clone_site` copies an EXISTING site into ground-truth to rebuild from — crawls sitemap-first and stores each page's REAL HTML/text (not an AI impression of it, which loses ~90% of the original). Add `render:true` to render JS/SPA pages in headless Chrome (async — poll `get_clone_status`). `rehost_clone_assets` downloads the source's images/CSS/JS/fonts into a public bucket and rewrites the HTML so the copy is self-contained; `get_clone_page` returns one page's ground truth so you rebuild page-by-page. The **grounded-site-rebuild** build skill drives the whole loop; use it (not `audit_site`) when someone wants their existing site imported/migrated.
- **Storage:** `create_bucket` (makes the bucket + correct RLS in one step), `list_buckets` + `list_objects` to browse what's in storage (e.g. pick a customer-uploaded photo) — these read via the wok's service role, so don't hand-roll an anon-key curl, which RLS returns an empty list for.
- **Design assets:** `design_page` — author an ad, social card, or infographic as a self-contained HTML page; it renders in a real headless Chrome, is screenshotted, and the PNG + HTML source land in a PRIVATE bucket with signed preview URLs. Drafts never appear on the wok's site; re-run with the same name to revise.
- **Realtime:** `realtime_add_table`, `list_realtime_tables`.
- **Scheduler / jobs:** `schedule_function` (a timed job that hits HTTP / a function), `schedule_job`, `list_scheduled_jobs`. A Redis + BullMQ queue ships with every Wok.
- **Model gateway:** `mint_llm_key` — a prepaid OpenAI-compatible key; functions call the gateway for any "ask the data" / AI feature.
- **Email:** `setup_email_domain` (sending DKIM/SPF + inbound MX), `send_email`, `list_email_domains`, `set_email_handler` (auto-process inbound), `list_inbox`, `read_email`.
- **SMS:** `provision_phone_number`, `send_sms`, `set_sms_handler`, `register_sms_brand` + `sms_registration_status` (US A2P 10DLC).
- **Domains:** `domain_check`, `domain_buy`, `connect_domain`, `verify_domain` (waits server-side while DNS propagates - one call, no retry loop), `redirect_domain` (301 a connected domain to another host, path+query preserved - the SEO-correct way to retire an old/duplicate domain), `list_domains`, `get_domain`.
- **Env / secrets:** `set_env`.
- **Credits:** `credits_balance`, `credits_topup_url`, `crypto_deposit_info`. Email, SMS, and model-gateway usage draw down prepaid org credits.
- **Diagnostics:** `browser_check` (a SYNTHETIC one-shot headless Chrome you drive — console errors, checks, and `failed_responses` with the response BODY of any non-2xx request, so a frontend "…JSON at position N" error resolves to the exact HTML-error-page an endpoint returned; text checks normalize Unicode, case, punctuation, and whitespace unless you explicitly set `exact:true`), `list_client_errors` (REAL-visitor JS errors — window.onerror + unhandledrejection from actual browsers, grouped with counts + a sample stack, so you see production bugs `browser_check` can't reproduce), `get_service_logs` (tail the auth/rest/storage/realtime/db container — where a signup or data-write failure actually lives), `save_test_plan` / `list_test_plans` / `get_test_plan`.
- **Web analytics:** `web_analytics` (real traffic — pageviews, unique visitors, top pages, sources), plus `define_metric` / `query_metric` / `list_metrics` (read back a metric's binding) and `define_funnel` for named business metrics and same-day conversion funnels over the first-party event stream.
- **State & inventory reads (observe instead of guess):** `list_env` (env var names, no values), `read_function` (deployed function source + sha), `get_function_telemetry` (per-function error-rate/latency trend), `deploy_timeline` (what changed + when), `list_backups`, `get_standby_status`, `get_realtime_status` (CDC slot health), `list_triggers`, `list_wok_domains` (dns_status / last_error / redirect_to), `list_approval_requests`. Org-level: `get_plan` (tier + entitlement ceilings), `list_llm_keys` (per-key token usage), `get_payments_balance` / `get_payment_kyc` / `list_payment_gateways`, `list_decisions` (standing operator authorizations), `list_wang_runs`, `list_site_audits`, `get_org_feed`.
- **Task tracking:** `add_todo`, `list_todos`, `update_todo` — your durable memory across sessions and the customer's live progress view.

## Build rules that actually matter

These are the failure modes that break a one-pass build. Follow them.

1. **Edge functions register a handler with `Deno.serve`.** Write `Deno.serve((req) => new Response(...))` — NOT `export default`. The runtime (edge-runtime v1.65) only makes a worker "available" once `Deno.serve` is called; a bare default export boots a worker that never serves and every invoke fails with "user worker not available."
2. **Inside a function, reach Postgres by RAW fetch to PostgREST at `http://rest:3000/<table>`** — never `supabase-js` pointed there (it appends `/rest/v1/` and 404s). Read: `GET http://rest:3000/<table>?select=*` with header `apikey`. Write: `POST`/`PATCH` (filtered, e.g. `?id=eq.1`) with `apikey` + `Authorization: Bearer <service-role>` + `Content-Type: application/json`; the service-role key is `Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')`. Redis is `redis:6379`.
3. **After `CREATE TABLE`, grant access.** RLS gates rows, but PostgREST also needs table GRANTs: `GRANT SELECT,INSERT,UPDATE,DELETE ON <table> TO anon, authenticated; GRANT ALL ON <table> TO service_role;` (+ sequence USAGE for identity columns). Without the grant the API 403s.
4. **Seed and write data SERVER-SIDE** (`exec_sql`, or a service-role fetch from a function). The browser anon key is SELECT-only — anon inserts 401 and the table stays empty. The browser only reads.
5. **Pick the auth model before the schema.** A public/no-login app uses public tables with a permissive policy. Per-user RLS keyed on `auth.uid()` makes every write from a logged-out visitor fail (`auth.uid()` is NULL) — only use it with a real login, and give owner columns `user_id uuid not null default auth.uid()`.
6. **An "analyst"/AI feature must actually call the model gateway** (`mint_llm_key`, then a function fetches the gateway), never a canned keyword lookup. The gateway is the PLATFORM host `https://tellwang.com/v1/llm/v1/chat/completions` with the `sllm_` key — never the wok host or a relative path.
7. **A timed job that hits HTTP uses `schedule_function`,** not `pg_cron` (SQL has no HTTP).
8. **Frontends: build with a real build dir and ship it via the tarball upload (`POST /v1/woks/{id}/frontend/upload`, additive), or edit an existing site through the git round-trip (`git_snapshot` → `git clone` → edit → `git push`).** `deploy_frontend` is for a trivial single-file page. Use the literal `__ANON__` for the anon key (substituted at deploy); never hardcode it. Ship a polished SPA, not bare HTML.
9. **Display owner-supplied photos** via `create_bucket` (public, not owner-scoped), then have the customer upload them in the dashboard under the Wok → Media tab; read the public URLs in the frontend. You cannot receive image files in chat and must not fabricate them.
10. **Never invent endpoints, tables, env vars, or tool names.** If unsure, READ the value (`get_connection`, `list_functions`, a `select`).

## Auth, access, errors

- All tool calls are org-scoped; you operate only on Woks your org owns. Destructive ops (delete/transfer a Wok) are not directly exposed — they go through a human approval queue in the dashboard.
- Errors are structured: `{ "error": { "code": "CP_…", "message", "hint" } }`. Read the `hint`. Registry: https://tellwang.com/errors.html
- A `2xx` that contains rows of `failed`/`error` is NOT success — inspect the body and fix the cause.

## Key URLs

- Homepage: https://tellwang.com/
- MCP endpoint: https://tellwang.com/v1/mcp
- MCP guide: https://tellwang.com/mcp.html
- Install steps (per client): https://tellwang.com/install.txt
- Operating soul: https://tellwang.com/SOUL.md
- OAuth metadata: https://tellwang.com/.well-known/oauth-protected-resource and https://tellwang.com/.well-known/oauth-authorization-server
- Quickstart: https://tellwang.com/quickstart.html
- GEO content guide: https://tellwang.com/geo-guide.html
- Newly provisioned Woks expose `get_geo_content`, `configure_geo_content`, and `run_geo_content`: DeepSeek-planned multilingual research grounded in a bounded live-homepage snapshot plus owner topics, an optional dedicated English Reddit search, confirmed author attribution, mandatory draft review, stored plans/runs/questions/sources, and owner-digest notifications. Page-read or planning failure falls back to deterministic topic searches. Existing Woks are not backfilled.
- API reference: https://tellwang.com/api-reference.html
- Error codes: https://tellwang.com/errors.html
- Model gateway: https://tellwang.com/model-gateway.html
- Functions: https://tellwang.com/functions.html
- Database: https://tellwang.com/database.html
- Security: https://tellwang.com/security.html
- Use cases: https://tellwang.com/use-cases.html
- For small merchants: https://tellwang.com/for-small-merchants.html
- Lead generation: https://tellwang.com/own-your-lead-generation-pipeline.html
- Lead qualification: https://tellwang.com/own-your-lead-qualification-pipeline.html
- CRM: https://tellwang.com/own-your-crm-pipeline.html
- Programmatic SEO: https://tellwang.com/own-your-seo-pipeline.html

## Use case: small merchants

For a small merchant, Wang can build software the business owns: storefront, self-ordering, loyalty, menu admin, staff views, sales summaries, notifications, and a website that all stay together as one tool. Treat this as an owner-facing use-case landing page, not a blog post or developer explainer.

## Owner-facing use cases

- Lead generation: a capture page, owned lead list, instant alerts, qualification, routing, and follow-up views.
- Lead qualification: a chatbot that asks the owner's questions, scores leads, books the good ones, and records the outcome.
- CRM: customers, deals, pipeline stages, lead alerts, cold-deal nudges, and the business's book of record.
- Programmatic SEO: landing pages generated from owned data, each discoverable by Google and AI search and tied back to owned leads.