Ventriloquist

An unofficial TikTok MCP facade. No official TikTok API, no OAuth, no app audit. Every read has two independent backends with automatic failover, every response is snapshotted into D1, and every tool advertises its own risk tier.

The full technical specification is in ventriloquist-tiktok-mcp-spec.md.

What is built

Not built: the pure-Python signer prototype, Whisper transcription on the VPS, and the 50-account cohort curation pass (see docs/decisions.md).

Related MCP server: tiktok-mcp-server

Quickstart

pnpm install
pnpm migrate:local
pnpm smoke

pnpm smoke runs the whole pipeline offline: it boots the signer gateway in mock mode plus a mock vendor, boots the facade on local D1/KV/R2/Queues, and drives the real MCP endpoint. Among the 40 checks it kills the signer to prove the paid fallback takes over, trips the circuit breaker, and confirms the velocity engine classifies an accelerating hashtag as GROWTH.

Driving it by hand:

MCP_AUTH_TOKEN=secret pnpm dev          # http://127.0.0.1:8787/mcp
curl -s localhost:8787/ | jq '.tools[] | {name, risk}'

Tool surface

Every description begins with [TIER · label] and ends with the tier's caveat, so a calling agent can reason about what it is touching.

tt_system_status (GREEN) reports provider health, breakers, budget and accumulation counters. It is an addition to the spec's table, documented in docs/decisions.md.

How a read flows

agent -> /mcp -> tool registry (risk tier + zod schema)
              -> backend router: candidates sorted by cost, breaker-aware
                   signer (owned, $0) -> Creative Center (public, $0) -> ScrapeBadger (paid)
              -> normalize into one domain model
              -> respond now; snapshot to D1 via ctx.waitUntil
              -> ledger row per attempt (success, failure, skipped)
      later -> velocity engine reads the accumulated snapshots

Design notes that matter in practice:

• Failures are classified. A bad video id is recorded but does not trip a breaker; only real provider faults count toward the three-strike threshold.

• Canary probes. While a breaker is open, one trial call is allowed every five minutes so recovery is early rather than after the full cooldown.

• Budget degrades gracefully. Once the daily paid budget is spent, paid providers are skipped and only free paths run; tt_system_status says so.

• Posting is structurally throttled. The cap and spacing are enforced before the job reaches the queue, and two consecutive failures halt posting.

Repository layout

worker/      Cloudflare Worker: MCP server, routing, D1 schema, crons, queue consumer
signer/      self-hosted signer gateway (Puppeteer + TikTok's web SDK), with MOCK=1 fixtures
vps-agent/   Playwright posting worker + AMBER Studio scrape + session custody
scripts/     smoke.mjs (end-to-end), seed-cohort.mjs
docs/        decisions.md (spec decisions + deviations), runbook.md (deploy + ops)

Spec phases

Phase 0 (smoke test / signer plumbing) and Phase 1 (read facade) are complete in code and verified offline. Phase 2 (velocity engine) is implemented and covered by tests plus the smoke run. Phase 3 (comment mining) is implemented. Phase 4 (posting) is implemented but unverified against live Studio, and Phases 5-6 (AMBER deep analytics, productization) are scaffolds.

Becoming a live deployment needs three things that cannot live in this repository: a VPS with Chromium, a real posting session, and vendor API keys. See docs/runbook.md.

Risks, in the open

• Signing breaks periodically. Budget the 2-4 hours/month from the spec; the gateway's strategy field tells you when it has degraded to the in-page path.

• RED posting violates TikTok's ToS. The mitigation here is low volume, human pacing, a dedicated session, and halting on the second consecutive failure - not immunity.

• Every scraper and vendor path is copyrighted third-party surface. This is a personal research tool, not something to resell without counsel.