Pricing

Pay per usage

Korean Data MCP Hub

25 MCP tools exposing real-time Korean media trends to AI agents. Cluster-deduped news across K-Pop, K-Drama, K-Movie, K-Beauty, K-Food, K-Game, K-Tech, K-Stock, K-Travel, K-Webtoon, and K-Trends. Multilingual native output (EN/KO/JA/ES). Pre-classified with 90%+ accuracy. Pay-per-call from $0.005.

Pricing

Pay per usage

Rating

0.0

(0)

Developer

teddy

Actor stats

Bookmarked

Total users

Monthly active users

9 days ago

Last modified

OpenPageRank Bulk Checker

codescraper/openpagerank-bulk-checker

Instantly check OpenPageRank (OPR) scores for thousands or even millions of domains at once. This is your fast, highly affordable solution for large-scale SEO and domain analysis. Paste upto 5k, 6k, 7k, 8k, 9k, 10k, 11k, 12k domains at once

CodeScraper

5.0

SEC EDGAR Filing Scraper (8-K and 10-K Reports)

scraped/sec-edgar-filing-scraper-8-k-and-10-k-reports

This scraper fetches 8-K and 10-K filings from the SEC's EDGAR system using a company's ticker symbol.

scraped

SEC EDGAR Analyzer — 10-K, 10-Q & 8-K Data

ryanclinton/sec-edgar-filing-analyzer

Search SEC filings by ticker, name, or CIK. Extract 10-K, 10-Q, 8-K metadata and structured XBRL financials (revenue, net income, assets, EPS). Covers 10,000+ public companies. Free SEC API, no key needed.

Ryan Clinton

SEC EDGAR Scraper for RAG: 10-K/10-Q/8-K as JSON

devanshlive/sec-edgar-rag-extractor

Extract SEC EDGAR filings (10-K, 10-Q, 8-K). Fixed-token text chunks of primary documents for finance LLMs and compliance RAG. Drop-in for LlamaIndex, LangChain. Skip manual XBRL parsing. $0.03/filing.

Devansh Tiwari

MCP Server: SEC EDGAR (US Public Companies + 10-K, insider)

dltik/mcp-server-sec-edgar

Apify MCP server for AI agents: 6 tools to query SEC EDGAR. Search companies, get filings (10-K, 10-Q, 8-K, Form 4 insider), XBRL financials, full-text search. 10K+ public companies, free official data. $0.01/call.

dltik

SEC EDGAR Filings Scraper - 10-K, 10-Q, 8-K & More

wetyr_corporation/sec-edgar-filings-scraper

Bulk extract SEC EDGAR filings: 10-K annual reports, 10-Q quarterly, 8-K material events, S-1 IPO prospectuses, 13F holdings. Filter by ticker, CIK, form type. For hedge funds, equity research, AI/quant.

WETYR

TikTok Shop Scraper & Analytics | 2$/1k

pro100chok/tiktok-shop-scraper-usage

Scrape TikTok Shop at scale — products, sellers, reviews, search results and more. Clean JSON output, $2 per 1k results.

Raven

159

📑 SEC EDGAR Scraper — 10-K, 10-Q & Filings

nexgendata/sec-edgar-filings-scraper

Extract SEC EDGAR filings — 10-K, 10-Q, 8-K reports, insider transactions. Financial research and compliance monitoring.

Stephan Corbeil

SEC EDGAR Filings Scraper — 10-K, 10-Q, 8-K, Insider Form 4

seemuapps/sec-edgar-scraper

Scrape SEC filings for any US public company by ticker or CIK. 10-K annual reports, 10-Q quarterly reports, 8-K material events, Form 4 insider trades, S-1 IPO prospectuses, and more. Direct PDF/HTML links included.

Andrew

SEC EDGAR Filings Search - 10-K, 10-Q, 8-K Leads

pink_comic/sec-edgar-company-filings

Search SEC EDGAR public records for company filings. Track 10-K, 10-Q, 8-K, Form 4 insider trades by company name, ticker, or CIK. Government data from the SEC covering 10,400+ public companies. For equity analysts, compliance teams, and fintech developers. Schedule daily monitoring runs.

Ava Torres

.dockerignore

# Exclude from Docker build context (Apify Actor build).
# Anything not needed in the container = faster builds + smaller context upload.

node_modules
dist

# Local env / secrets — must never enter the image.
.env
.env.local

# Apify local-run artifacts (Apify CLI copies .actor/INPUT.json into storage/
# at run time; neither belongs in the container).
.actor/INPUT.json
storage

# Logs + git metadata.
*.log
.git
.gitignore

# Editor / OS junk.
.DS_Store
.vscode
.idea

.env.example

# ─── MCP Hub env reference (system-wide) ──────────────────────────────────
# Comments tell you WHERE each var actually lives at runtime:
#   [server]     = set in mcp-server process (Apify Actor env, local .env)
#   [supabase]   = set via `supabase secrets set …` (Edge Function runtime)
#   [github-act] = set in GitHub Actions repo secrets (cron workflows)
# Values are placeholders — substitute real ones during deploy.

# ─── Supabase (read-only) — used by mcp-server runtime + scripts ──────────
SUPABASE_URL=https://aevpcppnmceuxchsyeoz.supabase.co                # [server]
SUPABASE_ANON_KEY=eyJhbGc...                                          # [server]

# Service role — required for backfill scripts + test fixtures (anon key
# blocked by RLS on writes). DO NOT use in client code.
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...                                  # [server]

# ─── OpenAI (tagger backfill only) ────────────────────────────────────────
OPENAI_API_KEY=sk-...                                                 # [server]

# ─── Ops monitoring ───────────────────────────────────────────────────────
# All optional — missing vars degrade to console-only logs.
# Sentry only sends when NODE_ENV=production AND SENTRY_DSN is set.
SENTRY_DSN=https://xxxxxx@xxxxx.ingest.sentry.io/xxxxx                # [server]
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/yyy          # [server][supabase]
NODE_ENV=development                                                  # [server]

# ─── Paddle (Supabase Edge Functions only) ────────────────────────────────
# These live in Supabase secrets (NOT this file). Documented here so the
# system-wide env surface is in one place.
#   MCP_PADDLE_WEBHOOK_SECRET     [supabase] mcp-paddle-webhook — HMAC signature verify.
#                                       Source: Paddle Dashboard → Developer Tools → Notifications.
#   MCP_PADDLE_API_KEY            [supabase] top-up, balance-check, refund-check, auto-topup-trigger.
#                                       Source: Paddle Dashboard → Developer Tools → Authentication → API keys.
#   MCP_PADDLE_ENV                [supabase] "production" | "sandbox" (default production).
#   MCP_PADDLE_TOPUP_PRICE_10     [supabase] Paddle one-time price_id for $10 top-up.
#   MCP_PADDLE_TOPUP_PRICE_25     [supabase] $25
#   MCP_PADDLE_TOPUP_PRICE_50     [supabase] $50
#   MCP_PADDLE_TOPUP_PRICE_100    [supabase] $100

# ─── Resend (Supabase Edge Functions only) ────────────────────────────────
#   RESEND_API_KEY            [supabase] signup-trial + mcp-paddle-webhook welcome emails.
#                                       Source: Resend → API Keys.
#   WELCOME_EMAIL_FROM        [supabase] default "Korean Data MCP Hub <noreply@korean-data.com>".
#                                       From-domain must be verified in Resend DNS.

# ─── Admin tokens (Supabase Edge Functions only) ──────────────────────────
# Each generated independently — never reuse across functions (blast-radius isolation).
# Command: openssl rand -hex 32
#   REFUND_CHECK_ADMIN_TOKEN  [supabase] refund-check function (operator-only).
#   OPS_REPORT_ADMIN_TOKEN    [supabase] daily-ops-report (also [github-act] for cron).
#   AUTO_TOPUP_ADMIN_TOKEN    [supabase] auto-topup-trigger (operator-only).

# ─── Playground hardening (Supabase Edge Functions only) ──────────────────
#   PLAYGROUND_IP_HASH_SALT   [supabase] public-playground IP hash salt
#                                       (defeats IPv4 rainbow tables).
#                                       Command: openssl rand -hex 16

# ─── MCP user api_key (Apify Actor only) ──────────────────────────────────
# At runtime the Apify Actor entrypoint sets this from Actor input:
#   MCP_USER_API_KEY          [server] (set per-run, never committed)

# ─── Test bypass (smoke/CI only) ──────────────────────────────────────────
# QUOTA_BYPASS=1 short-circuits applyGuard (smoke tests). NEVER set in prod.
#   QUOTA_BYPASS=1

.gitignore

node_modules/
dist/
.env
.env.local
*.log

# Apify local-only artifacts (canonical INPUT lives in .actor/, but the SDK
# reads from ./storage at runtime — both are dev-only, never in git).
.actor/INPUT.json
storage/

APIFY_DEPLOY.md

