# koreanpulse

> Get pinged in English the moment a 5%-rule filing or DART event hits a stock you care about. **(Beta — watchlist polling + alert dispatch ship Q3 2026.)** Today the public free `/today` snapshot, queries (DART filings + foreign-holder + activist tracking + industry news), and hosted English translation cache (no OpenAI key needed) are live; watchlist polling and alert dispatch (Discord / Telegram / Slack / webhook) are on the Q3 2026 roadmap. Cloud waitlist with locked-in launch rate: Solo $29/mo, Analyst $79/mo, Desk $249/mo — early supporters keep the rate, no auto-charge until the workflow ships. OSS self-host available for hackers.

koreanpulse fills the gap between Bloomberg-tier coverage ($24K/yr, weak on Korean primary sources) and English wire services (KED Global, Korea Bizwire — reactive, low signal). The English-IR gap is multi-source verified: KRX itself, ASIFMA, Wellington, Aberdeen, Matthews Asia all on record that Korean disclosure flow into English is structurally inadequate. We index the same Korean primary sources Korean analysts already use — DART (전자공시시스템) filings, 전자신문, 한국경제 — and surface them on the public web at /today (free, daily, public, live today) and inside Claude / Cursor / any MCP client (Cloud Solo $29/mo, Analyst $79/mo, Desk $249/mo waitlist), with on-demand English translation cached aggressively for cross-tenant margin. The product is workflow-priced — pick the tier that matches how many tickers you'll watch and how many alert channels you'll want pinged once polling/dispatch ships. Today the only runtime-enforced tier delta is the monthly query cap (2K / 15K / 100K); seat counts, watchlist counts, alert-channel limits, and retention windows are paper limits until the watchlist polling + alert dispatch loop ships in Q3 2026.

Foreign retail just got direct access to KRX in the last 7 days: Hana × Futu Securities (3.3M HK fintech retail) launched Korean stock trading in late April 2026, and Samsung Securities × Interactive Brokers (4.6M global retail) pilot launched on May 4, 2026 — the same day foreigners net-bought a record 3.9 trillion KRW ($2.7B) on KOSPI+NXT. ~7.9M foreign retail accounts are now wired in. The English-language data layer for this audience is what koreanpulse ships.

The MCP server runs locally on the user's machine over stdio — Cloud customers still install it locally with `pip install koreanpulse` (a true HTTP-transport remote MCP that eliminates the local install is on the Q3 2026 roadmap). Cloud customers can switch to `KOREANPULSE_CACHE_MODE=hosted`, which routes translation calls through a Cloudflare Worker that holds our OpenAI key and fronts a global KV cache — so the translation one Cloud Solo customer asks for is reused for every other Cloud customer who hits the same Korean filing title. DART traffic always stays on the customer's machine.

Source code is AGPL-3.0; the hosted service is commercial. Data redistribution follows fair-use for Korean news (summaries + attribution + outbound links, no full-text republication) and free public-domain rules for DART. No investment advice is generated — the product is data + translation, not recommendations.

## Daily snapshot (machine-readable)

- [/today](https://koreanpulse.dev/today): Human-readable HTML daily dashboard, refreshed once per Korean market close (KST 16:30, weekdays). Sections: foreign capital activity (5%-rule disclosures by global asset managers / SWFs), activist filings, major DART disclosures.
- [/today.json](https://koreanpulse.dev/today.json): Same data in versioned JSON. Top-level shape: `{ schema_version: 2, date, generated_at, market: "KRX", takeaway: [...], activist_filings: [...], foreign_flows: [...], top_filings: [...], attribution, data_sources, legal_notice }`. Pin against `schema_version` for stable parsing. `takeaway` is an array of 1–3 short English bullets summarising the day's most material moves (LLM-generated). Each filing carries `corp_code`, `corp_name_ko`, `corp_name_en` (LLM-translated, may be empty), `stock_code`, `title`, `title_en`, `summary_en` (when available), `filer_name_ko`, `dart_url`, `filed_at`. Foreign flows additionally carry `holder_label` (canonical English) and `holder_origin` (us/uk/eu/other/kr).
- [/today/YYYY-MM-DD](https://koreanpulse.dev/today/2026-05-05): Per-date snapshot, last 30 days retained.

## Documentation

- [README](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/README.md): Project overview, why-this-exists, pricing, capacity math, and architecture.
- [SPEC](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/SPEC.md): Customer personas, MVP slice, and the client-vs-server split for LLM work.
- [ARCHITECTURE](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/ARCHITECTURE.md): How the MCP server, three Cloudflare Workers (cache / daily / webhook), and D1 license store fit together. 100% Cloudflare-hosted; zero ops on the operator side.
- [BETA acquisition plan](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/BETA.md): 50 users in 30 days plan with explicit ICP, channels, hard rules, and decision matrix.
- [Pricing](https://koreanpulse.dev/pricing): Cloud Solo $29/mo (5 watchlists, ~2,000 queries, 30-day archive, 1 Discord/Telegram channel) / Cloud Analyst $79/mo (25 watchlists, ~15,000 queries, 1-year archive, multi-channel alerts, CSV/JSON export) / Cloud Desk $249/mo (3 seats, shared watchlists, ~100,000 queries, Slack/webhook alerts, team archive). OSS self-host available separately for hackers. Enterprise / SLA available on request — no published price. _Design partner program available for the first 20 named seats — contact us._

## MCP tools

- [track_korean_filings](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Fetch recent DART filings, optionally translated and summarized.
- [lookup_corp_code](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Korean company name → DART 8-digit corp_code.
- [resolve_stock_code](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): KRX 6-digit stock code → DART corp entry.
- [search_korean_industry_news](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): Korean industry news from etnews / 한국경제, classified into 16 industries.
- [monitor_activist_investors](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/src/koreanpulse/server.py): DART type-D shareholding disclosures auto-tagged for known Korean activists (KCGI, Align Partners, Truston, Anda, Cha, Life, Platform, VIP).

## Setup

- [Claude Desktop](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/CLAUDE_DESKTOP.md): Installation snippet for `claude_desktop_config.json` plus required env vars.
- [Lemon Squeezy webhook](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/LEMONSQUEEZY.md): How license keys are issued automatically on subscription.
- [Webhook Worker (Cloudflare D1)](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/webhook-worker/README.md): Production license store + Lemon Squeezy webhook handler running on Cloudflare Worker + D1. Replaces the legacy Lightsail/FastAPI/Postgres path (now at `docs/legacy/POSTGRES_LIGHTSAIL.md`).
- [Run live](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/RUN_LIVE.md): End-to-end smoke test against real DART + OpenAI.

## Optional

- [Marketplace listings](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/MARKETPLACE.md): Submission copy and checklists for Smithery / PulseMCP / Glama / MCP Market / Awesome MCP.
- [Demo script](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/DEMO.md): 60-second Loom recording outline.
- [CI](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/docs/CI.md): GitHub Actions matrix (Python 3.10/3.11/3.12) and PyPI trusted publishing.
- [CHANGELOG](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/CHANGELOG.md): Per-release notes including ICP pivots and bug fixes.
- [Cache Worker](https://github.com/whdrnr2583-cmd/koreanpulse/blob/main/cache-worker/README.md): Cloudflare Workers + KV translation cache that fronts the hosted-mode license gate.
