korean-stock-search

韩国股票搜索

技能功能

通过向 https://k-skill-proxy.nomadamas.org/v1/korean-stock/... 发送请求，搜索 KRX 上市股票、查看股票基本信息和每日行情。

上游设计参考了 jjlabsio/korea-stock-mcp，但用户无需申请 KRX_API_KEY 或安装本地 MCP 服务器。KRX_API_KEY 仅由代理服务器管理。

使用场景

• “帮我查三星电子的股票代码和市场分类”
• “显示 005930 的基本信息”
• “查询 SK 海力士 20260408 的收盘价和成交量”
• “在 KOSDAQ 上查看 Alteogen 的行情”

不使用场景

• 查询非韩国股票，如美国、日本或加密货币
• 实时成交、盘口、分钟线查询
• 财务报表或公告原文分析（超出本技能范围）
• 投资建议或买入推荐

输入参数

• q：股票名称或代码搜索词（用于 search 端点）
• market：KOSPI | KOSDAQ | KONEX
• code：股票代码（通常为 6 位简码，例如 005930）
• bas_dd：基准日期 YYYYMMDD（默认为韩国时间当天日期，若为非交易日则自动重试最近交易日）
• limit：搜索结果数量（默认 10，最大 20）

前提条件

无。用户无需准备 KRX_API_KEY，上游密钥仅由代理服务器注入。

默认路径

无需额外的客户端 API 层，只需向代理服务器发送 HTTP 请求即可。

如果设置了 KSKILL_PROXY_BASE_URL 环境变量，则使用该值；否则使用默认路径 https://k-skill-proxy.nomadamas.org。

支持的端点

股票搜索

GET /v1/korean-stock/search?q={搜索词}&bas_dd={YYYYMMDD}

股票基本信息

GET /v1/korean-stock/base-info?market={KOSPI|KOSDAQ|KONEX}&code={股票代码}&bas_dd={YYYYMMDD}

股票每日行情

GET /v1/korean-stock/trade-info?market={KOSPI|KOSDAQ|KONEX}&code={股票代码}&bas_dd={YYYYMMDD}

示例请求

股票搜索：

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/search' \
  --data-urlencode 'q=삼성전자' \
  --data-urlencode 'bas_dd=20260408'

股票基本信息：

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/base-info' \
  --data-urlencode 'market=KOSPI' \
  --data-urlencode 'code=005930' \
  --data-urlencode 'bas_dd=20260408'

股票每日行情：

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/trade-info' \
  --data-urlencode 'market=KOSPI' \
  --data-urlencode 'code=005930' \
  --data-urlencode 'bas_dd=20260408'

响应格式

搜索响应

{
  "items": [
    {
      "market": "KOSPI",
      "code": "005930",
      "standard_code": "KR7005930003",
      "name": "삼성전자",
      "short_name": "삼성전자",
      "english_name": "Samsung Electronics",
      "listed_at": "1975-06-11"
    }
  ],
  "query": { "q": "삼성전자", "bas_dd": "20260408", "limit": 10 },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

基本信息响应

{
  "item": {
    "market": "KOSPI",
    "code": "005930",
    "standard_code": "KR7005930003",
    "name": "삼성전자",
    "short_name": "삼성전자",
    "english_name": "Samsung Electronics",
    "security_group": "주권",
    "section_type": "대형주",
    "stock_certificate_type": "보통주",
    "par_value": 100,
    "listed_shares": 5969782550
  },
  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

每日行情响应

{
  "item": {
    "market": "KOSPI",
    "code": "005930",
    "standard_code": "KR7005930003",
    "base_date": "20260408",
    "name": "삼성전자",
    "close_price": 84000,
    "change_price": 1000,
    "fluctuation_rate": 1.2,
    "open_price": 83000,
    "high_price": 84500,
    "low_price": 82800,
    "trading_volume": 12345678,
    "trading_value": 1030000000000,
    "market_cap": 500000000000000
  },
  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

响应策略

• 如果股票名称模糊，先通过 search 缩小市场和股票代码范围，再调用 base-info 或 trade-info。
• 如果部分市场上游失败，返回 upstream.degraded=true 和 failed_markets，并说明部分故障情况。
• trade-info 结果是每日快照，不要描述为实时盘口或成交。
• 如果基准日期为非交易日或收盘前，可能无数据，应重试最近交易日。此时 trade-info 可能返回 not_found 而非 502。
• 数字应以易读单位（韩元、股、亿/兆）简要说明，同时保留原始数值。
• 回答末尾简短注明“基于 KRX 官方数据 / 非投资建议”。

保持回答简洁

• 股票名称 / 市场 / 股票代码
• 基准日期
• 收盘价 / 涨跌幅 / 成交量 / 市值
• 仅在必要时提供上市日期 / 上市股数 / 面值
• 如果出现多个候选，仅显示前 3-5 个，让用户选择

失败模式

• 如果 q、market、code、bas_dd 格式错误，返回 400 响应
• 如果代理服务器缺少 KRX_API_KEY，返回 503 响应
• 如果搜索时部分市场上游失败，仍返回 200 响应，但可能附带 upstream.degraded=true 和 failed_markets
• 如果所有请求市场的上游 KRX 查询均失败，返回 502 响应
• 如果指定基准日期或市场无该股票，返回 404 not_found

完成条件

• 如果搜索词模糊，已通过 search 缩小候选范围
• 必要时已调用 base-info 和 trade-info 整理核心数据
• 确保用户无需 KRX_API_KEY 即可查询
• 已简短注明基于 KRX 官方数据

备注

• 原始参考：https://github.com/jjlabsio/korea-stock-mcp
• 官方数据来源：KRX Open API (https://openapi.krx.co.kr/contents/OPP/MAIN/main/index.cmd)
• 本技能仅用于只读查询。