1# Apify Actor — Deploy Guide
2
3Step-by-step push for `korean-data-mcp-hub` on Apify. Terminal commands +
4exact UI clicks. No deployment date assumed.
5
6---
7
8## Pre-flight (already in repo — just verify)
9
10```bash
11ls .actor/
12# expect: actor.json  Dockerfile  INPUT.json  README.md  input_schema.json
13```
14
15- `.actor/actor.json` — spec v1, `apify/actor-node:20` base, `timeoutSecs: 3600`
16- `.actor/Dockerfile` — Node 20, `npm ci` full install, `RUN npm run build`, `CMD node dist/actor_entry.js`
17- `.actor/input_schema.json` — `api_key` required field (`isSecret: true`)
18- `.actor/README.md` — Store page copy (Apify reads this for the public listing)
19- `.actor/INPUT.json` — local test input (gitignored, not pushed to cloud)
20
21---
22
23## Runtime environment variables (5 total, NOT 7)
24
25**Critical:** `SUPABASE_SERVICE_ROLE_KEY` and `OPENAI_API_KEY` are **NOT** needed at runtime:
26- `src/lib/supabase.ts` uses **`SUPABASE_ANON_KEY`** (anon + RLS protects reads)
27- `OPENAI_API_KEY` is only consumed by the backfill script `scripts/llm_tag_backfill.ts` — never by the Actor
28- Setting either on the Actor = needless attack surface
29
30| Var | Required? | Value | Where it lives |
31|-----|-----------|-------|----------------|
32| `SUPABASE_URL` | yes | `https://aevpcppnmceuxchsyeoz.supabase.co` | Apify Console (Source → Environment variables) |
33| `SUPABASE_ANON_KEY` | yes | `eyJ…` (Supabase Dashboard → Settings → API → anon public) | Apify Console (Secret ✅) |
34| `SENTRY_DSN` | optional | `https://xxx@xxx.ingest.sentry.io/xxx` | Apify Console (Secret ✅) |
35| `DISCORD_WEBHOOK_URL` | optional | `https://discord.com/api/webhooks/…` | Apify Console (Secret ✅) |
36| `NODE_ENV` | yes (= `production`) | already baked into `actor.json` `environmentVariables` | actor.json — no manual setting needed |
37
38`MCP_USER_API_KEY` is **NOT a static env var** — `src/actor_entry.ts` sets it dynamically from each run's Actor input (`api_key` field in `input_schema.json`).
39
40---
41
42## Step 1 — Apify CLI install (one-time)
43
44```bash
45npm install -g apify-cli
46apify --version    # expect: 0.x or 1.x
47```
48
49## Step 2 — Login (one-time)
50
51```bash
52apify login
53# Opens browser → authenticate with the account that will host the Actor
54# (teddyan35@gmail.com per project conventions)
55```
56
57## Step 3 — Verify the repo
58
59```bash
60cd /Users/teddyan/projects/kstar-automation/mcp-server
61apify info
62# Confirms detected Actor: korean-data-mcp-hub
63```
64
65If `apify info` errors with "no actor.json found", you're in the wrong directory.
66
67## Step 4 — First push (creates the Actor)
68
69```bash
70apify push
71# Builds in Apify's cloud (~2-3 min):
72#   1. Uploads source (gitignored files excluded via .gitignore)
73#   2. Runs Dockerfile (apify/actor-node:20 base → npm ci → npm run build)
74#   3. Tags the build as :latest
75# Output ends with: "Actor build successful" + actor URL
76```
77
78If the build fails: check the streamed log. Most common: missing `package-lock.json` (run `npm install` locally first), or TS error (run `npm run build` locally).
79
80## Step 5 — Set environment variables (5 → click)
81
82Apify Console → **Actor → Source → Environment variables → Add**
83
84| Key | Value | Secret? |
85|-----|-------|---------|
86| `SUPABASE_URL` | `https://aevpcppnmceuxchsyeoz.supabase.co` | No |
87| `SUPABASE_ANON_KEY` | (paste from Supabase Dashboard → Settings → API → `anon public`) | **Yes ✅** |
88| `SENTRY_DSN` | (paste from Sentry → Settings → Client Keys) — optional | **Yes ✅** |
89| `DISCORD_WEBHOOK_URL` | (paste from Discord channel webhook) — optional | **Yes ✅** |
90
91(`NODE_ENV=production` is already in `actor.json` `environmentVariables` — no manual setting needed.)
92
93⚠️ Do **NOT** set `SUPABASE_SERVICE_ROLE_KEY` or `OPENAI_API_KEY` here. Neither is read at runtime.
94
95⚠️ Do **NOT** set `MCP_USER_API_KEY` here. It's per-run, sourced from Actor input.
96
97## Step 6 — Smoke test (still private)
98
99In Apify Console → **Actor → Run** → paste input:
100
101```json
102{
103  "api_key": "kdmcp_test_..."
104}
105```
106
107Click **Start**. Expected log output within ~10 seconds:
108
109```
110INFO  System info {"apifyVersion":"x.x.x","nodeVersion":"v20.x.x",...}
111[kstar-mcp] connected via stdio, 25 tools registered (5 kpop + 20 category tools)
112```
113
114(The Actor will run until timeout because MCP stdio expects a client to send requests. That's expected — abort manually after the "connected via stdio" line.)
115
116Alternative — Apify CLI from your terminal:
117
118```bash
119apify call korean-data-mcp-hub --input '{"api_key":"kdmcp_test_..."}'
120```
121
122## Step 7 — Make public
123
124Apify Console → **Actor → Settings → General**:
125
126- Toggle **"Make this Actor public"** to ON
127- (Optional) **Pricing** — leave as "Free" (BYO user API key handles billing on our side)
128
129Public URL: `https://apify.com/upstanding_wax/korean-data-mcp-hub`
130
131## Step 8 — Apify Store submission
132
133Apify Console → **Actor → Publication tab**:
134
1351. **Display name**: `Korean Data MCP Hub`
1362. **Short description** (≤ 256 chars):
137   > 25 MCP tools for Korean media trends (K-Pop, K-Drama, K-Movie, K-Beauty, K-Food, K-Game, K-Tech, K-Stock, K-Travel, K-Webtoon). Native multilingual (EN/KO/JA/ES). Pre-classified content with 90%+ accuracy. Pay-per-call from $0.005.
1383. **Long description** — Apify auto-pulls from `.actor/README.md` (already comprehensive)
1394. **Categories**: `AI`, `Data extraction` (matches `.actor/actor.json` categories)
1405. **Keywords**: `korean`, `k-pop`, `k-drama`, `mcp`, `ai-agent`, `news`, `trends`, `multilingual`, `claude`, `cursor`
1416. **Pricing model**: `Free + BYO API key`
142   - Add note: "Free to run on Apify. You bring your own Korean Data MCP Hub API key — get $5 free credit at https://korean-data.com (no card required)."
1437. **Click "Submit for review"** → Apify reviews in 1-3 business days
144
145---
146
147## Post-publish — Sanity checks
148
149After Apify approves:
150
151```bash
152# Public Actor reachable?
153curl -s "https://api.apify.com/v2/acts/teddyan35~korean-data-mcp-hub" | jq .data.username
154# expect: "teddyan35"
155
156# Store listing live?
157open "https://apify.com/upstanding_wax/korean-data-mcp-hub"
158```
159
160---
161
162## Common failure modes
163
164| Symptom | Fix |
165|---------|-----|
166| `apify push` fails on `npm ci` | Local `npm install` first to regenerate `package-lock.json` |
167| `apify push` fails on `npm run build` | Local `npm run build` first to see the TS error |
168| Run logs show `MCP_USER_API_KEY not set` | Actor input missing `api_key` field — check input JSON |
169| Run logs show `SUPABASE_URL not set` | Skipped Step 5 — set env vars in Apify Console |
170| Run logs show `Invalid api_key` (401) | API key doesn't exist in `mcp_subscriptions`. Check the customer used the right key from `/welcome` or `/settings/mcp`. |
171| Runs hit `timeoutSecs: 3600` constantly | Apify Standby Mode is the long-term answer; short-term raise per-run timeout in Apify Console |
172
173---
174
175## Updating later
176
177```bash
178# Code change → rebuild + redeploy
179apify push
180# Existing env vars + settings persist. Same Actor, new build.
181```
182
183No need to re-do Steps 5-8 on updates. Apify Store listing updates auto from `.actor/README.md` on each push.

DEPLOYMENT.md

1# Korean Data MCP Hub — Deployment Guide
2
35월 30-31일 라이브 직전 배포 작업 = 이 가이드대로 진행.
4한 번에 끝까지 박는 게 목표 = 각 Step 검증 OK 받고 다음으로.
5
6`[TODO]` 마크 = 추측 불가 = 실시간 화면 확인 후 박을 부분.
7
8---
9
10## Prerequisites
11
12- [ ] Apify 계정 = `teddyan35@gmail.com` (로그인 상태)
13- [ ] Supabase 프로젝트 = `aevpcppnmceuxchsyeoz`
14- [ ] 도메인 = `korean-data.com` (Namecheap)
15- [ ] Paddle 계정 = K-Star Hub 공유 (Seller ID `334227`)
16- [ ] OpenAI API 키 = $10+ 잔액
17- [ ] GitHub repo = `teddyan35-create/kstar-mcp` (이미 push 완료)
18- [ ] Apify CLI 설치됨 (`apify --version` 확인. 없으면 `npm install -g apify-cli`)
19- [ ] Supabase CLI 설치됨 (`supabase --version`. 없으면 `brew install supabase/tap/supabase`)
20
21---
22
23## Step 0 — Pending Supabase 마이그레이션 적용
24
25작업 36/37에서 만든 SQL = 아직 미적용.
26
27```bash
28# 부모 레포에서
29cd ~/projects/kstar-automation
30
31# 1. system_config 테이블 (작업 36)
32# 2. mcp-paddle-webhook은 SQL 아님 = 함수 = Step 5에서 deploy
33```
34
35**Supabase Dashboard → SQL Editor → New query** 에 박을 파일:
36- `supabase/migrations/20260519_system_config.sql`
37
38확인 SQL:
39```sql
40SELECT key, value, description FROM system_config ORDER BY key;
41-- 결과 4행: trial_calls_limit=100, trial_per_call_limit=5,
42--          trial_date_window_days=7, trial_cooldown_hours=24
43```
44
45---
46
47## Step 1 — Lovable 랜딩 페이지 도메인 연결
48
491. Lovable 대시보드 → Korean Data MCP Hub 프로젝트
502. **Publish** 또는 **Connect Domain** 클릭
513. 도메인: `korean-data.com` 입력
524. Lovable이 표시하는 CNAME/A record 값 = 화면 캡처
53   - `[TODO]` Lovable 안내 화면대로 정확한 record 타입/값 확인
545. Namecheap → Domain List → korean-data.com → **Advanced DNS**
556. `[TODO]` Lovable이 표시한 record 그대로 박기 (보통 CNAME `www` → `xxx.lovable.app`, A record `@` → Lovable IP)
567. DNS 전파 = 5-30분 대기. 확인:
57   ```bash
58   dig korean-data.com +short
59   dig www.korean-data.com +short
60   ```
618. `https://korean-data.com` 브라우저 접속 = 랜딩 표시 + HTTPS 자물쇠 ✅
629. 페이지 내 검증:
63   - [ ] Sign up 버튼 → 회원가입 폼
64   - [ ] Pricing 섹션 = Starter $29 / Pro $79 / Business $199
65   - [ ] Docs / Status 링크 작동
66
67---
68
69## Step 2 — Apify Actor 빌드 + 배포
70
71```bash
72cd ~/projects/kstar-automation/mcp-server
73
74# 1. 로컬 build 확인 (사전 sanity)
75npm run build
76# → dist/index.js, dist/actor_entry.js 둘 다 생성 확인
77
78# 2. Apify 로그인 (한 번만)
79apify login
80# 브라우저 인증 → teddyan35@gmail.com
81
82# 3. Actor 배포
83apify push
84# = .actor/actor.json + Dockerfile + 전체 소스 업로드
85# = Apify 클라우드에서 Docker build 실행 (apify/actor-node:20 base)
86# = 빌드 로그 = 터미널에 스트리밍
87```
88
89빌드 실패 시 = 로그에서 에러 확인. 흔한 원인:
90- `npm ci` 실패 = `package-lock.json` 누락/손상 → 로컬에서 `npm install` 후 재push
91- `npm run build` 실패 = TS 에러 → 로컬 `npm run build` clean 확인 후 재push
92
93배포 성공 → Apify Console:
94- Actor 이름: `korean-data-mcp-hub`
95- URL: `https://console.apify.com/actors/[ACTOR_ID]`
96- `[TODO]` Actor 공개 설정 = "Public" 토글 ON (Store 노출)
97
98---
99
100## Step 3 — Apify Actor 환경변수 설정
101
102Apify Console → korean-data-mcp-hub → **Settings → Environment variables** → 다음 7개 박기:
103
104| Key | Value 출처 | Secret? |
105|---|---|---|
106| `SUPABASE_URL` | `https://aevpcppnmceuxchsyeoz.supabase.co` | No |
107| `SUPABASE_ANON_KEY` | Supabase Dashboard → Settings → API → `anon public` | Yes |
108| `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard → Settings → API → `service_role` (= 작업 38 captureError 컨텍스트 보강용 / quota RPC는 anon key 안 됨 → service role 필요) | Yes |
109| `OPENAI_API_KEY` | OpenAI dashboard. `sk-...` | Yes |
110| `SENTRY_DSN` | `[TODO]` Sentry 프로젝트 생성 후 DSN 복사 | Yes |
111| `DISCORD_WEBHOOK_URL` | `[TODO]` Discord 서버 → 채널 → Integrations → Webhooks → New | Yes |
112| `NODE_ENV` | `production` | No |
113
114⚠️ `MCP_USER_API_KEY`는 **박지 마라** — Actor input에서 사용자별 API key를 받아 entrypoint(`src/actor_entry.ts`)가 동적으로 set.
115
116---
117
118## Step 4 — Supabase Edge Function 배포 (mcp-paddle-webhook)
119
120```bash
121cd ~/projects/kstar-automation
122
123# 1. Supabase CLI 프로젝트 연결 (한 번만)
124supabase login
125supabase link --project-ref aevpcppnmceuxchsyeoz
126
127# 2. 함수 deploy (2개)
128# = --no-verify-jwt = Paddle / 브라우저는 JWT 안 보냄 = HMAC 또는 Paddle API로 인증
129supabase functions deploy mcp-paddle-webhook  --no-verify-jwt
130supabase functions deploy get-api-key         --no-verify-jwt
131supabase functions deploy signup-trial        --no-verify-jwt
132supabase functions deploy top-up              --no-verify-jwt
133supabase functions deploy balance-check       --no-verify-jwt
134supabase functions deploy auto-topup-trigger  --no-verify-jwt
135supabase functions deploy refund-check        --no-verify-jwt
136
137# 배포 URL:
138# - mcp-paddle-webhook   = Paddle transaction.completed webhook
139# - get-api-key          = /welcome 페이지에서 호출 (= top-up 완료 후 key/balance 표시)
140# - signup-trial         = 카드 없는 $5 trial credit 발급
141# - top-up               = Paddle Hosted Checkout URL 동적 생성
142# - balance-check        = AI agent가 본인 balance 자율 확인 (= api_key auth)
143# - auto-topup-trigger   = saved-card 자동 충전 (admin-token auth)
144# - refund-check         = 환불 정책 자동 분류 (admin-token auth)
145```
146
147`[TODO]` 기존 `paddle-webhook` (K-Star Hub 웹앱 결제) = **건드리지 마라.** 위 명령은 `mcp-paddle-webhook` + `get-api-key` 둘만 deploy.
148
149---
150
151## Step 5 — Supabase Secrets (Edge Function 환경변수)
152
153Paddle MCP product/price 먼저 생성 (Step 6.1) → 받은 price_id를 여기에 박음.
154
155```bash
156# Paddle webhook secret = Paddle 대시보드 → Notifications → endpoint 생성 후 받음
157supabase secrets set MCP_PADDLE_WEBHOOK_SECRET=pdl_ntfset_xxxxx
158
159# Top-up product price IDs = Paddle 대시보드 → Catalog → Products
160supabase secrets set MCP_PADDLE_TOPUP_PRICE_10=pri_xxxxx
161supabase secrets set MCP_PADDLE_TOPUP_PRICE_25=pri_xxxxx
162supabase secrets set MCP_PADDLE_TOPUP_PRICE_50=pri_xxxxx
163supabase secrets set MCP_PADDLE_TOPUP_PRICE_100=pri_xxxxx
164
165# Paddle API key (top-up, balance-check, refund-check, auto-topup-trigger)
166# Paddle 대시보드 → Developer Tools → Authentication → API keys → Create
167supabase secrets set MCP_PADDLE_API_KEY=pdl_apikey_xxxxx
168# sandbox 환경이면 추가:
169# supabase secrets set MCP_PADDLE_ENV=sandbox
170
171# Resend (mcp-paddle-webhook + signup-trial = welcome email 발송)
172# Resend 가입 → API Keys → Create → re_xxx 받음
173supabase secrets set RESEND_API_KEY=re_xxxxx
174# from 주소 = 디폴트 noreply@korean-data.com. 다른 주소 쓰면:
175# supabase secrets set WELCOME_EMAIL_FROM="Korean Data <hi@korean-data.com>"
176
177# Admin tokens (각자 별도 = 권한 분리)
178supabase secrets set REFUND_CHECK_ADMIN_TOKEN=$(openssl rand -hex 16)
179supabase secrets set AUTO_TOPUP_ADMIN_TOKEN=$(openssl rand -hex 16)
180supabase secrets set OPS_REPORT_ADMIN_TOKEN=$(openssl rand -hex 16)
181
182# 확인
183supabase secrets list
184# = 약 10개 표시 (SUPABASE_URL / SERVICE_ROLE_KEY는 자동 주입 = 별도 set 불필요)
185```
186
187⚠️ `MCP_PADDLE_WEBHOOK_SECRET` = K-Star Hub `paddle-webhook`의 secret과 **다름** = MCP endpoint 전용 secret.
188
189⚠️ Resend = `from:` 도메인이 verified 이어야 발송 성공.
190- Resend 대시보드 → **Domains → Add** → `korean-data.com` → DNS records (TXT/CNAME) 표시
191- Namecheap DNS에 박기 → Resend 대시보드에서 "Verify" 클릭 → 5-15분 후 verified
192- `[TODO]` 도메인 인증 미완료 시 = 임시로 `WELCOME_EMAIL_FROM=onboarding@resend.dev` 박으면 Resend test 도메인으로 발송 가능 (개발 검증용)
193
194---
195
196## Step 6 — Paddle 대시보드 설정
197
198### 6.1 MCP product / prices 생성 (v2 — one-time top-ups)
199
200⚠️ 가격 모델 v2 = **pay-per-call prepaid credit**. Paddle subscription 제품 X = one-time payment 제품만.
201
202Paddle Dashboard → **Catalog → Products → New product**:
203- Name: `Korean Data MCP Hub — Credit Top-Up`
204- Tax category: SaaS / Digital service
205
206각 충전 금액마다 **one-time price** 추가:
207- `[TODO]` $10 top-up → price_id 복사 → `MCP_PADDLE_TOPUP_PRICE_10`
208- `[TODO]` $25 top-up → `MCP_PADDLE_TOPUP_PRICE_25`
209- `[TODO]` $50 top-up → `MCP_PADDLE_TOPUP_PRICE_50`
210- `[TODO]` $100 top-up → `MCP_PADDLE_TOPUP_PRICE_100`
211
212⚠️ Trial ($5 free credit) = **Paddle 제품 X** = `signup-trial` Edge Function이 직접 INSERT (= 결제 안 일어남).
213
214⚠️ Enterprise (`$79`/`$199` monthly) = **별도 Paddle subscription products** (= 수동 영업, 자동 결제 안 함). 영업 후 = `is_enterprise=true` + `monthly_quota` 수동 UPDATE.
215
216### 6.1b Paddle Hosted Checkout — v2 = `top-up` Edge Function이 동적 생성
217
218v2 = Top-up 금액 4개 × CTA 4개 ≠ 정적 URL 4개. 대신 = `top-up` Edge Function 호출 = 매 결제마다 Paddle Hosted Checkout URL 동적 생성.
219
220**호출 흐름**:
2211. Lovable `/topup` 페이지 → 금액 버튼 클릭 → POST `https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/top-up`
222   ```json
223   {
224     "customer_id": "<existing paddle customer_id OR trial_xxx synthetic>",
225     "amount_usd": 10,
226     "email": "user@example.com",
227     "k_star_user_id": "<K-Star UUID>",
228     "ref": "<channel>",
229     "save_payment_method": true
230   }
231   ```
2322. 응답: `{ checkout_url: "https://pay.paddle.io/...", transaction_id, amount_usd }`
2333. Frontend = `window.location = checkout_url` (= 사용자 Paddle Hosted Checkout 으로 redirect)
2344. 결제 완료 → Paddle Success URL = `https://korean-data.com/welcome?transaction_id={transaction_id}` (Paddle이 자동 치환)
2355. `/welcome` 페이지 = `get-api-key` 호출 → API key + 새 balance 표시
236
237⚠️ Trial signup (= 카드 없음) = Paddle 거치지 X = Lovable이 `signup-trial` 직접 호출 = `{ api_key, balance_usd: 5 }` 즉시 받음.
238
239**Success URL + Cancel URL 설정** (Paddle Catalog → Product 상단):
240- Success URL: `https://korean-data.com/welcome?transaction_id={transaction_id}`
241- Cancel URL: `https://korean-data.com/topup?canceled=1`
242
243### 6.1c Lovable 랜딩 = Pricing v2 CTA + 트래픽 출처 추적
244
245**Pricing 페이지 (v2)** — 단일 메인 카드 = pay-per-call:
246- **$0.005 per call** | **$10 minimum top-up** | **$5 free trial credit** | **No card for trial**
247- CTA 메인: `[Start free (no card)]` → POST `signup-trial` (= Trial credit 즉시 발급)
248- CTA 보조: `[Top up $10]` → POST `top-up` (= Paddle Hosted Checkout)
249
250작은 글씨 = 엔터프라이즈 안내:
251- "Need 20,000+ calls/month? See enterprise plans →" → `/pricing/enterprise`
252
253⚠️ 임시 placeholder (`#`, `/signup`, 기존 subscription CTA 전부) = 제거.
254
255**트래픽 출처 (referrer) 추적**:
256
257각 채널별 = Paddle Checkout URL에 `?ref=<source>` 박음:
258
259| 채널 | `ref` 값 | 예 |
260|---|---|---|
261| Hacker News | `hn` | `…?custom_data[ref]=hn` |
262| Reddit r/ClaudeAI | `reddit_claude` | … |
263| Reddit r/mcp | `reddit_mcp` | … |
264| X (Twitter) | `x` | … |
265| Reddit Ads | `ad_reddit` | … |
266| korean-data.com Playground 위젯 | `playground` | … |
267| 직접 방문 / 출처 미상 | `direct` | … |
268
269**구현 옵션 (Lovable 측)**:
270- A. **각 채널별 별도 Paddle 링크 박음** = 가장 단순. 6-7개 링크 메모.
271- B. **공유 한 개 링크 + URL에 ref 동적 박음** = Lovable JS가 `document.referrer` 또는 `?utm_source=` 파싱해서 자동 부착. 더 정밀.
272
273`[TODO]` 어느 방식으로 박을지 = 라이브 직전 결정. 추천 = B (UTM 표준 + 동적).
274
275저장 위치 = `mcp_subscriptions.referrer` (자동 by mcp-paddle-webhook). 매일 `ops_daily_signups` view에서 referrer GROUP BY로 확인 = 어디서 결제됐는지 즉시 박힘.
276
277### 6.1d `/welcome` 페이지 = API key 표시
278
279Lovable에 `/welcome` 라우트 신규 추가:
2801. URL 파라미터 `transaction_id` 읽기
2812. POST `https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/get-api-key`
282   ```json
283   { "transaction_id": "<from URL>" }
284   ```
2853. 응답 `{ ok: true, api_key, status, tier }` 받음 → 화면에 박음
2864. 응답 `404` ("subscription not found … retry") → 3초 후 재시도 (webhook 지연)
2875. 응답 `401` ("transaction not verified") → "결제 정보 확인 실패" 메시지
288
289`[TODO]` Lovable에서 페이지 컴포넌트 작성. fetch 호출 예시:
290```js
291const res = await fetch("https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/get-api-key", {
292  method: "POST",
293  headers: { "Content-Type": "application/json" },
294  body: JSON.stringify({ transaction_id: new URLSearchParams(location.search).get("transaction_id") }),
295});
296const data = await res.json();
297```
298
299⚠️ 백업 경로 = Resend welcome email (Step 5). `/welcome` 못 보거나 새로고침 시 = 이메일로도 키 받음.
300
301### 6.2 Webhook endpoint 등록
302
303Paddle Dashboard → **Developer Tools → Notifications → New endpoint**:
304- URL: `https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/mcp-paddle-webhook`
305- Description: `MCP Hub subscriptions`
306- Events (5개 체크):
307  - `subscription.created`
308  - `subscription.activated`
309  - `subscription.updated`
310  - `subscription.canceled`
311  - `subscription.past_due` (선택적으로 `transaction.payment_failed` 추가)
312- **Save** → 생성된 endpoint secret 복사 → Step 5의 `MCP_PADDLE_WEBHOOK_SECRET`에 박기 (안 박았으면 지금)
313
314기존 `paddle-webhook` endpoint (K-Star Hub 웹앱용) = 별도 row로 그대로 유지.
315
316### 6.3 Seller 인증
317
318`[TODO]` Paddle Seller 인증 = 본인 신원증 + 사업자 정보 입력 = 별도 절차 (Paddle 대시보드 안내). 인증 완료 전엔 실제 결제 처리 안 됨.
319
320### 6.4 Lovable trust badges + Footer legal links
321
322**Pricing 페이지** = 메인 카드 하단 공통 배지 한 줄로:
323
324> ✓ 24-hour money-back on any top-up · 💳 Paddle MoR · 🇰🇷 Made by Korean dev
325
326**Hero 섹션** (랜딩 페이지 상단):
327
328> 🔒 Secure payments via Paddle · ↩ 24h refund on top-ups · 🎁 $5 free credit on signup
329
330⚠️ "unlimited refund" / "no questions asked forever" 같은 카피 **절대 박지 마라** = 정책 (legal/refund.md) 과 모순. 24h 무조건 환불은 **top-up 단위** = "Trial credit ($5)은 환불 X" 임을 작은 글씨에 박을 것.
331
332**Footer 링크 3개**:
333- `/terms` → `legal/terms.md` 내용 렌더 (또는 Markdown 변환된 페이지)
334- `/privacy` → `legal/privacy.md`
335- `/refund` → `legal/refund.md`
336
337Lovable는 정적 페이지로 markdown 컴포넌트 또는 별도 라우트로 박을 것.
338
339### 6.5 K-Star Hub `/settings/mcp` self-service page (Lovable)
340
341Reduces 1-인 운영 CS 부담 — 사용자가 quota / API key 직접 관리.
342
343**3개 신규 Supabase Edge Function**:
344- `GET  /functions/v1/mcp-user-keys`    — 구독 요약 + masked api_key
345- `GET  /functions/v1/mcp-user-usage`   — quota + daily breakdown + 최근 50건
346- `POST /functions/v1/mcp-revoke-key`   — api_key 회전
347
348모두 K-Star Supabase JWT 필요 (`Authorization: Bearer <jwt>` 헤더).
349
350```bash
351# 배포 (3개 동시) — JWT 검증 활성화 필수 = --no-verify-jwt 박지 마라
352supabase functions deploy mcp-user-keys
353supabase functions deploy mcp-user-usage
354supabase functions deploy mcp-revoke-key
355```
356
357**K-Star → MCP 매핑**: K-Star JWT의 `auth.users.email` 을 `mcp_subscriptions.email` 과 매치 (= Paddle 결제 시점 동일 이메일 가정). 메일 변경 시나리오는 별도 처리 필요.
358
359**Lovable 페이지 구조** (`/settings/mcp`):
360
3611. **구독 상태 카드** (= `mcp-user-keys` 응답):
362   - tier + status + `monthly_quota`
363   - `trial_ends_at` (trialing) 또는 `current_period_end` (active)
364
3652. **API key 섹션**:
366   - 기본 = masked (`kdmcp_XXXX...abcd`)
367   - "Reveal" 버튼 = 클릭 시 = 알림 "key는 회전 시점에만 표시됩니다 - 잃었으면 Revoke & Regenerate"
368   - "Revoke & Regenerate" 버튼 + 확인 모달:
369     - 모달 본문: "현재 키 즉시 무효화. 새 키 1회만 표시됨. 진행?"
370     - 확인 → POST `mcp-revoke-key` → 응답의 `new_api_key` 를 큰 글씨로 표시 + Copy 버튼 + 경고 "이 화면 닫으면 다시 못 봄"
371   - 동시에 Discord ops 알람 자동 발사
372
3733. **사용량 그래프** (= `mcp-user-usage`):
374   - `usage_pct` = 진행 바 (color: <80%=green, 80-100%=yellow, >100%=red)
375   - `daily_breakdown` = 최근 30일 막대 그래프
376   - `recent_calls` = 최근 50건 테이블 (`tool_name`, `called_at`)
377
3784. **결제 관리** = 기존 K-Star Hub 결제 페이지 링크
379
380`[TODO]` Lovable에서 페이지 컴포넌트 + 3개 fetch 호출 작성. JWT = K-Star Supabase Auth 세션에서 자동 (`supabase.auth.getSession()`).
381
382### 6.6 "Try It Live" public playground (랜딩 페이지)
383
384B2B SaaS API 제품의 신뢰 빌더 — 결제 전에 데이터 직접 만져 보게 함.
385
386**새 Supabase Edge Function** = `public-playground` (parent repo commit에서 생성).
387- GET `?category=<kpop|kdrama|...>&limit=3`
388- 인증 없음 (= 무료, 무로그인)
389- IP 기반 rate limit 5/min/IP (= `check_playground_rate` RPC)
390- 결과 hard cap = 3건
391- **데이터 = 7일 이상 된 것만** (= 실시간 누출 X)
392- `category_confidence` 등 LLM enrichment 응답에서 제거
393
394**배포** (= public endpoint = `--no-verify-jwt`):
395```bash
396# 0. SQL 마이그레이션 (rate-limit 테이블 + RPC) 먼저 적용
397#    supabase/migrations/20260520_playground_rate_limit.sql
398
399# 1. Edge Function deploy
400supabase functions deploy public-playground --no-verify-jwt
401
402# 2. IP hash salt (선택적이지만 권장 = IP rainbow table 방어)
403supabase secrets set PLAYGROUND_IP_HASH_SALT=$(openssl rand -hex 16)
404```
405
406**Lovable 랜딩 페이지 작업** (`[TODO]`):
407
408Hero 바로 아래 신규 섹션 "Try It Live (No Signup)":
409
410```
411┌─────────────────────────────────────────────────────────┐
412│  Try It Live                            [No signup]     │
413│                                                          │
414│  Category: [ K-Pop ▾ ]                                  │
415│                                                          │
416│           [ Fetch Latest Samples ]                       │
417│                                                          │
418│  ┌─────────────────────────────────────────────────┐   │
419│  │ { "samples": [ {...}, {...}, {...} ], ... }    │   │
420│  │  (pretty-printed JSON)                          │   │
421│  └─────────────────────────────────────────────────┘   │
422│                                                          │
423│  Sample data only. Subscribe for real-time + full       │
424│  features.                                               │
425└─────────────────────────────────────────────────────────┘
426```
427
428JavaScript (Lovable 컴포넌트):
429```js
430const cat = document.querySelector("#playground-category").value;
431const res = await fetch(
432  `https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/public-playground?category=${cat}&limit=3`,
433);
434if (res.status === 429) {
435  showMessage("Rate limit. Subscribe for unlimited access.");
436} else {
437  const data = await res.json();
438  showCodeBlock(JSON.stringify(data, null, 2));
439}
440```
441
442⚠️ 카테고리 11개 드롭다운 = `kpop / kdrama / kmovie / kbeauty / kfood / kgame / ktech / kstock / ktravel / kwebtoon / ktrends`.
443
444### 6.7 운영자(Teddy) 일일 대시보드
445
446매일 아침 한 번에 = 어제 매출 / 가입 / 사용량 / 이상 패턴 확인. Discord 알람과 별개 = 종합 일일 리포트.
447
448**구성**:
449- 6개 SQL views (parent repo: `supabase/migrations/20260520_ops_views.sql`)
450- 1개 Edge Function (`daily-ops-report`) = 6 views 모두 조회 + JSON 통합
451- 1개 GitHub Actions cron (parent repo: `.github/workflows/daily-report.yml`) = 매일 08:00 KST 자동 Discord 발사
452
453**배포**:
454```bash
455# 0. SQL views 적용 (Supabase Dashboard → SQL Editor)
456#    supabase/migrations/20260520_ops_views.sql
457
458# 1. Admin token (refund-check와 별도 = 권한 분리)
459supabase secrets set OPS_REPORT_ADMIN_TOKEN=$(openssl rand -hex 16)
460
461# 2. Function deploy (public 호출 X = --no-verify-jwt + admin-token 헤더로 fail-closed)
462supabase functions deploy daily-ops-report --no-verify-jwt
463```
464
465**수동 확인** (= 매일 아침 30초):
466```bash
467curl -H "X-Admin-Token: <your-token>" \
468  "https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/daily-ops-report" \
469  | jq
470```
471
472**응답 필드**:
473- `signups_last_24h` — 어제 가입자 수 (status별 + tier별 합산)
474- `active_subscribers` — 현재 살아있는 가입자 ({trialing, starter, pro, business})
475- `estimated_mrr_usd` — 이번 달 MRR 추정 (Paddle 데이터 X = mcp_subscriptions만으로 추정)
476- `total_calls_last_24h` + `top_tools_last_24h` (top 5)
477- `anomalies` — 1분 100+ calls 사용자 (봇 감지)
478- `high_usage_users` — quota 사용률 top 10 (upsell 타겟)
479- `near_trial_end` — 트라이얼 24h 내 만료 예정자
480
481**GitHub Actions cron 활성화**:
4821. parent repo (`teddyan35-create/kstar-automation`) → Settings → **Secrets and variables → Actions → New repository secret**
4832. `OPS_REPORT_ADMIN_TOKEN` = 위에서 만든 토큰 (= `supabase secrets`에 박은 값과 동일)
4843. Actions 탭 → **Daily Ops Report** → 첫 수동 발사 (`Run workflow`) → green ✅ 확인
4854. 이후 매일 08:00 KST 자동 = Discord `#alerts` 채널에 markdown 요약 박힘
486
487⚠️ `OPS_REPORT_ADMIN_TOKEN` ≠ `REFUND_CHECK_ADMIN_TOKEN`. 둘 다 별도 발급 권장 = 노출 시 영향 격리.
488
489---
490
491## Step 7 — Registry 6개 등록
492
493### 7.1 Apify Store (자동)
494Step 2에서 `apify push` + Public 토글 ON → 자동 등록.
495`https://apify.com/upstanding_wax/korean-data-mcp-hub` 페이지 확인.
496
497### 7.2 Smithery (자동)
498`smithery.yaml` + `README.md` 이미 push됨.
4991. https://smithery.ai 로그인 (GitHub OAuth)
5002. **Add server** → `teddyan35-create/kstar-mcp` repo 선택
5013. Smithery가 `smithery.yaml` 읽어 자동 빌드
5024. 공개 URL: `https://smithery.ai/server/korean-data-mcp-hub`
503
504### 7.3 Glama (자동)
505`README.md` 기반 크롤링.
5061. https://glama.ai → MCP servers → **Submit**
5072. GitHub repo URL: `https://github.com/teddyan35-create/kstar-mcp`
5083. 자동 메타데이터 추출 + 24-48h 후 게재
509
510### 7.4 Anthropic 공식 MCP Registry (수동 PR)
5111. `https://github.com/modelcontextprotocol/servers` fork
5122. README 또는 등록 디렉토리에 entry 추가
5133. PR body = `.registry/anthropic-pr-body.md` 내용 복붙
5144. 리뷰 ~1주 (사전 푸시 권장)
515
516### 7.5 MCP Compass (수동)
5171. `https://mcphub.io` 또는 `https://mcp-compass.xyz` 의 Submit 폼
5182. 입력값 = `.registry/server-metadata.json` 의 필드 그대로
519
520### 7.6 MCPfinder (수동)
5211. MCPfinder Submit 폼
5222. 입력값 = `.registry/server-metadata.json` 동일
523
524---
525
526## Step 8 — Healthcheck 크론 설정
527
528옵션 A = Apify Scheduler (권장 = 같은 인프라에서 실행):
5291. Apify Console → **Schedules → Create schedule**
5302. Cron expression: `*/15 * * * *` (15분마다)
5313. Actor: 별도 Actor 생성 (`korean-data-healthcheck`) 또는 기존 Actor에 input 분기
532   - `[TODO]` healthcheck 전용 Actor 따로 만들지, 같은 Actor에 mode flag로 분기할지 결정
5334. 환경변수: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `DISCORD_WEBHOOK_URL`
5345. 실패 시 = 스크립트가 `process.exit(1|2)` + Discord 알람 발화
535
536옵션 B = GitHub Actions cron:
537```yaml
538# .github/workflows/healthcheck.yml (=[TODO] 별도 PR로 박을 것)
539on:
540  schedule:
541    - cron: '*/15 * * * *'
542jobs:
543  health:
544    runs-on: ubuntu-latest
545    steps:
546      - uses: actions/checkout@v4
547      - uses: actions/setup-node@v4
548        with: { node-version: '20' }
549      - run: npm ci
550      - run: npm run healthcheck
551        env:
552          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
553          SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
554          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
555```
556
557---
558
559## Step 9 — K-Star Funnel 검증 + End-to-End Live Test
560
561### 9.1 K-Star Hub 웹앱 결제 = 영향 없는지 확인
5621. K-Star Hub 웹앱에서 기존 가입 흐름 1회 실행 (테스트 계정)
5632. Supabase `users` 테이블 = `plan_status=pro` 정상 update 확인
5643. = 기존 `paddle-webhook`이 mcp-paddle-webhook 추가로 영향 받지 않음 검증
565
566### 9.2 MCP Hub 신규 가입 + 결제 = E2E (credit 모델)
567
568#### 9.2.A — Trial signup (카드 없음)
5691. `https://korean-data.com` → "Start free" 클릭 → 이메일 입력 → POST `signup-trial`
5702. 응답 = `{ api_key, balance_usd: 5 }` 즉시 표시
5713. Supabase 확인:
572   ```sql
573   SELECT user_id, status, api_key, credit_balance_usd, total_topup_usd, email_verified
574   FROM mcp_subscriptions
575   ORDER BY created_at DESC LIMIT 1;
576   ```
577   기대값: `status='active'`, `credit_balance_usd=5.0000`, `total_topup_usd=0`, `user_id` starts with `trial_`
5784. 발급된 `api_key`로 Apify Actor 호출. tool 호출 1회 → Supabase 확인:
579   ```sql
580   SELECT credit_balance_usd FROM mcp_subscriptions WHERE api_key='kdmcp_...';
581   ```
582   기대값: `4.9950` (= 5 - 0.005)
5835. `search_news` (같은 query 2회) → 2회차 = `COOLDOWN_ACTIVE` (= trial cooldown 작동)
584
585#### 9.2.B — 첫 top-up (Paddle test card)
5861. 위 trial 사용자 → `/topup` → "$10" 클릭 → POST `top-up`
5872. 응답 = `{ checkout_url }` → window.location 으로 redirect
5883. Paddle Hosted Checkout → test card `4000 0000 0000 0002` 결제 완료
5894. Paddle Success URL → `/welcome?transaction_id=...` 도달
5905. `transaction.completed` webhook → `mcp-paddle-webhook` 처리:
591   ```sql
592   SELECT credit_balance_usd, total_topup_usd, last_topup_at FROM mcp_subscriptions
593   WHERE api_key='kdmcp_...';
594   SELECT amount_usd, is_auto_topup FROM mcp_topups
595   WHERE user_id=(SELECT user_id FROM mcp_subscriptions WHERE api_key='kdmcp_...')
596   ORDER BY created_at DESC LIMIT 1;
597   ```
598   기대: `credit_balance_usd ≈ 14.99` (= 4.99 + 10), `total_topup_usd = 10`, mcp_topups row `amount_usd=10, is_auto_topup=false`
5996. 같은 query 2회 search_news → 두 번 다 통과 (= paid user = cooldown 없음)
600
601#### 9.2.C — Auto-topup (선택 검증)
6021. 위 사용자 → `/settings/mcp` → auto-topup 토글 ON + threshold $5 + amount $10
6032. balance 가 $5 미만으로 떨어지도록 사용 (= 약 1,800 calls)
6043. POST `auto-topup-trigger { customer_id }` 수동 트리거 (또는 sweep 모드)
6054. Paddle saved card charge → 새 `transaction.completed` webhook → balance +$10
6065. ⚠️ Paddle 측 saved card 미저장 시 = `auto_topup` 실패 = Discord alert + 사용자 이메일
607
608### 9.3 Sentry / Discord 알람 작동 확인
609- 의도적 에러 유발 (잘못된 api_key 입력) → Sentry에 captureError 도달
610- `npm run healthcheck` 수동 실행 → 정상 시 stale 알람 없음 / DB 끊고 실행 시 error 알람
611
612### 9.4 Apify Actor timeout 검증
613
614현재 = `defaultRunOptions.timeoutSecs = 3600` (1시간). 라이브 직후 24h 안에 모니터링:
615
616- Apify Console → Actor → **Runs** → 평균 `Duration` 측정
617- Claude Desktop 세션의 실제 평균 길이 = 30분 정도 추정 → 1시간 충분
618- **Duration ≈ 3600s에 도달하는 run이 늘면** = 사용자가 1h 통째로 stdio 점유 = idle disconnect 처리 필요
619  - 단기 대응 = Apify Console run 단위로 timeoutSecs 즉시 raise (재배포 X)
620  - 장기 대응 = Apify Standby Mode + idle stdio timeout 5분 (= 별도 PR)
621- **Duration이 평균 5분 미만이면** = timeoutSecs를 낮춰 비용 절감 가능 (라이브 1주 후 측정)
622
623---
624
625## Step 10 — Marketing 발사
626
627### 10.1 Reddit posts (5/30 미국 동부 오전)
628- `r/ClaudeAI` — 제목: "I built an MCP server for real-time Korean media (K-Pop, K-Drama + 9 more) — 7-day free trial"
629- `r/mcp` — 제목: "Korean Data MCP Hub: 25 tools, 4 languages, cluster-deduped JSON"
630- 각 post 본문 = `[TODO]` 라이브 직전 작성 (README 요약 + 1개 demo screenshot + 가격 + Sign up 링크)
631- 댓글 = 첫 1시간 가장 중요 = 적극 응답
632
633### 10.2 X (Twitter) pinned tweet
634`[TODO]` 본문 + GIF demo 준비. 핵심 카피:
635> Just launched Korean Data MCP Hub — real-time K-pop/K-drama news for AI agents.
636> 25 tools, 4 languages, pre-clustered for 70-80% token savings.
637> 7-day free trial → korean-data.com
638
639### 10.3 Reddit Ads ($500 credit)
6401. https://ads.reddit.com → 새 캠페인
6412. Targeting: r/ClaudeAI, r/cursor, r/LocalLLaMA, r/SaaS, r/sideproject (Tier 1)
6423. Budget: $50/day × 10일 = $500
6434. Creative: 동일 demo GIF + "Real-time Korean media for Claude/Cursor"
6445. Landing: `https://korean-data.com/?utm_source=reddit&utm_campaign=launch`
645
646### 10.4 Product Hunt
647`[TODO]` 5/31 PT 12:01 AM 등록 (Reddit/X 24h 반응 본 후 결정)
648
649---
650
651## Step 11 — Emergency Manual Recovery (1인 운영 서바이벌 키트)
652
653라이브 첫 30일 = webhook 실패 / 사용자 키 분실 / 환불 처리 등 = 다음 SQL 그대로 박으면 해결. **모두 Supabase Dashboard → SQL Editor** 에서 실행.
654
655### 시나리오 1 — Paddle 결제 성공인데 mcp_subscriptions row 없음 (webhook 실패)
656
657```sql
658INSERT INTO mcp_subscriptions (
659  user_id, email, api_key, status, tier,
660  trial_started_at, trial_ends_at, monthly_quota, email_verified
661) VALUES (
662  '<paddle_customer_id>',
663  '<email>',
664  'kdmcp_' || replace(gen_random_uuid()::text, '-', ''),
665  'trialing',
666  '<starter|pro|business>',
667  NOW(),
668  NOW() + INTERVAL '7 days',
669  100,
670  true
671)
672ON CONFLICT (user_id) DO NOTHING
673RETURNING api_key;
674```
675
676Paddle webhook log 먼저 확인 → 재배달 가능하면 = `mcp-paddle-webhook` 자동 처리가 우선. 위 SQL은 webhook이 끝까지 실패할 때만.
677
678### 시나리오 2 — 사용자: "Welcome 페이지를 못 봤어요 / 키를 잃었어요"
679
680```sql
681SELECT api_key, status, tier, api_key_last_viewed_at
682FROM mcp_subscriptions
683WHERE email = '<email>'
684   OR user_id = '<paddle_customer_id>';
685```
686
687⚠️ 평문 키 전달 = 안전한 채널만 (= K-Star `/settings/mcp` 페이지 또는 본인 인증 후 1:1 DM). Slack/Discord 일반 채널 절대 X. 더 안전한 옵션 = 사용자에게 시나리오 3 (회전)으로 안내.
688
689### 시나리오 3 — API key 회전 (사용자 요청 or 키 노출 의심)
690
691```sql
692UPDATE mcp_subscriptions
693SET api_key = 'kdmcp_' || replace(gen_random_uuid()::text, '-', ''),
694    api_key_last_viewed_at = NULL
695WHERE user_id = '<paddle_customer_id>'
696   OR email = '<email>'
697RETURNING api_key;
698```
699
700`api_key_last_viewed_at = NULL` 박는 이유 = `/welcome` 또는 `mcp-revoke-key` 응답에서 `first_view: true` 트리거 = "save this now" UX 다시 발사.
701
702### 시나리오 4 — Subscription 강제 취소 (어뷰즈 대응)
703
704```sql
705UPDATE mcp_subscriptions
706SET status = 'canceled',
707    updated_at = NOW()
708WHERE user_id = '<paddle_customer_id>';
709```
710
711⚠️ 환불 처리는 별도 = `refund-check` Edge Function 호출 → Paddle 대시보드 수동 환불. 위 SQL은 즉시 API 차단만.
712
713### 시나리오 5 — k_star_user_id 수동 매핑 (이메일 변경 사용자)
714
715```sql
716UPDATE mcp_subscriptions
717SET k_star_user_id = '<new_k_star_uuid>'
718WHERE email = '<old_email>'
719  AND k_star_user_id IS NULL;
720```
721
722K-Star 사용자가 이메일 변경 후 `/settings/mcp` 매핑 깨질 때.
723
724### 시나리오 6 — Credit 수동 부여 (CS 보상 / 프로모션)
725
726```sql
727UPDATE mcp_subscriptions
728SET credit_balance_usd = credit_balance_usd + 5.00,
729    updated_at = NOW()
730WHERE email = '<email>'
731RETURNING credit_balance_usd;
732```
733
734⚠️ `total_topup_usd` 는 안 건드림 = "유료 사용자" 카운트와 다른 분류 유지.
735
736### 시나리오 7 — 환불 후 Credit 차감
737
738```sql
739UPDATE mcp_subscriptions
740SET credit_balance_usd = GREATEST(0, credit_balance_usd - <refunded_amount_usd>),
741    total_topup_usd    = GREATEST(0, total_topup_usd    - <refunded_amount_usd>),
742    updated_at         = NOW()
743WHERE user_id = '<paddle_customer_id>';
744```
745
746Paddle 대시보드에서 환불 실행 후 = 우리 DB에서도 차감. `refund-check` 함수가 추천하는 금액 사용.
747
748---
749
750## Step 12 — Lovable: `/topup` + `/pricing/enterprise` 페이지
751
752가격 모델 v2 = pricing 페이지 + 두 페이지 신규.
753
754### 12.1 `/topup` 페이지
755
756레이아웃:
757```
758┌──────────────────────────────────────────────────┐
759│  Top up your credit                              │
760│                                                  │
761│  Current balance: $4.97 (~994 calls)             │
762│                                                  │
763│  [ $10  ]   [ $25  ]   [ $50  ]   [ $100 ]      │
764│   2,000     5,000      10,000     20,000        │
765│   calls     calls      calls      calls         │
766│                                                  │
767│  ☐ Enable auto top-up (saves payment method)     │
768│                                                  │
769│           [ Continue to checkout ]               │
770└──────────────────────────────────────────────────┘
771```
772
773JS:
774```js
775const res = await fetch("https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/top-up", {
776  method: "POST",
777  headers: { "Content-Type": "application/json" },
778  body: JSON.stringify({
779    customer_id: currentSession.paddleCustomerId,
780    amount_usd: selectedAmount,
781    email: currentSession.email,
782    k_star_user_id: currentSession.kStarUserId,
783    ref: getQueryParam("ref") || "direct",
784    save_payment_method: autoTopupCheckbox.checked,
785  }),
786});
787const { checkout_url } = await res.json();
788window.location.href = checkout_url;
789```
790
791⚠️ `save_payment_method: true` = 자동 충전 가입 = Paddle Vault에 카드 저장. 사용자에게 체크박스로 명시 동의 받아야 함.
792
793### 12.2 `/pricing/enterprise` 페이지
794
795레이아웃:
796```
797┌──────────────────────────────────────────────────┐
798│  Enterprise Plans (flat-rate monthly)            │
799│                                                  │
800│  Enterprise Pro      Enterprise Business         │
801│  $79/month           $199/month                  │
802│  20,000 calls/mo     50,000 calls/mo             │
803│  Volume discount     SLA + custom limits         │
804│                                                  │
805│  [ Contact sales ]                               │
806│                                                  │
807│  For higher volume: enterprise@korean-data.com   │
808└──────────────────────────────────────────────────┘
809```
810
811CTA = 폼 또는 mailto 링크 (= Paddle 자동 결제 안 함 = 수동 영업). 문의 접수 후 = 직접 Paddle Subscription 만들고 `is_enterprise = true`, `monthly_quota = 20000/50000` 수동 UPDATE.
812
813### 12.3 `/welcome` 페이지 (= top-up 완료 도착 페이지) 갱신
814
815기존 `/welcome` (작업 46) = `transaction_id` → `get-api-key` 호출. v2에서 응답 형식 확장됨:
816```js
817const data = await res.json();
818// data.api_key, data.first_view
819// v2 추가: data.credit_balance_usd, data.total_topup_usd, data.is_trial
820showBalance(data.credit_balance_usd);
821if (data.first_view) showSaveKeyWarning(data.api_key);
822```
823
824`first_view=true` 시 = "이 화면 닫으면 키 다시 못 봐. 지금 저장해." UX 강조.
825
826### 12.4 `/settings/mcp` 페이지 갱신 (= 작업 49 → v2)
827
828기존 섹션 + 신규:
829
830| 섹션 | 함수 호출 | 표시 |
831|---|---|---|
832| 구독 상태 | GET `mcp-user-keys` | tier (= `null` 이면 "Pay-per-call"), status, masked api_key |
833| **잔액** (신규) | GET `balance-check?api_key=<masked키X = full session 가져온 key>` | balance_usd, approx_calls_remaining, is_trial |
834| 사용량 | GET `mcp-user-usage` | usage_pct, daily_breakdown, recent_calls |
835| **충전 이력** (신규) | direct query `mcp_topups` (또는 K-Star Edge Function 추가) | amount_usd, created_at, is_auto_topup |
836| **자동 충전 설정** (신규) | direct UPDATE via K-Star Edge Function | toggle ON/OFF, threshold input, amount input |
837| API key 회전 | POST `mcp-revoke-key` | 새 키 1회 표시 |
838
839`[TODO]` 자동 충전 토글/threshold/amount UPDATE 용 Edge Function = 별도 추가 필요 (= 현재는 SQL로만 변경 가능). 라이브 후 우선순위 박을 것.
840
841---
842
843## Rollback Plan
844
845### Rollback A — Apify Actor 문제
846Apify Console → Actor → **Builds** → 이전 빌드 → **Set as latest**.
847또는 git revert + `apify push` 다시.
848
849### Rollback B — mcp-paddle-webhook 문제
850즉시:
851```bash
852# 함수 일시 비활성화 = Paddle 대시보드에서 webhook endpoint 토글 OFF
853# (코드 deploy 보다 빠름 = Paddle 측에서 송신 중단)
854```
855영구:
856```bash
857# 이전 버전 git checkout 후
858supabase functions deploy mcp-paddle-webhook --no-verify-jwt
859```
860주의: 이미 발생한 결제는 Paddle 대시보드에서 수동 처리 또는 webhook 재발송 트리거.
861
862### Rollback C — 도메인 / 랜딩 문제
863Lovable 대시보드에서 이전 Publish 버전으로 revert.
864또는 Namecheap DNS를 임시 메인터넌스 페이지로 전환.
865
866### Rollback D — Supabase RPC / 쿼터 시스템 문제
867**환경변수 임시 토글**: Apify Actor env에 `QUOTA_BYPASS=1` 추가 → 모든 호출 통과.
868= 안전망 = 결제·인증은 건너뛰지만 라이브 유지 가능 = 그 사이에 root cause 디버깅.
869복구 후 = `QUOTA_BYPASS` env 제거.
870
871### Emergency 정지
8721. Apify Actor → Stop 모든 Run
8732. Paddle webhook endpoint OFF
8743. Discord 알람 채널에 incident 박기
8754. korean-data.com landing → "Temporarily unavailable" 안내 (Lovable에서 페이지 교체)
876
877---
878
879## 최종 Go/No-Go 체크리스트
880
881라이브 직전 (5/30 발사 1시간 전):
882
883- [ ] Step 0 = `system_config` 4행 SELECT 확인
884- [ ] Step 1 = `https://korean-data.com` HTTPS 접속 OK
885- [ ] Step 2 = Apify Actor 빌드 success + Public ON
886- [ ] Step 3 = Apify env 7개 박힘 + `MCP_USER_API_KEY` 없음 확인
887- [ ] Step 4 = mcp-paddle-webhook + get-api-key deploy success
888- [ ] Step 5 = `supabase secrets list` = 6개 (MCP_PADDLE_WEBHOOK_SECRET, MCP_PADDLE_PRICE_*, MCP_PADDLE_API_KEY, RESEND_API_KEY)
889- [ ] Resend 도메인 verified (또는 `WELCOME_EMAIL_FROM=onboarding@resend.dev` 임시)
890- [ ] Lovable `/welcome` 페이지 = get-api-key 호출 동작 확인 (placeholder transaction_id로 401 응답이라도 나면 routing OK)
891- [ ] Step 6 = Paddle endpoint Active + 5 events + Seller 인증 완료
892- [ ] Step 7.1 = Apify Store 페이지 노출
893- [ ] Step 9.2 = E2E test 1회 success (`mcp_subscriptions` 새 row + MCP call 성공)
894- [ ] Step 9.3 = Sentry 1건 도달 / Discord 알람 1건 발사 검증
895- [ ] Healthcheck cron 작동 (Apify Schedules에서 마지막 run timestamp 확인)
896
897전부 ✅면 → Step 10 발사.

MONITORING_SETUP.md

1# Monitoring Setup Guide
2
35/30 라이브 직전 = `DISCORD_WEBHOOK_URL` + `SENTRY_DSN` 발급 + 배포 위치별 박기.
4
5## 1. Discord Webhook 발급
6
7### Step 1 — Discord 서버 생성 (또는 기존 서버 사용)
81. Discord 앱 열기
92. 좌측 = "+" 아이콘 → "Create My Own" → "For me and my friends"
103. Server name: `Korean Data MCP Ops`
114. **Create**
12
13### Step 2 — 채널 Webhook 생성
141. `#general` 채널 (또는 새 채널 `#alerts` 생성 권장)
152. 채널 우클릭 → **Edit Channel**
163. 좌측 = **Integrations** → **Webhooks**
174. **New Webhook**
185. Name: `MCP Hub Alerts`
196. **Copy Webhook URL**
207. URL 형식: `https://discord.com/api/webhooks/...`
218. 메모장에 저장
22
23### Step 3 — Supabase secrets에 박기
24```bash
25supabase secrets set DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
26```
27
28### Step 4 — Apify Actor env에 박기
29- Apify Console → Actor → **Settings → Environment variables**
30- `DISCORD_WEBHOOK_URL` = (위 URL)
31
32### 테스트
33```bash
34cd ~/projects/kstar-automation/mcp-server
35DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... npm run healthcheck
36```
37→ Discord 채널에 알람 메시지 박히면 OK.
38
39⚠️ 알람은 `stories_last_1h === 0` 이거나 `db_latency_ms > 1000` 일 때만 발화 (healthcheck 정상 시엔 메시지 없음). 강제 발화 원하면 헬스체크 시점에 DB가 stale이거나 잠시 Supabase 연결을 차단한 채 실행.
40
41---
42
43## 2. Sentry DSN 발급
44
45### Step 1 — Sentry 가입
461. https://sentry.io 접속
472. **Get Started** → GitHub OAuth (`teddyan35-create`)
48
49### Step 2 — 프로젝트 생성
501. **Create Project**
512. Platform: **Node.js**
523. Alert frequency: **Alert me on every new issue**
534. Project name: `korean-data-mcp-hub`
545. **Create Project**
55
56### Step 3 — DSN 받기
571. 프로젝트 생성 직후 setup 화면에 DSN 표시
582. 형식: `https://xxx@xxx.ingest.sentry.io/xxx`
593. 메모장에 저장
604. 이후엔 **Settings → Client Keys (DSN)** 에서 재확인 가능
61
62### Step 4 — 박기
63```bash
64# Supabase secrets (= mcp-paddle-webhook은 Sentry 직접 안 씀 = optional)
65supabase secrets set SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
66
67# Apify Actor env (= MCP 서버가 Sentry 쓰는 주된 곳)
68SENTRY_DSN  = (위 DSN)
69NODE_ENV    = production
70```
71
72⚠️ `src/lib/monitoring.ts` 정책: `NODE_ENV=production` **AND** `SENTRY_DSN` 둘 다 있어야 실제 send. 둘 중 하나라도 없으면 console.error 로만 출력 (= 로컬/CI 보호 장치).
73
74### Step 5 — 테스트
75실제 Sentry 도달 검증은 예외가 발생해야 함. 옵션 2가지:
76
77**옵션 A** — 실제 tool 호출에서 예외 유발:
78```bash
79# 잘못된 SUPABASE_URL로 실행 → tool handler 내부에서 throw
80SUPABASE_URL=https://invalid.supabase.co \
81SUPABASE_ANON_KEY=invalid \
82SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx \
83NODE_ENV=production \
84QUOTA_BYPASS=1 \
85npm run smoke:test
86```
87
88**옵션 B** — 1회용 테스트 스니펫:
89```bash
90NODE_ENV=production SENTRY_DSN=https://... node -e "
91  import('./dist/lib/monitoring.js').then(m => {
92    m.initSentry();
93    m.captureError(new Error('sentry connection test'), { tool_name: 'smoke' });
94    setTimeout(() => process.exit(0), 2000);
95  });
96"
97```
98
99→ Sentry 대시보드 → **Issues** = 새 이벤트 박히면 OK (전송까지 2-5초).
100
101---
102
103## 3. Healthcheck Cron — GitHub Actions
104
105이 repo (`teddyan35-create/kstar-mcp`)에 `.github/workflows/healthcheck.yml` 등록됨 (이 가이드 PR과 동시).
106
107**스케줄**: 매 30분 자동 실행 + `workflow_dispatch` 수동 트리거.
108
109### GitHub Actions secrets 박을 거
110
111GitHub repo → **Settings → Secrets and variables → Actions → New repository secret**:
112
113| Secret | Value |
114|---|---|
115| `SUPABASE_URL` | `https://aevpcppnmceuxchsyeoz.supabase.co` |
116| `SUPABASE_ANON_KEY` | Supabase Dashboard → Settings → API → `anon public` |
117| `DISCORD_WEBHOOK_URL` | Discord webhook URL (Section 1) |
118| `SENTRY_DSN` | Sentry DSN (Section 2) |
119
120박은 후 → Actions 탭 → **MCP Hub Healthcheck** → **Run workflow** 로 1회 수동 발사 → green check ✅.
121
122이후 = 매 30분 자동 + Discord 알람 (stale/latency 임계 초과 시).
123
124---
125
126## 4. 모니터링 대시보드 URL
127
128| 서비스 | URL |
129|--------|-----|
130| Sentry | `https://sentry.io/organizations/<your-org>/issues/` |
131| Discord | 너 서버 `#alerts` 채널 |
132| Supabase | `https://supabase.com/dashboard/project/aevpcppnmceuxchsyeoz` |
133| GitHub Actions | `https://github.com/teddyan35-create/kstar-mcp/actions` |
134| Apify Console | `https://console.apify.com/actors` |
135
136---
137
138## 5. 검증 체크리스트
139
140라이브 후 첫 24시간:
141
142- [ ] Discord `#alerts` 채널 = 30분마다 healthcheck 결과 (정상 시 = 메시지 없음 = 정상)
143- [ ] DB stale 인위 발생 시 = 🚨 메시지 박힘 검증 완료
144- [ ] Sentry 대시보드 = 첫 실제 에러 1건 도달 확인
145- [ ] GitHub Actions → **MCP Hub Healthcheck** = 매 30분 green ✅
146- [ ] Apify Console → Actor logs = `[monitoring] Sentry initialized.` 로그 확인 (= prod env에서 init 성공 증거)

POST_LAUNCH_24H.md

1# Post-Launch — First 24 Hours Playbook
2
3What to check at hour 1 / 6 / 12 / 24 + 6 emergency scenarios with the
4exact SQL / commands to run. Treat this as the runbook beside the laptop.
5
6---
7
8## Hour 1 — All systems green check
9
10Goal: confirm the pipeline didn't break the moment real traffic hit.
11
12### 1.1 Apify Actor
13- Apify Console → Actor → **Runs** tab
14- At least 1 run with status `RUNNING` or `SUCCEEDED` (= someone connected via Claude Desktop / Apify Run UI)
15- Open the run log — look for `[kstar-mcp] connected via stdio, 25 tools registered`
16- ❌ If `EXIT_CODE 1` immediately → check Run input has `api_key` field
17
18### 1.2 GitHub Actions
19- https://github.com/teddyan35-create/kstar-mcp/actions → **MCP Hub Healthcheck**
20- Latest run = green ✅. 5-min cadence visible (next run = ~5min after last).
21- If RED → click the run → see which step failed (most likely: SUPABASE_ANON_KEY mismatch)
22
23### 1.3 Supabase
24```sql
25-- functions reachable?
26SELECT routine_name FROM information_schema.routines
27WHERE routine_name IN ('check_and_charge_credit','check_and_record_usage','check_playground_rate');
28-- expect 3 rows
29
30-- any signups in last hour?
31SELECT count(*) FROM mcp_subscriptions WHERE created_at > NOW() - INTERVAL '1 hour';
32
33-- any tool calls in last hour?
34SELECT count(*) FROM mcp_usage WHERE called_at > NOW() - INTERVAL '1 hour';
35```
36
37### 1.4 Discord
38- Channel = mostly quiet
39- One `🚨 No new stories in the last hour` is OK if scraper hasn't run yet (= K-Star scraper, not our problem)
40- Repeated `RPC failure` or `auto-topup FAILED` = real issue → jump to scenarios below
41
42---
43
44## Hour 6 — Discord alert pattern
45
46Goal: pattern-match the noise. Decide if any alerts are signal vs. noise.
47
48Expected alerts (= noise, not signal):
49- 🚨 `No new stories in the last hour` — fires when K-Star scraper has a quiet hour (happens daily at 03-04 KST)
50- 📊 Per-tool stats from `daily-ops-report` (= 08:00 KST = won't fire yet at hour 6)
51
52Real signal (= investigate):
53- 🚨 `RPC failure (… tool name …) — fail-open activated` — Supabase RPC misbehaving. **Check scenario 2 below.**
54- 🚨 `Auto-topup FAILED for …` — Paddle saved-card rejected. **Check scenario 3 below.**
55- 🚨 `DB latency NNNms (>1000ms)` — Supabase slowdown. Check Supabase status page.
56- ⚠️ `User <customer_id> balance below threshold` — normal — fires whenever auto-topup-enabled user dips below $5. **Not an action item** unless they also fail to top up.
57
58```sql
59-- See your healthcheck history (if you've configured Sentry):
60-- Sentry → Issues → filter project=korean-data-mcp-hub
61```
62
63---
64
65## Hour 12 — Signup velocity
66
67Goal: are people actually signing up? Where from?
68
69```sql
70-- last 12 hours by status + tier
71SELECT status, tier, COUNT(*)
72FROM mcp_subscriptions
73WHERE created_at > NOW() - INTERVAL '12 hours'
74GROUP BY status, tier
75ORDER BY 3 DESC;
76
77-- last 12 hours by referrer (= acquisition channel)
78SELECT referrer, COUNT(*)
79FROM mcp_subscriptions
80WHERE created_at > NOW() - INTERVAL '12 hours'
81GROUP BY referrer
82ORDER BY 2 DESC;
83
84-- emails of recent signups (for debugging duplicates / churn)
85SELECT email, status, created_at, total_topup_usd
86FROM mcp_subscriptions
87WHERE created_at > NOW() - INTERVAL '12 hours'
88ORDER BY created_at DESC
89LIMIT 50;
90```
91
92Decision: if signup count is 0 after 12h → marketing not reaching audience. If signups but 0 top-ups → /welcome page or API key UX broken.
93
94---
95
96## Hour 24 — First-day revenue + retention
97
98Goal: how much money came in, how engaged are new users.
99
100```sql
101-- top-ups in last 24h (total revenue)
102SELECT
103  COUNT(*) AS topup_count,
104  COALESCE(SUM(amount_usd), 0) AS revenue_usd,
105  COALESCE(AVG(amount_usd), 0)::NUMERIC(10,2) AS avg_topup_usd,
106  COUNT(*) FILTER (WHERE is_auto_topup) AS auto_topups
107FROM mcp_topups
108WHERE created_at > NOW() - INTERVAL '24 hours';
109
110-- conversion = signups who topped up
111SELECT
112  (SELECT COUNT(*) FROM mcp_subscriptions WHERE created_at > NOW() - INTERVAL '24 hours') AS signups,
113  (SELECT COUNT(*) FROM mcp_subscriptions WHERE created_at > NOW() - INTERVAL '24 hours' AND total_topup_usd > 0) AS converted;
114
115-- tool usage distribution
116SELECT tool_name, COUNT(*) AS calls, COUNT(DISTINCT user_id) AS unique_users
117FROM mcp_usage
118WHERE called_at > NOW() - INTERVAL '24 hours'
119GROUP BY tool_name
120ORDER BY 2 DESC
121LIMIT 10;
122
123-- balance distribution (= ops_credit_balances view if migration #10 applied)
124SELECT * FROM ops_credit_balances;
125```
126
127---
128
129## Emergency scenarios (6)
130
131### Scenario 1 — Apify Actor crashed mid-session
132
133**Symptoms**:
134- Apify Console → Runs → status `FAILED` repeatedly
135- Sentry shows `Error: ...` from `dist/actor_entry.js` or a tool handler
136- Users report "Claude Desktop says MCP server disconnected"
137
138**Action**:
139```bash
140# 1. Check Apify run logs for the error
141#    Apify Console → Actor → Runs → click failing run → Log tab
142
143# 2. If TS/runtime error:
144#    Roll back to previous build:
145apify build set-default <previous_build_number>
146#    (Or push a hotfix: edit code → apify push → set as default build)
147
148# 3. If env var missing:
149#    Apify Console → Source → Environment variables → re-add the missing one
150
151# 4. If a third-party (Supabase / OpenAI) is the root cause → scenario 2 or 4
152```
153
154### Scenario 2 — Supabase function returning 5xx
155
156**Symptoms**:
157- Discord: `RPC failure (...) — fail-open activated`
158- Healthcheck workflow: red runs every 5 min
159- Sentry: spike of `DB_ERROR` from quota_guard
160
161**Action**:
162```bash
163# 1. Supabase status page first — global outage?
164open "https://status.supabase.com"
165
166# 2. If just our project, check function logs:
167#    Supabase Dashboard → Edge Functions → click the failing one → Logs tab
168
169# 3. Common causes + fixes:
170#    (a) Missing secret after redeploy → check `supabase secrets list`
171#        Re-add: supabase secrets set XXX=value
172#    (b) RPC referenced doesn't exist → re-apply the migration from
173#        supabase/migrations/README_MIGRATIONS.md
174#    (c) Connection pool exhausted (rare at our scale) → restart project
175#        from Supabase Dashboard → Project Settings → Restart Project
176
177# 4. While debugging — fail-open already protects paid users for the
178#    first 60s per process; persistent failure → SERVICE_UNAVAILABLE
179#    until recovery (designed behavior, no need to panic)
180```
181
182### Scenario 3 — Paddle webhook failures (transactions arriving, balances not crediting)
183
184**Symptoms**:
185- User reports "I paid but my balance didn't go up"
186- Paddle Dashboard → Notifications → endpoint shows `failed` deliveries
187- `mcp_topups` table has no row for the transaction
188
189**Action**:
190```bash
191# 1. Check Paddle delivery status
192#    Paddle Dashboard → Developer Tools → Notifications →
193#    your endpoint → Recent deliveries
194
195# 2. If signature mismatch:
196#    Supabase Console → Secrets → MCP_PADDLE_WEBHOOK_SECRET — does it match
197#    the Paddle endpoint's "Endpoint secret"? Rotate if not.
198
199# 3. Re-deliver the missed event:
200#    Paddle Dashboard → click the failed delivery → "Resend"
201
202# 4. Manual recovery while waiting (= Step 11 scenario 1 in DEPLOYMENT.md):
203```
204```sql
205-- backfill mcp_subscriptions if user has paid but no row exists
206INSERT INTO mcp_subscriptions (
207  user_id, email, api_key, status, credit_balance_usd, total_topup_usd,
208  email_verified, last_topup_at
209) VALUES (
210  '<paddle_customer_id>',
211  '<email>',
212  'kdmcp_' || replace(gen_random_uuid()::text, '-', ''),
213  'active', 10.00, 10.00, true, NOW()
214)
215ON CONFLICT (user_id) DO UPDATE
216  SET credit_balance_usd = mcp_subscriptions.credit_balance_usd + 10.00,
217      total_topup_usd    = mcp_subscriptions.total_topup_usd + 10.00,
218      last_topup_at      = NOW()
219RETURNING api_key, credit_balance_usd;
220
221INSERT INTO mcp_topups (user_id, amount_usd, paddle_transaction_id, is_auto_topup)
222VALUES ('<paddle_customer_id>', 10.00, '<paddle_tx_id>', false)
223ON CONFLICT (paddle_transaction_id) DO NOTHING;
224```
225
226### Scenario 4 — OpenAI quota exceeded (backfill / tagger)
227
228**Symptoms**:
229- Discord: `OpenAI daily cost exceeded: $XX.XX > limit $10.00. Auto-pausing tagger.`
230- Backfill scripts (`npm run tag:run1000` etc.) throwing `DailyCostLimitExceeded`
231- ⚠️ This does **NOT** affect the live MCP Actor — Actor runtime doesn't call OpenAI
232
233**Action**:
234```bash
235# 1. Decide: did this match real demand (= legitimate burn) or runaway loop?
236#    Check OpenAI dashboard: usage by hour. Smooth curve = real, spike = bug.
237
238# 2. If real demand → raise the limit in tagger.ts (DAILY_COST_LIMIT_USD)
239#    Edit src/lib/tagger.ts → npm run build → re-deploy mcp-server (apify push)
240#    But tagger doesn't run inside Actor; it runs from manual `npm run tag:*` cron
241
242# 3. If runaway → halt the backfill cron:
243#    Whatever scheduler runs `npm run tag:runall` (cron / GitHub Action /
244#    Apify schedule) → disable it. Investigate the loop before re-enabling.
245
246# 4. Verify the live Actor is unaffected:
247#    Apify run log should NOT contain any OpenAI error — Actor never imports tagger
248```
249
250### Scenario 5 — Bot signup wave (100+ trial accounts in minutes)
251
252**Symptoms**:
253- `mcp_subscriptions` growth rate spike (100+ rows/minute)
254- Discord: `auto_topup_warning` flood (= bot using free $5 credit fast)
255- `signup-trial` Edge Function 200s flooding logs
256
257**Action**:
258```sql
259-- 1. Identify the wave — common pattern: same domain + sequential timestamps
260SELECT
261  split_part(email, '@', 2) AS domain,
262  COUNT(*) AS signups,
263  MIN(created_at) AS first,
264  MAX(created_at) AS last
265FROM mcp_subscriptions
266WHERE created_at > NOW() - INTERVAL '1 hour'
267GROUP BY domain
268ORDER BY 2 DESC
269LIMIT 20;
270
271-- 2. Cancel bot accounts (mark as canceled — preserves audit trail)
272UPDATE mcp_subscriptions
273SET status = 'canceled',
274    updated_at = NOW()
275WHERE created_at > NOW() - INTERVAL '1 hour'
276  AND email LIKE '%@<bot_domain>'
277  AND total_topup_usd = 0;
278
279-- 3. Reset their credit so they can't continue using the trial
280UPDATE mcp_subscriptions
281SET credit_balance_usd = 0
282WHERE status = 'canceled'
283  AND created_at > NOW() - INTERVAL '1 hour';
284```
285
286**Then add domain to a blocklist** (= TODO if it keeps happening — implement
287domain regex check in `signup-trial` Edge Function).
288
289### Scenario 6 — Sentry alert flood (real or false alarm)
290
291**Symptoms**:
292- Sentry: 100+ events in 5 minutes
293- Discord: silence (because Sentry is separate from Discord)
294- App appears to work fine
295
296**Action**:
297```
298# 1. Sentry → Issues → group by error message
299#    Is it ONE recurring error or many distinct errors?
300
301# 2. If ONE error (= same root cause):
302#    a. Identify the root cause from the stack trace
303#    b. Apply a mute rule on the specific error message (Sentry → Alerts → Rules)
304#       OR fix the root cause in code and redeploy
305
306# 3. If many distinct errors:
307#    Real problem — pause and triage. Most likely cause:
308#    - Apify Actor instance hit OOM (raise memoryMbytes in actor.json)
309#    - Supabase RPC misbehaving (jump to scenario 2)
310#    - Bad user input crashing a tool handler (check the input shape from Sentry context)
311
312# 4. Spike protection (proactive):
313#    Sentry → Settings → Spike Protection ON
314#    Limits hourly events — prevents accidental $$$$ on Sentry bill
315```
316
317---
318
319## Post-24h handoff
320
321After 24h with the above checks green:
322
3231. **Document what actually happened** — note any scenarios that fired so they can be hardened
3242. **Tune `auto_topup_threshold_usd` defaults** based on real usage patterns
3253. **Decide on Apify timeout** — if avg run duration ≪ 3600s, lower for cost savings
3264. **Pick the top 3 most-used tools** for marketing copy refinement
3275. **Lower healthcheck cadence** from 5min back to 15-30min once you trust the system

package.json

{
  "name": "kstar-mcp-server",
  "version": "0.1.0",
  "description": "MCP server exposing K-Star Hub Korean entertainment news + scripts as tools",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json",
    "smoke:test": "tsx scripts/smoke_test.ts",
    "test:rpc": "tsx scripts/test_quota_rpc.ts",
    "test:e2e": "tsx scripts/e2e_test.ts",
    "test:credit_system": "tsx scripts/test_credit_system.ts",
    "healthcheck": "tsx scripts/healthcheck.ts",
    "cache:invalidate": "tsx scripts/invalidate_cache.ts",
    "tag:test10": "tsx scripts/llm_tag_backfill.ts --mode=test10",
    "tag:test100": "tsx scripts/llm_tag_backfill.ts --mode=test100",
    "tag:run1000": "tsx scripts/llm_tag_backfill.ts --mode=run1000",
    "tag:runall": "tsx scripts/llm_tag_backfill.ts --mode=runall"
  },
  "keywords": [
    "mcp",
    "kpop",
    "kdrama",
    "kstar-hub"
  ],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.29.0",
    "@sentry/node": "^10.53.1",
    "@supabase/supabase-js": "^2.105.4",
    "apify": "^3.7.2",
    "openai": "^6.38.0",
    "zod": "^4.4.3"
  },
  "devDependencies": {
    "@types/node": "^25.8.0",
    "tsx": "^4.22.1",
    "typescript": "^6.0.3"
  }
}

