用途
koreanpulse 是一个 MCP 服务器，用于把韩国股票市场一手数据接入 AI 助手，目标用户是 Claude Desktop、Cursor、ChatGPT、OpenAI Responses API、FastMCP 等客户端上的 AI / 交易智能体构建者。它解决的问题是韩国信息披露（DART 전자공시）英文化不足：韩文原始文件明确无歧义，但英文覆盖往往滞后数小时甚至缺失。该工具对韩国一手披露数据进行翻译、打标和筛选，以英文输出。用途为数据与情报，不构成买卖建议，也不执行任何交易。
主要能力
- 查询任意 KOSPI / KOSDAQ / KONEX / KRX 代码的 DART 电子公示。
- 5% 规则持股披露，按维护的白名单进行标注：包括韩国维权投资者（KCGI、Align Partners、Truston Asset、Anda Asset、Cha Partners、VIP Asset、Life Asset、Platform Partners、Must Asset Management、Dalton Investments、Flashlight Capital Partners、Oasis Management、Palliser Capital、Whitebox Advisors、City of London Investment Management，以及在韩国申报的 ValueAct、Elliott）和全球外资持有者（BlackRock、Vanguard、State Street、Fidelity、Capital Group、T. Rowe Price、Wellington、Matthews Asia、Templeton、Aberdeen、Schroders、Norges Bank、GIC、Temasek、Goldman Sachs、JPMorgan、Morgan Stanley、Citadel、Millennium、Bridgewater）。
- 韩国行业新闻，覆盖 16 个板块：半导体、造船、电池、生物科技、国防、汽车、电动车充电、AI、钢铁、石化、建筑、金融科技、游戏、电商、电信、能源；来源包括 전자신문、한국경제、The Korea Herald（英文原生）、지디넷코리아。
- 所有内容提供按需英文翻译，服务端缓存。
- koreanpulse_about 工具可返回工具目录和示例查询，用于智能体侧能力发现。
使用方式
三种连接模式：
- 托管远程 MCP：https://mcp.koreanpulse.dev/mcp，用于 ChatGPT / Claude.ai / OpenAI Responses API 自定义连接器。在 Claude.ai 设置 → Connectors 添加，或在 OpenAI Responses API 中写 tools=[{type: "mcp", server_url: "https://mcp.koreanpulse.dev/mcp"}]。只读，仅呈现披露文件，不执行交易，不提供投资建议。
- pip install koreanpulse 加四行配置，用于 Claude Desktop / Cursor 的 stdio 模式。
- Smithery 市场清单，供 Smithery CLI 用户使用。
已发布的 7 个 MCP 工具中，免费层（无需 license_key、无需注册）提供原始 DART 与 RSS 数据面；付费层（Solo 29 美元/月起，需要 license_key）解锁白名单标注工具。白名单标注是需要韩语使用者手工完成的工作。付费工具在缺少许可证时会返回提示，说明需要许可证密钥，工具响应中不含结账链接。
订阅通过 Polar 进行（Polar 是唯一计费方和 Merchant of Record），按分层提供结账，许可证密钥由 webhook worker 在 subscription.created 时邮件发出。首次付款有 30 天退款窗口。企业 / SLA 需联系，未公布价格。
自托管：源代码 AGPL-3.0，自托管者可用自己的 DART 和 OpenAI 密钥在本地运行 MCP 服务器，安装与密钥接线见 docs/SELF_HOSTING.md。也可通过 KOREANPULSE_CACHE_MODE 在 OSS 自托管与 Cloud 之间切换。
适用场景
适合把韩国股票一手数据接入已有 Claude Desktop / Cursor / FastMCP 智能体的开发者，沿用其美国数据所用的同一 MCP 形态，无需更换客户端。典型用法是询问某只关心股票是否有新披露，例如 5% 规则申报或 DART 事件。免费每日快照位于 /today，无需登录和 API 密钥，每个工作日发布一次。
限制
- 当前为 pre-alpha（v0.1.13）；测试 433 通过、1 跳过。
- 观察列表轮询与告警推送处于 Beta 规划中，尚未可用；目前可用的是按需查询。D1 schema 与告警推送原语已发布，缺少的是 cron 循环。
- 观察列表数量、告警渠道数量、档案保留窗口、席位数量等按分层限制尚未强制，属纸面限制；多数分层差异仍在路线图。早订阅用户在该功能上线后保留注册价格。
- DART 每个 API 密钥上限 40,000 次/天（2026-05 核实），服务端软上限 32,000 次/天（80%），可用 DART_DAILY_QUOTA 环境变量覆盖；单密钥硬天花板约 30,000 MAU，超出需第二个密钥（独立 사업자등록번호）。
- 另计划 4 个工具：digest_analyst_reports、get_ma_pipeline、track_government_policy、summarize_korean_earnings_call（见 docs/SPEC.md）。
- 与其他韩国数据 MCP 服务器相比，若需原始 KRX OHLCV 或韩文财务报表表格，其他项目更合适。
基础设施
MCP 服务器为 FastMCP（Python），通过 stdio 在用户机器上运行。Cloud 层包含 Cache Worker（Cloudflare Workers + KV，持有 OpenAI 密钥，前置全局翻译缓存，按许可证检查限流）、Daily Worker（Cron 驱动，KST 工作日 16:30 构建 /today 仪表盘）、Webhook Worker（Cloudflare Worker + D1，处理 Polar 计费事件与 /v1/validate）。复用 agentprod 的 Throttle、Retry、CostTracker。
