viral-mcp

Team MCP server wrapping the last30days-skill research engine.

• One server, central API keys. All provider keys (ScrapeCreators, xAI, Brave, Gemini, …) live on the server. Teammates get a bearer token, never the keys.
• Any agent can use it — Claude Code, Cursor, Codex, or programmatically via the AI SDK — over Streamable HTTP MCP.
• The skill's instructions travel with the data. Every last30days_research result is prefixed with the upstream SKILL.md synthesis contract (badge + LAWs), extracted live from the synced upstream, so the calling model writes the canonical brief.
• Always up to date. Upstream is a git submodule. A daily GitHub Action bumps it; POST /admin/sync pulls it into a running server with zero downtime. We hold no diffs against upstream, so sync can never conflict.

Architecture

agent (Claude Code / Cursor / AI SDK)
   │  Streamable HTTP MCP + bearer token
   ▼
viral-mcp (Express + @modelcontextprotocol/sdk)
   │  spawns per request
   ▼
upstream/skills/last30days/scripts/last30days.py   ← git submodule, synced daily
   │  server-side API keys (.env)
   ▼
Reddit · X · YouTube · TikTok · HN · Polymarket · GitHub · Bluesky · web

The tool returns synthesis contract + ranked evidence; the caller's model does the final synthesis. This mirrors how the skill works in Claude Code, where the host model is the synthesizer.

MCP surface

Kind	Name	Purpose
tool	last30days_research	Run the engine: topic, optional sources, depth, github_user, x_handle, subreddits, mock
tool	last30days_diagnose	Per-source availability report (which keys/CLIs the server has)
resource	last30days://skill.md	Full upstream SKILL.md
resource	last30days://synthesis-contract	Extracted output contract
prompt	last30days-synthesis	Same contract as a prompt

Run it

cp .env.template .env   # fill in keys + AUTH_TOKENS + ADMIN_TOKEN
docker compose up -d --build
curl localhost:3030/healthz

Local dev (needs Python ≥ 3.12 and Node ≥ 20):

npm install
git submodule update --init
PYTHON_BIN=python3.13 AUTH_TOKENS=me:dev npm run dev

Put a TLS reverse proxy (Caddy is two lines) in front of port 3030 in production.

Connect

Claude Code

claude mcp add --transport http last30days https://research.example.com/mcp \
  --header "Authorization: Bearer <your-token>"

AI SDK — see examples/ai-sdk-client.ts:

import { createMCPClient } from "@ai-sdk/mcp";
const mcp = await createMCPClient({
  transport: { type: "http", url: "https://research.example.com/mcp",
               headers: { Authorization: "Bearer <token>" } },
});
const tools = await mcp.tools();

Upstream sync

• Daily: .github/workflows/sync-upstream.yml bumps the submodule, verifies the contract anchors still extract, smoke-tests the engine with --mock, commits.
• One click: curl -X POST https://research.example.com/admin/sync -H "Authorization: Bearer $ADMIN_TOKEN" — pulls upstream main and re-extracts the contract in-process.
• Rule: never edit files under upstream/. All adaptation happens at runtime in src/instructions.ts. If upstream renames the # OUTPUT CONTRACT section, /healthz reports contractExtraction: "fallback" and the CI anchor check fails loudly.

Keys (.env)

See .env.template. Minimum useful set: one reasoning key (GOOGLE_API_KEY), one web-search key (BRAVE_API_KEY or PARALLEL_API_KEY), XAI_API_KEY for X, SCRAPECREATORS_API_KEY for TikTok/Instagram. Reddit, Hacker News, Polymarket and GitHub work with no keys.