smithery.yaml

startCommand:
  type: stdio
  configSchema:
    type: object
    required: ["api_key"]
    properties:
      api_key:
        type: string
        title: API Key
        description: Your Korean Data MCP Hub API key. Sign up at https://korean-data.com
  commandFunction: |-
    config => ({
      command: 'node',
      args: ['dist/index.js'],
      env: {
        MCP_USER_API_KEY: config.api_key,
        SUPABASE_URL: process.env.SUPABASE_URL,
        SUPABASE_ANON_KEY: process.env.SUPABASE_ANON_KEY
      }
    })

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "types": ["node"],
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": false,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

tsconfig.scripts.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "rootDir": ".",
    "outDir": "dist-typecheck"
  },
  "include": ["src/**/*", "scripts/**/*"],
  "exclude": ["node_modules", "dist", "dist-typecheck"]
}

.actor/Dockerfile

# Apify Actor container for Korean Data MCP Hub.
# Base: apify/actor-node:20 (Node 20, Apify CLI + SDK preinstalled).
#
# Note: the base image sets `ENV NODE_ENV=production`, which makes
# `npm ci` skip devDependencies by default. We need TypeScript + tsx
# during the build step, so we explicitly --include=dev for install,
# then `npm prune --omit=dev` after build to strip them from the final
# layer (≈50MB smaller image without going full multi-stage).

FROM apify/actor-node:20

# Copy manifests first for better layer caching.
COPY --chown=myuser package*.json ./

# Install with devDeps (TypeScript, tsx, @types/node needed for the build
# step below). The base image's NODE_ENV=production would otherwise drop them.
RUN npm ci --include=dev \
    && echo "Installed npm modules (incl. devDeps for build):" \
    && (npm list --depth=0 || true)

# Copy sources.
COPY --chown=myuser . ./

# Compile TS → dist/.
RUN npm run build

# Strip devDeps now that tsc/tsx have done their job. The final image keeps
# only the runtime deps (@modelcontextprotocol/sdk, @supabase/supabase-js,
# apify, openai, @sentry/node, zod).
RUN npm prune --omit=dev

# Apify Actor entrypoint (wraps the stdio MCP server).
CMD ["node", "dist/actor_entry.js"]

.actor/README.md

1# Korean Data MCP Hub
2
3**25 MCP tools for Korean media trends.** Cluster-deduped, multilingual JSON for AI agents.
4
5> Part of **Korean Data Hub** — the data layer for our two products on the same pipeline. The other product (K-Star Hub at `kstarhub.org`) eats the same dogfood: a daily digest service for human video creators. The MCP product gives AI agents the same pre-clustered, deduped stories the digest service has been delivering since November.
6
7## What this Actor does
8
9This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes the [Korean Data MCP Hub](https://korean-data.com) API to AI clients like Claude Desktop, Cursor, and Continue.
10
11It speaks **stdio MCP** — when Claude Desktop launches the Actor, it can call any of 25 tools across 11 Korean content categories.
12
13## Pricing model
14
15**Free Actor, paid backend.** Apify charges nothing for running this Actor itself; you use your **own Korean Data MCP Hub API key** (BYO) to pay per call ($0.005 each, $5 free signup credit, no card required).
16
17Get a key in 60 seconds: https://korean-data.com
18
19## Categories covered
20
21| Category | What's in it | Tier |
22|----------|-------------|------|
23| K-Pop | Idol news, comebacks, charts | realtime |
24| K-Drama | Scripted TV/streaming series | realtime |
25| K-Movie | Korean cinema, film festivals | trend |
26| K-Beauty | Cosmetics, skincare, brands | trend |
27| K-Food | Korean cuisine, restaurants | trend |
28| K-Game | Gaming industry, esports | trend |
29| K-Tech | Korean tech, startups | trend |
30| K-Stock | KOSPI, entertainment company financials | trend |
31| K-Travel | Tourism, destinations | trend |
32| K-Webtoon | Webtoons, Naver/Kakao | trend |
33| K-Trends | General Korean cultural trends | trend |
34
35## 25 tools
36
37- **K-Pop specialized (5)**: `get_kpop_news_today`, `get_artist_timeline`, `get_trending_clusters`, `search_news`, `generate_video_script`
38- **Category factory (20)**: `get_<cat>_weekly_trend` + `search_<cat>_archive` × 10 categories
39
40Each tool returns pre-clustered JSON (one row per real-world event, not per outlet) in EN / KO / JA / ES.
41
42## Token efficiency
43
44Pre-clustering + LLM classification reduces input tokens **70-80%** vs raw HTML scraping. The same Korean news event written 8× by 8 outlets becomes 1 cluster lead in our response.
45
46## Use in Claude Desktop
47
48```json
49{
50  "mcpServers": {
51    "korean-data": {
52      "command": "npx",
53      "args": ["-y", "@apify/actor-cli", "run", "upstanding_wax/korean-data-mcp-hub"],
54      "env": {
55        "MCP_USER_API_KEY": "kdmcp_..."
56      }
57    }
58  }
59}
60```
61
62Restart Claude Desktop. Ask: *"What's trending in K-pop this week?"* or *"Search Korean news for 'NewJeans Hanni'"*.
63
64## Use directly (Apify Run UI / API)
65
66Provide your API key as Actor input:
67
68```json
69{
70  "api_key": "kdmcp_..."
71}
72```
73
74## Resources
75
76- 📚 Tool docs: https://korean-data.com/docs
77- 🔑 Get an API key: https://korean-data.com ($5 free credit, no card)
78- 💸 Top up: https://korean-data.com/topup ($10 minimum, $0.005/call)
79- 📄 Refund policy: https://korean-data.com/refund
80- 🐛 Issues: https://github.com/teddyan35-create/kstar-mcp/issues
81
82## Keywords
83
84korean, k-pop, k-drama, k-beauty, k-food, k-movie, k-game, k-tech, k-stock, k-travel, k-webtoon, mcp, model-context-protocol, claude, cursor, ai-agent, news, trends, multilingual, korean-data

.actor/actor.json

{
  "actorSpecification": 1,
  "name": "korean-data-mcp-hub",
  "title": "Korean Data MCP Hub",
  "description": "MCP server exposing K-pop, K-drama, K-beauty, K-food, and 6 more Korean content categories as 25 LLM-ready tools. Cluster-deduped, multilingual (en/ko/ja/es), real-time.",
  "version": "0.2",
  "buildTag": "latest",
  "categories": ["AI", "DATA_EXTRACTION", "MCP"],
  "input": "./input_schema.json",
  "readme": "./README.md",
  "dockerfile": "./Dockerfile",
  "environmentVariables": {
    "NODE_ENV": "production"
  },
  "defaultRunOptions": {
    "build": "latest",
    "timeoutSecs": 3600,
    "memoryMbytes": 1024
  }
}

.actor/input_schema.json

{
  "title": "Korean Data MCP Hub",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "api_key": {
      "title": "API Key",
      "type": "string",
      "description": "Your Korean Data MCP Hub API key. Sign up at https://korean-data.com",
      "editor": "textfield",
      "isSecret": true
    }
  },
  "required": ["api_key"]
}

.registry/REGISTRY_SUBMIT.md

1# Registry Submission Guide
2
35 places to register the Korean Data MCP Hub. Submit in this order — easier ones first, Anthropic PR last (longest review).
4
5Reference URLs you'll paste repeatedly:
6- **Apify Actor**: https://apify.com/upstanding_wax/korean-data-mcp-hub
7- **GitHub repo**: https://github.com/teddyan35-create/kstar-mcp
8- **Landing page**: https://korean-data.com
9- **Docs**: https://korean-data.com/docs
10
11⚠️ URLs marked `[VERIFY]` below — I'm not 100% certain of the exact submission URL. Check the registry's homepage if the link 404s.
12
13---
14
15## 1. Smithery (auto-build from GitHub)
16
17**Submit at**: https://smithery.ai/new
18
19Smithery clones your GitHub repo + reads `smithery.yaml` + auto-builds + auto-hosts.
20
21### Steps
221. Sign in with GitHub at https://smithery.ai
232. Click **"Add Server"** → paste `https://github.com/teddyan35-create/kstar-mcp`
243. Smithery detects `smithery.yaml` at the repo root
254. Build runs (~2-3 min): `npm ci && npm run build` → `node dist/index.js`
265. Configuration UI exposes the `api_key` field (= what users will fill in)
276. Public URL: `https://smithery.ai/server/korean-data-mcp-hub`
28
29### Pre-flight (already done)
30- ✅ `smithery.yaml` at repo root with stdio + configSchema(api_key) + commandFunction
31- ✅ `README.md` at repo root with the marketing copy
32- ✅ `package.json` has `build` script and `start` script
33
34### Env vars on Smithery's hosting
35Smithery's hosted runtime sets `SUPABASE_URL` + `SUPABASE_ANON_KEY` from its config UI. You'll need to set them once after first build:
36- Smithery Dashboard → your server → **Environment** tab
37- Add `SUPABASE_URL=https://aevpcppnmceuxchsyeoz.supabase.co`
38- Add `SUPABASE_ANON_KEY=eyJ…` (Supabase Dashboard → Settings → API → anon public)
39- Optional: `NODE_ENV=production`, `SENTRY_DSN`, `DISCORD_WEBHOOK_URL`
40
41Note: `MCP_PADDLE_*` secrets are NOT needed on Smithery — those live in Supabase Edge Functions, not the MCP server runtime.
42
43---
44
45## 2. Glama (auto-crawl, zero submission)
46
47**Submit at**: https://glama.ai/mcp/servers
48
49Glama auto-crawls public GitHub repos with `mcp` keyword. If the README mentions MCP clearly, it should appear within 24-48h.
50
51### Steps (mostly passive)
521. Confirm README.md mentions "MCP" / "Model Context Protocol" — ✅ already does
532. (Optional) Submit manually: https://glama.ai/mcp/servers → "Submit a server" link if visible
543. Paste GitHub repo URL: `https://github.com/teddyan35-create/kstar-mcp`
554. Wait 24-48h for crawl
56
57No env-var or build config needed — Glama is a discovery index, not a hosting runtime.
58
59---
60
61## 3. MCP Compass
62
63**Submit at**: `[VERIFY]` https://mcp-compass.com or https://mcphub.io — check the homepage for the submit/add button.
64
65A community-maintained MCP server directory. Submission is typically a small form.
66
67### Fields to fill (paste from `server-metadata.json`)
68| Field | Value |
69|-------|-------|
70| Name | Korean Data MCP Hub |
71| Description | Real-time Korean media trends API for AI agents. 11 categories, 4 languages, pre-clustered JSON. Pay-per-call ($0.005) with $5 free trial credit. |
72| Repository | https://github.com/teddyan35-create/kstar-mcp |
73| Homepage | https://korean-data.com |
74| Categories | AI, Data Extraction, Media |
75| Transport | stdio |
76| Languages supported | English, Korean, Japanese, Spanish |
77| Pricing model | Pay-per-call ($0.005) + $5 free trial credit |
78| License | Commercial |
79| Tags | korean, kpop, kdrama, media, trends, multilingual, pay-per-call |
80
81---
82
83## 4. MCPfinder
84
85**Submit at**: `[VERIFY]` https://mcpfinder.com or https://mcpfinder.dev — check homepage.
86
87Similar to MCP Compass: community directory, form-based submission. Same field list above works.
88
89---
90
91## 5. Anthropic Official Registry (GitHub PR)
92
93**Submit at**: https://github.com/modelcontextprotocol/servers
94
95This is the official Anthropic-maintained list. Submission is a Pull Request to their README or registry directory. Review typically 1-2 weeks. Highest signal, slowest path.
96
97### Steps
981. Fork https://github.com/modelcontextprotocol/servers
992. Check the repo structure — typically there's a `README.md` with a server list or a `servers/` directory with one JSON per server
1003. Add an entry following the existing format. If JSON, use the fields from `.registry/server-metadata.json` as a starting point.
1014. Open the PR
1025. **PR body**: paste the contents of `.registry/anthropic-pr-body.md` (already drafted with sections: Server Description / What does it do / Why is it useful / Categories / Installation / Pricing / License)
1036. Address any reviewer feedback (typically: clarify pricing model, confirm production stability, ensure README is accurate)
104
105### Strategy for review
106- They prefer servers that are **already in production** with real users — submit AFTER you have ≥100 paying users for stronger signal
107- Highlight the **multilingual** angle (most MCP servers are English-only)
108- Highlight the **pre-clustering / token efficiency** angle (resonates with the LLM-native audience)
109
110---
111
112## Submission Tracker
113
114Copy this checklist into your operations notebook:
115
116```
117[ ] 1. Smithery
118      Submitted:  ____ / build success: ____ / public URL: smithery.ai/server/korean-data-mcp-hub
119[ ] 2. Glama
120      Crawl confirmed: ____ / listed URL: ____
121[ ] 3. MCP Compass
122      Submitted: ____ / listed URL: ____
123[ ] 4. MCPfinder
124      Submitted: ____ / listed URL: ____
125[ ] 5. Anthropic Official Registry
126      PR opened:  ____ / merged: ____ / PR URL: ____
127```
128
129## Update flow (after live)
130
131When you ship new tools or change pricing:
132- **Smithery / Glama / MCP Compass / MCPfinder**: usually re-crawl from README on a schedule — push to GitHub + wait
133- **Anthropic Official**: open a second PR if the entry needs updating
134
135The single source of truth is the GitHub README + `.registry/server-metadata.json`. Keep those accurate first; registries follow.

.registry/anthropic-pr-body.md

1## Server Description
2Korean Data MCP Hub — Real-time Korean media trends API for AI agents (pay-per-call). Part of **Korean Data Hub**, the parent brand running two products on the same data pipeline: this MCP product (for AI agents) and **K-Star Hub** (`kstarhub.org`, a daily digest product for human video creators that has been in production since November).
3
4## What does it do?
5Provides structured, multilingual Korean entertainment and cultural data to AI agents. 25 tools across 11 categories (K-Pop, K-Drama, K-Movie, K-Beauty, K-Food, K-Game, K-Tech, K-Stock, K-Travel, K-Webtoon, K-Trends) with output in English, Korean, Japanese, and Spanish.
6
7## Why is it useful?
8- Eliminates 3-week setup time for Korean news crawler infrastructure
9- 70-80% reduction in LLM input tokens via pre-clustered JSON
10- Multilingual translation built-in (no separate translation API needed)
11- Real-time clustering across 8+ Korean media sources with deduplication
12
13## Categories
14AI, DATA_EXTRACTION, MCP
15
16## Installation
17- Apify Actor: `upstanding_wax/korean-data-mcp-hub` — https://apify.com/upstanding_wax/korean-data-mcp-hub
18- npm: TBD
19- Smithery: https://smithery.ai/server/korean-data-mcp-hub
20
21## Pricing
22- **$0.005 per call** (pay-per-call prepaid credit)
23- **$10 minimum top-up** (2,000 calls)
24- **$5 free signup credit** — no card required (~1,000 calls)
25- Auto top-up available
26- Enterprise flat-rate plans available on request
27
28## License
29Commercial. Free trial credit + transparent usage-based pricing.

.registry/server-metadata.json

{
  "name": "korean-data-mcp-hub",
  "displayName": "Korean Data MCP Hub",
  "organization": "Korean Data Hub",
  "sibling_product": {
    "name": "K-Star Hub",
    "url": "https://kstarhub.org",
    "audience": "Human video creators (YouTube/TikTok)",
    "note": "Same data pipeline, different surface. The K-Star digest product proves the pipeline works in production (since November)."
  },
  "description": "Real-time Korean media trends API for AI agents. 11 categories, 4 languages, pre-clustered JSON. Pay-per-call ($0.005) with $5 free trial credit. Part of Korean Data Hub.",
  "version": "0.2.0",
  "license": "Commercial",
  "homepage": "https://korean-data.com",
  "repository": "https://github.com/teddyan35-create/kstar-mcp",
  "apify_actor_url": "https://apify.com/upstanding_wax/korean-data-mcp-hub",
  "smithery_url": "https://smithery.ai/server/korean-data-mcp-hub",
  "tags": ["korean", "kpop", "kdrama", "media", "trends", "multilingual", "api", "data", "pay-per-call"],
  "categories": ["AI", "DATA_EXTRACTION", "MEDIA", "MCP"],
  "transports": ["stdio"],
  "languages": ["en", "ko", "ja", "es"],
  "pricing": {
    "model": "pay_per_call_prepaid",
    "per_call_usd": 0.005,
    "minimum_topup_usd": 10,
    "trial_credit_usd": 5,
    "trial_card_required": false,
    "auto_topup_available": true,
    "enterprise": {
      "model": "monthly_flat",
      "contact": "enterprise@korean-data.com",
      "tiers": [
        {"name": "Enterprise Pro",      "price_usd_per_month": 79,  "monthly_calls": 20000},
        {"name": "Enterprise Business", "price_usd_per_month": 199, "monthly_calls": 50000}
      ]
    }
  },
  "support": {
    "email": "support@korean-data.com",
    "docs": "https://korean-data.com/docs"
  }
}

.marketing/hn_show_hn.md

1# Show HN: Korean Data MCP Hub — denoised Korean media for AI agents
2
3**Title (post field):**
4Show HN: Korean Data MCP Hub – denoised Korean media signal for AI agents
5
6**Body:**
7
8Hi HN — I'm Teddy, solo developer. I've been running a Korean entertainment news site (K-Star Hub) for ~6 months. Building it taught me something painful: **the Korean media landscape is 80% noise**. Press release reprints, paid placements, comeback-day puff pieces, the same headline rewritten by eight outlets.
9
10For my own site I had to build a pipeline to extract real signal. After enough people asked "how do you get clean Korean entertainment data into Claude / Cursor?", I exposed the same pipeline as an MCP server.
11
12**What it is:** 25 tools across 11 Korean content categories (K-Pop, K-Drama, K-Movie, K-Beauty, K-Food, K-Game, K-Tech, K-Stock, K-Travel, K-Webtoon, K-Trends), 4 languages (EN/KO/JA/ES), pre-clustered JSON.
13
14**The pipeline (5 stages):**
151. Scrape 8 major Korean outlets (Naver-indexed)
162. TF-IDF cluster — one story per real-world event, not per outlet
173. LLM classify (GPT-4o-mini) into 11 categories + off-topic
184. Translate (en/ja/es) on the cluster lead only — 8× cheaper than per-article
195. Serve via MCP stdio — Claude Desktop / Cursor / any MCP client
20
21**Why this matters for AI agents:**
22- Raw HTML scraping: ~3 weeks of setup, Korean NLP expertise, $300/mo in LLM tokens just to dedupe
23- Generic news APIs: no Korean coverage, no cluster dedup, no multilingual
24- Pre-clustered JSON cuts input token cost ~70-80% vs raw scraping
25
26**Pricing (the v2 pivot):**
27- $0.005 per call (= 200 calls per $1)
28- $5 free credit on signup, no card required (~1,000 calls)
29- $10 minimum top-up; auto top-up optional
30- No subscription unless you want the enterprise flat-rate tier
31
32I pivoted to pay-per-call right before launch because "monthly subscription" is a human-centric model — AI agents that make autonomous decisions should pay per autonomous decision, not per human-billed month.
33
34**Free playground** (no signup, IP-rate-limited): https://korean-data.com (HN'd this on launch day — be gentle)
35
36**Self-validation:** the same pipeline powers K-Star Hub (the news site). It's been in production since November, processing ~2,000 stories/day. The MCP server is the same Supabase backend, just with a different transport.
37
38Repo: https://github.com/teddyan35-create/kstar-mcp
39Apify Store: https://apify.com/upstanding_wax/korean-data-mcp-hub
40Docs / pricing: https://korean-data.com
41
42Happy to dive into the cluster algorithm, why I dropped subscription pricing 3 days before launch, what hurt about translating Korean idioms with GPT-4o-mini, or any tangent. Roast away.
43
44---
45
46## Editor's notes (don't post these)
47
48- **Title length**: under 80 chars (HN limit). Current: 76. ✅
49- **Avoid words**: "revolutionary", "disruptive", "amazing". Use plain English.
50- **Bury self-promo**: tech detail FIRST, link at the end.
51- **Engagement**: stay in the thread for 4+ hours. Reply to every top-level comment.
52- **Likely critiques to prep replies for**:
53  - "Why MCP and not REST?" → Both. MCP is the new agent interface; REST exists internally.
54  - "Won't this kill the source publishers?" → We link source_url in every response.
55  - "$0.005 sounds cheap — what's the margin?" → Marginal cost ~$0.0001 (Supabase + Apify). Pricing reflects packaging value, not compute.
56  - "Korean media is niche" → 78M Korean speakers + global K-content economy ($14B exports in 2024).
57- **Don't mention**: K-Star Hub revenue, Paddle MoR, exact AWS bills.

.marketing/lovable_config_update.md

1# Lovable: MCP Config Snippet — Use the SAME pattern everywhere
2
3**Problem found at launch review**: the MCP setup config shown to users
4varies across pages:
5- Some pages show `"args": ["-y", "@kstar/mcp-hub"]` + `env: { KSTAR_API_KEY: ... }`
6- The Apify Store README + our /settings/mcp page show `"args": ["-y", "@apify/actor-cli", "run", "upstanding_wax/korean-data-mcp-hub"]` + `env: { MCP_USER_API_KEY: ... }`
7
8Only ONE of these works:
9- `@kstar/mcp-hub` = npm package — **does NOT exist on the npm registry**. Users following this snippet get `npm ERR! 404 Not Found`.
10- `@apify/actor-cli` = our live deployment path. Users following this snippet succeed.
11
12**Decision**: Use **Apify** everywhere. npm publish is a separate post-launch project (Q3).
13
14---
15
16## Pages to update in Lovable
17
18Open Lovable Editor → search every page that mentions Claude Desktop config or MCP setup. Most likely:
19
20| Page | Likely location |
21|------|-----------------|
22| Landing / Hero | "How it works" section |
23| `/welcome` (post-payment) | "Connect to Claude Desktop" CTA |
24| `/docs` | Quick-start section |
25| `/settings/mcp` | Setup guide section (already correct in our `lovable-handoff/src/routes/settings-mcp.tsx` source) |
26| `/pricing` (if shown) | Trust signal "works with Claude / Cursor" |
27
28## The canonical snippet (paste verbatim)
29
30```json
31{
32  "mcpServers": {
33    "korean-data": {
34      "command": "npx",
35      "args": [
36        "-y",
37        "@apify/actor-cli",
38        "run",
39        "upstanding_wax/korean-data-mcp-hub"
40      ],
41      "env": {
42        "MCP_USER_API_KEY": "kdmcp_..."
43      }
44    }
45  }
46}
47```
48
49⚠️ **Three things that MUST be exactly this**:
501. `command: "npx"`
512. `"@apify/actor-cli"` (NOT `@apify/cli` and NOT `@kstar/mcp-hub`)
523. `MCP_USER_API_KEY` (NOT `KSTAR_API_KEY`, NOT `API_KEY`, NOT `KOREAN_DATA_KEY`)
53
54The MCP server reads `process.env.MCP_USER_API_KEY` inside `actor_entry.ts` —
55any other env var name = "Invalid or missing API key" error on first call.
56
57---
58
59## Verification
60
61After updating each page, paste the snippet into Claude Desktop config
62(`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac)
63and restart Claude Desktop. Within ~30s:
64
65- Bottom-right corner of Claude Desktop = a hammer icon appears with
66  "25 tools available from korean-data"
67- Ask Claude: *"What's trending in K-pop this week?"* — should call
68  `get_kpop_news_today` and return cluster-deduped JSON
69
70If the hammer icon doesn't appear, look at:
71- `~/Library/Logs/Claude/mcp-server-korean-data.log` for runtime errors
72- Most common cause: typo in the JSON snippet (trailing comma, missing quote)
73
74---
75
76## Future: npm package
77
78When you want `@kstar/mcp-hub` to be a real install path, this is the work:
791. Author + publish `@kstar/mcp-hub` npm package — a tiny wrapper that does
80   the same thing `@apify/actor-cli run upstanding_wax/korean-data-mcp-hub`
81   does today (spawn the MCP server, pipe stdio)
822. Update all pages to use the cleaner snippet
833. Keep the Apify path as the canonical hosted runtime — npm just becomes
84   an alias users can install locally if they prefer
85
86Estimated effort: ~half a day. Not required for launch.

.marketing/lovable_docs_fix.md

1# Lovable: Docs page — tool names + examples fix (P0)
2
3**Problem found at 2차 검수**: the docs page on korean-data.com shows
4tool names like `kpop.latest`, `kdrama.latest` — these **do not exist**.
5The page also shows REST API examples against `api.korean-data.com` —
6that domain doesn't exist either. Users following these docs will hit
7404 or "tool not found" 100% of the time.
8
9This document gives Teddy:
101. The actual 25 MCP tool names (extracted from `src/mcp/kr/kpop/*.ts` + `src/lib/category_tools.ts`)
112. Parameters per tool
123. Claude Desktop usage examples (= MCP, not REST)
134. A paste-ready Lovable prompt to overwrite the docs page
14
15---
16
17## The actual 25 tools
18
19### K-Pop specialized (5)
20
21| Tool name | Purpose | Required params | Optional params |
22|-----------|---------|-----------------|-----------------|
23| `get_kpop_news_today` | Today's cluster-deduped K-Pop news | — | `lang`, `date`, `limit`, `group_filter` |
24| `get_artist_timeline` | One artist's news timeline | `artist` | `lang`, `start_date`, `end_date`, `limit` |
25| `get_trending_clusters` | Cross-category trending events ranked by mentions × source diversity × decay | — | `lang`, `limit`, `momentum_filter`, `category` |
26| `search_news` | Free-text search across all clusters | `query` | `lang`, `date_from`, `date_to`, `limit` |
27| `generate_video_script` | Script template for a story/cluster | `cluster_id` OR `topic` | `lang`, `length_seconds` |
28
29### Category tools (10 × 2 = 20)
30
31For each of the 10 categories — **kdrama, kmovie, kbeauty, kfood, kgame, ktech, kstock, ktravel, kwebtoon, ktrends** — the factory generates 2 tools:
32
33| Pattern | Example | Purpose | Required | Optional |
34|---------|---------|---------|----------|----------|
35| `get_<cat>_weekly_trend` | `get_kdrama_weekly_trend` | Last 1-7 days, cluster leads in that category | — | `lang`, `date_range_days` (1-7), `limit` |
36| `search_<cat>_archive` | `search_kdrama_archive` | Keyword search within that category's archive | `query` | `lang`, `date_from`, `date_to`, `limit` |
37
38Full list:
39- `get_kdrama_weekly_trend` / `search_kdrama_archive`
40- `get_kmovie_weekly_trend` / `search_kmovie_archive`
41- `get_kbeauty_weekly_trend` / `search_kbeauty_archive`
42- `get_kfood_weekly_trend` / `search_kfood_archive`
43- `get_kgame_weekly_trend` / `search_kgame_archive`
44- `get_ktech_weekly_trend` / `search_ktech_archive`
45- `get_kstock_weekly_trend` / `search_kstock_archive`
46- `get_ktravel_weekly_trend` / `search_ktravel_archive`
47- `get_kwebtoon_weekly_trend` / `search_kwebtoon_archive`
48- `get_ktrends_weekly_trend` / `search_ktrends_archive`
49
50Note: **K-Pop does NOT follow the factory pattern**. Don't write `get_kpop_weekly_trend` or `search_kpop_archive` — those don't exist. K-Pop uses the 5 specialized tools above.
51
52---
53
54## How users invoke them
55
56⚠️ **No REST API.** The docs page must NOT show `curl https://api.korean-data.com/...` examples — that endpoint doesn't exist. Korean Data MCP Hub is **MCP-only**: Claude Desktop / Cursor / Continue speaks stdio MCP to our Apify-hosted Actor.
57
58### Claude Desktop setup
59```json
60{
61  "mcpServers": {
62    "korean-data": {
63      "command": "npx",
64      "args": [
65        "-y",
66        "@apify/actor-cli",
67        "run",
68        "upstanding_wax/korean-data-mcp-hub"
69      ],
70      "env": {
71        "MCP_USER_API_KEY": "kdmcp_..."
72      }
73    }
74  }
75}
76```
77After saving, restart Claude Desktop. The hammer icon (bottom-right) shows "25 tools available from korean-data". Then just ask:
78
79### Example user prompts (= what to copy onto the docs page)
80
81| Prompt | Tool Claude picks |
82|--------|-------------------|
83| "What's trending in K-pop today?" | `get_kpop_news_today` |
84| "Show me NewJeans Hanni news from the last 30 days" | `get_artist_timeline` |
85| "What K-dramas are people talking about this week?" | `get_kdrama_weekly_trend` |
86| "Search Korean news for 'Squid Game 3'" | `search_news` |
87| "Search K-Beauty archive for 'Olive Young Q1 earnings'" | `search_kbeauty_archive` |
88| "What's the biggest story across all Korean media right now?" | `get_trending_clusters` |
89| "Generate a 60-second video script about the Hybe/Min Hee-jin dispute" | `generate_video_script` |
90
91### Response shape (= what the docs page should show as the JSON example)
92
93Every story-returning tool returns this shape:
94```json
95{
96  "category": "K-Pop",
97  "items": [
98    {
99      "id": 12345,
100      "cluster_id": "c_xxxxx",
101      "title": "...",
102      "summary": "...",
103      "source": "Naver",
104      "url": "https://...",
105      "subjects": ["NewJeans", "Hanni"],
106      "published_at": "2026-05-22T13:00:00+09:00"
107    }
108  ],
109  "count": 5,
110  "data_freshness": "fresh"
111}
112```
113
114`generate_video_script` returns a different shape (= script object); document it separately if you keep it on the docs page.
115
116---
117
118## Don't promise on the docs page
119
120The current docs page implies a REST API exists. **Delete or rewrite** any of these:
121
122- ❌ `curl https://api.korean-data.com/v1/kpop/latest`
123- ❌ `import { KoreanData } from '@korean-data/sdk'` (no such npm package — see `lovable_config_update.md` for the @kstar/mcp-hub problem)
124- ❌ "Authorization: Bearer kdmcp_..." in HTTP headers
125- ❌ "kpop.latest" / "kdrama.latest" / "kpop.search" — all fake
126
127The product is exclusively MCP-over-stdio via the Apify Actor. REST API
128support is a post-launch initiative (Q3+), if ever.
129
130---
131
132## Paste-ready Lovable prompt
133
134> Rewrite the /docs page top-to-bottom. The current content has invented
135> tool names (`kpop.latest`, `kdrama.latest`) and references a non-existent
136> REST API at `api.korean-data.com`. Replace with:
137>
138> 1. **Hero**: "25 tools across 11 Korean content categories. MCP-native.
139>    English / Korean / Japanese / Spanish."
140>
141> 2. **Quick start**: the Claude Desktop config JSON snippet (use the
142>    canonical version from `.marketing/lovable_config_update.md` —
143>    `@apify/actor-cli` + `upstanding_wax/korean-data-mcp-hub` +
144>    `MCP_USER_API_KEY`).
145>
146> 3. **Tool list**: render the 5 K-Pop specialized tools + the
147>    factory-generated 20 (per category × 2). Each row: tool name,
148>    one-line description, required params, optional params. Source the
149>    list from `.marketing/lovable_docs_fix.md`. No invented tools.
150>
151> 4. **Response shape**: show ONE JSON example covering the common shape
152>    (category, items[], count, data_freshness). Don't show `curl` —
153>    use a "Try it in Claude Desktop" prompt instead.
154>
155> 5. **Remove**: any REST endpoint mention, `api.korean-data.com`,
156>    "Authorization: Bearer", `kpop.latest`-style names, fake SDK imports.
157>
158> 6. **Add at bottom**: "Looking for a REST API? It's on the roadmap —
159>    join the waitlist." (with email field).

.marketing/lovable_hide_badge.md

1# Lovable: Hide "Edit with Lovable" badge
2
3**Problem found at launch review**: footer shows the "Edit with Lovable"
4badge on korean-data.com — looks like a hobby site, not a production product.
5
6## How to remove
7
8### If you're on Lovable Pro ($20/month)
91. Lovable Dashboard → your project → **Settings** → **Branding** (or **General**)
102. Toggle **"Hide Lovable badge"** to ON
113. Republish (or wait for next auto-deploy)
124. Verify: open https://korean-data.com in incognito → footer should be clean
13
14### If you're on Lovable free plan
15The "Hide badge" toggle is **Pro-only**. Three options:
16
17#### Option A — Upgrade to Pro ($20/month)
18- Cheapest path to a clean footer
19- Also unlocks: more credits, more projects, faster builds
20- ROI: $20/mo vs. perception cost of looking like a hobby project is trivially worth it for a launching B2B product
21
22#### Option B — Remove the badge via custom CSS (hack — may break ToS)
23Lovable's ToS may prohibit this. Check before doing. Roughly:
24```css
25/* In Lovable Custom CSS settings or a global style */
26[data-lovable-badge],
27.lovable-badge,
28a[href*="lovable.dev"] {
29  display: none !important;
30}
31```
32⚠️ If Lovable detects + flags, your site may be taken down.
33⚠️ This is a wear-down attack, not a clean fix. Upgrade is better.
34
35#### Option C — Leave the badge on
36- Accept the perception cost; revisit when you have first revenue
37- Acceptable for "soft launch" / friends-and-family beta
38- NOT acceptable once you're posting to HN / paying for Reddit ads
39
40## Recommendation
41
42Pay the $20. Apify alone will recoup it via "looks legit" conversion
43lift. Do it BEFORE the HN / Reddit launch — the badge is exactly the
44kind of detail that gets called out in launch threads.
45
46Once toggled, verify on:
47- Desktop (incognito tab)
48- Mobile (incognito tab)
49- All key pages: `/`, `/pricing`, `/welcome`, `/settings/mcp`, `/topup`,
50  `/terms`, `/privacy`, `/refund`

.marketing/lovable_playground_fix.md

1# Lovable: Playground widget — payload fix (P0)
2
3**Problem found at 2차 검수**: the "Try It Live" widget on korean-data.com
4sends `{tool: "..."}` to the public-playground Edge Function. The function
5requires `category` (one of 11) and returns `400 "invalid or missing category"`.
6
7The widget's "tool" dropdown is conceptually wrong for this endpoint. The
8public-playground is a **simplified sampling endpoint**, not a 25-tool
9proxy. It only returns one shape: a list of recent stories filtered by
10ONE category. The full 25-tool MCP surface is unlocked after signup.
11
12---
13
14## Correct payload
15
16```json
17POST https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/public-playground
18Content-Type: application/json
19
20{
21  "category": "kpop",
22  "lang": "en",
23  "limit": 5
24}
25```
26
27Fields:
28- `category` (required) — one of: `kpop`, `kdrama`, `kmovie`, `kbeauty`,
29  `kfood`, `kgame`, `ktech`, `kstock`, `ktravel`, `kwebtoon`, `ktrends`
30- `lang` (optional, default `en`) — `en` / `ko` / `ja` / `es`
31- `limit` (optional, default 3, hard-capped at 3) — 1-3
32
33Response:
34```json
35{
36  "samples": [
37    { "title": "...", "summary": "...", "source": "...", "url": "...", "published_at": "..." }
38  ],
39  "lang": "en",
40  "note": "Sample data with watermark, older than 7 days. ...",
41  "daily_remaining": 49
42}
43```
44
45---
46
47## UI redesign (replace tool dropdown)
48
49The current "tool" dropdown should be removed. The widget needs **3 controls**:
50
511. **Category dropdown** (required, 11 options):
52   ```
53   K-Pop / K-Drama / K-Movie / K-Beauty / K-Food / K-Game /
54   K-Tech / K-Stock / K-Travel / K-Webtoon / K-Trends
55   ```
56   Internal value → API: `K-Pop` → `"kpop"`, `K-Drama` → `"kdrama"`, etc.
57   (lowercase, no hyphen — see CATEGORY_MAP in public-playground/index.ts)
58
592. **Language dropdown** (optional, 4 options): `English / 한국어 / 日本語 / Español`
60   Internal value: `en` / `ko` / `ja` / `es`
61
623. **Run** button → fetch the URL above with the 3 fields.
63
64---
65
66## Common pitfalls (= why the widget broke)
67
68- ❌ Sending `tool: "get_kpop_news_today"` — that's a MCP tool name, not
69  a playground category. The playground doesn't know MCP tool names.
70- ❌ Sending `category: "K-Pop"` (display name with hyphen) — the
71  backend normalizes to lowercase but expects no hyphen. Use `kpop`.
72- ❌ Adding a `keyword` or `query` field — the playground doesn't search.
73  It just returns the N most recent cluster leads in the category. Full
74  search is `search_<cat>_archive` and `search_news`, which require a
75  paid API key (= not in the public playground).
76
77---
78
79## What about the other MCP tools (get_artist_timeline, search_news, etc.)?
80
81These are **MCP-only**, gated behind the api_key. The public playground
82does NOT expose them. If the marketing copy promises "try search" or "try
83artist timeline", that promise is wrong — fix the copy:
84
85| Tool | Public playground? | How to try it |
86|------|-------------------|---------------|
87| `get_kpop_news_today` | partial (= the category sample is its equivalent) | playground with `category: "kpop"` |
88| `get_kdrama_weekly_trend` | partial | playground with `category: "kdrama"` |
89| `get_kmovie_weekly_trend` / 8 others | partial | playground with matching category |
90| `get_artist_timeline` | ❌ no | sign up + use Claude Desktop |
91| `search_news` (cross-category search) | ❌ no | sign up + use Claude Desktop |
92| `search_<cat>_archive` × 10 | ❌ no | sign up + use Claude Desktop |
93| `get_trending_clusters` | ❌ no | sign up + use Claude Desktop |
94| `generate_video_script` | ❌ no | sign up + use Claude Desktop |
95
96The widget should NOT have a "tool" dropdown that lists 25 items. Either:
97- (a) just expose category + lang (= sampling preview), OR
98- (b) add a "Sign up for the full 25-tool API →" CTA below the widget
99
100Recommend (a) for the playground, (b) elsewhere on the page.
101
102---
103
104## Paste-ready Lovable prompt
105
106> Update the Try It Live widget on the home page:
107>
108> 1. Remove the "tool" dropdown entirely.
109> 2. Add a "Category" dropdown (required) with these 11 options (display →
110>    internal value): K-Pop → kpop, K-Drama → kdrama, K-Movie → kmovie,
111>    K-Beauty → kbeauty, K-Food → kfood, K-Game → kgame, K-Tech → ktech,
112>    K-Stock → kstock, K-Travel → ktravel, K-Webtoon → kwebtoon,
113>    K-Trends → ktrends.
114> 3. Add a "Language" dropdown (optional, default English) with 4 options:
115>    English/en, 한국어/ko, 日本語/ja, Español/es.
116> 4. On Run, POST to
117>    https://aevpcppnmceuxchsyeoz.supabase.co/functions/v1/public-playground
118>    with body: { "category": <internal>, "lang": <internal>, "limit": 5 }
119> 5. Render `samples[]` as a list of {title, summary, source, published_at}.
120> 6. If response is 429, show the `message` field as an upsell ("Rate limit. Subscribe for unlimited access at korean-data.com").
121> 7. Below the widget add small text: "This is a sampling preview. Sign up for the full 25-tool MCP API at /signup."

.marketing/reddit_claudeai.md

1# r/ClaudeAI — Korean Data MCP Hub launch
2
3**Title:**
4I built an MCP server so Claude can read clean Korean news (K-Pop, K-Drama + 9 more) — $5 free credit, no card
5
6**Body:**
7
8Hey r/ClaudeAI 👋 solo dev here.
9
10I run a Korean entertainment news site on the side. While building it I had to solve a problem that kept frustrating me: **Korean media has a brutal signal-to-noise ratio**. The same comeback story gets rewritten by 8 outlets within 30 minutes, half of which are paid placements. Trying to ask Claude "what's actually happening in K-pop this week" using raw scraped text would burn through tokens with mostly duplicates.
11
12After hearing the same question a few times ("how do you get clean Korean entertainment data into Claude?"), I exposed my pipeline as an MCP server. **It just shipped today.**
13
14### What it does
15- 25 tools across 11 Korean categories: K-Pop, K-Drama, K-Movie, K-Beauty, K-Food, K-Game, K-Tech, K-Stock, K-Travel, K-Webtoon, K-Trends
16- 4 languages: English, Korean, Japanese, Spanish (translation happens once per cluster, not per call)
17- Cluster-deduplicated — one story per real event, not per outlet
18- Off-topic filter (LLM classifier) — religious newsletters, political op-eds, etc. get dropped
19
20### How it feels in Claude Desktop
21Add to your MCP config (Apify-hosted, so no local install):
22```json
23{
24  "mcpServers": {
25    "korean-data": {
26      "command": "npx",
27      "args": ["-y", "@apify/actor-cli", "run", "upstanding_wax/korean-data-mcp-hub"],
28      "env": { "MCP_USER_API_KEY": "kdmcp_..." }
29    }
30  }
31}
32```
33
34Then just ask: "what K-dramas premiered this week?" or "search Korean news for 'NewJeans Hanni'" — Claude picks the right tool, fetches pre-clustered JSON, summarizes.
35
36### What was hard
37- **Cluster dedup at low latency**: TF-IDF cosine + outlet-aware merge. Took 3 iterations to get below 100ms.
38- **LLM classification confidence**: 11 categories overlap (K-Movie ↔ K-Drama for screen actors). Added secondary_category + confidence so the catch-all bucket is honest.
39- **Multilingual translation cost**: doing it per-article would cost ~$300/mo. Doing it once per cluster lead = ~$30. Same UX.
40
41### Pricing — and why I pivoted 3 days before launch
42Originally I had Starter $29 / Pro $79 / Business $199 monthly subscriptions. Three days ago I realized: **monthly billing is a human model**. If Claude makes 47 autonomous decisions today, it doesn't care about a billing cycle.
43
44Switched to:
45- **$0.005 per call** (200 calls per $1)
46- **$5 free credit on signup, no card required** (~1,000 calls)
47- **$10 minimum top-up**, auto top-up optional
48- Enterprise flat-rate still exists for the few who want it (manual onboarding)
49
50### Self-validation
51The same pipeline runs my own news site (K-Star Hub) in production since November — ~2,000 stories/day. The MCP server is the same Supabase backend with a different transport. So I'm eating my own dog food before charging anyone.
52
53### Try it free
54- Free playground (no signup): https://korean-data.com
55- Sign up for $5 credit: https://korean-data.com (email only, no card)
56- Apify Store: https://apify.com/upstanding_wax/korean-data-mcp-hub
57- Repo: https://github.com/teddyan35-create/kstar-mcp
58
59Happy to answer anything — pipeline details, why I dropped subscription pricing, tradeoffs of Apify vs hosting it myself, anything. Roast my pricing 🙏
60
61---
62
63## Editor's notes (don't post)
64- **Title under 100 chars** for Reddit mobile. Current: 98. ✅
65- **Builder diary tone** = first-person, what was hard, what was surprising. NOT marketing-speak.
66- **Pricing pivot story** is the unique angle — most subreddit launches are "$X for Y features". The "I changed my pricing model right before launch" hook is real and gets sympathy upvotes.
67- **No emojis in body** beyond the wave at the start. r/ClaudeAI skews technical.
68- **Comments to expect**: "Why MCP not REST" / "How does it compare to NewsAPI" / "Can it search by Korean person/group name (NER)" — prep replies.
69- **Don't mention**: revenue, Paddle, AWS bills.

.marketing/reddit_mcp.md

1# r/mcp — Korean Data MCP Hub: architecture writeup
2
3**Title:**
4Korean Data MCP Hub — production MCP server architecture (Apify + Supabase + applyGuard pattern)
5
6**Body:**
7
8Solo dev, shipping today. This is more architecture writeup than launch post — the marketing thread is on r/ClaudeAI.
9
10### Stack
11- **Transport**: stdio via `@modelcontextprotocol/sdk` v1.29
12- **Hosting**: Apify Actor (Docker, Node 20, `apify/actor-node:20` base)
13- **Backend**: Supabase Postgres + PostgREST + 12 Edge Functions (Deno)
14- **LLM**: GPT-4o-mini (classification + translation, ~$30/mo at current volume)
15- **Webhooks**: Paddle Billing (one-time payments, transaction.completed event)
16
17### 25 tools, one wrapper
18
19All 25 tool handlers go through a single `applyGuard()` wrapper. The wrapper:
20
211. Resolves api_key → user via `mcp_subscriptions` table (per-process cache, invalidates on key change)
222. Calls atomic RPC `check_and_charge_credit(user_id, tool_name, query_hash)`
233. On RPC error: 60s fail-open window (first failure = allow + Sentry/Discord alert, subsequent = SERVICE_UNAVAILABLE)
244. Mutates `args.limit` in place for trial-tier clamping (tool handler uses `args.limit` directly)
255. Returns `GuardOk` envelope with credit balance + auto-topup warning
26
27The RPC is the security perimeter — `SELECT FOR UPDATE` + counter increment + INSERT into `mcp_usage` all in one transaction. Race-safe at the quota boundary.
28
29```sql
30-- pseudocode of the RPC body
31SELECT * FROM mcp_subscriptions WHERE user_id=… FOR UPDATE;
32IF balance < price THEN RETURN insufficient_credit;
33IF cooldown_hit THEN RETURN cooldown_active;
34UPDATE mcp_subscriptions SET balance -= price;
35INSERT INTO mcp_usage (…);
36RETURN allowed + new_balance;
37```
38
39### Tool design
40
4120 of 25 tools are auto-generated by a factory pattern (`buildWeeklyTrendTool` / `buildSearchArchiveTool`) — 10 content categories × 2 tools each. Adding K-Sports next month is one entry in a metadata map.
42
43The 5 K-Pop specialized tools (`get_kpop_news_today`, `get_artist_timeline`, `search_news`, `get_trending_clusters`, `generate_video_script`) are hand-written because they have category-specific logic (artist NER, timeline windowing, script template).
44
45### Pricing model = pay-per-call
46
47Pivoted from monthly subscription 3 days before launch. Reasoning: **subscription billing is a human model**. An AI agent making 47 decisions today doesn't care about billing cycles. So:
48
49- `$0.005/call` (200 calls per $1)
50- `$5 free credit` on signup (no card)
51- Auto top-up via Paddle Vault saved card
52- Enterprise flat-rate remains (manual onboarding) for the few who want it
53
54The credit deduction is in the same RPC as the quota check — one transaction, no orphan charges if the tool body fails after debit (we record usage BEFORE tool body executes).
55
56### Things I'd do differently
57
58- **Apify timeoutSecs**: started at 60s, fixed to 3600s right before launch because MCP stdio = interactive session, not one-shot. Apify Standby Mode would be better long-term but adds setup complexity.
59- **Tier downgrade protection**: legacy `check_and_record_usage` RPC has a special branch for active users whose usage > new monthly_quota → returns `QUOTA_EXCEEDED_DOWNGRADED` instead of plain `QUOTA_EXCEEDED` (softer error copy). Took me an hour to realize the downgrade case existed.
60- **Watermarking the public playground**: appends `[via korean-data.com — subscribe for clean data]` to every text field. Scrapers get unusable data without a regex strip step.
61
62### Repo + docs
63- GitHub: https://github.com/teddyan35-create/kstar-mcp
64- Apify Store: https://apify.com/upstanding_wax/korean-data-mcp-hub
65- DEPLOYMENT.md and DEPLOY_CHECKLIST.md in the repo are the full launch playbook
66- Pricing/landing: https://korean-data.com
67- Free playground (no signup): same domain
68
69Happy to nerd out about anything — applyGuard tradeoffs, why I chose Apify over Cloudflare Workers, RPC vs PostgREST for the hot path, how I survived a 3-days-before-launch pricing pivot.
70
71---
72
73## Editor's notes (don't post)
74- **r/mcp is tiny + technical** — don't lead with pricing. Lead with architecture.
75- **Title under 90 chars**. Current: 88. ✅
76- **No marketing emojis**. Plain code blocks.
77- **Pre-launch fact-check**: confirm Apify build succeeded + tool count = 25 before posting.
78- **Likely comments**: "Why not Cloudflare Workers" / "Race condition in check_and_charge_credit?" (answer: FOR UPDATE) / "Open source the cluster algorithm?" (answer: not yet, but might publish a blog).
79- **Don't mention**: revenue, real Paddle/Resend/Sentry keys.

.marketing/x_pinned.md

1# X / Twitter — pinned tweet
2
3## Primary option (276 chars)
4
5> Just launched Korean Data MCP Hub — denoised Korean media for AI agents.
6>
7> 25 tools, 11 categories (K-pop, K-drama, K-beauty, +8), 4 languages.
8> Cluster-deduped JSON cuts input tokens 70-80% vs raw scraping.
9>
10> $5 free credit, no card. $0.005/call after.
11>
12> korean-data.com
13
14**Char count: 276 / 280** ✅
15
16---
17
18## Alternate A — angle: pricing pivot (279 chars)
19
20> Pivoted from monthly subscription to $0.005/call 3 days before launch.
21>
22> Why: monthly billing is a human model. AI agents make autonomous decisions, should pay per autonomous decision.
23>
24> $5 free credit on signup, no card → korean-data.com
25
26**Char count: 269 / 280** ✅
27
28---
29
30## Alternate B — angle: technical (278 chars)
31
32> Shipped Korean Data MCP Hub today.
33>
34> 25 MCP tools, 11 Korean categories, 4 languages.
35> Production-tested pipeline (same backend powers my news site since Nov).
36>
37> Pay-per-call: $0.005, $5 free credit, no card.
38>
39> korean-data.com
40
41**Char count: 232 / 280** ✅
42
43---
44
45## Notes for posting (don't include in tweet)
46- **Pin the chosen one** within 30 minutes of launch.
47- **Quote-tweet** the HN / Reddit threads as replies for distribution.
48- **Reply thread (optional)** with a short demo GIF showing Claude Desktop using `get_kpop_news_today`.
49- **Apify Store URL** = too long for pinned (would push over 280). Drop it
50  as a REPLY to your own pinned tweet:
51  > Hosted on Apify, free to run, BYO API key:
52  > https://apify.com/upstanding_wax/korean-data-mcp-hub
53  This keeps the pinned tweet tight + still gets the Store traffic.
54- **Avoid #hashtags** in pinned — eats char budget, looks spammy on launch posts.
55- **Drop "Just launched"** if it feels stale by day 2 → swap to "Korean Data MCP Hub: …".
56- **DO NOT add UTM** in pinned tweet (looks like an ad). Add UTM only when posting to ad campaigns.
57- **Recommend Alternate A** for HN crowd retweets — "pricing pivot story" gets reshared more than features.
58- **Recommend Primary** for general feed — clearest value prop.

legal/privacy.md

1# Privacy Policy
2
3Last updated: [TODO: 라이브 날짜]
4
5## What We Collect
6- Email (account + invoices via Paddle)
7- API usage logs (tool_name, called_at, query_hash)
8- Payment: handled by Paddle (we never see card data)
9
10## What We Don't Collect
11- Queries NOT stored beyond 24-hour hash for cooldown
12- No device fingerprinting
13- No tracking cookies on API endpoints
14
15## How We Use
16- Service operation (quota, cooldown)
17- Anomaly detection (abuse, fraud)
18- Aggregate analytics (no individual ID)
19
20## Data Sharing
21- Paddle (payment)
22- Supabase (database, US/EU)
23- OpenAI (content classification, no user PII)
24- No selling, no ad partners
25
26## Your Rights (GDPR/CCPA)
27- Request data: support@korean-data.com
28- Delete account: cancel + email request
29- Data portability: usage logs exportable
30
31## Retention
32- Active subscriptions: indefinite
33- Canceled: 90 days then deleted
34- Query hashes: 24 hours
35
36## Security
37- HTTPS only
38- API keys = unique random strings (32 hex)
39- Payment data: PCI-DSS via Paddle
40- 2FA on all admin accounts
41
42## Children
43Service not for under 18. We do not knowingly collect minor data.
44
45## Contact
46support@korean-data.com (same inbox as privacy@)

legal/refund.md

1# Refund Policy
2
3Prepaid credit model. Here's exactly how refunds work — no surprises.
4
5## TL;DR
6- First 24 hours after a top-up: **100% refund of that top-up**, no questions asked
7- After 24 hours: **refund up to your unused credit balance only**
8- Service outages (>24 hours within a period when you topped up): **100% refund**
9- Free trial credit (~$5) is non-refundable (no money was charged)
10
11## Trial Credit
12- $5 free credit on signup (~1,000 calls)
13- No card required, no time limit
14- Free trial users are subject to a 24h cooldown on identical search queries (lifts on first top-up)
15
16## How refunds are computed
17
18### Within 24 hours of a paid top-up
19- Full refund of that top-up's amount
20- No usage check
21- Email `support@korean-data.com` with subject "Refund 24h"
22- Processed within 1 business day
23
24### After 24 hours
25We refund **only the credit you haven't consumed**:
26- Charged $10, consumed $4 → refund up to $6
27- Charged $25, consumed $25 → no refund (fully used)
28- Multiple top-ups → each top-up is its own 24h window; older ones can only refund unused balance
29
30This protects against data-extraction abuse while remaining fair to genuine cancellations.
31
32### Service Outages
33- If our API is unreachable for >24 hours during a period when you topped up
34- 100% refund of the top-up, regardless of consumption during the outage
35- Public uptime monitor at [TODO: status page]
36
37### Abuse Patterns = No Refund
38We reserve the right to deny refunds for:
39- 100+ calls/min sustained (bot-like behavior beyond normal API use)
40- Same API key from many IPs simultaneously (key sharing)
41- Repeated top-up → refund cycles (fraud pattern)
42- Reverse engineering / scraping our infrastructure
43
44## How to Request
451. Email `support@korean-data.com`
462. Subject: "Refund request" + the Paddle transaction ID of the top-up
473. We check usage + respond within 1 business day
484. Approved refunds return via Paddle (5-10 business days to card)
49
50## Cancellation
51There's nothing to cancel — credit doesn't auto-renew.
52- Stop using the API = stop spending. Your remaining balance stays in your account.
53- Disable auto top-up anytime at `korean-data.com/settings/mcp`.
54- Enterprise (monthly-billed) subscribers: contact us to cancel auto-renewal.
55
56## Paddle Merchant of Record
57Paddle handles payment processing and refund execution. You may also contact Paddle directly: paddle.com/support
58
59## Disputes
601. Reply to our email first
612. Escalate to support@paddle.com
623. Chargebacks (= last resort): please contact us first — chargebacks may result in account suspension

legal/terms.md

1# Terms of Service
2
3Last updated: [TODO: 라이브 날짜]
4
5## 1. Service Description
6Korean Data MCP Hub provides API access to Korean media trend data via the Model Context Protocol (MCP). Operated by [TODO: 사업자명].
7
8## 2. Pricing & Credit
9- **Pay-per-call**: $0.005 per tool invocation
10- **Top-up**: $10 minimum (= 2,000 calls). Other tiers: $25, $50, $100
11- **Free trial**: $5 free credit on signup (~1,000 calls), no card required
12- **Auto top-up** (optional): when balance falls below $5, we charge your saved card for $10 (configurable)
13- **Enterprise** (manual sales): $79/mo (20,000 calls) or $199/mo (50,000 calls) flat
14- Payment via Paddle.com as Merchant of Record
15
16## 3. Acceptable Use
17- API calls deduct from your credit balance ($0.005 each)
18- Free-trial users: 24h cooldown on identical search queries (lifts on first top-up)
19- Enterprise users: monthly quota enforced per plan
20- Prohibited: reselling data, scraping our infrastructure, abusive automated requests
21
22## 4. Data Sources
23Content sourced from 8 Korean media organizations, processed via TF-IDF clustering and LLM classification. We do not guarantee accuracy, completeness, or timeliness.
24
25## 5. Refunds
26See full Refund Policy at `korean-data.com/refund`. Summary: 100% refund within 24h of any top-up; after that, unused credit is refundable; service outages get full refunds.
27
28## 6. API Key Security
29You are responsible for keeping your API key confidential. Compromised keys: rotate immediately at `korean-data.com/settings/mcp`. We may suspend keys exhibiting abuse patterns.
30
31## 7. Service Availability
3299% uptime target. No SLA on per-call pricing; Enterprise plans get written SLA. We are not liable for downtime or data loss beyond the refund commitments in §5.
33
34## 8. Termination
35- Stop using = no further charges. Credit balance remains in your account indefinitely.
36- We may terminate for ToS violation with 7 days notice
37- Upon termination: API key revoked, unused credit refundable (subject to §5)
38
39## 9. Limitation of Liability
40"As is" service. Maximum liability = the lesser of (a) total top-ups in the prior 90 days, or (b) $200.
41
42## 10. Changes
4330 days email notice for material changes. Continued use = acceptance.
44
45## 11. Contact
46support@korean-data.com

scripts/e2e_test.ts

1// End-to-end credit-model lifecycle test — runs through tool handlers
2// (applyGuard → check_and_charge_credit → handler body).
3//
4// Required env: SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY.
5// MUST NOT have QUOTA_BYPASS=1.
6// Run: npm run test:e2e
7
8import { createClient, type SupabaseClient } from "@supabase/supabase-js";
9
10const url = process.env.SUPABASE_URL;
11const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
12if (!url || !serviceKey) {
13  console.error("Missing SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY in env.");
14  process.exit(1);
15}
16if (process.env.QUOTA_BYPASS === "1") {
17  console.error("QUOTA_BYPASS=1 set — unset to test the real guard. exiting.");
18  process.exit(1);
19}
20
21const STAMP = Date.now();
22const TEST_USER_ID = `test_user_e2e_${STAMP}`;
23const TEST_API_KEY = `test_key_e2e_${STAMP}`;
24process.env.MCP_USER_API_KEY = TEST_API_KEY;
25
26import { applyGuard } from "../src/lib/quota_guard.js";
27import * as getKpopNewsToday from "../src/mcp/kr/kpop/get_kpop_news_today.js";
28import * as searchNews from "../src/mcp/kr/kpop/search_news.js";
29
30const admin: SupabaseClient = createClient(url, serviceKey, {
31  auth: { persistSession: false },
32});
33
34// ─── helpers ─────────────────────────────────────────────────────────────
35async function insertTrialUser(): Promise<void> {
36  const now = new Date().toISOString();
37  const { error } = await admin.from("mcp_subscriptions").insert({
38    user_id: TEST_USER_ID,
39    api_key: TEST_API_KEY,
40    email: `e2e_${STAMP}@example.com`,
41    status: "active",
42    tier: null,
43    monthly_quota: 0,
44    email_verified: true,
45    credit_balance_usd: 5,
46    total_topup_usd: 0,
47    trial_started_at: now,
48  });
49  if (error) throw new Error(`insertTrialUser: ${error.message}`);
50}
51
52async function balance(): Promise<number> {
53  const { data, error } = await admin
54    .from("mcp_subscriptions")
55    .select("credit_balance_usd")
56    .eq("user_id", TEST_USER_ID).single();
57  if (error) throw new Error(`balance: ${error.message}`);
58  return Number(data?.credit_balance_usd ?? 0);
59}
60
61async function patchSubscription(patch: Record<string, unknown>): Promise<void> {
62  const { error } = await admin
63    .from("mcp_subscriptions").update(patch).eq("user_id", TEST_USER_ID);
64  if (error) throw new Error(`patchSubscription: ${error.message}`);
65}
66
67async function cleanup(): Promise<void> {
68  await admin.from("mcp_usage").delete().eq("user_id", TEST_USER_ID);
69  await admin.from("mcp_topups").delete().eq("user_id", TEST_USER_ID);
70  await admin.from("mcp_subscriptions").delete().eq("user_id", TEST_USER_ID);
71}
72
73interface ToolEnvelope { isError?: boolean; content?: Array<{ type: string; text: string }>; }
74interface ParsedEnv { isError: boolean; errorCode: string | null; raw: string; }
75
76function parseEnv(r: unknown): ParsedEnv {
77  const env = r as ToolEnvelope;
78  const text = env.content?.[0]?.text ?? "{}";
79  let errorCode: string | null = null;
80  try {
81    const p = JSON.parse(text) as { error?: { code?: string } };
82    errorCode = p.error?.code ?? null;
83  } catch { /* */ }
84  return { isError: Boolean(env.isError), errorCode, raw: text };
85}
86
87const REJECTION_CODES = new Set([
88  "ERR_UNAUTHORIZED", "QUOTA_EXCEEDED", "COOLDOWN_ACTIVE",
89  "SUBSCRIPTION_INACTIVE", "EMAIL_NOT_VERIFIED", "INVALID_SUBSCRIPTION_STATE",
90  "INSUFFICIENT_CREDIT", "SERVICE_UNAVAILABLE",
91]);
92function guardPassed(p: ParsedEnv): boolean {
93  if (!p.isError) return true;
94  if (!p.errorCode) return false;
95  return !REJECTION_CODES.has(p.errorCode);
96}
97
98function approx(a: number, b: number, eps = 1e-4): boolean {
99  return Math.abs(a - b) < eps;
100}
101
102interface Result { name: string; pass: boolean; detail: string; }
103const results: Result[] = [];
104
105async function scenario(name: string, fn: () => Promise<{ pass: boolean; detail: string }>): Promise<void> {
106  let row: Result;
107  try { row = { name, ...(await fn()) }; }
108  catch (e) { row = { name, pass: false, detail: `EXCEPTION: ${(e as Error).message}` }; }
109  results.push(row);
110  console.log(`${row.pass ? "✅" : "❌"} ${row.name}\n    ${row.detail}\n`);
111}
112
113// ─── main ─────────────────────────────────────────────────────────────────
114async function main(): Promise<void> {
115  console.log("\n=== MCP server e2e test (credit model) ===");
116  console.log(`STAMP=${STAMP} user=${TEST_USER_ID}\n`);
117
118  try {
119    await scenario("1. Setup trial user — $5 credit, status=active", async () => {
120      await insertTrialUser();
121      const b = await balance();
122      return { pass: approx(b, 5), detail: `balance=${b} (expected 5)` };
123    });
124
125    await scenario("2. First tool call — guard passes, $4.995 left", async () => {
126      const r = await getKpopNewsToday.handler({});
127      const p = parseEnv(r);
128      const b = await balance();
129      return {
130        pass: guardPassed(p) && approx(b, 4.995),
131        detail: `code=${p.errorCode ?? "OK"} balance=${b} (expected 4.995)`,
132      };
133    });
134
135    await scenario("3. 5 more calls — balance ≈ $4.97", async () => {
136      for (let i = 0; i < 5; i++) await getKpopNewsToday.handler({});
137      const b = await balance();
138      return { pass: approx(b, 4.97, 5e-4), detail: `balance=${b} (expected ~4.97)` };
139    });
140
141    await scenario("4. search_news 'e2e_q' — allowed", async () => {
142      const r = await searchNews.handler({ query: `e2e_q_${STAMP}`, lang: "en" });
143      const p = parseEnv(r);
144      const b = await balance();
145      return {
146        pass: guardPassed(p) && approx(b, 4.965, 5e-4),
147        detail: `code=${p.errorCode ?? "OK"} balance=${b} (expected ~4.965)`,
148      };
149    });
150
151    await scenario("5. Repeat same search query (trial = total_topup=0) = COOLDOWN_ACTIVE", async () => {
152      const r = await searchNews.handler({ query: `e2e_q_${STAMP}`, lang: "en" });
153      const p = parseEnv(r);
154      const b = await balance();
155      return {
156        pass: p.isError && p.errorCode === "COOLDOWN_ACTIVE" && approx(b, 4.965, 5e-4),
157        detail: `code=${p.errorCode} balance=${b} (cooldown doesn't consume credit)`,
158      };
159    });
160
161    await scenario("6. Drain balance → next call = INSUFFICIENT_CREDIT", async () => {
162      await patchSubscription({ credit_balance_usd: 0 });
163      const r = await getKpopNewsToday.handler({});
164      const p = parseEnv(r);
165      return {
166        pass: p.isError && p.errorCode === "INSUFFICIENT_CREDIT",
167        detail: `code=${p.errorCode}`,
168      };
169    });
170
171    await scenario("7. Simulate $10 top-up → balance=$10, total_topup>0 (paid)", async () => {
172      await patchSubscription({ credit_balance_usd: 10, total_topup_usd: 10, last_topup_at: new Date().toISOString() });
173      const b = await balance();
174      return { pass: approx(b, 10), detail: `balance=${b}` };
175    });
176
177    await scenario("8. Paid user — call allowed + no cooldown on repeat query", async () => {
178      const q = `paid_q_${STAMP}`;
179      const r1 = await searchNews.handler({ query: q, lang: "en" });
180      const r2 = await searchNews.handler({ query: q, lang: "en" });
181      const p1 = parseEnv(r1);
182      const p2 = parseEnv(r2);
183      return {
184        pass: guardPassed(p1) && guardPassed(p2),
185        detail: `r1.code=${p1.errorCode ?? "OK"} r2.code=${p2.errorCode ?? "OK"}`,
186      };
187    });
188
189    await scenario("9. Cleanup", async () => {
190      await cleanup();
191      const { data: sub } = await admin
192        .from("mcp_subscriptions").select("user_id").eq("user_id", TEST_USER_ID).maybeSingle();
193      return { pass: sub === null, detail: `row=${sub === null ? "null" : "present"}` };
194    });
195
196  } finally {
197    try { await cleanup(); } catch { /* */ }
198  }
199
200  const passed = results.filter((r) => r.pass).length;
201  console.log(`=== Summary: ${passed}/${results.length} passed ===`);
202  if (passed !== results.length) process.exit(1);
203}
204
205main().catch((e) => {
206  console.error("Fatal:", e instanceof Error ? e.message : e);
207  process.exit(1);
208});

scripts/healthcheck.ts

1// Ops healthcheck — DB connectivity + freshness + recent MCP usage.
2// Designed to be cheap (3 small queries) so it can run on a cron every N min.
3//
4// Exit codes:
5//   0 = ok
6//   1 = stale (data older than expected, or no traffic) — Discord alert sent
7//   2 = error (DB unreachable or query failed) — Discord alert sent
8//
9// Run: SUPABASE_URL=... SUPABASE_ANON_KEY=... npm run healthcheck
10
11import { createClient, type SupabaseClient } from "@supabase/supabase-js";
12import { sendDiscordAlert } from "../src/lib/monitoring.js";
13
14const url = process.env.SUPABASE_URL;
15const key = process.env.SUPABASE_ANON_KEY;
16if (!url || !key) {
17  console.error("Missing SUPABASE_URL / SUPABASE_ANON_KEY in env.");
18  process.exit(2);
19}
20
21const supabase: SupabaseClient = createClient(url, key, {
22  auth: { persistSession: false },
23});
24
25const STALE_LATENCY_MS = 1000;
26
27interface HealthReport {
28  status: "ok" | "stale" | "error";
29  db_latency_ms: number;
30  stories_last_1h: number;
31  mcp_usage_24h: number;
32  timestamp: string;
33  errors?: string[];
34}
35
36async function timeQuery<T>(fn: () => Promise<T>): Promise<{ result: T; ms: number }> {
37  const t0 = Date.now();
38  const result = await fn();
39  return { result, ms: Date.now() - t0 };
40}
41
42async function checkConnectivity(): Promise<{ ok: boolean; latency_ms: number; err?: string }> {
43  try {
44    const { result, ms } = await timeQuery(async () =>
45      await supabase.from("stories").select("id").limit(1),
46    );
47    if (result.error) return { ok: false, latency_ms: ms, err: result.error.message };
48    return { ok: true, latency_ms: ms };
49  } catch (e) {
50    return { ok: false, latency_ms: -1, err: (e as Error).message };
51  }
52}
53
54async function countSince(table: string, column: string, sinceIso: string): Promise<number> {
55  const { count, error } = await supabase
56    .from(table)
57    .select("*", { count: "exact", head: true })
58    .gte(column, sinceIso);
59  if (error) throw new Error(`${table} count failed: ${error.message}`);
60  return count ?? 0;
61}
62
63async function main(): Promise<void> {
64  const errors: string[] = [];
65  const now = new Date();
66  const oneHourAgo = new Date(now.getTime() - 3600_000).toISOString();
67  const oneDayAgo = new Date(now.getTime() - 86_400_000).toISOString();
68
69  const conn = await checkConnectivity();
70  if (!conn.ok) {
71    const report: HealthReport = {
72      status: "error",
73      db_latency_ms: conn.latency_ms,
74      stories_last_1h: -1,
75      mcp_usage_24h: -1,
76      timestamp: now.toISOString(),
77      errors: [`db_unreachable: ${conn.err ?? "unknown"}`],
78    };
79    console.log(JSON.stringify(report, null, 2));
80    await sendDiscordAlert(
81      `Healthcheck FAILED — DB unreachable: ${conn.err ?? "unknown"}`,
82      "error",
83    );
84    process.exit(2);
85  }
86
87  let storiesLast1h = -1;
88  let usage24h = -1;
89  try {
90    storiesLast1h = await countSince("stories", "published_at", oneHourAgo);
91  } catch (e) {
92    errors.push((e as Error).message);
93  }
94  try {
95    usage24h = await countSince("mcp_usage", "called_at", oneDayAgo);
96  } catch (e) {
97    errors.push((e as Error).message);
98  }
99
100  // Decide status BEFORE firing alerts (alert fan-out shouldn't change status).
101  const hasError = errors.length > 0;
102  const stale = storiesLast1h === 0 || conn.latency_ms > STALE_LATENCY_MS;
103  const status: HealthReport["status"] = hasError ? "error" : stale ? "stale" : "ok";
104
105  const report: HealthReport = {
106    status,
107    db_latency_ms: conn.latency_ms,
108    stories_last_1h: storiesLast1h,
109    mcp_usage_24h: usage24h,
110    timestamp: now.toISOString(),
111    ...(errors.length > 0 ? { errors } : {}),
112  };
113
114  console.log(JSON.stringify(report, null, 2));
115
116  // Alert fan-out (sendDiscordAlert never throws).
117  if (storiesLast1h === 0) {
118    await sendDiscordAlert("No new stories in the last hour.", "error");
119  }
120  if (conn.latency_ms > STALE_LATENCY_MS) {
121    await sendDiscordAlert(`DB latency ${conn.latency_ms}ms (>${STALE_LATENCY_MS}ms).`, "warn");
122  }
123  if (hasError) {
124    await sendDiscordAlert(`Healthcheck query errors: ${errors.join("; ")}`, "error");
125  }
126
127  process.exit(status === "ok" ? 0 : status === "stale" ? 1 : 2);
128}
129
130main().catch((e) => {
131  console.error("Fatal:", e instanceof Error ? e.message : e);
132  process.exit(2);
133});

scripts/invalidate_cache.ts

1// Ops helper — flushes the trial-config cache in THIS process.
2//
3// ⚠️ Caches are per-PROCESS. Running this script only clears state in the
4// script's own short-lived Node process — it has NO effect on the live
5// MCP server's cache. To force the live server (Apify Actor) to re-read
6// system_config, you need to restart its run instead.
7//
8// Useful for: local development / smoke verification that the export wires
9// up correctly. For production cache rotation, restart the Actor.
10
11import { invalidateConfigCache } from "../src/lib/quota_guard.js";
12
13invalidateConfigCache();
14console.log("Config cache invalidated (this process only).");
15console.log(
16  "NOTE: To rotate the live Actor's cache, restart the Apify run — caches are per-process.",
17);

scripts/llm_tag_backfill.ts

1// scripts/llm_tag_backfill.ts
2// 4-mode LLM tagging backfill for stories.category (11-category taxonomy incl. K-Movie).
3//
4// Modes:
5//   --mode=test10   = 10 rows, dry-run (no DB writes)
6//   --mode=test100  = 100 rows, dry-run + confidence stats
7//   --mode=run1000  = 1,000 rows, DB writes
8//   --mode=runall   = up to 10,000 rows (last 30 days), DB writes
9//
10// Guardrails:
11//   - $30 hard cost cap per run — halts mid-loop if reached
12//   - Y/N confirmation prompt before doing any work
13//     (pass --yes to skip — required for background runs where stdin isn't a TTY)
14//   - Targets only rows where tagged_at IS NULL (idempotent — safe to re-run)
15//     ⚠️ overwrites existing `category` values from older classifier (different taxonomy)
16//   - Window = last 30 days by published_at
17//
18// Requires:
19//   SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY (writes), OPENAI_API_KEY.
20//   Falls back to SUPABASE_ANON_KEY for dry-run modes if service role not set.
21
22import { createClient, type SupabaseClient } from "@supabase/supabase-js";
23import { createInterface } from "node:readline/promises";
24import { stdin, stdout } from "node:process";
25
26import { tagStory } from "../src/lib/tagger.js";
27
28const COST_CAP_USD = 30;
29const COST_PER_CALL_ESTIMATE = 0.0003; // GPT-4o-mini, ~1.5K in / 100 out
30const WINDOW_DAYS = 30;
31const FETCH_PAGE = 1000;
32
33type Mode = "test10" | "test100" | "run1000" | "runall";
34
35interface ModeConfig {
36  mode: Mode;
37  maxRows: number;
38  dryRun: boolean;
39}
40
41const MODES: Record<Mode, ModeConfig> = {
42  test10: { mode: "test10", maxRows: 10, dryRun: true },
43  test100: { mode: "test100", maxRows: 100, dryRun: true },
44  run1000: { mode: "run1000", maxRows: 1000, dryRun: false },
45  // runall has a soft 10K row ceiling; the $30 cost cap is the primary brake.
46  runall: { mode: "runall", maxRows: 10000, dryRun: false },
47};
48
49interface StoryRow {
50  id: number | string;
51  title_ko: string | null;
52  content_ko: string | null;
53}
54
55// 한국어 원문 컬럼만 사용 (base title/summary 컬럼 X).
56// content_ko 는 본문 전체라 길이 길 수 있어 분류용으로는 앞부분만 잘라 쓴다.
57const SUMMARY_CHAR_CAP = 600;
58
59function parseMode(argv: string[]): Mode {
60  const arg = argv.find((a) => a.startsWith("--mode="));
61  if (!arg) {
62    throw new Error(
63      "missing --mode= argument. valid: " + Object.keys(MODES).join(", "),
64    );
65  }
66  const m = arg.split("=")[1] ?? "";
67  if (!(m in MODES)) {
68    throw new Error(
69      `invalid mode '${m}'. valid: ` + Object.keys(MODES).join(", "),
70    );
71  }
72  return m as Mode;
73}
74
75function buildSupabase(): { client: SupabaseClient; hasServiceRole: boolean } {
76  const url = process.env.SUPABASE_URL;
77  const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
78  const anonKey = process.env.SUPABASE_ANON_KEY;
79  const key = serviceKey ?? anonKey;
80  if (!url || !key) {
81    throw new Error(
82      "missing SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (or SUPABASE_ANON_KEY).",
83    );
84  }
85  return {
86    client: createClient(url, key, { auth: { persistSession: false } }),
87    hasServiceRole: Boolean(serviceKey),
88  };
89}
90
91async function fetchUntagged(
92  supabase: SupabaseClient,
93  maxRows: number,
94): Promise<StoryRow[]> {
95  const cutoff = new Date(Date.now() - WINDOW_DAYS * 86_400_000).toISOString();
96  const out: StoryRow[] = [];
97  while (out.length < maxRows) {
98    const remaining = maxRows - out.length;
99    const take = Math.min(FETCH_PAGE, remaining);
100    const { data, error } = await supabase
101      .from("stories")
102      .select("id, title_ko, content_ko")
103      .is("tagged_at", null)
104      .eq("is_off_topic", false)
105      .gte("published_at", cutoff)
106      .order("published_at", { ascending: false })
107      .range(out.length, out.length + take - 1);
108    if (error) {
109      throw new Error(
110        `fetch failed: ${error.message} (hint: did the 20260518_add_category_columns.sql migration run?)`,
111      );
112    }
113    if (!data || data.length === 0) break;
114    out.push(...(data as unknown as StoryRow[]));
115    if (data.length < take) break;
116  }
117  return out;
118}
119
120async function confirm(question: string): Promise<boolean> {
121  const rl = createInterface({ input: stdin, output: stdout });
122  try {
123    const ans = (await rl.question(question)).trim().toLowerCase();
124    return ans === "y" || ans === "yes";
125  } finally {
126    rl.close();
127  }
128}
129
130async function main() {
131  const mode = parseMode(process.argv.slice(2));
132  const cfg = MODES[mode];
133
134  if (!process.env.OPENAI_API_KEY) {
135    throw new Error("OPENAI_API_KEY is required (see .env.example).");
136  }
137
138  const { client: supabase, hasServiceRole } = buildSupabase();
139
140  console.log(`\n=== LLM tagging backfill: mode=${mode} ===`);
141  console.log(
142    `Fetching un-tagged stories (last ${WINDOW_DAYS} days, tagged_at IS NULL, is_off_topic=false, cap=${cfg.maxRows})...`,
143  );
144
145  const stories = await fetchUntagged(supabase, cfg.maxRows);
146
147  if (stories.length === 0) {
148    console.log("No un-tagged stories in window. Nothing to do.");
149    return;
150  }
151
152  const estCost = stories.length * COST_PER_CALL_ESTIMATE;
153  console.log(`Rows to process: ${stories.length}`);
154  console.log(
155    `Estimated cost:  $${estCost.toFixed(4)}  (hard cap: $${COST_CAP_USD.toFixed(2)})`,
156  );
157  if (estCost > COST_CAP_USD) {
158    const haltAt = Math.floor(COST_CAP_USD / COST_PER_CALL_ESTIMATE);
159    console.log(
160      `⚠️  Estimate exceeds cap — will halt at approximately ${haltAt} rows.`,
161    );
162  }
163  console.log(`DB writes:       ${cfg.dryRun ? "NO  (dry-run)" : "YES"}`);
164  if (!cfg.dryRun && !hasServiceRole) {
165    console.log(
166      "⚠️  No SUPABASE_SERVICE_ROLE_KEY set — using anon key. Writes will likely fail under RLS.",
167    );
168  }
169
170  const autoYes = process.argv.includes("--yes");
171  if (autoYes) {
172    console.log("\n--yes flag set — skipping confirmation prompt.");
173  } else if (!(await confirm("\nContinue? (y/N) "))) {
174    console.log("Aborted by user.");
175    return;
176  }
177
178  const counts = new Map<string, number>();
179  const confidences: number[] = [];
180  let totalCost = 0;
181  let processed = 0;
182  let failed = 0;
183  let skipped = 0;
184  const start = Date.now();
185
186  for (const story of stories) {
187    if (totalCost >= COST_CAP_USD) {
188      console.log(
189        `\n[halt] Cost cap $${COST_CAP_USD.toFixed(2)} reached after ${processed} rows.`,
190      );
191      break;
192    }
193
194    const title = (story.title_ko ?? "").trim();
195    const summary = (story.content_ko ?? "").slice(0, SUMMARY_CHAR_CAP).trim();
196    if (title.length === 0 && summary.length === 0) {
197      skipped += 1;
198      continue;
199    }
200
201    try {
202      const { result, usage } = await tagStory({ title, summary });
203      totalCost += usage.cost_usd;
204      counts.set(result.category, (counts.get(result.category) ?? 0) + 1);
205      confidences.push(result.confidence);
206      processed += 1;
207
208      if (cfg.dryRun) {
209        const sec = result.secondary_category ? ` (+${result.secondary_category})` : "";
210        const shortTitle = title.slice(0, 60);
211        console.log(
212          `[${processed}/${stories.length}] id=${story.id} → ${result.category}${sec}` +
213            `  conf=${result.confidence.toFixed(2)}  | "${shortTitle}"`,
214        );
215      } else {
216        const { error } = await supabase
217          .from("stories")
218          .update({
219            category: result.category,
220            secondary_category: result.secondary_category,
221            category_confidence: result.confidence,
222            tagged_at: new Date().toISOString(),
223          })
224          .eq("id", story.id);
225        if (error) {
226          failed += 1;
227          console.log(`[update fail] id=${story.id}: ${error.message}`);
228        } else if (processed % 50 === 0) {
229          console.log(
230            `[progress] ${processed}/${stories.length}  cost=$${totalCost.toFixed(4)}`,
231          );
232        }
233      }
234    } catch (e) {
235      failed += 1;
236      const msg = e instanceof Error ? e.message : String(e);
237      console.log(`[tag fail] id=${story.id}: ${msg}`);
238    }
239  }
240
241  // Summary
242  const elapsedS = (Date.now() - start) / 1000;
243  console.log(`\n=== Summary ===`);
244  console.log(`Mode:        ${mode}${cfg.dryRun ? "  (dry-run)" : ""}`);
245  console.log(
246    `Processed:   ${processed}  /  attempted ${stories.length}  /  failed ${failed}  /  skipped ${skipped}`,
247  );
248  console.log(`Actual cost: $${totalCost.toFixed(4)}`);
249  console.log(`Elapsed:     ${elapsedS.toFixed(1)}s`);
250
251  if (mode === "test100" && confidences.length > 0) {
252    const avg = confidences.reduce((a, b) => a + b, 0) / confidences.length;
253    const lowConf = confidences.filter((c) => c < 0.6).length;
254    const pct = ((lowConf / confidences.length) * 100).toFixed(1);
255    console.log(`Avg confidence: ${avg.toFixed(3)}`);
256    console.log(`Low-confidence (<0.6) rows: ${lowConf} (${pct}%)`);
257  }
258
259  if (counts.size > 0) {
260    console.log(`\nCategory distribution:`);
261    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
262    const total = sorted.reduce((acc, [, n]) => acc + n, 0);
263    for (const [cat, n] of sorted) {
264      const pct = ((n / total) * 100).toFixed(1);
265      console.log(`  ${cat.padEnd(12)}  ${String(n).padStart(5)}  (${pct}%)`);
266    }
267  }
268}
269
270main().catch((e) => {
271  console.error("Fatal:", e instanceof Error ? e.message : e);
272  process.exit(1);
273});

scripts/smoke_test.ts

1// scripts/smoke_test.ts
2// 25 MCP tools 전체 production-readiness 검증 (stdio 우회, handler 직접 호출).
3//
4// Test 분포:
5//   - K-Pop specialized (5 tools × 2 케이스) = 10
6//   - 10 카테고리 × (weekly_trend + search_archive) = 20
7//   - 총 30 케이스
8//
9// 실행: npm run smoke:test
10// 요구: SUPABASE_URL + SUPABASE_ANON_KEY (.env). LLM 호출 0번 (script tool 은 placeholder 반환).
11
12// ---- K-Pop specialized (5)
13import * as getKpopNewsToday from "../src/mcp/kr/kpop/get_kpop_news_today.js";
14import * as getArtistTimeline from "../src/mcp/kr/kpop/get_artist_timeline.js";
15import * as generateVideoScript from "../src/mcp/kr/kpop/generate_video_script.js";
16import * as getTrendingClusters from "../src/mcp/kr/kpop/get_trending_clusters.js";
17import * as searchNews from "../src/mcp/kr/kpop/search_news.js";
18
19// ---- 10 categories × 2 tools each (20 total)
20import * as kdramaWeekly from "../src/mcp/kr/kdrama/get_weekly_media_trend.js";
21import * as kdramaSearch from "../src/mcp/kr/kdrama/search_media_archive.js";
22import * as kmovieWeekly from "../src/mcp/kr/kmovie/get_weekly_media_trend.js";
23import * as kmovieSearch from "../src/mcp/kr/kmovie/search_media_archive.js";
24import * as kbeautyWeekly from "../src/mcp/kr/kbeauty/get_weekly_media_trend.js";
25import * as kbeautySearch from "../src/mcp/kr/kbeauty/search_media_archive.js";
26import * as kfoodWeekly from "../src/mcp/kr/kfood/get_weekly_media_trend.js";
27import * as kfoodSearch from "../src/mcp/kr/kfood/search_media_archive.js";
28import * as kgameWeekly from "../src/mcp/kr/kgame/get_weekly_media_trend.js";
29import * as kgameSearch from "../src/mcp/kr/kgame/search_media_archive.js";
30import * as ktechWeekly from "../src/mcp/kr/ktech/get_weekly_media_trend.js";
31import * as ktechSearch from "../src/mcp/kr/ktech/search_media_archive.js";
32import * as kstockWeekly from "../src/mcp/kr/kstock/get_weekly_media_trend.js";
33import * as kstockSearch from "../src/mcp/kr/kstock/search_media_archive.js";
34import * as ktravelWeekly from "../src/mcp/kr/ktravel/get_weekly_media_trend.js";
35import * as ktravelSearch from "../src/mcp/kr/ktravel/search_media_archive.js";
36import * as kwebtoonWeekly from "../src/mcp/kr/kwebtoon/get_weekly_media_trend.js";
37import * as kwebtoonSearch from "../src/mcp/kr/kwebtoon/search_media_archive.js";
38import * as ktrendsWeekly from "../src/mcp/kr/ktrends/get_weekly_media_trend.js";
39import * as ktrendsSearch from "../src/mcp/kr/ktrends/search_media_archive.js";
40
41// Hardcoded cluster_id (오늘 KST 윈도우 안 — 나홍진 <호프> 칸 프리미어 cluster).
42const SAMPLE_CLUSTER_ID = "3876";
43
44interface TestCase {
45  tool: { NAME: string; handler: (raw: Record<string, unknown>) => Promise<unknown> };
46  label: string;
47  input: Record<string, unknown>;
48  /** 성공으로 간주할 응답에 반드시 있어야 할 top-level key 들. */
49  expectKeys: string[];
50}
51
52// ---- K-Pop tests (existing — 10 cases) ----
53const KPOP_TESTS: TestCase[] = [
54  {
55    tool: getKpopNewsToday,
56    label: "정상 / lang=en, default date=today, limit=5",
57    input: { lang: "en", limit: 5 },
58    expectKeys: ["date", "lang", "count", "items"],
59  },
60  {
61    tool: getKpopNewsToday,
62    label: "엣지 / lang=ja, group_filter='NewJeans' = 다국어 폴백 + 필터",
63    input: { lang: "ja", group_filter: "NewJeans", limit: 5 },
64    expectKeys: ["date", "lang", "count", "items"],
65  },
66  {
67    tool: getArtistTimeline,
68    label: "정상 / artist='BTS', lang=en, default 30d window",
69    input: { artist: "BTS", lang: "en", limit: 10 },
70    expectKeys: ["artist", "start_date", "end_date", "count", "items"],
71  },
72  {
73    tool: getArtistTimeline,
74    label: "엣지 / artist='아이유', lang=ko = 한국어 쿼리",
75    input: { artist: "아이유", lang: "ko", limit: 10 },
76    expectKeys: ["artist", "start_date", "end_date", "count", "items"],
77  },
78  {
79    tool: getTrendingClusters,
80    label: "정상 / category=kpop, lang=en, limit=3, momentum_filter=rising",
81    input: { category: "kpop", lang: "en", limit: 3, momentum_filter: "rising" },
82    expectKeys: ["window_hours", "category", "momentum_filter", "count", "items"],
83  },
84  {
85    tool: getTrendingClusters,
86    label: "엣지 / category=all, lang=es = 스페인어 + all",
87    input: { category: "all", lang: "es", limit: 5 },
88    expectKeys: ["window_hours", "category", "momentum_filter", "count", "items"],
89  },
90  {
91    tool: searchNews,
92    label: "정상 / query='comeback', lang=en, limit=5",
93    input: { query: "comeback", lang: "en", limit: 5 },
94    expectKeys: ["query", "lang", "date_from", "date_to", "count", "items"],
95  },
96  {
97    tool: searchNews,
98    label: "엣지 / query='컴백', lang=ko = 한국어 키워드 + content_ko ILIKE",
99    input: { query: "컴백", lang: "ko", limit: 5 },
100    expectKeys: ["query", "lang", "date_from", "date_to", "count", "items"],
101  },
102  {
103    tool: generateVideoScript,
104    label: "정상 / topic only, lang=en, platform=tiktok (LLM placeholder)",
105    input: { topic: "K-pop trending", lang: "en", platform: "tiktok", duration_seconds: 60 },
106    expectKeys: ["lang", "platform", "duration_seconds", "grounding", "script"],
107  },
108  {
109    tool: generateVideoScript,
110    label: `엣지 / cluster_id='${SAMPLE_CLUSTER_ID}', lang=ja = 실제 cluster + 일본어`,
111    input: { cluster_id: SAMPLE_CLUSTER_ID, lang: "ja", platform: "youtube_shorts" },
112    expectKeys: ["lang", "platform", "grounding", "script"],
113  },
114];
115
116// ---- 10 categories × 2 tool tests = 20 auto-generated ----
117interface CategorySpec {
118  shortKey: string;
119  weekly: { NAME: string; handler: (raw: Record<string, unknown>) => Promise<unknown> };
120  search: { NAME: string; handler: (raw: Record<string, unknown>) => Promise<unknown> };
121  /** search 시 사용할 키워드 (영어). */
122  keyword: string;
123}
124
125const CATEGORY_SPECS: CategorySpec[] = [
126  { shortKey: "kdrama", weekly: kdramaWeekly, search: kdramaSearch, keyword: "drama" },
127  { shortKey: "kmovie", weekly: kmovieWeekly, search: kmovieSearch, keyword: "movie" },
128  { shortKey: "kbeauty", weekly: kbeautyWeekly, search: kbeautySearch, keyword: "beauty" },
129  { shortKey: "kfood", weekly: kfoodWeekly, search: kfoodSearch, keyword: "food" },
130  { shortKey: "kgame", weekly: kgameWeekly, search: kgameSearch, keyword: "game" },
131  { shortKey: "ktech", weekly: ktechWeekly, search: ktechSearch, keyword: "tech" },
132  { shortKey: "kstock", weekly: kstockWeekly, search: kstockSearch, keyword: "stock" },
133  { shortKey: "ktravel", weekly: ktravelWeekly, search: ktravelSearch, keyword: "travel" },
134  { shortKey: "kwebtoon", weekly: kwebtoonWeekly, search: kwebtoonSearch, keyword: "webtoon" },
135  { shortKey: "ktrends", weekly: ktrendsWeekly, search: ktrendsSearch, keyword: "trend" },
136];
137
138const CATEGORY_TESTS: TestCase[] = CATEGORY_SPECS.flatMap((c) => [
139  {
140    tool: c.weekly,
141    label: `${c.shortKey} weekly_trend / lang=en, default 7d window`,
142    input: { lang: "en" },
143    expectKeys: ["category", "window_days", "lang", "data_freshness", "count", "items"],
144  },
145  {
146    tool: c.search,
147    label: `${c.shortKey} search_archive / query="${c.keyword}", lang=en, default 30d`,
148    input: { query: c.keyword, lang: "en", limit: 5 },
149    expectKeys: ["category", "query", "lang", "date_from", "date_to", "count", "items"],
150  },
151]);
152
153const TESTS: TestCase[] = [...KPOP_TESTS, ...CATEGORY_TESTS];
154
155interface ToolEnvelope {
156  content?: { type: string; text: string }[];
157  isError?: boolean;
158}
159
160interface TestResult {
161  idx: number;
162  tool: string;
163  label: string;
164  input: Record<string, unknown>;
165  status: "pass" | "fail" | "empty";
166  elapsedMs: number;
167  notes: string[];
168  preview: string;
169}
170
171function isToolEnvelope(x: unknown): x is ToolEnvelope {
172  return typeof x === "object" && x !== null && "content" in x;
173}
174
175function summarizeItems(parsed: Record<string, unknown>): string {
176  const count = typeof parsed.count === "number" ? parsed.count : undefined;
177  const items = Array.isArray(parsed.items) ? parsed.items : undefined;
178  if (count !== undefined && items) {
179    if (items.length === 0) return `count=0 (empty)`;
180    const first = items[0] as Record<string, unknown>;
181    const titlePreview =
182      typeof first.title === "string"
183        ? `"${first.title.slice(0, 50)}"`
184        : typeof first.lead === "object" && first.lead !== null
185          ? `lead="${String((first.lead as Record<string, unknown>).title ?? "").slice(0, 50)}"`
186          : "<no title>";
187    const freshness = typeof parsed.data_freshness === "string" ? ` [${parsed.data_freshness}]` : "";
188    return `count=${count}${freshness}, first: ${titlePreview}`;
189  }
190  if (parsed.script && parsed.grounding) {
191    const status = String(parsed.status ?? "unknown");
192    return `status=${status}, grounding.lead_title="${String((parsed.grounding as Record<string, unknown>).lead_title ?? "").slice(0, 50)}"`;
193  }
194  return JSON.stringify(parsed).slice(0, 120);
195}
196
197async function runOne(t: TestCase, idx: number): Promise<TestResult> {
198  const start = Date.now();
199  const notes: string[] = [];
200  let status: TestResult["status"] = "pass";
201  let preview = "";
202
203  try {
204    const raw = await t.tool.handler(t.input);
205    const elapsedMs = Date.now() - start;
206
207    if (!isToolEnvelope(raw)) {
208      return {
209        idx,
210        tool: t.tool.NAME,
211        label: t.label,
212        input: t.input,
213        status: "fail",
214        elapsedMs,
215        notes: ["handler did not return a tool envelope"],
216        preview: "",
217      };
218    }
219
220    if (raw.isError) {
221      const errText = raw.content?.[0]?.text ?? "<no error text>";
222      return {
223        idx,
224        tool: t.tool.NAME,
225        label: t.label,
226        input: t.input,
227        status: "fail",
228        elapsedMs,
229        notes: [`isError=true: ${errText.slice(0, 200)}`],
230        preview: errText.slice(0, 200),
231      };
232    }
233
234    const text = raw.content?.[0]?.text;
235    if (!text) {
236      return {
237        idx,
238        tool: t.tool.NAME,
239        label: t.label,
240        input: t.input,
241        status: "fail",
242        elapsedMs,
243        notes: ["empty content[0].text"],
244        preview: "",
245      };
246    }
247
248    let parsed: Record<string, unknown>;
249    try {
250      parsed = JSON.parse(text);
251    } catch (e) {
252      return {
253        idx,
254        tool: t.tool.NAME,
255        label: t.label,
256        input: t.input,
257        status: "fail",
258        elapsedMs,
259        notes: [`JSON parse fail: ${(e as Error).message}`],
260        preview: text.slice(0, 200),
261      };
262    }
263
264    for (const k of t.expectKeys) {
265      if (!(k in parsed)) notes.push(`missing key: ${k}`);
266    }
267    if (notes.length > 0) {
268      return { idx, tool: t.tool.NAME, label: t.label, input: t.input, status: "fail", elapsedMs, notes, preview: summarizeItems(parsed) };
269    }
270
271    if (typeof parsed.count === "number" && parsed.count === 0) {
272      status = "empty";
273      notes.push("count=0 — no data matched (tool works, but DB has no rows for this query)");
274    }
275
276    preview = summarizeItems(parsed);
277    return { idx, tool: t.tool.NAME, label: t.label, input: t.input, status, elapsedMs, notes, preview };
278  } catch (e) {
279    return {
280      idx,
281      tool: t.tool.NAME,
282      label: t.label,
283      input: t.input,
284      status: "fail",
285      elapsedMs: Date.now() - start,
286      notes: [`exception: ${(e as Error).message}`],
287      preview: "",
288    };
289  }
290}
291
292async function main() {
293  console.log(`\n=== MCP smoke test: ${TESTS.length} cases (10 K-Pop + 20 category) ===\n`);
294
295  if (!process.env.SUPABASE_URL || !process.env.SUPABASE_ANON_KEY) {
296    console.error("Missing SUPABASE_URL / SUPABASE_ANON_KEY env vars.");
297    process.exit(1);
298  }
299
300  const results: TestResult[] = [];
301  for (let i = 0; i < TESTS.length; i++) {
302    const r = await runOne(TESTS[i]!, i + 1);
303    results.push(r);
304
305    const icon = r.status === "pass" ? "✅" : r.status === "empty" ? "⚠️" : "❌";
306    const inputStr = JSON.stringify(r.input);
307    console.log(
308      `${icon} [${r.idx.toString().padStart(2)}] ${r.tool.padEnd(28)} ${r.elapsedMs.toString().padStart(5)}ms  | ${r.label}`,
309    );
310    console.log(`     input:   ${inputStr}`);
311    console.log(`     output:  ${r.preview}`);
312    if (r.notes.length > 0) {
313      for (const n of r.notes) console.log(`     note:    ${n}`);
314    }
315    console.log("");
316  }
317
318  const pass = results.filter((r) => r.status === "pass").length;
319  const empty = results.filter((r) => r.status === "empty").length;
320  const fail = results.filter((r) => r.status === "fail").length;
321
322  console.log(`\n=== Summary ===`);
323  console.log(`  ✅ pass:  ${pass}/${TESTS.length}`);
324  console.log(`  ⚠️ empty: ${empty}/${TESTS.length}  (handler works, 0 results)`);
325  console.log(`  ❌ fail:  ${fail}/${TESTS.length}`);
326  if (fail > 0) {
327    console.log(`\nFailures:`);
328    for (const r of results.filter((r) => r.status === "fail")) {
329      console.log(`  - [${r.idx}] ${r.tool}: ${r.notes.join("; ")}`);
330    }
331    process.exit(1);
332  }
333}
334
335main().catch((e) => {
336  console.error("Fatal:", e instanceof Error ? e.message : e);
337  process.exit(1);
338});

scripts/test_credit_system.ts

1// Credit system integration tests — hit live Supabase, exercise the
2// check_and_charge_credit RPC + the enterprise fallback.
3//
4// Required env: SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY.
5// MUST NOT have QUOTA_BYPASS=1.
6// Run: npm run test:credit_system
7
8import { createClient, type SupabaseClient } from "@supabase/supabase-js";
9
10const url = process.env.SUPABASE_URL;
11const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
12if (!url || !serviceKey) {
13  console.error("Missing SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY in env.");
14  process.exit(1);
15}
16if (process.env.QUOTA_BYPASS === "1") {
17  console.error("QUOTA_BYPASS=1 set — would skip the flow under test. unset and rerun.");
18  process.exit(1);
19}
20
21const admin: SupabaseClient = createClient(url, serviceKey, {
22  auth: { persistSession: false },
23});
24
25const STAMP = Date.now();
26const PRICE = 0.005;
27
28interface SubFixture {
29  user_id: string;
30  api_key: string;
31  email: string;
32  status?: "active" | "canceled";
33  is_enterprise?: boolean;
34  credit_balance_usd?: number;
35  total_topup_usd?: number;
36  monthly_quota?: number;
37}
38
39async function insertSub(f: SubFixture): Promise<void> {
40  const now = new Date().toISOString();
41  const { error } = await admin.from("mcp_subscriptions").insert({
42    user_id: f.user_id,
43    api_key: f.api_key,
44    email: f.email,
45    status: f.status ?? "active",
46    tier: null,
47    monthly_quota: f.monthly_quota ?? 0,
48    email_verified: true,
49    credit_balance_usd: f.credit_balance_usd ?? 5,
50    total_topup_usd: f.total_topup_usd ?? 0,
51    is_enterprise: f.is_enterprise ?? false,
52    trial_started_at: now,
53    current_period_start: now,
54  });
55  if (error) throw new Error(`insertSub ${f.user_id}: ${error.message}`);
56}
57
58async function cleanup(userId: string): Promise<void> {
59  await admin.from("mcp_usage").delete().eq("user_id", userId);
60  await admin.from("mcp_topups").delete().eq("user_id", userId);
61  await admin.from("mcp_subscriptions").delete().eq("user_id", userId);
62}
63
64interface ChargeResp {
65  allowed: boolean;
66  error_code?: string;
67  credit_balance_remaining?: number;
68  cost_this_call?: number;
69  total_calls?: number;
70  current_balance?: number;
71  required?: number;
72  is_trial?: boolean;
73  // enterprise fallback fields
74  quota_used?: number;
75  quota_limit?: number;
76}
77
78async function charge(userId: string, tool = "test_tool", hash: string | null = null): Promise<ChargeResp> {
79  const { data, error } = await admin.rpc("check_and_charge_credit", {
80    p_user_id: userId,
81    p_tool_name: tool,
82    p_query_hash: hash,
83  });
84  if (error) throw new Error(`rpc: ${error.message}`);
85  return data as ChargeResp;
86}
87
88interface Result { name: string; pass: boolean; detail: string; }
89const results: Result[] = [];
90
91async function scenario(name: string, fn: () => Promise<{ pass: boolean; detail: string }>): Promise<void> {
92  let row: Result;
93  try { row = { name, ...(await fn()) }; }
94  catch (e) { row = { name, pass: false, detail: `EXCEPTION: ${(e as Error).message}` }; }
95  results.push(row);
96  console.log(`${row.pass ? "✅" : "❌"} ${row.name}\n    ${row.detail}\n`);
97}
98
99function approxEq(a: number, b: number, eps = 1e-6): boolean {
100  return Math.abs(a - b) < eps;
101}
102
103async function main(): Promise<void> {
104  console.log("\n=== check_and_charge_credit integration tests ===");
105  console.log(`STAMP=${STAMP}\n`);
106
107  // 1 — Trial signup gets $5 credit.
108  const uid1 = `test_credit_trial_${STAMP}`;
109  await scenario("1. New trial user = $5 free credit + status=active", async () => {
110    await insertSub({
111      user_id: uid1,
112      api_key: `apk_trial_${STAMP}`,
113      email: `t1_${STAMP}@example.com`,
114      credit_balance_usd: 5,
115      total_topup_usd: 0,
116    });
117    const { data } = await admin
118      .from("mcp_subscriptions")
119      .select("credit_balance_usd, status, total_topup_usd")
120      .eq("user_id", uid1).single();
121    return {
122      pass: data?.status === "active" && Number(data?.credit_balance_usd) === 5 && Number(data?.total_topup_usd) === 0,
123      detail: `balance=${data?.credit_balance_usd} status=${data?.status} total_topup=${data?.total_topup_usd}`,
124    };
125  });
126
127  // 2 — Single call deducts $0.005.
128  await scenario("2. One call = $0.005 deducted", async () => {
129    const r = await charge(uid1, "tool_a");
130    return {
131      pass: r.allowed === true && approxEq(r.credit_balance_remaining ?? 0, 4.995) && r.cost_this_call === PRICE,
132      detail: `allowed=${r.allowed} balance_after=${r.credit_balance_remaining} cost=${r.cost_this_call}`,
133    };
134  });
135
136  // 3 — 5 calls = balance ≈ 4.97.
137  await scenario("3. 5 more calls = balance ≈ $4.97", async () => {
138    for (let i = 0; i < 5; i++) await charge(uid1, "tool_b");
139    const { data } = await admin.from("mcp_subscriptions").select("credit_balance_usd, total_calls_made").eq("user_id", uid1).single();
140    const bal = Number(data?.credit_balance_usd ?? 0);
141    return {
142      pass: approxEq(bal, 4.97, 1e-4) && data?.total_calls_made === 6,
143      detail: `balance=${bal} total_calls_made=${data?.total_calls_made} (expected ~4.97, 6)`,
144    };
145  });
146
147  // 4 — Exhaust balance → INSUFFICIENT_CREDIT.
148  const uid4 = `test_credit_empty_${STAMP}`;
149  await scenario("4. balance=0 next call = INSUFFICIENT_CREDIT", async () => {
150    await insertSub({
151      user_id: uid4,
152      api_key: `apk_empty_${STAMP}`,
153      email: `t4_${STAMP}@example.com`,
154      credit_balance_usd: 0,
155      total_topup_usd: 0,
156    });
157    const r = await charge(uid4, "tool_x");
158    return {
159      pass: r.allowed === false && r.error_code === "INSUFFICIENT_CREDIT" && r.current_balance === 0,
160      detail: `code=${r.error_code} current=${r.current_balance} required=${r.required}`,
161    };
162  });
163
164  // 5 — Simulate top-up = balance += 10. Subsequent calls allowed.
165  await scenario("5. Manual top-up $10 → 2,000+ calls available", async () => {
166    await admin.from("mcp_subscriptions").update({
167      credit_balance_usd: 10,
168      total_topup_usd: 10,
169      last_topup_at: new Date().toISOString(),
170    }).eq("user_id", uid4);
171    await admin.from("mcp_topups").insert({
172      user_id: uid4,
173      amount_usd: 10,
174      paddle_transaction_id: `txn_test_${STAMP}_5`,
175      is_auto_topup: false,
176    });
177    const r = await charge(uid4, "tool_y");
178    return {
179      pass: r.allowed === true && approxEq(r.credit_balance_remaining ?? 0, 9.995),
180      detail: `allowed=${r.allowed} balance_after=${r.credit_balance_remaining}`,
181    };
182  });
183
184  // 6 — Trial user (total_topup=0) + same query hash = COOLDOWN_ACTIVE on repeat.
185  const uid6 = `test_credit_cooldown_${STAMP}`;
186  const sharedHash = `hash_cd_${STAMP}`;
187  await scenario("6. Trial user + repeated query = COOLDOWN_ACTIVE", async () => {
188    await insertSub({
189      user_id: uid6,
190      api_key: `apk_cd_${STAMP}`,
191      email: `t6_${STAMP}@example.com`,
192      credit_balance_usd: 5,
193      total_topup_usd: 0,
194    });
195    const r1 = await charge(uid6, "search_news", sharedHash);
196    const r2 = await charge(uid6, "search_news", sharedHash);
197    return {
198      pass: r1.allowed === true && r2.allowed === false && r2.error_code === "COOLDOWN_ACTIVE",
199      detail: `r1.allowed=${r1.allowed} r2.code=${r2.error_code}`,
200    };
201  });
202
203  // 7 — Paid user (total_topup>0) + same query hash = NO cooldown.
204  await scenario("7. Paid user (uid4 = $10 topped up) + repeated query = no cooldown", async () => {
205    const h = `hash_paid_${STAMP}`;
206    const r1 = await charge(uid4, "search_news", h);
207    const r2 = await charge(uid4, "search_news", h);
208    return {
209      pass: r1.allowed === true && r2.allowed === true,
210      detail: `r1.allowed=${r1.allowed} r2.allowed=${r2.allowed} (paid users skip cooldown)`,
211    };
212  });
213
214  // 8 — Enterprise user falls through to check_and_record_usage.
215  const uid8 = `test_credit_ent_${STAMP}`;
216  await scenario("8. Enterprise user routes to check_and_record_usage (quota path)", async () => {
217    await insertSub({
218      user_id: uid8,
219      api_key: `apk_ent_${STAMP}`,
220      email: `t8_${STAMP}@example.com`,
221      is_enterprise: true,
222      monthly_quota: 100,
223      credit_balance_usd: 0, // irrelevant for enterprise
224      total_topup_usd: 0,
225    });
226    const r = await charge(uid8, "tool_e");
227    // Enterprise response has quota_used / quota_limit, NOT credit_balance_remaining
228    return {
229      pass: r.allowed === true && typeof r.quota_used === "number" && r.credit_balance_remaining === undefined,
230      detail: `allowed=${r.allowed} quota_used=${r.quota_used} credit_balance_remaining=${r.credit_balance_remaining}`,
231    };
232  });
233
234  // Cleanup all fixtures.
235  for (const uid of [uid1, uid4, uid6, uid8]) {
236    try { await cleanup(uid); } catch { /* noop */ }
237  }
238
239  const passed = results.filter((r) => r.pass).length;
240  console.log(`=== Summary: ${passed}/${results.length} passed ===`);
241  if (passed !== results.length) process.exit(1);
242}
243
244main().catch(async (e) => {
245  console.error("Fatal:", e instanceof Error ? e.message : e);
246  process.exit(1);
247});

scripts/test_quota_rpc.ts

1// scripts/test_quota_rpc.ts
2// Integration test for check_and_record_usage RPC (live Supabase).
3// 6 scenarios; each creates + cleans up its own fixture rows.
4//
5// Requires: SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY (writes).
6// Run: npm run test:rpc
7
8import { createClient, type SupabaseClient } from "@supabase/supabase-js";
9
10const url = process.env.SUPABASE_URL;
11const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
12if (!url || !key) {
13  console.error("Missing SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY in env.");
14  process.exit(1);
15}
16
17const supabase: SupabaseClient = createClient(url, key, {
18  auth: { persistSession: false },
19});
20
21const STAMP = Date.now();
22
23interface SubscriptionFixture {
24  user_id: string;
25  api_key: string;
26  status: "trialing" | "active";
27  email_verified: boolean;
28  monthly_quota: number;
29}
30
31async function insertSubscription(f: SubscriptionFixture): Promise<void> {
32  const now = new Date().toISOString();
33  const inWeek = new Date(Date.now() + 7 * 86_400_000).toISOString();
34  const inMonth = new Date(Date.now() + 30 * 86_400_000).toISOString();
35
36  const base: Record<string, unknown> = {
37    user_id: f.user_id,
38    api_key: f.api_key,
39    status: f.status,
40    email_verified: f.email_verified,
41    monthly_quota: f.monthly_quota,
42  };
43  const row: Record<string, unknown> =
44    f.status === "trialing"
45      ? { ...base, tier: null, trial_started_at: now, trial_ends_at: inWeek }
46      : { ...base, tier: "starter", current_period_start: now, current_period_end: inMonth };
47
48  const { error } = await supabase.from("mcp_subscriptions").insert(row);
49  if (error) throw new Error(`insert subscription failed: ${error.message}`);
50}
51
52async function cleanup(userId: string): Promise<void> {
53  await supabase.from("mcp_usage").delete().eq("user_id", userId);
54  await supabase.from("mcp_subscriptions").delete().eq("user_id", userId);
55}
56
57interface RpcResponse {
58  allowed: boolean;
59  error_code?: string;
60  status?: string;
61  used?: number;
62  limit?: number;
63  user_id?: string;
64  tier?: string | null;
65  quota_used?: number;
66  quota_limit?: number;
67  is_trial?: boolean;
68}
69
70async function rpc(
71  userId: string,
72  toolName: string,
73  queryHash: string | null = null,
74): Promise<RpcResponse> {
75  const { data, error } = await supabase.rpc("check_and_record_usage", {
76    p_user_id: userId,
77    p_tool_name: toolName,
78    p_query_hash: queryHash,
79  });
80  if (error) throw new Error(`rpc error: ${error.message}`);
81  return data as RpcResponse;
82}
83
84interface TestResult {
85  name: string;
86  pass: boolean;
87  detail: string;
88}
89
90async function runTest(
91  name: string,
92  fn: () => Promise<{ pass: boolean; detail: string }>,
93): Promise<TestResult> {
94  try {
95    const result = await fn();
96    return { name, ...result };
97  } catch (e) {
98    return { name, pass: false, detail: `EXCEPTION: ${(e as Error).message}` };
99  }
100}
101
102// ---- Scenarios ----
103
104async function test1_unauthorized(): Promise<TestResult> {
105  return runTest("1. UNAUTHORIZED (non-existent user_id)", async () => {
106    const r = await rpc(`nonexistent_user_${STAMP}`, "test_tool");
107    const pass = r.allowed === false && r.error_code === "UNAUTHORIZED";
108    return { pass, detail: JSON.stringify(r) };
109  });
110}
111
112async function test2_emailNotVerified(): Promise<TestResult> {
113  return runTest("2. EMAIL_NOT_VERIFIED (trialing + unverified)", async () => {
114    const uid = `test_quota_email_${STAMP}`;
115    try {
116      await insertSubscription({
117        user_id: uid,
118        api_key: `apk_email_${STAMP}`,
119        status: "trialing",
120        email_verified: false,
121        monthly_quota: 100,
122      });
123      const r = await rpc(uid, "test_tool");
124      const pass = r.allowed === false && r.error_code === "EMAIL_NOT_VERIFIED";
125      return { pass, detail: JSON.stringify(r) };
126    } finally {
127      await cleanup(uid);
128    }
129  });
130}
131
132async function test3_normalTrial(): Promise<TestResult> {
133  return runTest("3. NORMAL TRIAL FLOW (verified, 1 call)", async () => {
134    const uid = `test_quota_trial_${STAMP}`;
135    try {
136      await insertSubscription({
137        user_id: uid,
138        api_key: `apk_trial_${STAMP}`,
139        status: "trialing",
140        email_verified: true,
141        monthly_quota: 100,
142      });
143      const r = await rpc(uid, "test_tool");
144      const pass = r.allowed === true && r.is_trial === true && r.quota_used === 1;
145      return { pass, detail: JSON.stringify(r) };
146    } finally {
147      await cleanup(uid);
148    }
149  });
150}
151
152async function test4_cooldown(): Promise<TestResult> {
153  return runTest("4. COOLDOWN (same query_hash within 24h)", async () => {
154    const uid = `test_quota_cooldown_${STAMP}`;
155    try {
156      await insertSubscription({
157        user_id: uid,
158        api_key: `apk_cooldown_${STAMP}`,
159        status: "trialing",
160        email_verified: true,
161        monthly_quota: 100,
162      });
163      const r1 = await rpc(uid, "search_news", "test_hash_123");
164      const r2 = await rpc(uid, "search_news", "test_hash_123");
165      const pass =
166        r1.allowed === true &&
167        r2.allowed === false &&
168        r2.error_code === "COOLDOWN_ACTIVE";
169      return {
170        pass,
171        detail: `r1=${JSON.stringify(r1)} r2=${JSON.stringify(r2)}`,
172      };
173    } finally {
174      await cleanup(uid);
175    }
176  });
177}
178
179async function test5_quotaExceeded(): Promise<TestResult> {
180  return runTest("5. QUOTA_EXCEEDED (quota=2, call 3x)", async () => {
181    const uid = `test_quota_exceeded_${STAMP}`;
182    try {
183      await insertSubscription({
184        user_id: uid,
185        api_key: `apk_exceeded_${STAMP}`,
186        status: "trialing",
187        email_verified: true,
188        monthly_quota: 2,
189      });
190      const r1 = await rpc(uid, "test_tool");
191      const r2 = await rpc(uid, "test_tool");
192      const r3 = await rpc(uid, "test_tool");
193      const pass =
194        r1.allowed === true &&
195        r2.allowed === true &&
196        r3.allowed === false &&
197        r3.error_code === "QUOTA_EXCEEDED" &&
198        r3.used === 2 &&
199        r3.limit === 2;
200      return {
201        pass,
202        detail: `r1=${JSON.stringify(r1)} r2=${JSON.stringify(r2)} r3=${JSON.stringify(r3)}`,
203      };
204    } finally {
205      await cleanup(uid);
206    }
207  });
208}
209
210async function test6_activePaidUser(): Promise<TestResult> {
211  return runTest("6. ACTIVE PAID (email_verified=false skipped for active)", async () => {
212    const uid = `test_quota_active_${STAMP}`;
213    try {
214      await insertSubscription({
215        user_id: uid,
216        api_key: `apk_active_${STAMP}`,
217        status: "active",
218        email_verified: false,
219        monthly_quota: 1000,
220      });
221      const r = await rpc(uid, "test_tool");
222      const pass = r.allowed === true && r.is_trial === false;
223      return { pass, detail: JSON.stringify(r) };
224    } finally {
225      await cleanup(uid);
226    }
227  });
228}
229
230// ---- Runner ----
231
232async function main(): Promise<void> {
233  console.log("\n=== check_and_record_usage RPC integration tests ===\n");
234
235  const tests = [
236    test1_unauthorized,
237    test2_emailNotVerified,
238    test3_normalTrial,
239    test4_cooldown,
240    test5_quotaExceeded,
241    test6_activePaidUser,
242  ];
243
244  const results: TestResult[] = [];
245  for (const t of tests) {
246    const r = await t();
247    results.push(r);
248    const icon = r.pass ? "✅" : "❌";
249    console.log(`${icon} ${r.name}`);
250    console.log(`    ${r.detail}`);
251    console.log("");
252  }
253
254  const passed = results.filter((r) => r.pass).length;
255  console.log(`\n=== Summary: ${passed}/${results.length} passed ===`);
256  if (passed !== results.length) process.exit(1);
257}
258
259main().catch((e) => {
260  console.error("Fatal:", e instanceof Error ? e.message : e);
261  process.exit(1);
262});

src/actor_entry.ts

1// Apify Actor entrypoint — wraps the stdio MCP server so it can run on Apify.
2// Reads the user's api_key from Actor input, sets MCP_USER_API_KEY env var
3// (consumed by auth.ts), then hands off to the standard startMcpServer().
4
5import { Actor } from "apify";
6import { startMcpServer } from "./index.js";
7
8interface ActorInput {
9  api_key?: unknown;
10}
11
12async function run(): Promise<void> {
13  await Actor.init();
14
15  const input = ((await Actor.getInput()) ?? {}) as ActorInput;
16  const apiKey = typeof input.api_key === "string" ? input.api_key.trim() : "";
17
18  if (!apiKey) {
19    console.error("[kstar-mcp/actor] missing api_key in Actor input");
20    await Actor.exit({ exitCode: 1 });
21    return;
22  }
23
24  process.env.MCP_USER_API_KEY = apiKey;
25
26  try {
27    await startMcpServer();
28  } catch (e) {
29    console.error("[kstar-mcp/actor] fatal:", e);
30    await Actor.exit({ exitCode: 1 });
31  }
32}
33
34run().catch(async (e) => {
35  console.error("[kstar-mcp/actor] unhandled:", e);
36  await Actor.exit({ exitCode: 1 });
37});

src/index.ts

1// MCP server entry — K-Star Hub Korean entertainment tools over stdio.
2// 25 tools 등록: kpop (5 specialized) + 10 categories × 2 (weekly_trend + search_archive) = 25.
3//
4// 사용:
5//   npm run dev     — tsx watch
6//   npm run build   — tsc → dist/
7//   npm run start   — node dist/index.js
8// 환경변수: SUPABASE_URL, SUPABASE_ANON_KEY (.env.example 참조)
9
10import { fileURLToPath } from "node:url";
11import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
12import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
13import { initSentry, captureError } from "./lib/monitoring.js";
14
15// K-Pop specialized tools (5)
16import * as getKpopNewsToday from "./mcp/kr/kpop/get_kpop_news_today.js";
17import * as getArtistTimeline from "./mcp/kr/kpop/get_artist_timeline.js";
18import * as generateVideoScript from "./mcp/kr/kpop/generate_video_script.js";
19import * as getTrendingClusters from "./mcp/kr/kpop/get_trending_clusters.js";
20import * as searchNews from "./mcp/kr/kpop/search_news.js";
21
22// 10 categories × 2 tools (weekly trend + search archive) = 20
23import * as kdramaWeekly from "./mcp/kr/kdrama/get_weekly_media_trend.js";
24import * as kdramaSearch from "./mcp/kr/kdrama/search_media_archive.js";
25import * as kmovieWeekly from "./mcp/kr/kmovie/get_weekly_media_trend.js";
26import * as kmovieSearch from "./mcp/kr/kmovie/search_media_archive.js";
27import * as kbeautyWeekly from "./mcp/kr/kbeauty/get_weekly_media_trend.js";
28import * as kbeautySearch from "./mcp/kr/kbeauty/search_media_archive.js";
29import * as kfoodWeekly from "./mcp/kr/kfood/get_weekly_media_trend.js";
30import * as kfoodSearch from "./mcp/kr/kfood/search_media_archive.js";
31import * as kgameWeekly from "./mcp/kr/kgame/get_weekly_media_trend.js";
32import * as kgameSearch from "./mcp/kr/kgame/search_media_archive.js";
33import * as ktechWeekly from "./mcp/kr/ktech/get_weekly_media_trend.js";
34import * as ktechSearch from "./mcp/kr/ktech/search_media_archive.js";
35import * as kstockWeekly from "./mcp/kr/kstock/get_weekly_media_trend.js";
36import * as kstockSearch from "./mcp/kr/kstock/search_media_archive.js";
37import * as ktravelWeekly from "./mcp/kr/ktravel/get_weekly_media_trend.js";
38import * as ktravelSearch from "./mcp/kr/ktravel/search_media_archive.js";
39import * as kwebtoonWeekly from "./mcp/kr/kwebtoon/get_weekly_media_trend.js";
40import * as kwebtoonSearch from "./mcp/kr/kwebtoon/search_media_archive.js";
41import * as ktrendsWeekly from "./mcp/kr/ktrends/get_weekly_media_trend.js";
42import * as ktrendsSearch from "./mcp/kr/ktrends/search_media_archive.js";
43
44const server = new McpServer(
45  { name: "kstar-mcp-server", version: "0.2.0" },
46  { capabilities: { tools: {} } },
47);
48
49const TOOLS = [
50  // K-Pop (5)
51  getKpopNewsToday,
52  getArtistTimeline,
53  generateVideoScript,
54  getTrendingClusters,
55  searchNews,
56  // 10 categories × 2
57  kdramaWeekly, kdramaSearch,
58  kmovieWeekly, kmovieSearch,
59  kbeautyWeekly, kbeautySearch,
60  kfoodWeekly, kfoodSearch,
61  kgameWeekly, kgameSearch,
62  ktechWeekly, ktechSearch,
63  kstockWeekly, kstockSearch,
64  ktravelWeekly, ktravelSearch,
65  kwebtoonWeekly, kwebtoonSearch,
66  ktrendsWeekly, ktrendsSearch,
67];
68
69for (const t of TOOLS) {
70  // Wrap each handler so unexpected throws are sent to Sentry. Tools normally
71  // return error envelopes via toolError() (no throw), so this only fires on
72  // truly unexpected paths — but those are exactly what we want paged.
73  const wrapped = async (raw: Record<string, unknown>) => {
74    try {
75      return await t.handler(raw);
76    } catch (err) {
77      captureError(err, { tool_name: t.NAME, input: raw });
78      throw err;
79    }
80  };
81  server.tool(t.NAME, t.DESCRIPTION, t.inputSchema, wrapped);
82}
83
84export async function startMcpServer() {
85  initSentry();
86  const transport = new StdioServerTransport();
87  await server.connect(transport);
88  // stdio MCP 는 stdout 을 protocol 전용으로 씀 — 모든 로그는 stderr.
89  console.error(
90    `[kstar-mcp] connected via stdio, ${TOOLS.length} tools registered (5 kpop + 20 category tools)`,
91  );
92}
93
94const isMain =
95  process.argv[1] !== undefined &&
96  fileURLToPath(import.meta.url) === process.argv[1];
97
98if (isMain) {
99  startMcpServer().catch((e) => {
100    console.error("[kstar-mcp] fatal:", e);
101    process.exit(1);
102  });
103}

.github/workflows/healthcheck.yml

name: MCP Hub Healthcheck

on:
  schedule:
    # Every 5 minutes. GitHub Actions cron has a 5-min minimum and is
    # best-effort under high load — actual runs may be a few min late.
    # Cost: ~5min × 24h × 30d = ~3hr/month, well under free-tier 2000 min/mo.
    - cron: '*/5 * * * *'
  workflow_dispatch:

jobs:
  healthcheck:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install deps
        run: npm ci

      - name: Run healthcheck
        run: npm run healthcheck
        env:
          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
          SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
          NODE_ENV: production

      # Defensive: if the workflow infra itself breaks (npm ci fails, etc.)
      # the script never runs and can't send its own Discord alert. This
      # step pings Discord on ANY failure of the steps above.
      - name: Discord notify on workflow failure
        if: failure()
        run: |
          if [ -n "${{ secrets.DISCORD_WEBHOOK_URL }}" ]; then
            curl -s -X POST -H "Content-Type: application/json" \
              -d "{\"content\":\"🚨 MCP Hub healthcheck workflow FAILED (infra error before script ran). Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\"}" \
              "${{ secrets.DISCORD_WEBHOOK_URL }}"
          fi

src/lib/api_key.ts

1// API key issuance helper.
2// Format: kdmcp_<24 random bytes base64url> (= 32 chars after prefix, URL-safe).
3// Real issuance happens in the Paddle webhook handler (not yet wired). This
4// module exists so the rest of the codebase can import a single generator.
5
6import { randomBytes } from "node:crypto";
7
8const PREFIX = "kdmcp_";
9
10export function generateApiKey(): string {
11  return PREFIX + randomBytes(24).toString("base64url");
12}

src/lib/auth.ts

1// MCP user resolution.
2// API key resolution order:
3//   1. override.api_key (e.g. Apify Actor input passed by the entrypoint)
4//   2. MCP_USER_API_KEY env var (local dev fallback)
5// Returns { user_id, api_key } from mcp_subscriptions. Caches per-process
6// (one user per stdio session). The quota check itself runs through the
7// check_and_record_usage RPC — this module only resolves identity.
8
9import { supabase } from "./supabase.js";
10
11export interface AuthResult {
12  user_id: string;
13  api_key: string;
14}
15
16let _cachedApiKey: string | undefined;
17let _cachedAuth: AuthResult | null | undefined; // undefined = not yet fetched
18
19interface ApiKeyOverride {
20  api_key?: unknown;
21}
22
23function readApiKey(override?: ApiKeyOverride): string | null {
24  if (override && typeof override.api_key === "string" && override.api_key.length > 0) {
25    return override.api_key;
26  }
27  const envKey = process.env.MCP_USER_API_KEY;
28  return envKey && envKey.length > 0 ? envKey : null;
29}
30
31async function lookup(apiKey: string): Promise<AuthResult | null> {
32  const { data, error } = await supabase
33    .from("mcp_subscriptions")
34    .select("user_id")
35    .eq("api_key", apiKey)
36    .maybeSingle();
37  if (error || !data) return null;
38  const userId = (data as { user_id: string }).user_id;
39  return { user_id: userId, api_key: apiKey };
40}
41
42export async function getCurrentUser(override?: ApiKeyOverride): Promise<AuthResult | null> {
43  const apiKey = readApiKey(override);
44  if (!apiKey) return null;
45
46  // Cache by api_key — invalidates if key changes.
47  if (_cachedApiKey === apiKey && _cachedAuth !== undefined) return _cachedAuth;
48
49  _cachedApiKey = apiKey;
50  _cachedAuth = await lookup(apiKey);
51  return _cachedAuth;
52}
53
54/** Test-only — clears the per-process auth cache. */
55export function _resetAuthCache(): void {
56  _cachedApiKey = undefined;
57  _cachedAuth = undefined;
58}

src/lib/category_tools.ts

1// DRY factory — 10개 카테고리 × 2 tool (weekly_trend + search_archive) = 20 tool 자동 생성.
2//
3// 각 카테고리 폴더의 tool 파일 = 3줄짜리 shim:
4//   import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
5//   export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kdrama");
6//
7// 카테고리별 description / 폴백 정책 (realtime vs trend) 은 META 에서 관리.
8// stories.category 가 분류기 출력 (CATEGORIES enum) 과 매치 필요.
9
10import { z } from "zod";
11import { supabase } from "./supabase.js";
12import { ERR, toolError, toolJson } from "./errors.js";
13import { applyGuard } from "./quota_guard.js";
14import {
15  type Lang,
16  LANGS,
17  pickTitle,
18  pickSummary,
19  titleSelect,
20  summarySelect,
21} from "./lang.js";
22import type { ApiStory } from "../shared/types.js";
23
24interface CategoryMeta {
25  /** stories.category 값. */
26  categoryKey: string;
27  /** 사람이 읽는 짧은 이름 (e.g. "Korean drama"). */
28  longName: string;
29  /** 실시간 tier (24h stale = error) vs 트렌드 tier (48h stale = 라벨링 후 반환). */
30  isRealtime: boolean;
31  /** get_<short>_weekly_trend description 본문. (Token efficiency tail 자동 추가) */
32  weeklyDesc: string;
33  /** search_<short>_archive description 본문. */
34  searchDesc: string;
35}
36
37const TOKEN_EFFICIENCY_TAIL =
38  " Token efficiency: Returns highly condensed, pre-clustered JSON optimized for LLM context windows. " +
39  "Reduces input token costs by up to 70-80% compared to raw HTML scraping or generic news APIs.";
40
41const META: Record<string, CategoryMeta> = {
42  kdrama: {
43    categoryKey: "K-Drama",
44    longName: "Korean drama",
45    isRealtime: true,
46    weeklyDesc:
47      "Get Korean drama (K-Drama) media trends from major Korean publishers. Covers scripted TV series and " +
48      "streaming dramas (Netflix, Disney+, Tving, Wavve, Coupang Play), casting, ratings, plot updates, " +
49      "drama writers, directors, and production studios. Use this tool when: user asks 'what's trending " +
50      "in K-Drama this week', user needs Korean drama industry insights, user builds K-Drama coverage for " +
51      "a global audience, or user researches a recent drama release or controversy.",
52    searchDesc:
53      "Search Korean drama (K-Drama) news archive by free-text query. Matches across title and body within " +
54      "K-Drama-tagged stories from the Korean publisher landscape. Use this tool when: user searches a " +
55      "specific drama title, actor casting, controversy, ratings figure, or production company. Excludes " +
56      "variety / reality / film coverage (use K-Trends or K-Movie tools for those).",
57  },
58  kmovie: {
59    categoryKey: "K-Movie",
60    longName: "Korean film",
61    // Trend tier (48h_stale allowed). K-Movie volume is too low for a strict
62    // realtime SLA — realtime tier kept narrow to K-Pop + K-Drama only.
63    isRealtime: false,
64    weeklyDesc:
65      "Get Korean film (K-Movie) media trends from major Korean publishers. Covers Korean cinema, " +
66      "theatrical and streaming releases, film festivals (Cannes, Venice, Berlin, Busan / BIFF, " +
67      "Bucheon / BIFAN), directors (Park Chan-wook, Bong Joon-ho, Na Hong-jin, etc.), screen actors, " +
68      "box office, and critical reviews. Use this tool when: user asks 'what Korean films are making news " +
69      "this week', user tracks festival reactions, user covers Korean cinema for a global audience, or " +
70      "user researches a director or release.",
71    searchDesc:
72      "Search Korean film (K-Movie) news archive by free-text query. Matches across title and body within " +
73      "K-Movie-tagged stories from Korean publishers. Use this tool when: user searches a specific film " +
74      "title, director, festival appearance, box-office report, or actor's film role.",
75  },
76  kbeauty: {
77    categoryKey: "K-Beauty",
78    longName: "Korean beauty",
79    isRealtime: false,
80    weeklyDesc:
81      "Get Korean beauty (K-Beauty) media trends from major Korean publishers. Covers cosmetics, skincare, " +
82      "makeup, beauty brands (Innisfree, Etude, Laneige, Sulwhasoo, Olive Young, COSRX, etc.), beauty " +
83      "influencers, K-beauty exports, and skincare routines. Use this tool when: user asks 'what's " +
84      "trending in K-beauty', user needs Korean cosmetics market insights, user builds K-beauty content " +
85      "for a global audience, or user researches a Korean skincare brand's activity.",
86    searchDesc:
87      "Search Korean beauty (K-Beauty) news archive by free-text query. Matches across title and body " +
88      "within K-Beauty-tagged stories. Use this tool when: user searches a specific brand, product line " +
89      "(cushion, serum, sheet mask, etc.), beauty trend, or K-beauty export figure.",
90  },
91  kfood: {
92    categoryKey: "K-Food",
93    longName: "Korean food",
94    isRealtime: false,
95    weeklyDesc:
96      "Get Korean food (K-Food) media trends from major Korean publishers. Covers Korean cuisine, " +
97      "restaurants, food trends, regional dishes, K-food exports (kimchi, ramyun, gochujang, tteokbokki, " +
98      "etc.), street food, and food brands. Use this tool when: user asks 'what's trending in Korean " +
99      "food', user needs K-food industry insights, user builds Korean cuisine content, or user researches " +
100      "a Korean restaurant or food brand.",
101    searchDesc:
102      "Search Korean food (K-Food) news archive by free-text query. Matches across title and body within " +
103      "K-Food-tagged stories. Use this tool when: user searches a specific Korean dish, restaurant, food " +
104      "brand, or export trend.",
105  },
106  kgame: {
107    categoryKey: "K-Game",
108    longName: "Korean game",
109    isRealtime: false,
110    weeklyDesc:
111      "Get Korean game (K-Game) media trends from major Korean publishers. Covers the Korean gaming " +
112      "industry, game releases, esports leagues, game studios (Nexon, NCsoft, Krafton, Smilegate, Pearl " +
113      "Abyss, Netmarble, Com2uS, etc.), and gamer culture. Use this tool when: user asks 'what's happening " +
114      "in Korean gaming this week', user tracks Korean esports, user builds K-gaming coverage, or user " +
115      "researches a Korean studio or game release.",
116    searchDesc:
117      "Search Korean game (K-Game) news archive by free-text query. Matches across title and body within " +
118      "K-Game-tagged stories. Use this tool when: user searches a specific game title, studio, esports " +
119      "event, or industry development.",
120  },
121  ktech: {
122    categoryKey: "K-Tech",
123    longName: "Korean technology",
124    isRealtime: false,
125    weeklyDesc:
126      "Get Korean technology (K-Tech) media trends from major Korean publishers. Covers Korean tech " +
127      "companies (Samsung, LG, SK Hynix, Naver, Kakao, Coupang, Toss, etc.), startups, IT industry, AI " +
128      "/ semiconductors / consumer electronics, and tech-policy news. Use this tool when: user asks " +
129      "'what's happening in Korean tech', user needs Korean IT industry insights, user covers Korean " +
130      "startups or hardware, or user researches a Korean tech innovation.",
131    searchDesc:
132      "Search Korean technology (K-Tech) news archive by free-text query. Matches across title and body " +
133      "within K-Tech-tagged stories. Use this tool when: user searches a specific Korean tech company, " +
134      "product launch, executive statement, or industry development.",
135  },
136  kstock: {
137    categoryKey: "K-Stock",
138    longName: "Korean stock",
139    isRealtime: false,
140    weeklyDesc:
141      "Get Korean stock market (K-Stock) media trends from major Korean publishers. Covers KOSPI / " +
142      "KOSDAQ daily moves, IPOs, corporate earnings, dividends, and especially financial reports of " +
143      "Korean entertainment / media companies (Hybe, SM, JYP, YG, CJ ENM, YH Entertainment, etc.). Use " +
144      "this tool when: user asks 'how are Korean entertainment stocks doing', user needs KOSPI / KOSDAQ " +
145      "context, user covers Korean financial markets, or user researches an entertainment company's " +
146      "quarterly performance.",
147    searchDesc:
148      "Search Korean stock (K-Stock) news archive by free-text query. Matches across title and body " +
149      "within K-Stock-tagged stories. Use this tool when: user searches a specific ticker, company name, " +
150      "earnings event, IPO, or analyst rating.",
151  },
152  ktravel: {
153    categoryKey: "K-Travel",
154    longName: "Korean travel",
155    isRealtime: false,
156    weeklyDesc:
157      "Get Korean travel (K-Travel) media trends from major Korean publishers. Covers Korean tourism, " +
158      "popular destinations (Seoul, Busan, Jeju, Gangneung, Gyeongju, etc.), hotels, travel trends, " +
159      "visit-Korea campaigns, and inbound / outbound tourism figures. Use this tool when: user asks " +
160      "'what's trending in Korean travel', user covers Korean tourism, user builds visit-Korea content, " +
161      "or user researches a Korean destination or hospitality brand.",
162    searchDesc:
163      "Search Korean travel (K-Travel) news archive by free-text query. Matches across title and body " +
164      "within K-Travel-tagged stories. Use this tool when: user searches a specific destination, hotel, " +
165      "travel campaign, or tourism statistic.",
166  },
167  kwebtoon: {
168    categoryKey: "K-Webtoon",
169    longName: "Korean webtoon",
170    isRealtime: false,
171    weeklyDesc:
172      "Get Korean webtoon (K-Webtoon) media trends from major Korean publishers. Covers webtoons, " +
173      "manhwa, web animation, Naver Webtoon, Kakao Page, Lezhin, webtoon-to-drama / film adaptations, " +
174      "and webtoon creators. Use this tool when: user asks 'what's trending in Korean webtoons', user " +
175      "tracks webtoon-to-screen adaptations, user covers Korean web comics, or user researches a " +
176      "webtoon platform or author.",
177    searchDesc:
178      "Search Korean webtoon (K-Webtoon) news archive by free-text query. Matches across title and body " +
179      "within K-Webtoon-tagged stories. Use this tool when: user searches a specific webtoon title, " +
180      "author, platform, or adaptation news.",
181  },
182  ktrends: {
183    categoryKey: "K-Trends",
184    longName: "Korean trend",
185    isRealtime: false,
186    weeklyDesc:
187      "Get general Korean cultural trends (K-Trends) from major Korean publishers — the catch-all bucket " +
188      "for variety / reality TV, celebrity dating / lifestyle, social phenomena, and anything that " +
189      "doesn't fit a narrower K-* category. Use this tool when: user asks 'what's trending in Korean " +
190      "culture broadly', user covers Korean variety / reality TV, user tracks celebrity lifestyle / " +
191      "gossip, or user is unsure which K-* category fits.",
192    searchDesc:
193      "Search the K-Trends (miscellaneous Korean cultural news) archive by free-text query. Matches " +
194      "across title and body within K-Trends-tagged stories. Use this tool when: user searches for " +
195      "variety / reality TV content, celebrity dating, or general Korean cultural references that don't " +
196      "fit a narrower category.",
197  },
198};
199
200export const SHORT_KEYS = Object.keys(META) as (keyof typeof META)[];
201
202const REALTIME_STALE_HOURS = 24;
203const TREND_STALE_HOURS = 48;
204const MIN_CATEGORY_CONFIDENCE = 0.5;
205
206// ---------- Input schemas (shared) ----------
207
208const weeklyInputSchemaShape = {
209  lang: z.enum(LANGS).default("en").describe("Response language (en/ko/ja/es)"),
210  date_range_days: z
211    .number()
212    .int()
213    .min(1)
214    .max(7)
215    .default(7)
216    .describe("How many days back to scan (1-7)"),
217  limit: z.number().int().min(1).max(20).default(10),
218} as const;
219const weeklyInputZ = z.object(weeklyInputSchemaShape);
220
221const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
222const searchInputSchemaShape = {
223  query: z.string().min(1).max(200).describe("Search keyword or phrase"),
224  lang: z.enum(LANGS).default("en"),
225  date_from: z
226    .string()
227    .regex(dateRegex, "date_from must be YYYY-MM-DD (Asia/Seoul calendar day)")
228    .optional()
229    .describe("Window start, KST (default: 30 days before date_to)"),
230  date_to: z
231    .string()
232    .regex(dateRegex, "date_to must be YYYY-MM-DD (Asia/Seoul calendar day)")
233    .optional()
234    .describe("Window end, KST (default: today KST)"),
235  limit: z.number().int().min(1).max(50).default(10),
236} as const;
237const searchInputZ = z.object(searchInputSchemaShape);
238
239// ---------- Helpers ----------
240
241function todayKST(): string {
242  const kstMs = Date.now() + 9 * 3600 * 1000;
243  return new Date(kstMs).toISOString().slice(0, 10);
244}
245
246function shiftDays(date: string, deltaDays: number): string {
247  const t = Date.parse(`${date}T00:00:00+09:00`);
248  return new Date(t + deltaDays * 86_400_000).toISOString().slice(0, 10);
249}
250
251function kstStartUTC(date: string): string {
252  return new Date(`${date}T00:00:00+09:00`).toISOString();
253}
254
255function kstEndUTC(date: string): string {
256  return new Date(`${date}T23:59:59.999+09:00`).toISOString();
257}
258
259function commonCols(lang: Lang): string {
260  return [
261    "id",
262    "cluster_id",
263    ...titleSelect(lang),
264    ...summarySelect(lang),
265    "source_name",
266    "source_url",
267    "subjects",
268    "published_at",
269    "category_confidence",
270  ].join(", ");
271}
272
273function shapeApiStory(r: Record<string, unknown>, lang: Lang): ApiStory {
274  return {
275    id: r.id as number | string,
276    cluster_id: (r.cluster_id as string | null) ?? null,
277    title: pickTitle(r, lang),
278    summary: pickSummary(r, lang),
279    source: (r.source_name as string | null) ?? null,
280    url: (r.source_url as string | null) ?? null,
281    subjects: Array.isArray(r.subjects) ? (r.subjects as string[]) : [],
282    published_at: (r.published_at as string | null) ?? null,
283  };
284}
285
286function freshnessLabel(
287  latestPublishedAt: string | null,
288  isRealtime: boolean,
289): "fresh" | "24h_stale" | "48h_stale" {
290  if (!latestPublishedAt) return isRealtime ? "24h_stale" : "48h_stale";
291  const ageHours = (Date.now() - Date.parse(latestPublishedAt)) / 3600_000;
292  if (isRealtime) return ageHours <= REALTIME_STALE_HOURS ? "fresh" : "24h_stale";
293  return ageHours <= TREND_STALE_HOURS ? "fresh" : "48h_stale";
294}
295
296function formatZodIssues(err: z.ZodError): string {
297  return err.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
298}
299
300// ---------- Factory: weekly trend ----------
301
302export function buildWeeklyTrendTool(shortKey: keyof typeof META) {
303  const cfg = META[shortKey];
304  if (!cfg) throw new Error(`unknown category shortKey: ${shortKey}`);
305
306  const NAME = `get_${shortKey}_weekly_trend`;
307  const DESCRIPTION = cfg.weeklyDesc + TOKEN_EFFICIENCY_TAIL;
308  const inputSchema = weeklyInputSchemaShape;
309
310  async function handler(raw: Record<string, unknown>) {
311    const parsed = weeklyInputZ.safeParse(raw);
312    if (!parsed.success) {
313      return toolError(
314        ERR.INVALID_PARAM,
315        `Invalid input for ${NAME}`,
316        formatZodIssues(parsed.error),
317      );
318    }
319    const args = parsed.data;
320
321    const guard = await applyGuard(NAME, args);
322    if (!guard.ok) return guard.error;
323
324    const lang = args.lang as Lang;
325    const cutoff = new Date(Date.now() - args.date_range_days * 86_400_000).toISOString();
326
327    const { data, error } = await supabase
328      .from("stories")
329      .select(commonCols(lang))
330      .eq("category", cfg.categoryKey)
331      .eq("is_cluster_lead", true)
332      .eq("is_off_topic", false)
333      .gte("category_confidence", MIN_CATEGORY_CONFIDENCE)
334      .gte("published_at", cutoff)
335      .order("published_at", { ascending: false })
336      .limit(args.limit);
337
338    if (error) {
339      return toolError(
340        ERR.DB_ERROR,
341        "Supabase query failed",
342        `${error.code ?? ""} ${error.message}`.trim(),
343      );
344    }
345
346    const rows = (data ?? []) as unknown as Record<string, unknown>[];
347    const latestPublishedAt = (rows[0]?.published_at as string | null) ?? null;
348    const freshness = freshnessLabel(latestPublishedAt, cfg.isRealtime);
349
350    // Realtime tier: error on empty or > 24h stale.
351    if (cfg.isRealtime && (rows.length === 0 || freshness === "24h_stale")) {
352      return toolError(
353        ERR.REALTIME_UNAVAILABLE,
354        `No fresh ${cfg.longName} stories available within ${args.date_range_days}d window.`,
355        `Realtime tier — stale fallback disallowed. Use search_${shortKey}_archive for older windows.`,
356      );
357    }
358
359    const items = rows.map((r) => shapeApiStory(r, lang));
360    return toolJson({
361      category: cfg.categoryKey,
362      window_days: args.date_range_days,
363      lang,
364      data_freshness: freshness,
365      count: items.length,
366      items,
367    });
368  }
369
370  return { NAME, DESCRIPTION, inputSchema, handler };
371}
372
373// ---------- Factory: search archive ----------
374
375export function buildSearchArchiveTool(shortKey: keyof typeof META) {
376  const cfg = META[shortKey];
377  if (!cfg) throw new Error(`unknown category shortKey: ${shortKey}`);
378
379  const NAME = `search_${shortKey}_archive`;
380  const DESCRIPTION = cfg.searchDesc + TOKEN_EFFICIENCY_TAIL;
381  const inputSchema = searchInputSchemaShape;
382
383  async function handler(raw: Record<string, unknown>) {
384    const parsed = searchInputZ.safeParse(raw);
385    if (!parsed.success) {
386      return toolError(
387        ERR.INVALID_PARAM,
388        `Invalid input for ${NAME}`,
389        formatZodIssues(parsed.error),
390      );
391    }
392    const args = parsed.data;
393
394    const guard = await applyGuard(NAME, args);
395    if (!guard.ok) return guard.error;
396
397    const lang = args.lang as Lang;
398    const dateTo = args.date_to ?? todayKST();
399    const dateFrom = args.date_from ?? shiftDays(dateTo, -30);
400    if (dateFrom > dateTo) {
401      return toolError(
402        ERR.INVALID_PARAM,
403        "date_from must be on or before date_to",
404        `date_from=${dateFrom} date_to=${dateTo}`,
405      );
406    }
407
408    const qEsc = args.query.replace(/[%,{}]/g, "").trim();
409    if (qEsc.length === 0) {
410      return toolError(
411        ERR.INVALID_PARAM,
412        "query must contain searchable characters",
413        "Strip out commas / percent signs / braces and retry.",
414      );
415    }
416
417    const orParts = [`title_ko.ilike.%${qEsc}%`, `content_ko.ilike.%${qEsc}%`];
418    if (lang !== "ko") {
419      orParts.push(`title_${lang}.ilike.%${qEsc}%`, `summary_${lang}.ilike.%${qEsc}%`);
420    }
421    const orFilter = orParts.join(",");
422
423    const { data, error } = await supabase
424      .from("stories")
425      .select(commonCols(lang))
426      .eq("category", cfg.categoryKey)
427      .eq("is_cluster_lead", true)
428      .eq("is_off_topic", false)
429      .gte("category_confidence", MIN_CATEGORY_CONFIDENCE)
430      .gte("published_at", kstStartUTC(dateFrom))
431      .lte("published_at", kstEndUTC(dateTo))
432      .or(orFilter)
433      .order("published_at", { ascending: false })
434      .limit(args.limit);
435
436    if (error) {
437      return toolError(
438        ERR.DB_ERROR,
439        "Supabase query failed",
440        `${error.code ?? ""} ${error.message}`.trim(),
441      );
442    }
443
444    const rows = (data ?? []) as unknown as Record<string, unknown>[];
445    const items = rows.map((r) => shapeApiStory(r, lang));
446
447    return toolJson({
448      category: cfg.categoryKey,
449      query: args.query,
450      lang,
451      date_from: dateFrom,
452      date_to: dateTo,
453      count: items.length,
454      items,
455    });
456  }
457
458  return { NAME, DESCRIPTION, inputSchema, handler };
459}

src/lib/errors.ts

1// 표준 에러 코드 + 응답 페이로드 빌더.
2// 모든 tool 응답은 { error: { code, message, hint } } 형식으로 에러 반환.
3
4export const ERR = {
5  INVALID_PARAM: "ERR_INVALID_PARAM",
6  REALTIME_UNAVAILABLE: "ERR_REALTIME_UNAVAILABLE",
7  DB_ERROR: "ERR_DB_ERROR",
8  NOT_FOUND: "ERR_NOT_FOUND",
9  INTERNAL: "ERR_INTERNAL",
10  // Trial / billing / auth guard (no ERR_ prefix on the runtime value — separate tier).
11  QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
12  QUOTA_EXCEEDED_DOWNGRADED: "QUOTA_EXCEEDED_DOWNGRADED",
13  COOLDOWN_ACTIVE: "COOLDOWN_ACTIVE",
14  UNAUTHORIZED: "UNAUTHORIZED",
15  SUBSCRIPTION_INACTIVE: "SUBSCRIPTION_INACTIVE",
16  EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED",
17  INVALID_SUBSCRIPTION_STATE: "INVALID_SUBSCRIPTION_STATE",
18  // Credit / pay-per-call (v2 pricing).
19  INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT",
20  AUTO_TOPUP_FAILED: "AUTO_TOPUP_FAILED",
21  // Service degradation (graceful failure, not a guard rejection).
22  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
23} as const;
24
25export type ErrCode = (typeof ERR)[keyof typeof ERR];
26
27// Customer-facing English copy for each error code. Tool call sites still
28// pass their own `message` (which holds technical / contextual detail);
29// `user_message` is the friendly, actionable version surfaced alongside.
30// Keep these short, plain English — they appear directly in the MCP client UI.
31export const USER_MESSAGES: Record<ErrCode, string> = {
32  [ERR.INVALID_PARAM]:               "One of your inputs was invalid. See the hint for which field.",
33  [ERR.REALTIME_UNAVAILABLE]:        "Real-time data temporarily unavailable. Try a trend-tier category or retry shortly.",
34  [ERR.DB_ERROR]:                    "Our database is briefly unavailable. Please retry in a moment.",
35  [ERR.NOT_FOUND]:                   "No matching record was found.",
36  [ERR.INTERNAL]:                    "Something went wrong on our end. We're on it — please retry.",
37  [ERR.QUOTA_EXCEEDED]:              "Monthly quota reached. Upgrade or wait until your next billing cycle.",
38  [ERR.QUOTA_EXCEEDED_DOWNGRADED]:   "Plan was downgraded mid-cycle. Quota will reset on your next billing cycle.",
39  [ERR.COOLDOWN_ACTIVE]:             "Free-credit users: same query within 24h is rate-limited. Top up at korean-data.com/topup to remove.",
40  [ERR.INSUFFICIENT_CREDIT]:         "Credit insufficient. Top up at korean-data.com/topup ($10 = 2,000 calls).",
41  [ERR.AUTO_TOPUP_FAILED]:           "Auto top-up could not charge your saved card. Check payment method at korean-data.com/settings/mcp.",
42  [ERR.UNAUTHORIZED]:                "Invalid API key. Sign up at korean-data.com.",
43  [ERR.SUBSCRIPTION_INACTIVE]:       "Subscription canceled or expired. Reactivate at korean-data.com.",
44  [ERR.EMAIL_NOT_VERIFIED]:          "Email verification pending. Check your inbox for the verification link.",
45  [ERR.INVALID_SUBSCRIPTION_STATE]:  "Account state needs attention. Contact support@korean-data.com.",
46  [ERR.SERVICE_UNAVAILABLE]:         "Our service is briefly unavailable. Please retry in 60 seconds.",
47};
48
49// Optional docs URL per code (omit = no link surfaced).
50export const DOCS_URLS: Partial<Record<ErrCode, string>> = {
51  [ERR.UNAUTHORIZED]:                "https://korean-data.com/docs/auth",
52  [ERR.QUOTA_EXCEEDED]:              "https://korean-data.com/pricing",
53  [ERR.QUOTA_EXCEEDED_DOWNGRADED]:   "https://korean-data.com/pricing",
54  [ERR.COOLDOWN_ACTIVE]:             "https://korean-data.com/topup",
55  [ERR.INSUFFICIENT_CREDIT]:         "https://korean-data.com/topup",
56  [ERR.AUTO_TOPUP_FAILED]:           "https://korean-data.com/settings/mcp",
57  [ERR.SUBSCRIPTION_INACTIVE]:       "https://korean-data.com/billing",
58  [ERR.EMAIL_NOT_VERIFIED]:          "https://korean-data.com/docs/email-verification",
59  [ERR.SERVICE_UNAVAILABLE]:         "https://korean-data.com/status",
60};
61
62export interface ErrorResponse {
63  error: {
64    code: ErrCode;
65    message: string;
66    user_message: string;
67    hint?: string;
68    docs_url?: string;
69  };
70}
71
72export function errorPayload(code: ErrCode, message: string, hint?: string): ErrorResponse {
73  const body: ErrorResponse["error"] = {
74    code,
75    message,
76    user_message: USER_MESSAGES[code],
77  };
78  if (hint) body.hint = hint;
79  const docs = DOCS_URLS[code];
80  if (docs) body.docs_url = docs;
81  return { error: body };
82}
83
84export function toolError(code: ErrCode, message: string, hint?: string) {
85  return {
86    content: [
87      {
88        type: "text" as const,
89        text: JSON.stringify(errorPayload(code, message, hint), null, 2),
90      },
91    ],
92    isError: true,
93  };
94}
95
96export function toolJson(payload: unknown) {
97  return {
98    content: [
99      {
100        type: "text" as const,
101        text: JSON.stringify(payload, null, 2),
102      },
103    ],
104  };
105}

src/lib/lang.ts

1// lang 파라미터 → stories 테이블 컬럼 매핑.
2//
3// 실제 DB 스키마 (Supabase stories 테이블):
4//   - title_ko (항상), title_en / title_ja / title_es (번역 있을 때만)
5//   - content_ko (항상), content_en / content_ja / content_es (번역 있을 때만)
6//   - summary_en / summary_ja / summary_es (번역 있을 때만). summary_ko 컬럼은 없음.
7//
8// base `title` / `summary` 컬럼은 현재 스키마에 없음 — pickTitle/pickSummary 의 마지막
9// 폴백으로만 남겨둠 (혹시 미래에 추가되면 자동으로 동작).
10
11export type Lang = "en" | "ko" | "ja" | "es";
12export const LANGS = ["en", "ko", "ja", "es"] as const;
13
14// content_* 본문을 summary 폴백으로 쓸 때 자르는 길이.
15const BODY_CHAR_CAP = 600;
16
17export function titleCol(lang: Lang): string {
18  return `title_${lang}`;
19}
20
21export function summaryCol(lang: Lang): string {
22  return `summary_${lang}`;
23}
24
25/** SELECT 절에 박을 lang 별 컬럼. 비한국어 = lang 컬럼 + 한국어 폴백. */
26export function titleSelect(lang: Lang): string[] {
27  return lang === "ko" ? ["title_ko"] : [`title_${lang}`, "title_ko"];
28}
29
30/**
31 * SELECT 절에 박을 summary 컬럼.
32 * - lang=ko: content_ko (summary_ko 가 없으므로 본문에서 자름)
33 * - else:    summary_${lang} → content_${lang} → content_ko 폴백 체인
34 */
35export function summarySelect(lang: Lang): string[] {
36  if (lang === "ko") return ["content_ko"];
37  return [`summary_${lang}`, `content_${lang}`, "content_ko"];
38}
39
40/** row 에서 title pick — title_${lang} → title_ko → (legacy) title. */
41export function pickTitle(row: Record<string, unknown>, lang: Lang): string | null {
42  if (lang !== "ko") {
43    const localized = row[`title_${lang}`];
44    if (typeof localized === "string" && localized.length > 0) return localized;
45  }
46  const ko = row.title_ko;
47  if (typeof ko === "string" && ko.length > 0) return ko;
48  const base = row.title;
49  return typeof base === "string" && base.length > 0 ? base : null;
50}
51
52/**
53 * row 에서 summary pick.
54 * - 비한국어: summary_${lang} → content_${lang} (cap) → content_ko (cap) → (legacy) summary
55 * - 한국어:   content_ko (cap) → (legacy) summary
56 */
57export function pickSummary(row: Record<string, unknown>, lang: Lang): string | null {
58  if (lang !== "ko") {
59    const localized = row[`summary_${lang}`];
60    if (typeof localized === "string" && localized.length > 0) return localized;
61    const localizedBody = row[`content_${lang}`];
62    if (typeof localizedBody === "string" && localizedBody.length > 0) return capBody(localizedBody);
63  }
64  const koBody = row.content_ko;
65  if (typeof koBody === "string" && koBody.length > 0) return capBody(koBody);
66  const base = row.summary;
67  return typeof base === "string" && base.length > 0 ? base : null;
68}
69
70function capBody(s: string): string {
71  return s.length > BODY_CHAR_CAP ? s.slice(0, BODY_CHAR_CAP).trim() + "…" : s;
72}

src/lib/monitoring.ts

1// Ops monitoring — Sentry error tracking + Discord ops alerts.
2//
3// Both are env-gated; missing env vars degrade to console-only so local dev
4// and CI never page anyone. Production sends are conditional on
5// NODE_ENV=production (Sentry) or a non-empty DISCORD_WEBHOOK_URL (Discord).
6
7import * as Sentry from "@sentry/node";
8
9let _sentryInitialized = false;
10
11export function initSentry(): void {
12  if (_sentryInitialized) return;
13  _sentryInitialized = true;
14
15  const dsn = process.env.SENTRY_DSN;
16  if (!dsn) {
17    console.error("[monitoring] SENTRY_DSN not set — Sentry disabled.");
18    return;
19  }
20  const env = process.env.NODE_ENV ?? "development";
21  if (env !== "production") {
22    console.error(
23      `[monitoring] NODE_ENV=${env} (not production) — Sentry init skipped.`,
24    );
25    return;
26  }
27
28  Sentry.init({
29    dsn,
30    environment: env,
31    tracesSampleRate: 0,
32    sendDefaultPii: false,
33  });
34  console.error("[monitoring] Sentry initialized.");
35}
36
37export interface ErrorContext {
38  tool_name?: string;
39  user_id?: string;
40  input?: unknown;
41  [key: string]: unknown;
42}
43
44export function captureError(err: unknown, context?: ErrorContext): void {
45  const e = err instanceof Error ? err : new Error(String(err));
46  const env = process.env.NODE_ENV ?? "development";
47
48  if (env === "production" && process.env.SENTRY_DSN) {
49    Sentry.captureException(e, { extra: context as Record<string, unknown> });
50    return;
51  }
52  // Local / non-prod: log so the dev can see what would have been sent.
53  console.error("[monitoring] captureError:", e.message, context ?? "");
54}
55
56export type AlertLevel = "info" | "warn" | "error";
57
58const LEVEL_EMOJI: Record<AlertLevel, string> = {
59  info: "📊",
60  warn: "⚠️",
61  error: "🚨",
62};
63
64export async function sendDiscordAlert(
65  message: string,
66  level: AlertLevel = "info",
67): Promise<void> {
68  const url = process.env.DISCORD_WEBHOOK_URL;
69  const formatted = `${LEVEL_EMOJI[level]} ${message}`;
70
71  if (!url) {
72    console.error("[monitoring] DISCORD_WEBHOOK_URL not set —", formatted);
73    return;
74  }
75
76  try {
77    const res = await fetch(url, {
78      method: "POST",
79      headers: { "Content-Type": "application/json" },
80      body: JSON.stringify({ content: formatted }),
81    });
82    if (!res.ok) {
83      console.error(
84        `[monitoring] Discord webhook ${res.status}: ${await res.text()}`,
85      );
86    }
87  } catch (e) {
88    // Never throw from an alerter — alerts should never crash the caller.
89    console.error("[monitoring] Discord webhook failed:", (e as Error).message);
90  }
91}

src/lib/preprocess.ts

1// Raw HTML → { title, body, published_at } 알맹이만 추출.
2// regex 기반 — jsdom/cheerio dep 안 끌어옴 (단순 광고/공지/댓글 제거 + 텍스트 추출).
3// Naver-syndicated 한국 매체 기사 대부분 잡힘 (충분히 robust 한 v1).
4
5export interface ExtractedContent {
6  title: string | null;
7  body: string;
8  published_at: string | null;
9}
10
11export function extractContent(html: string): ExtractedContent {
12  // 1. script / style / noscript / iframe 통째로 제거
13  let h = html
14    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
15    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "")
16    .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, "")
17    .replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, "");
18
19  // 2. title — og:title / twitter:title meta 우선, <title> 폴백
20  const ogTitle = matchMeta(h, "og:title") || matchMeta(h, "twitter:title");
21  const titleTag = h.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? "";
22  const title = decodeEntities((ogTitle || titleTag).replace(/\s+/g, " ").trim()) || null;
23
24  // 3. published_at — 흔한 meta 들
25  const publishedAt =
26    matchMeta(h, "article:published_time") ||
27    matchMeta(h, "og:article:published_time") ||
28    matchMetaName(h, "pubdate") ||
29    matchMetaName(h, "publication_date") ||
30    matchMetaName(h, "date") ||
31    null;
32
33  // 4. body — nav/header/footer/aside/form 제거 + class/id 휴리스틱으로 광고/댓글 블록 제거
34  let body = h
35    .replace(/<(nav|header|footer|aside|form)\b[^>]*>[\s\S]*?<\/\1>/gi, "")
36    .replace(
37      /<(div|section|aside|ul)\b[^>]*\b(class|id)=["'][^"']*(ad|ads|advert|comment|share|social|related|recommend|popup|banner|subscribe|newsletter|paywall)[^"']*["'][^>]*>[\s\S]*?<\/\1>/gi,
38      "",
39    );
40
41  body = stripTags(body);
42  body = decodeEntities(body).replace(/\s+/g, " ").trim();
43
44  return { title, body, published_at: publishedAt };
45}
46
47function matchMeta(html: string, property: string): string | null {
48  const re = new RegExp(
49    `<meta[^>]+property=["']${escapeRe(property)}["'][^>]+content=["']([^"']*)["']`,
50    "i",
51  );
52  return html.match(re)?.[1]?.trim() || null;
53}
54
55function matchMetaName(html: string, name: string): string | null {
56  const re = new RegExp(
57    `<meta[^>]+name=["']${escapeRe(name)}["'][^>]+content=["']([^"']*)["']`,
58    "i",
59  );
60  return html.match(re)?.[1]?.trim() || null;
61}
62
63function stripTags(html: string): string {
64  return html.replace(/<\/?[^>]+>/g, " ");
65}
66
67function decodeEntities(s: string): string {
68  return s
69    .replace(/&nbsp;/gi, " ")
70    .replace(/&amp;/gi, "&")
71    .replace(/&lt;/gi, "<")
72    .replace(/&gt;/gi, ">")
73    .replace(/&quot;/gi, '"')
74    .replace(/&#39;/gi, "'")
75    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)));
76}
77
78function escapeRe(s: string): string {
79  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
80}

src/lib/quota_guard.ts

1// Trial / billing guard — single DRY wrapper applied at the top of every tool handler.
2//
3// Flow:
4//   1. Bypass: QUOTA_BYPASS=1 short-circuits the entire check.
5//   2. Resolve api_key → user_id (via auth.ts).
6//   3. Call check_and_record_usage RPC (atomic: SELECT FOR UPDATE + count + INSERT
7//      in one transaction; uses called_at >= reference, NOT = operator on TIMESTAMPTZ).
8//   4. On allowed: mutate the parsed input in place to apply trial clamps
9//      (limit cap, date-field clamp). Tool then uses input.limit / input.date_from / etc.
10//   5. On denied: return a ready-to-emit tool error envelope.
11
12import { createHash } from "node:crypto";
13import { supabase } from "./supabase.js";
14import { ERR, toolError } from "./errors.js";
15import { getCurrentUser } from "./auth.js";
16import { captureError, sendDiscordAlert } from "./monitoring.js";
17
18const PAID_PER_CALL_LIMIT_MAX = 50;
19
20// Trial knobs come from the `system_config` table so we can tune trial
21// behavior without redeploying. Defaults below are the safety fallback —
22// used on first-call cold start, on DB error, or when a key is missing.
23interface TrialConfig {
24  perCallLimit: number;
25  windowDays: number;
26  callsLimit: number;
27  cooldownHours: number;
28}
29
30const DEFAULT_TRIAL: TrialConfig = {
31  perCallLimit: 5,
32  windowDays: 7,
33  callsLimit: 100,
34  cooldownHours: 24,
35};
36
37const CONFIG_TTL_MS = 5 * 60 * 1000;
38let _cachedConfig: TrialConfig | null = null;
39let _cachedAt = 0;
40
41async function getTrialConfig(): Promise<TrialConfig> {
42  const now = Date.now();
43  if (_cachedConfig && now - _cachedAt < CONFIG_TTL_MS) return _cachedConfig;
44
45  const { data, error } = await supabase
46    .from("system_config")
47    .select("key, value");
48
49  // Read failure: serve stale cache if we have one, otherwise defaults.
50  // Don't update _cachedAt so the next call retries.
51  if (error || !data) return _cachedConfig ?? DEFAULT_TRIAL;
52
53  const cfg: TrialConfig = { ...DEFAULT_TRIAL };
54  for (const row of data as { key: string; value: string }[]) {
55    const num = Number(row.value);
56    if (!Number.isFinite(num)) continue;
57    switch (row.key) {
58      case "trial_per_call_limit":   cfg.perCallLimit = num; break;
59      case "trial_date_window_days": cfg.windowDays = num; break;
60      case "trial_calls_limit":      cfg.callsLimit = num; break;
61      case "trial_cooldown_hours":   cfg.cooldownHours = num; break;
62    }
63  }
64
65  _cachedConfig = cfg;
66  _cachedAt = now;
67  return cfg;
68}
69
70/** Test-only — clears the per-process trial-config cache. */
71export function _resetTrialConfigCache(): void {
72  _cachedConfig = null;
73  _cachedAt = 0;
74}
75
76/**
77 * Manual cache invalidation entry point for ops tooling.
78 * Note: caches are per-PROCESS — calling this from a one-shot script only
79 * clears state in that script's own process. To invalidate the live MCP
80 * server's cache, restart the Apify Actor run.
81 */
82export function invalidateConfigCache(): void {
83  _resetTrialConfigCache();
84}
85
86// ---- Tool categories (drive trial-mode clamp decisions) ----
87
88export const SEARCH_TOOLS = new Set<string>([
89  "search_news",
90  "search_kdrama_archive",
91  "search_kmovie_archive",
92  "search_kbeauty_archive",
93  "search_kfood_archive",
94  "search_kgame_archive",
95  "search_ktech_archive",
96  "search_kstock_archive",
97  "search_ktravel_archive",
98  "search_kwebtoon_archive",
99  "search_ktrends_archive",
100]);
101
102export const TIMELINE_TOOLS = new Set<string>(["get_artist_timeline"]);
103
104export const DATE_AWARE_TOOLS = new Set<string>([
105  "get_kpop_news_today",
106  "get_kdrama_weekly_trend",
107  "get_kmovie_weekly_trend",
108  "get_kbeauty_weekly_trend",
109  "get_kfood_weekly_trend",
110  "get_kgame_weekly_trend",
111  "get_ktech_weekly_trend",
112  "get_kstock_weekly_trend",
113  "get_ktravel_weekly_trend",
114  "get_kwebtoon_weekly_trend",
115  "get_ktrends_weekly_trend",
116]);
117
118// ---- Public types ----
119
120type ToolEnvelope = ReturnType<typeof toolError>;
121
122export interface GuardOk<T> {
123  ok: true;
124  input: T;
125  isTrial: boolean;
126  /** Enterprise users — monthly_quota path. 0 on credit path. */
127  quotaUsed: number;
128  quotaLimit: number;
129  /** Credit path only — remaining USD balance after this call. */
130  creditBalance?: number;
131  /** Credit path only — price paid for this call (USD). */
132  costThisCall?: number;
133  /** Credit path only — true when balance dipped below auto-topup threshold. */
134  autoTopupWarning?: boolean;
135  /** Set when the guard fell back due to RPC failure (e.g. "rpc_failure_recovery"). */
136  fallback?: string;
137  /** Human-readable note for the caller when in a fallback state. */
138  warning?: string;
139}
140export interface GuardFail {
141  ok: false;
142  error: ToolEnvelope;
143}
144export type GuardResult<T> = GuardOk<T> | GuardFail;
145
146// ---- RPC response shape ----
147
148interface RpcResult {
149  allowed: boolean;
150  error_code?: string;
151  status?: string;
152  // ── Enterprise path (check_and_record_usage fallback) ───────────
153  used?: number;
154  limit?: number;
155  user_id?: string;
156  tier?: string | null;
157  quota_used?: number;
158  quota_limit?: number;
159  // ── Credit path (pay-per-call main flow) ────────────────────────
160  current_balance?: number;
161  required?: number;
162  credit_balance_remaining?: number;
163  cost_this_call?: number;
164  total_calls?: number;
165  auto_topup_warning?: boolean;
166  auto_topup_enabled?: boolean;
167  is_trial?: boolean;
168}
169
170// ---- Helpers ----
171
172function hashQuery(q: string): string {
173  return createHash("sha1").update(q.toLowerCase().trim()).digest("hex");
174}
175
176function trialEarliestYmd(windowDays: number): string {
177  const kstNowMs = Date.now() + 9 * 3600 * 1000;
178  const earliestMs = kstNowMs - windowDays * 86_400_000;
179  return new Date(earliestMs).toISOString().slice(0, 10);
180}
181
182function mapRpcError(r: RpcResult): ToolEnvelope {
183  switch (r.error_code) {
184    case "UNAUTHORIZED":
185      return toolError(
186        ERR.UNAUTHORIZED,
187        "Invalid or missing API key.",
188        "Sign up at https://korean-data.com.",
189      );
190    case "SUBSCRIPTION_INACTIVE":
191      return toolError(
192        ERR.SUBSCRIPTION_INACTIVE,
193        `Subscription is ${r.status ?? "inactive"}.`,
194        "Reactivate or upgrade at https://korean-data.com/billing.",
195      );
196    case "EMAIL_NOT_VERIFIED":
197      return toolError(
198        ERR.EMAIL_NOT_VERIFIED,
199        "Trial requires email verification before API access.",
200        "Check your inbox for the verification link.",
201      );
202    case "INVALID_SUBSCRIPTION_STATE":
203      return toolError(
204        ERR.INVALID_SUBSCRIPTION_STATE,
205        "Subscription period boundaries are missing.",
206        "Contact support@korean-data.com.",
207      );
208    case "QUOTA_EXCEEDED":
209      return toolError(
210        ERR.QUOTA_EXCEEDED,
211        `Monthly call quota exceeded (${r.used ?? "?"}/${r.limit ?? "?"}). Upgrade your plan at https://korean-data.com/pricing`,
212        "Trial limit is 100 calls. Upgrade to Starter ($29/mo, 1,000 calls) or Pro ($79/mo, 5,000 calls).",
213      );
214    case "QUOTA_EXCEEDED_DOWNGRADED":
215      return toolError(
216        ERR.QUOTA_EXCEEDED_DOWNGRADED,
217        `Plan was downgraded mid-cycle and existing usage (${r.used ?? "?"}) exceeds the new limit (${r.limit ?? "?"}). Quota resets next billing cycle.`,
218        "No charge for the over-usage. Wait for cycle reset or upgrade back to your previous tier.",
219      );
220    case "INSUFFICIENT_CREDIT": {
221      const bal = r.current_balance ?? 0;
222      const req = r.required ?? 0.005;
223      return toolError(
224        ERR.INSUFFICIENT_CREDIT,
225        `Credit insufficient — balance $${bal.toFixed(4)}, this call needs $${req.toFixed(4)}.`,
226        "Top up at https://korean-data.com/topup ($10 = 2,000 calls). Enable auto top-up to never run out.",
227      );
228    }
229    case "COOLDOWN_ACTIVE":
230      return toolError(
231        ERR.COOLDOWN_ACTIVE,
232        "Same search query within 24h is rate-limited on trial. Try a different query or upgrade.",
233        "Paid tiers have no cooldown.",
234      );
235    default:
236      return toolError(ERR.INTERNAL, "Quota check returned unknown state", JSON.stringify(r));
237  }
238}
239
240function applyClamps(
241  toolName: string,
242  input: object,
243  isTrial: boolean,
244  cfg: TrialConfig,
245): void {
246  const m = input as Record<string, unknown>;
247  const limitCap = isTrial ? cfg.perCallLimit : PAID_PER_CALL_LIMIT_MAX;
248  if (typeof m.limit === "number" && m.limit > limitCap) {
249    m.limit = limitCap;
250  }
251
252  if (!isTrial) return;
253
254  // Trial-mode date clamp — applies to date-aware / search / timeline tools.
255  const isDateAware =
256    DATE_AWARE_TOOLS.has(toolName) || SEARCH_TOOLS.has(toolName) || TIMELINE_TOOLS.has(toolName);
257  if (!isDateAware) return;
258
259  const earliest = trialEarliestYmd(cfg.windowDays);
260  for (const field of ["date_from", "date", "start_date"] as const) {
261    const v = m[field];
262    if (typeof v === "string" && v < earliest) m[field] = earliest;
263  }
264}
265
266// ---- Fail-open state ----
267// Auth = fail-CLOSED always (invalid key never gets through).
268// Quota check = fail-OPEN once per 60s window if the RPC itself errors,
269// then fail-CLOSED on the next failure inside the window. This protects
270// paid users from a brief DB hiccup while bounding the free-call blast
271// radius if the DB stays down (~1 free call/min per server process).
272
273const FAILOPEN_WINDOW_MS = 60_000;
274let lastRpcFailureMs = 0;
275
276// ---- Main entry ----
277
278export async function applyGuard<T extends object>(
279  toolName: string,
280  input: T,
281): Promise<GuardResult<T>> {
282  // 1. Bypass mode (smoke tests, admin operators).
283  if (process.env.QUOTA_BYPASS === "1") {
284    return { ok: true, input, isTrial: false, quotaUsed: 0, quotaLimit: 999_999 };
285  }
286
287  // 2. Resolve api_key → user (input.api_key takes precedence over env).
288  //    Auth is ALWAYS fail-closed — never let an unauthenticated call through.
289  const user = await getCurrentUser(input as { api_key?: unknown });
290  if (!user) {
291    return {
292      ok: false,
293      error: toolError(
294        ERR.UNAUTHORIZED,
295        "Invalid or missing API key.",
296        "Sign up at https://korean-data.com.",
297      ),
298    };
299  }
300
301  // 3. Compute query hash (search tools only — used for 24h cooldown).
302  const queryRaw =
303    SEARCH_TOOLS.has(toolName) &&
304    typeof (input as Record<string, unknown>).query === "string"
305      ? ((input as Record<string, unknown>).query as string)
306      : null;
307  const queryHash = queryRaw ? hashQuery(queryRaw) : null;
308
309  // 4. Atomic RPC call. v2 = check_and_charge_credit (pay-per-call). Enterprise
310  //    users are routed to check_and_record_usage inside the RPC itself.
311  //    Wrapped: rpcErr means the DB itself is sick — apply fail-open policy.
312  let data: unknown = null;
313  let rpcErr: { message: string } | null = null;
314  try {
315    const res = await supabase.rpc("check_and_charge_credit", {
316      p_user_id: user.user_id,
317      p_tool_name: toolName,
318      p_query_hash: queryHash,
319    });
320    data = res.data;
321    rpcErr = res.error ? { message: res.error.message } : null;
322  } catch (e) {
323    rpcErr = { message: (e as Error).message };
324  }
325
326  if (rpcErr) {
327    const now = Date.now();
328    const sinceLast = now - lastRpcFailureMs;
329    if (sinceLast > FAILOPEN_WINDOW_MS) {
330      // First failure in window → fail-OPEN (allow). Page ops.
331      lastRpcFailureMs = now;
332      captureError(new Error(rpcErr.message), {
333        tool_name: toolName,
334        user_id: user.user_id,
335        fallback: "fail-open",
336      });
337      void sendDiscordAlert(
338        `RPC failure (${toolName}) — fail-open activated for next 60s. msg=${rpcErr.message}`,
339        "error",
340      );
341      return {
342        ok: true,
343        input,
344        isTrial: false,
345        quotaUsed: 0,
346        quotaLimit: 0,
347        fallback: "rpc_failure_recovery",
348        warning:
349          "Quota check temporarily unavailable. Your call was allowed as a courtesy.",
350      };
351    }
352    // Second+ failure inside window → fail-CLOSED.
353    captureError(new Error(rpcErr.message), {
354      tool_name: toolName,
355      user_id: user.user_id,
356      fallback: "fail-closed",
357    });
358    return {
359      ok: false,
360      error: toolError(
361        ERR.SERVICE_UNAVAILABLE,
362        "Service temporarily unavailable. Please retry in a moment.",
363        "Quota subsystem is recovering. If this persists, contact support@korean-data.com.",
364      ),
365    };
366  }
367
368  const result = data as RpcResult | null;
369  if (!result || typeof result !== "object") {
370    return {
371      ok: false,
372      error: toolError(ERR.INTERNAL, "Quota RPC returned no data"),
373    };
374  }
375
376  if (!result.allowed) {
377    return { ok: false, error: mapRpcError(result) };
378  }
379
380  // 5. Mutate input with trial clamps. Tool downstream uses input.X directly.
381  const isTrial = Boolean(result.is_trial);
382  const cfg = await getTrialConfig();
383  applyClamps(toolName, input, isTrial, cfg);
384
385  // Auto-topup low-balance signal — page ops once per call when it crosses.
386  // The actual auto-topup execution happens in the auto-topup-trigger Edge
387  // Function (background); here we just emit visibility.
388  if (result.auto_topup_warning && result.auto_topup_enabled) {
389    void sendDiscordAlert(
390      `User ${user.user_id} balance below threshold (now $${(result.credit_balance_remaining ?? 0).toFixed(4)}) — auto-topup should fire.`,
391      "warn",
392    );
393  }
394
395  return {
396    ok: true,
397    input,
398    isTrial,
399    quotaUsed: result.quota_used ?? 0,
400    quotaLimit: result.quota_limit ?? 0,
401    creditBalance: result.credit_balance_remaining,
402    costThisCall: result.cost_this_call,
403    autoTopupWarning: result.auto_topup_warning,
404  };
405}

src/lib/supabase.ts

1// Supabase 클라이언트 싱글톤. SUPABASE_URL + SUPABASE_ANON_KEY env 필수.
2// anon key 만 사용 — stories/digests 는 RLS 로 public read 허용 중.
3
4import { createClient, type SupabaseClient } from "@supabase/supabase-js";
5
6const url = process.env.SUPABASE_URL;
7const key = process.env.SUPABASE_ANON_KEY;
8
9if (!url || !key) {
10  throw new Error(
11    "MCP server requires SUPABASE_URL + SUPABASE_ANON_KEY env vars (see .env.example).",
12  );
13}
14
15export const supabase: SupabaseClient = createClient(url, key, {
16  auth: { persistSession: false },
17});

src/lib/tagger.ts

1// LLM tagger — GPT-4o-mini 로 11개 카테고리 중 1개 분류 + secondary + confidence.
2// OPENAI_API_KEY env 필수.
3// 분류 카테고리 (DB 저장) = 11개 / MCP tool 노출은 별개 (현재는 K-Pop 만).
4
5import OpenAI from "openai";
6import { z } from "zod";
7import { sendDiscordAlert } from "./monitoring.js";
8
9export const CATEGORIES = [
10  "K-Pop",
11  "K-Drama",
12  "K-Movie",
13  "K-Beauty",
14  "K-Food",
15  "K-Game",
16  "K-Tech",
17  "K-Stock",
18  "K-Travel",
19  "K-Webtoon",
20  "K-Trends",
21] as const;
22export type Category = (typeof CATEGORIES)[number];
23
24export const TagResultZ = z.object({
25  category: z.enum(CATEGORIES),
26  secondary_category: z.enum(CATEGORIES).nullable(),
27  confidence: z.number().min(0).max(1),
28});
29export type TagResult = z.infer<typeof TagResultZ>;
30
31export interface Usage {
32  input_tokens: number;
33  output_tokens: number;
34  cost_usd: number;
35}
36
37// GPT-4o-mini pricing (USD per 1M tokens, OpenAI public list).
38const PRICE_INPUT_PER_1M = 0.15;
39const PRICE_OUTPUT_PER_1M = 0.6;
40const MODEL = "gpt-4o-mini";
41
42export function calcCost(inputTokens: number, outputTokens: number): number {
43  return (
44    (inputTokens * PRICE_INPUT_PER_1M + outputTokens * PRICE_OUTPUT_PER_1M) / 1_000_000
45  );
46}
47
48// ─── OpenAI cost guard ──────────────────────────────────────────────────
49// In-memory daily counter — resets on process restart (= per backfill run).
50// Per-call ceiling guards against pathological prompts; daily ceiling kills
51// runaway backfill loops before they nuke the OpenAI budget.
52
53const DAILY_COST_LIMIT_USD = 10;
54const PER_CALL_COST_LIMIT_USD = 0.1;
55
56let dailyCostUSD = 0;
57let dailyResetDate = new Date().toISOString().slice(0, 10);
58
59export class DailyCostLimitExceeded extends Error {
60  constructor(spent: number, limit: number) {
61    super(
62      `DAILY_COST_LIMIT_EXCEEDED — spent $${spent.toFixed(2)} > limit $${limit.toFixed(2)}`,
63    );
64    this.name = "DailyCostLimitExceeded";
65  }
66}
67
68/**
69 * Records a tagger call's cost, alerts on anomalies, and throws
70 * DailyCostLimitExceeded when the daily ceiling is breached so the calling
71 * backfill loop can stop cleanly.
72 *
73 * Returns the rolling totals so the caller can log them.
74 */
75function trackCost(costUSD: number): { costUSD: number; dailyTotalUSD: number } {
76  const today = new Date().toISOString().slice(0, 10);
77  if (today !== dailyResetDate) {
78    dailyCostUSD = 0;
79    dailyResetDate = today;
80  }
81  dailyCostUSD += costUSD;
82
83  if (costUSD > PER_CALL_COST_LIMIT_USD) {
84    void sendDiscordAlert(
85      `Single OpenAI call cost $${costUSD.toFixed(4)} (per-call limit $${PER_CALL_COST_LIMIT_USD.toFixed(2)}).`,
86      "error",
87    );
88  }
89
90  if (dailyCostUSD > DAILY_COST_LIMIT_USD) {
91    void sendDiscordAlert(
92      `OpenAI daily cost exceeded: $${dailyCostUSD.toFixed(2)} > limit $${DAILY_COST_LIMIT_USD.toFixed(2)}. Auto-pausing tagger.`,
93      "error",
94    );
95    throw new DailyCostLimitExceeded(dailyCostUSD, DAILY_COST_LIMIT_USD);
96  }
97
98  return { costUSD, dailyTotalUSD: dailyCostUSD };
99}
100
101/** Test/ops helper — clears the per-process daily counter. */
102export function _resetDailyCost(): void {
103  dailyCostUSD = 0;
104  dailyResetDate = new Date().toISOString().slice(0, 10);
105}
106
107const SYSTEM_PROMPT = `You are a content classifier for Korean entertainment and lifestyle news.
108
109Classify each story into EXACTLY ONE primary category from this taxonomy:
110
1111. K-Pop — music releases, music videos, idol activities, group news, comebacks, charts, fandoms, music awards, concerts. Celebrity dating / lifestyle of pop idols → K-Trends UNLESS it directly involves a music release or performance.
1122. K-Drama — scripted TV series or streaming dramas only. Casting, ratings, plot updates, drama production. NOT variety shows, NOT reality shows, NOT celebrity dating, NOT celebrity lifestyle, NOT movies. Variety / reality / celebrity gossip → K-Trends. Films → K-Movie.
1133. K-Movie — Korean films, film festivals (Cannes, Venice, Busan / BIFF, Bucheon / BIFAN, Berlin), film reviews, box office, directors, screen actors when the story is film-focused.
1144. K-Beauty — cosmetics, skincare, makeup, beauty brands, K-beauty exports and trends.
1155. K-Food — Korean cuisine, restaurants, food trends, recipes, Korean dishes / snacks / drinks.
1166. K-Game — Korean gaming industry, esports, game studios, game releases.
1177. K-Tech — Korean tech companies, startups, AI, semiconductors, IT industry (non-stock).
1188. K-Stock — Korean stock market (KOSPI / KOSDAQ), financial news, IPOs, corporate earnings, and financial reports of Korean entertainment / media companies (Hybe, SM, JYP, YG, CJ ENM, YH Entertainment, etc.) including their stock performance, debt ratios, leverage, and quarterly earnings.
1199. K-Travel — tourism, destinations, travel trends, hotels, visit-Korea content.
12010. K-Webtoon — webtoons, manhwa, web animation, webtoon adaptations.
12111. K-Trends — general / miscellaneous Korean cultural trends, variety / reality TV, celebrity dating / lifestyle, social commentary, and stories that don't clearly fit the above categories.
122
123If the story strongly straddles TWO categories, set secondary_category to the second-best fit.
124Otherwise set secondary_category to null.
125
126Confidence: 0.0 to 1.0 — how sure you are about the primary category. If the story is essentially off-topic (religion, politics, op-eds, obituaries unrelated to entertainment) but you must still bucket it into K-Trends, return LOW confidence (≤ 0.4) so downstream filters can catch it.
127
128Output STRICT JSON only, no preamble, no markdown fences:
129{"category": "...", "secondary_category": "..." | null, "confidence": 0.00}
130
131Examples:
132
133Input: {"title": "BTS Jin announces 2026 solo arena tour dates", "summary": "Big Hit confirms Asia leg starting in March."}
134Output: {"category": "K-Pop", "secondary_category": null, "confidence": 0.98}
135
136Input: {"title": "Squid Game season 3 wraps filming, premieres December", "summary": "Netflix confirms release window with new cast additions."}
137Output: {"category": "K-Drama", "secondary_category": null, "confidence": 0.97}
138
139Input: {"title": "Olive Young expands glass-skin serum globally as K-beauty exports hit record", "summary": "Q1 revenue beats estimates on US demand."}
140Output: {"category": "K-Beauty", "secondary_category": "K-Stock", "confidence": 0.85}
141
142Input: {"title": "정해인·조정석, 미쟝센영화제 심사 맡는다", "summary": "신진 단편영화 감독 발굴 프로젝트 심사위원으로 위촉."}
143Output: {"category": "K-Movie", "secondary_category": null, "confidence": 0.95}
144
145Input: {"title": "송지은♥박위, 결혼 2년차 데이트 중 눈물 쏟아", "summary": "유튜브 채널에서 공개된 부부의 일상 영상."}
146Output: {"category": "K-Trends", "secondary_category": null, "confidence": 0.85}
147
148Input: {"title": "tvN 새 드라마 '뿌리깊은 나무2' 1회 시청률 12% 돌파", "summary": "동시간대 1위로 출발."}
149Output: {"category": "K-Drama", "secondary_category": null, "confidence": 0.95}
150
151Input: {"title": "BLACKPINK 컴백 첫날 음원차트 1위", "summary": "신곡 5개 트랙 모두 멜론 톱10 진입."}
152Output: {"category": "K-Pop", "secondary_category": null, "confidence": 0.97}
153
154Input: {"title": "[감리회 주간 브리핑] 김국도 목사 별세", "summary": "교계 동향 및 행정 소식 요약."}
155Output: {"category": "K-Trends", "secondary_category": null, "confidence": 0.25}`;
156
157let _client: OpenAI | null = null;
158function client(): OpenAI {
159  if (!_client) {
160    const apiKey = process.env.OPENAI_API_KEY;
161    if (!apiKey) throw new Error("OPENAI_API_KEY is required for tagger");
162    _client = new OpenAI({ apiKey });
163  }
164  return _client;
165}
166
167export interface TagInput {
168  title: string;
169  summary: string;
170}
171
172export interface TagOutcome {
173  result: TagResult;
174  usage: Usage;
175}
176
177export async function tagStory(input: TagInput): Promise<TagOutcome> {
178  const completion = await client().chat.completions.create({
179    model: MODEL,
180    response_format: { type: "json_object" },
181    temperature: 0.1,
182    messages: [
183      { role: "system", content: SYSTEM_PROMPT },
184      {
185        role: "user",
186        content: JSON.stringify({ title: input.title, summary: input.summary }),
187      },
188    ],
189  });
190
191  const raw = completion.choices[0]?.message?.content;
192  if (!raw) throw new Error("OpenAI returned empty content");
193
194  let parsed: unknown;
195  try {
196    parsed = JSON.parse(raw);
197  } catch {
198    throw new Error(`OpenAI returned non-JSON: ${raw.slice(0, 200)}`);
199  }
200
201  const result = TagResultZ.parse(parsed);
202
203  const u = completion.usage;
204  const inputTokens = u?.prompt_tokens ?? 0;
205  const outputTokens = u?.completion_tokens ?? 0;
206  const usage: Usage = {
207    input_tokens: inputTokens,
208    output_tokens: outputTokens,
209    cost_usd: calcCost(inputTokens, outputTokens),
210  };
211
212  // Records the cost + alerts on per-call / daily ceilings. Throws
213  // DailyCostLimitExceeded once the daily limit is breached — the caller
214  // (backfill loop) should let that propagate to halt the run.
215  trackCost(usage.cost_usd);
216
217  return { result, usage };
218}

src/shared/types.ts

1// 공통 타입 — 내부 DB shape 와 외부 tool output shape 분리.
2// Story    = stories 테이블 row shape (source_name, source_url — Supabase 컬럼 그대로).
3// ApiStory = tool output shape (source, url — clean external API contract).
4// 내부 ingest 파이프라인 (Python) 이 source_name/source_url 컬럼을 쓰고 있으므로
5// DB 쪽은 건드리지 않고 MCP 응답에서만 alias 함.
6
7export interface Story {
8  id: number | string;
9  cluster_id: string | null;
10  title: string | null;
11  summary: string | null;
12  source_name: string | null;
13  source_url: string | null;
14  subjects: string[] | null;
15  published_at: string | null;
16}
17
18export interface ApiStory {
19  id: number | string;
20  cluster_id: string | null;
21  title: string | null;
22  summary: string | null;
23  source: string | null;
24  url: string | null;
25  subjects: string[];
26  published_at: string | null;
27}
28
29export interface ClusterSummary {
30  cluster_id: string;
31  mention_count: number;
32  source_diversity: number;
33  momentum: "rising" | "peaking" | "fading";
34  score: number;
35  lead: ApiStory | null;
36}
37
38export interface VideoScript {
39  hook: string;
40  beats: string[];
41  cta: string;
42  hashtags: string[];
43}

src/mcp/kr/kbeauty/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kbeauty");

src/mcp/kr/kbeauty/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kbeauty");

src/mcp/kr/kdrama/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kdrama");

src/mcp/kr/kdrama/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kdrama");

src/mcp/kr/kmovie/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kmovie");

src/mcp/kr/kmovie/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kmovie");

src/mcp/kr/kfood/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kfood");

src/mcp/kr/kfood/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kfood");

src/mcp/kr/kpop/generate_video_script.ts

1// generate_video_script — 클러스터 또는 토픽 기반 short-form 비디오 스크립트.
2// LLM 호출 부분은 placeholder — 실제 generation 은 후속 PR.
3
4import { z } from "zod";
5import { supabase } from "../../../lib/supabase.js";
6import { ERR, toolError, toolJson } from "../../../lib/errors.js";
7import { applyGuard } from "../../../lib/quota_guard.js";
8import {
9  type Lang,
10  LANGS,
11  pickTitle,
12  pickSummary,
13  titleSelect,
14  summarySelect,
15} from "../../../lib/lang.js";
16import type { VideoScript } from "../../../shared/types.js";
17
18export const NAME = "generate_video_script";
19
20export const DESCRIPTION =
21  "Production-ready short-form video script generator (hook + beats + CTA + hashtags) for K-pop and K-drama " +
22  "creators on TikTok, YouTube Shorts, Instagram Reels, or platform-agnostic. Use this tool when the user " +
23  "asks 'make a 60-second TikTok about [event/cluster]', 'draft a YouTube Shorts script on the latest " +
24  "BLACKPINK news', 'turn this trending K-drama cluster into a Reels script', or any request to convert " +
25  "Korean entertainment news into a structured short-form video outline. Differentiators: multilingual " +
26  "native output (en/ko/ja/es), platform-aware tone and pacing presets (tiktok / youtube_shorts / " +
27  "instagram_reels / generic), duration-aware beat count (30-180s), grounded in real-time clustered " +
28  "K-Star coverage (cluster_id input pulls deduplicated lead + supporting stories). " +
29  "Token efficiency: Returns highly condensed, pre-clustered JSON optimized for LLM context windows. " +
30  "Reduces input token costs by up to 70-80% compared to raw HTML scraping or generic news APIs.";
31
32const platformEnum = z.enum(["tiktok", "youtube_shorts", "instagram_reels", "generic"]);
33const toneEnum = z.enum(["hype", "informative", "dramatic", "casual", "fan-pov"]);
34
35export const inputSchema = {
36  cluster_id: z
37    .string()
38    .min(1)
39    .max(200)
40    .optional()
41    .describe("Cluster ID (preferred — grounds the script in deduplicated coverage)"),
42  topic: z
43    .string()
44    .min(1)
45    .max(200)
46    .optional()
47    .describe("Free-text topic (used when no cluster_id is available)"),
48  lang: z.enum(LANGS).default("en"),
49  platform: platformEnum.default("tiktok"),
50  duration_seconds: z.number().int().min(30).max(180).default(60),
51  tone: toneEnum.default("hype"),
52};
53
54const InputZ = z.object(inputSchema).refine((v) => Boolean(v.cluster_id || v.topic), {
55  message: "either cluster_id or topic is required",
56  path: ["cluster_id"],
57});
58
59export async function handler(raw: Record<string, unknown>) {
60  const parsed = InputZ.safeParse(raw);
61  if (!parsed.success) {
62    return toolError(
63      ERR.INVALID_PARAM,
64      "Invalid input for generate_video_script",
65      parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
66    );
67  }
68  const args = parsed.data;
69
70  const guard = await applyGuard(NAME, args);
71  if (!guard.ok) return guard.error;
72
73  const lang = args.lang as Lang;
74
75  let groundingTitle: string | null = null;
76  let groundingSummary: string | null = null;
77  let supportingCount = 0;
78
79  if (args.cluster_id) {
80    const cols = [
81      "id",
82      "cluster_id",
83      "is_cluster_lead",
84      ...titleSelect(lang),
85      ...summarySelect(lang),
86    ].join(", ");
87
88    const { data, error } = await supabase
89      .from("stories")
90      .select(cols)
91      .eq("cluster_id", args.cluster_id)
92      .eq("is_off_topic", false);
93
94    if (error) {
95      return toolError(
96        ERR.DB_ERROR,
97        "Supabase query failed while loading cluster",
98        `${error.code ?? ""} ${error.message}`.trim(),
99      );
100    }
101
102    const rows = (data ?? []) as unknown as Record<string, unknown>[];
103    if (rows.length === 0) {
104      return toolError(
105        ERR.NOT_FOUND,
106        "No stories found for cluster_id",
107        `cluster_id=${args.cluster_id}`,
108      );
109    }
110
111    const lead = rows.find((r) => r.is_cluster_lead === true) ?? rows[0]!;
112    groundingTitle = pickTitle(lead, lang);
113    groundingSummary = pickSummary(lead, lang);
114    supportingCount = Math.max(0, rows.length - 1);
115  } else if (args.topic) {
116    groundingTitle = args.topic;
117    groundingSummary = null;
118  }
119
120  // TODO: replace placeholder with a real LLM script-generation call.
121  // Keeping the surface stable so callers can wire the output schema today.
122  const script: VideoScript = {
123    hook: "[LLM script generation pending]",
124    beats: ["[LLM script generation pending]"],
125    cta: "[LLM script generation pending]",
126    hashtags: [],
127  };
128
129  return toolJson({
130    lang,
131    platform: args.platform,
132    duration_seconds: args.duration_seconds,
133    tone: args.tone,
134    grounding: {
135      cluster_id: args.cluster_id ?? null,
136      topic: args.topic ?? null,
137      lead_title: groundingTitle,
138      lead_summary: groundingSummary,
139      supporting_story_count: supportingCount,
140    },
141    script,
142    status: "placeholder",
143    notice:
144      "LLM script generation is not yet wired. Response shape is stable; swap in real generation upstream.",
145  });
146}

src/mcp/kr/kpop/get_artist_timeline.ts

1// get_artist_timeline — 특정 아티스트/그룹의 시간순 뉴스 흐름.
2
3import { z } from "zod";
4import { supabase } from "../../../lib/supabase.js";
5import { ERR, toolError, toolJson } from "../../../lib/errors.js";
6import { applyGuard } from "../../../lib/quota_guard.js";
7import {
8  type Lang,
9  LANGS,
10  pickTitle,
11  pickSummary,
12  titleSelect,
13  summarySelect,
14} from "../../../lib/lang.js";
15import type { ApiStory } from "../../../shared/types.js";
16
17export const NAME = "get_artist_timeline";
18
19export const DESCRIPTION =
20  "Chronological, deduplicated news timeline for a specific Korean artist, group, actor, or IP across a " +
21  "given date range. Use this tool when the user asks 'what's been happening with BTS / aespa / IU / Park " +
22  "Seo-joon recently', 'BLACKPINK news this month', or any question that scopes K-entertainment coverage " +
23  "to one subject. Matches against the structured subjects[] NER tag array first (precise) and falls back " +
24  "to title substring (catches solo artists and works not tagged at scrape time). Differentiators: multilingual native " +
25  "(en/ko/ja/es title and summary columns), cluster-lead only (one story per event — outlet duplicates " +
26  "suppressed), real-time backing store (no scraping latency at request time), production-ready date-range " +
27  "scoping (start_date / end_date in Asia/Seoul calendar days). " +
28  "Token efficiency: Returns highly condensed, pre-clustered JSON optimized for LLM context windows. " +
29  "Reduces input token costs by up to 70-80% compared to raw HTML scraping or generic news APIs.";
30
31const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
32
33export const inputSchema = {
34  artist: z
35    .string()
36    .min(1)
37    .max(100)
38    .describe("Artist, group, or IP name (e.g. 'BTS', '뉴진스', 'Park Seo-joon')"),
39  start_date: z
40    .string()
41    .regex(dateRegex, "start_date must be YYYY-MM-DD (Asia/Seoul calendar day)")
42    .optional()
43    .describe("Start of window, KST (default: 30 days before end_date)"),
44  end_date: z
45    .string()
46    .regex(dateRegex, "end_date must be YYYY-MM-DD (Asia/Seoul calendar day)")
47    .optional()
48    .describe("End of window, KST (default: today KST)"),
49  lang: z.enum(LANGS).default("en"),
50  event_types: z
51    .array(z.string().min(1).max(40))
52    .default(["all"])
53    .describe(
54      "Reserved for event-type filtering (comeback / scandal / award / tour / etc). " +
55        "Currently accepted but not yet wired to a classifier column — pass ['all'] for forward-compat.",
56    ),
57  limit: z.number().int().min(1).max(100).default(30),
58};
59
60const InputZ = z.object(inputSchema);
61
62function todayKST(): string {
63  const kstMs = Date.now() + 9 * 3600 * 1000;
64  return new Date(kstMs).toISOString().slice(0, 10);
65}
66
67function kstStartUTC(date: string): string {
68  return new Date(`${date}T00:00:00+09:00`).toISOString();
69}
70
71function kstEndUTC(date: string): string {
72  return new Date(`${date}T23:59:59.999+09:00`).toISOString();
73}
74
75function shiftDays(date: string, deltaDays: number): string {
76  const t = Date.parse(`${date}T00:00:00+09:00`);
77  return new Date(t + deltaDays * 86400_000).toISOString().slice(0, 10);
78}
79
80export async function handler(raw: Record<string, unknown>) {
81  const parsed = InputZ.safeParse(raw);
82  if (!parsed.success) {
83    return toolError(
84      ERR.INVALID_PARAM,
85      "Invalid input for get_artist_timeline",
86      parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
87    );
88  }
89  const args = parsed.data;
90  const lang = args.lang as Lang;
91
92  const guard = await applyGuard(NAME, args);
93  if (!guard.ok) return guard.error;
94
95  const endDate = args.end_date ?? todayKST();
96  const startDate = args.start_date ?? shiftDays(endDate, -30);
97
98  if (startDate > endDate) {
99    return toolError(
100      ERR.INVALID_PARAM,
101      "start_date must be on or before end_date",
102      `start=${startDate} end=${endDate}`,
103    );
104  }
105
106  const artist = args.artist.replace(/[%,{}]/g, "").trim();
107  if (artist.length === 0) {
108    return toolError(ERR.INVALID_PARAM, "artist must contain non-whitespace characters");
109  }
110
111  const cols = [
112    "id",
113    "cluster_id",
114    ...titleSelect(lang),
115    ...summarySelect(lang),
116    "source_name",
117    "source_url",
118    "subjects",
119    "published_at",
120  ].join(", ");
121
122  const { data, error } = await supabase
123    .from("stories")
124    .select(cols)
125    .eq("is_cluster_lead", true)
126    .eq("is_off_topic", false)
127    .gte("published_at", kstStartUTC(startDate))
128    .lte("published_at", kstEndUTC(endDate))
129    .or(
130      lang === "ko"
131        ? `subjects.cs.{${artist}},title_ko.ilike.%${artist}%`
132        : `subjects.cs.{${artist}},title_ko.ilike.%${artist}%,title_${lang}.ilike.%${artist}%`,
133    )
134    .order("published_at", { ascending: false })
135    .limit(args.limit);
136
137  if (error) {
138    return toolError(
139      ERR.DB_ERROR,
140      "Supabase query failed",
141      `${error.code ?? ""} ${error.message}`.trim(),
142    );
143  }
144
145  const rows = (data ?? []) as unknown as Record<string, unknown>[];
146  const items: ApiStory[] = rows.map((r) => ({
147    id: r.id as number | string,
148    cluster_id: (r.cluster_id as string | null) ?? null,
149    title: pickTitle(r, lang),
150    summary: pickSummary(r, lang),
151    source: (r.source_name as string | null) ?? null,
152    url: (r.source_url as string | null) ?? null,
153    subjects: Array.isArray(r.subjects) ? (r.subjects as string[]) : [],
154    published_at: (r.published_at as string | null) ?? null,
155  }));
156
157  return toolJson({
158    artist: args.artist,
159    start_date: startDate,
160    end_date: endDate,
161    lang,
162    event_types_requested: args.event_types,
163    count: items.length,
164    items,
165  });
166}

src/mcp/kr/kpop/get_kpop_news_today.ts

1// get_kpop_news_today — 실시간 한국 K-pop / K-entertainment 뉴스 (cluster-deduplicated).
2// Realtime category: 데이터 없거나 24h 이상 stale 면 ERR_REALTIME_UNAVAILABLE.
3
4import { z } from "zod";
5import { supabase } from "../../../lib/supabase.js";
6import { ERR, toolError, toolJson } from "../../../lib/errors.js";
7import { applyGuard } from "../../../lib/quota_guard.js";
8import {
9  type Lang,
10  LANGS,
11  pickTitle,
12  pickSummary,
13  titleSelect,
14  summarySelect,
15} from "../../../lib/lang.js";
16import type { ApiStory } from "../../../shared/types.js";
17
18export const NAME = "get_kpop_news_today";
19
20export const DESCRIPTION =
21  "Real-time, cluster-deduplicated K-pop and K-entertainment news from Korean publishers (Naver-sourced, " +
22  "off-topic filtered, lead-only per event cluster). Use this tool when the user asks 'what's happening " +
23  "in K-pop today', 'latest K-drama news', 'today's K-entertainment headlines', or any question scoped to " +
24  "the current day's Korean entertainment coverage. Differentiators: multilingual native (en/ko/ja/es title " +
25  "and summary columns, no on-the-fly translation), production-ready cluster leads (one story per event — " +
26  "duplicate outlet coverage suppressed upstream), KST-aware day boundary (date param is Asia/Seoul calendar " +
27  "day, not UTC), optional group_filter for artist/IP scoping. " +
28  "Token efficiency: Returns highly condensed, pre-clustered JSON optimized for LLM context windows. " +
29  "Reduces input token costs by up to 70-80% compared to raw HTML scraping or generic news APIs.";
30
31const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
32
33export const inputSchema = {
34  lang: z.enum(LANGS).default("en").describe("Response language (en/ko/ja/es)"),
35  date: z
36    .string()
37    .regex(dateRegex, "date must be YYYY-MM-DD (Asia/Seoul calendar day)")
38    .optional()
39    .describe("Target KST date YYYY-MM-DD (default: today KST)"),
40  limit: z.number().int().min(1).max(50).default(10),
41  group_filter: z
42    .string()
43    .min(1)
44    .max(100)
45    .optional()
46    .describe(
47      "Optional artist / group / IP name; matches subjects[] (NER tags) and title_ko / title_${lang} substring.",
48    ),
49};
50
51const InputZ = z.object(inputSchema);
52
53function todayKST(): string {
54  const kstMs = Date.now() + 9 * 3600 * 1000;
55  return new Date(kstMs).toISOString().slice(0, 10);
56}
57
58function kstDayBoundsUTC(date: string): [string, string] {
59  const start = new Date(`${date}T00:00:00+09:00`).toISOString();
60  const end = new Date(`${date}T23:59:59.999+09:00`).toISOString();
61  return [start, end];
62}
63
64export async function handler(raw: Record<string, unknown>) {
65  const parsed = InputZ.safeParse(raw);
66  if (!parsed.success) {
67    return toolError(
68      ERR.INVALID_PARAM,
69      "Invalid input for get_kpop_news_today",
70      parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
71    );
72  }
73  const args = parsed.data;
74
75  const guard = await applyGuard(NAME, args);
76  if (!guard.ok) return guard.error;
77
78  const lang = args.lang as Lang;
79  const todayStr = todayKST();
80  const date = args.date ?? todayStr;
81  const isToday = date === todayStr;
82  const [startUtc, endUtc] = kstDayBoundsUTC(date);
83
84  const cols = [
85    "id",
86    "cluster_id",
87    ...titleSelect(lang),
88    ...summarySelect(lang),
89    "source_name",
90    "source_url",
91    "subjects",
92    "published_at",
93  ].join(", ");
94
95  let q = supabase
96    .from("stories")
97    .select(cols)
98    .eq("is_cluster_lead", true)
99    .eq("is_off_topic", false)
100    .gte("published_at", startUtc)
101    .lte("published_at", endUtc)
102    .order("published_at", { ascending: false })
103    .limit(args.limit);
104
105  if (args.group_filter) {
106    const f = args.group_filter.replace(/[%,{}]/g, "");
107    // subjects = NER 추출 entity 배열 (text[]) — 정확 매치 우선, title substring 도 추가.
108    const orParts = [`subjects.cs.{${f}}`, `title_ko.ilike.%${f}%`];
109    if (lang !== "ko") orParts.push(`title_${lang}.ilike.%${f}%`);
110    q = q.or(orParts.join(","));
111  }
112
113  const { data, error } = await q;
114  if (error) {
115    return toolError(
116      ERR.DB_ERROR,
117      "Supabase query failed",
118      `${error.code ?? ""} ${error.message}`.trim(),
119    );
120  }
121
122  const rows = (data ?? []) as unknown as Record<string, unknown>[];
123
124  // realtime check 은 unfiltered 케이스에만 적용 — group_filter 가 있으면
125  // 필터 결과 0개는 "그 아티스트가 오늘 안 다뤄짐" 으로 정상 응답해야 함.
126  if (isToday && !args.group_filter) {
127    if (rows.length === 0) {
128      return toolError(
129        ERR.REALTIME_UNAVAILABLE,
130        "No fresh stories available for today (KST).",
131        "Realtime tool — stale fallback disallowed by policy. Retry shortly or use search_news for a wider window.",
132      );
133    }
134    const latest = rows[0]?.published_at;
135    if (typeof latest === "string") {
136      const ageMs = Date.now() - Date.parse(latest);
137      if (ageMs > 24 * 3600 * 1000) {
138        return toolError(
139          ERR.REALTIME_UNAVAILABLE,
140          "Most recent story is older than 24h — feed considered stale.",
141          "Realtime tool — stale fallback disallowed by policy. Investigate the ingest pipeline.",
142        );
143      }
144    }
145  }
146
147  const items: ApiStory[] = rows.map((r) => ({
148    id: r.id as number | string,
149    cluster_id: (r.cluster_id as string | null) ?? null,
150    title: pickTitle(r, lang),
151    summary: pickSummary(r, lang),
152    source: (r.source_name as string | null) ?? null,
153    url: (r.source_url as string | null) ?? null,
154    subjects: Array.isArray(r.subjects) ? (r.subjects as string[]) : [],
155    published_at: (r.published_at as string | null) ?? null,
156  }));
157
158  return toolJson({
159    date,
160    lang,
161    count: items.length,
162    items,
163  });
164}

src/mcp/kr/kpop/get_trending_clusters.ts

1// get_trending_clusters — 최근 24h cluster 랭킹 (mention × source diversity × time decay).
2
3import { z } from "zod";
4import { supabase } from "../../../lib/supabase.js";
5import { ERR, toolError, toolJson } from "../../../lib/errors.js";
6import { applyGuard } from "../../../lib/quota_guard.js";
7import {
8  type Lang,
9  LANGS,
10  pickTitle,
11  pickSummary,
12  titleSelect,
13  summarySelect,
14} from "../../../lib/lang.js";
15import type { ApiStory, ClusterSummary } from "../../../shared/types.js";
16
17export const NAME = "get_trending_clusters";
18
19export const DESCRIPTION =
20  "Real-time trending K-entertainment story clusters ranked by mention count × source diversity × " +
21  "time decay over the last 24 hours. Use this tool when the user asks 'what's trending in K-pop right " +
22  "now', 'biggest K-drama stories today', 'what are Korean outlets converging on', or any question about " +
23  "story momentum across the Korean publisher landscape. A cluster = multiple outlets covering the same " +
24  "event; larger and more diverse cluster = bigger story. Differentiators: cluster-deduplicated " +
25  "(one row per event, not per outlet), multi-signal ranking (volume + source diversity + recency, not " +
26  "raw count), momentum-aware (rising / peaking / fading bucketing via half-window comparison), " +
27  "multilingual native lead story (en/ko/ja/es), production-ready (off-topic stories pre-filtered upstream). " +
28  "Token efficiency: Returns highly condensed, pre-clustered JSON optimized for LLM context windows. " +
29  "Reduces input token costs by up to 70-80% compared to raw HTML scraping or generic news APIs.";
30
31const categoryEnum = z.enum(["kpop", "kdrama", "kactor", "all"]);
32const momentumEnum = z.enum(["rising", "peaking", "all"]);
33
34export const inputSchema = {
35  category: categoryEnum
36    .default("all")
37    .describe(
38      "Content scope (kpop / kdrama / kactor / all). Currently accepted but not yet wired to a classifier " +
39        "column — treated as 'all' for now; reserved for forward-compat.",
40    ),
41  lang: z.enum(LANGS).default("en"),
42  limit: z.number().int().min(1).max(20).default(5),
43  momentum_filter: momentumEnum.default("all"),
44};
45
46const InputZ = z.object(inputSchema);
47
48const WINDOW_HOURS = 24;
49const HALF_HOURS = 12;
50const DECAY_HALF_LIFE_HOURS = 12;
51
52interface ClusterAgg {
53  cluster_id: string;
54  mention_count: number;
55  sources: Set<string>;
56  decay_sum: number;
57  newer_half: number;
58  older_half: number;
59}
60
61function bucketMomentum(newer: number, older: number): "rising" | "peaking" | "fading" {
62  const ratio = newer / Math.max(older, 1);
63  if (ratio > 1.5) return "rising";
64  if (ratio < 0.5) return "fading";
65  return "peaking";
66}
67
68export async function handler(raw: Record<string, unknown>) {
69  const parsed = InputZ.safeParse(raw);
70  if (!parsed.success) {
71    return toolError(
72      ERR.INVALID_PARAM,
73      "Invalid input for get_trending_clusters",
74      parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
75    );
76  }
77  const args = parsed.data;
78
79  const guard = await applyGuard(NAME, args);
80  if (!guard.ok) return guard.error;
81
82  const lang = args.lang as Lang;
83  const nowMs = Date.now();
84  const cutoffMs = nowMs - WINDOW_HOURS * 3600 * 1000;
85  const halfMs = nowMs - HALF_HOURS * 3600 * 1000;
86  const cutoffIso = new Date(cutoffMs).toISOString();
87
88  // Step 1: pull all in-window non-off-topic rows. PostgREST has no GROUP BY,
89  // so client-side aggregate by cluster_id.
90  const { data: agg, error: aggErr } = await supabase
91    .from("stories")
92    .select("cluster_id, source_name, published_at")
93    .eq("is_off_topic", false)
94    .not("cluster_id", "is", null)
95    .gte("published_at", cutoffIso);
96
97  if (aggErr) {
98    return toolError(
99      ERR.DB_ERROR,
100      "Supabase aggregate query failed",
101      `${aggErr.code ?? ""} ${aggErr.message}`.trim(),
102    );
103  }
104
105  const buckets = new Map<string, ClusterAgg>();
106  for (const r of (agg ?? []) as unknown as Record<string, unknown>[]) {
107    const cid = r.cluster_id as string | null;
108    if (!cid) continue;
109    const publishedAt = r.published_at as string | null;
110    const publishedMs = publishedAt ? Date.parse(publishedAt) : NaN;
111    if (!Number.isFinite(publishedMs)) continue;
112
113    const hoursAgo = Math.max(0, (nowMs - publishedMs) / 3600_000);
114    const decay = Math.exp(-hoursAgo / DECAY_HALF_LIFE_HOURS);
115
116    let b = buckets.get(cid);
117    if (!b) {
118      b = {
119        cluster_id: cid,
120        mention_count: 0,
121        sources: new Set<string>(),
122        decay_sum: 0,
123        newer_half: 0,
124        older_half: 0,
125      };
126      buckets.set(cid, b);
127    }
128    b.mention_count += 1;
129    const src = r.source_name as string | null;
130    if (src) b.sources.add(src);
131    b.decay_sum += decay;
132    if (publishedMs >= halfMs) b.newer_half += 1;
133    else b.older_half += 1;
134  }
135
136  const scored = [...buckets.values()].map((b) => {
137    const sourceDiversity = b.sources.size;
138    const avgDecay = b.mention_count > 0 ? b.decay_sum / b.mention_count : 0;
139    const score = b.mention_count * sourceDiversity * avgDecay;
140    const momentum = bucketMomentum(b.newer_half, b.older_half);
141    return { ...b, sourceDiversity, score, momentum };
142  });
143
144  const filtered = scored.filter((c) => {
145    if (args.momentum_filter === "all") return true;
146    if (args.momentum_filter === "rising") return c.momentum === "rising";
147    if (args.momentum_filter === "peaking") return c.momentum === "peaking";
148    return true;
149  });
150
151  filtered.sort((a, b) => b.score - a.score);
152  const top = filtered.slice(0, args.limit);
153
154  if (top.length === 0) {
155    return toolJson({
156      window_hours: WINDOW_HOURS,
157      category: args.category,
158      momentum_filter: args.momentum_filter,
159      lang,
160      count: 0,
161      items: [] as ClusterSummary[],
162    });
163  }
164
165  // Step 2: fetch lead row for each top cluster.
166  const leadCols = [
167    "id",
168    "cluster_id",
169    ...titleSelect(lang),
170    ...summarySelect(lang),
171    "source_name",
172    "source_url",
173    "subjects",
174    "published_at",
175  ].join(", ");
176
177  const leadIds = top.map((t) => t.cluster_id);
178  const { data: leads, error: lErr } = await supabase
179    .from("stories")
180    .select(leadCols)
181    .in("cluster_id", leadIds)
182    .eq("is_cluster_lead", true);
183
184  if (lErr) {
185    return toolError(
186      ERR.DB_ERROR,
187      "Supabase lead-fetch failed",
188      `${lErr.code ?? ""} ${lErr.message}`.trim(),
189    );
190  }
191
192  const byCluster = new Map<string, Record<string, unknown>>();
193  for (const l of (leads ?? []) as unknown as Record<string, unknown>[]) {
194    const cid = l.cluster_id as string | null;
195    if (cid) byCluster.set(cid, l);
196  }
197
198  const items: ClusterSummary[] = top.map((c) => {
199    const leadRow = byCluster.get(c.cluster_id);
200    const lead: ApiStory | null = leadRow
201      ? {
202          id: leadRow.id as number | string,
203          cluster_id: c.cluster_id,
204          title: pickTitle(leadRow, lang),
205          summary: pickSummary(leadRow, lang),
206          source: (leadRow.source_name as string | null) ?? null,
207          url: (leadRow.source_url as string | null) ?? null,
208          subjects: Array.isArray(leadRow.subjects) ? (leadRow.subjects as string[]) : [],
209          published_at: (leadRow.published_at as string | null) ?? null,
210        }
211      : null;
212    return {
213      cluster_id: c.cluster_id,
214      mention_count: c.mention_count,
215      source_diversity: c.sourceDiversity,
216      momentum: c.momentum,
217      score: Number(c.score.toFixed(4)),
218      lead,
219    };
220  });
221
222  return toolJson({
223    window_hours: WINDOW_HOURS,
224    category: args.category,
225    momentum_filter: args.momentum_filter,
226    lang,
227    count: items.length,
228    items,
229  });
230}

src/mcp/kr/kpop/search_news.ts

1// search_news — title / summary substring + recency ranking.
2
3import { z } from "zod";
4import { supabase } from "../../../lib/supabase.js";
5import { ERR, toolError, toolJson } from "../../../lib/errors.js";
6import { applyGuard } from "../../../lib/quota_guard.js";
7import {
8  type Lang,
9  LANGS,
10  pickTitle,
11  pickSummary,
12  titleSelect,
13  summarySelect,
14} from "../../../lib/lang.js";
15import type { ApiStory } from "../../../shared/types.js";
16
17export const NAME = "search_news";
18
19export const DESCRIPTION =
20  "Free-text search across cluster-deduplicated K-pop and K-entertainment news (title and summary " +
21  "substring match, off-topic filtered). Use this tool when the user supplies a keyword, phrase, artist " +
22  "name, work title, or event reference and wants matching stories across the Korean publisher landscape — " +
23  "e.g. 'search for [Newjeans comeback]', 'find news about [the Hybe / Min Hee-jin dispute]', 'show " +
24  "stories mentioning [Squid Game 3]'. Differentiators: multilingual native (en/ko/ja/es title and summary " +
25  "columns matched simultaneously), cluster-lead only (one story per event, no outlet duplicates), " +
26  "production-ready relevance ordering (substring match × recency), real-time backing store. " +
27  "Token efficiency: Returns highly condensed, pre-clustered JSON optimized for LLM context windows. " +
28  "Reduces input token costs by up to 70-80% compared to raw HTML scraping or generic news APIs.";
29
30const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
31
32export const inputSchema = {
33  query: z.string().min(1).max(200).describe("Search keyword or phrase"),
34  lang: z.enum(LANGS).default("en"),
35  date_from: z
36    .string()
37    .regex(dateRegex, "date_from must be YYYY-MM-DD (Asia/Seoul calendar day)")
38    .optional()
39    .describe("Start of window, KST (default: 30 days before date_to)"),
40  date_to: z
41    .string()
42    .regex(dateRegex, "date_to must be YYYY-MM-DD (Asia/Seoul calendar day)")
43    .optional()
44    .describe("End of window, KST (default: today KST)"),
45  limit: z.number().int().min(1).max(50).default(20),
46};
47
48const InputZ = z.object(inputSchema);
49
50function todayKST(): string {
51  const kstMs = Date.now() + 9 * 3600 * 1000;
52  return new Date(kstMs).toISOString().slice(0, 10);
53}
54
55function shiftDays(date: string, deltaDays: number): string {
56  const t = Date.parse(`${date}T00:00:00+09:00`);
57  return new Date(t + deltaDays * 86400_000).toISOString().slice(0, 10);
58}
59
60function kstStartUTC(date: string): string {
61  return new Date(`${date}T00:00:00+09:00`).toISOString();
62}
63
64function kstEndUTC(date: string): string {
65  return new Date(`${date}T23:59:59.999+09:00`).toISOString();
66}
67
68export async function handler(raw: Record<string, unknown>) {
69  const parsed = InputZ.safeParse(raw);
70  if (!parsed.success) {
71    return toolError(
72      ERR.INVALID_PARAM,
73      "Invalid input for search_news",
74      parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
75    );
76  }
77  const args = parsed.data;
78
79  const guard = await applyGuard(NAME, args);
80  if (!guard.ok) return guard.error;
81
82  const lang = args.lang as Lang;
83
84  const dateTo = args.date_to ?? todayKST();
85  const dateFrom = args.date_from ?? shiftDays(dateTo, -30);
86
87  if (dateFrom > dateTo) {
88    return toolError(
89      ERR.INVALID_PARAM,
90      "date_from must be on or before date_to",
91      `date_from=${dateFrom} date_to=${dateTo}`,
92    );
93  }
94
95  const qEsc = args.query.replace(/[%,]/g, "").trim();
96  if (qEsc.length === 0) {
97    return toolError(
98      ERR.INVALID_PARAM,
99      "query must contain searchable characters",
100      "Strip out commas and percent signs and retry.",
101    );
102  }
103
104  // base title/summary 컬럼 없음 — title_ko + content_ko 가 한국어 원문 (항상 존재).
105  // 비한국어는 번역 컬럼도 함께 매치.
106  const orParts = [`title_ko.ilike.%${qEsc}%`, `content_ko.ilike.%${qEsc}%`];
107  if (lang !== "ko") {
108    orParts.push(`title_${lang}.ilike.%${qEsc}%`, `summary_${lang}.ilike.%${qEsc}%`);
109  }
110  const orFilter = orParts.join(",");
111
112  const cols = [
113    "id",
114    "cluster_id",
115    ...titleSelect(lang),
116    ...summarySelect(lang),
117    "source_name",
118    "source_url",
119    "subjects",
120    "published_at",
121  ].join(", ");
122
123  const { data, error } = await supabase
124    .from("stories")
125    .select(cols)
126    .eq("is_cluster_lead", true)
127    .eq("is_off_topic", false)
128    .gte("published_at", kstStartUTC(dateFrom))
129    .lte("published_at", kstEndUTC(dateTo))
130    .or(orFilter)
131    .order("published_at", { ascending: false })
132    .limit(args.limit);
133
134  if (error) {
135    return toolError(
136      ERR.DB_ERROR,
137      "Supabase query failed",
138      `${error.code ?? ""} ${error.message}`.trim(),
139    );
140  }
141
142  const rows = (data ?? []) as unknown as Record<string, unknown>[];
143  const items: ApiStory[] = rows.map((r) => ({
144    id: r.id as number | string,
145    cluster_id: (r.cluster_id as string | null) ?? null,
146    title: pickTitle(r, lang),
147    summary: pickSummary(r, lang),
148    source: (r.source_name as string | null) ?? null,
149    url: (r.source_url as string | null) ?? null,
150    subjects: Array.isArray(r.subjects) ? (r.subjects as string[]) : [],
151    published_at: (r.published_at as string | null) ?? null,
152  }));
153
154  return toolJson({
155    query: args.query,
156    lang,
157    date_from: dateFrom,
158    date_to: dateTo,
159    count: items.length,
160    items,
161  });
162}

src/mcp/kr/kstock/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kstock");

src/mcp/kr/kstock/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kstock");

src/mcp/kr/kgame/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kgame");

src/mcp/kr/kgame/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kgame");

src/mcp/kr/ktravel/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("ktravel");

src/mcp/kr/ktravel/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("ktravel");

src/mcp/kr/ktech/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("ktech");

src/mcp/kr/ktech/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("ktech");

src/mcp/kr/ktrends/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("ktrends");

src/mcp/kr/ktrends/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("ktrends");

src/mcp/kr/kwebtoon/get_weekly_media_trend.ts

1import { buildWeeklyTrendTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildWeeklyTrendTool("kwebtoon");

src/mcp/kr/kwebtoon/search_media_archive.ts

1import { buildSearchArchiveTool } from "../../../lib/category_tools.js";
2export const { NAME, DESCRIPTION, inputSchema, handler } = buildSearchArchiveTool("kwebtoon");

.actor/INPUT.json

{
  "api_key": "test_bypass_key"
}