Skip to main content
Glama
deenesjakoruzh
OldTemple91

koreafilings-mcp

by OldTemple91
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Remote

韩国披露信息 (Korea Filings)

PyPI PyPI MCP License x402

为 AI 智能体、量化基金和研究平台提供机器可读的韩国企业披露信息（DART · 电子公示）英文摘要。通过 Base 链上的 x402 协议按调用次数以 USDC 付费。无需阅读韩文 PDF，即可通过程序化方式获取韩国市场动态。

在线访问: https://koreafilings.com · API 地址 https://api.koreafilings.com · 交互式文档 /swagger-ui。

功能介绍

原始 DART 数据虽然免费，但均为韩文且结构是为人工审核员设计的，而非 LLM。Korea Filings 将每份披露信息转化为结构化、已缓存且带有英文摘要的 JSON 数据包——智能体可以通过名称免费解析韩国公司，然后通过一次付费的 x402 调用获取该股票代码的一批摘要。每份摘要格式如下：

{
  "rcptNo": "20260424900874",
  "summaryEn": "Global SM's stock trading was temporarily suspended on April 24, 2026, due to a change in electronic registration related to a stock consolidation or split.",
  "importanceScore": 10,
  "eventType": "SINGLE_STOCK_TRADING_SUSPENSION",
  "sectorTags": ["Capital Goods"],
  "tickerTags": ["095440"],
  "actionableFor": ["traders", "long_term_investors"],
  "generatedAt": "2026-04-24T08:47:51Z"
}

缓存是核心壁垒——第一个请求某份披露信息的智能体会支付 LLM 成本；后续针对同一 rcpt_no 的智能体将以近乎零成本命中数据库查询，但仍需支付每份摘要 0.005 USDC 的固定费用。按股票代码批量调用会逐行命中同一缓存，因此一次包含五份摘要的调用仅需五次缓存查询，对应一笔 USDC 转账支付。随着采用率的提高，利润率会不断叠加。

Related MCP server: DART 공시 브리핑 MCP 서버

如何使用

选择适合您技术栈的接口。所有三种方式在底层都使用相同的 x402 流程；签署 PAYMENT-SIGNATURE 请求头的钱包即为身份标识。无需 API 密钥，无需注册。

Python SDK

pip install koreafilings
from koreafilings import Client

with Client(private_key="0x...", network="base") as client:
    # 1. Free name → ticker resolution
    matches = client.find_company("Samsung Electronics")
    ticker = matches[0].ticker  # "005930"

    # 2. Paid batch summary fetch (0.005 × limit USDC)
    filings = client.get_recent_filings(ticker, limit=5)
    for f in filings:
        print(f"[{f.importance_score}/10] {f.event_type}: {f.summary_en}")
    print("paid:", client.last_settlement.tx_hash)

MCP 服务器 (Claude Desktop, Cursor, Continue 等)

uv tool install koreafilings-mcp

在您的 MCP 客户端配置中：

{
  "mcpServers": {
    "koreafilings": {
      "command": "uv",
      "args": ["tool", "run", "koreafilings-mcp"],
      "env": {
        "KOREAFILINGS_PRIVATE_KEY": "0x...",
        "KOREAFILINGS_NETWORK": "base"
      }
    }
  }
}

提供五个工具——三个免费用于发现，两个付费：

  • find_company(query) — 免费；通过韩文名称、英文名称或股票代码对 3,961 家韩国交易所上市公司进行三元模糊搜索。

  • list_recent_filings(limit) — 免费；全市场最新的 DART 信息流（仅元数据——让智能体决定为何付费）。

  • get_pricing() — 免费；实时钱包、网络、USDC 合约及各端点价格。

  • get_recent_filings(ticker, limit) — 付费 0.005 × limit USDC；获取单个股票代码的批量 AI 摘要，并附带链上结算交易哈希。

  • get_disclosure_summary(rcpt_no) — 付费 0.005 USDC；获取已知收据编号的单份 AI 摘要。

自然的智能体流程是 find_company → get_recent_filings：一次免费调用将名称解析为股票代码，一次付费调用获取该代码的摘要。

curl / 直接 HTTP

# 1) Resolve a company name to a ticker. Free, no wallet needed.
curl 'https://api.koreafilings.com/v1/companies?q=Samsung+Electronics&limit=1'
#   HTTP/2 200
#   { "matches": [{ "ticker": "005930", "nameKr": "삼성전자",
#                   "nameEn": "SAMSUNG ELECTRONICS CO.,LTD.",
#                   "market": "KOSPI", ... }] }

# 2) Probe the paid endpoint without payment — server tells you the
#    exact USDC amount it wants for `limit=N` summaries.
curl -i 'https://api.koreafilings.com/v1/disclosures/by-ticker?ticker=005930&limit=3'
#   HTTP/2 402
#   payment-required: <base64 PaymentRequired payload, amount = 15000>
#   { "x402Version": 2, "accepts": [{ "scheme": "exact",
#       "amount": "15000", "asset": "USDC", "payTo": "0x8467…",
#       ... }], ... }

# 3) Sign an EIP-3009 TransferWithAuthorization for one of the entries
#    in `accepts`, base64-encode the signed PaymentPayload, and resend
#    with the PAYMENT-SIGNATURE header (x402 v2 transport spec).
#    See testclient/payer.py for a ~150-line reference implementation.
curl -H "PAYMENT-SIGNATURE: $SIGNED" \
     'https://api.koreafilings.com/v1/disclosures/by-ticker?ticker=005930&limit=3'
#   HTTP/2 200
#   payment-response: <base64 SettlementResponse with tx hash>
#   [ { "rcptNo": "...", "summaryEn": "...", "importanceScore": 7, ... },
#     { ... }, { ... } ]

对于已经拥有 14 位收据编号的调用者，固定 0.005 USDC 的 /v1/disclosures/summary?rcptNo=… 端点依然可用——流程与 x402 相同，只需设置 amount = 5000 并发送单份摘要请求体。

定价

按调用次数计费，使用 Base 链上的 USDC。免费端点（/v1/companies、/v1/companies/{ticker}、/v1/disclosures/recent）不包含支付挑战，因此智能体可以在付费前进行浏览。

端点

方法

价格 (USDC)

/v1/disclosures/by-ticker?ticker=…&limit=N

GET

0.005 × N

/v1/disclosures/summary?rcptNo=…

GET

0.005

按股票代码端点的每结果定价在 402 挑战中动态声明——对于 limit=N，服务器将 0.005 × N USDC 签名写入 accepts[0].amount，以便调用者在授权钱包前看到确切费用。固定费率的单份摘要端点保持在 0.005 USDC，适合调用者已从其他地方获得 14 位收据编号的情况。

完整的机器可读定价描述符（当前钱包、网络、USDC 合约、所有付费端点）位于 /v1/pricing；智能体驱动的发现位于 /.well-known/x402。

通过 Coinbase CDP 设施在 Base 主网上运行。首次链上结算永久记录于 0x681c995e… ——付款人钱包通过单次 transferWithAuthorization 调用向商户钱包 0x8467Be164C75824246CFd0fCa8E7F7009fB8f720 转账了 0.005 USDC。

架构

三个逻辑子系统共享一个 Spring Boot 应用程序：

  1. 摄取 (Ingestion) — 调度对 DART Open API 的 30 秒轮询，通过 rcpt_no 去重，将原始元数据持久化到 Postgres，并将摘要任务加入队列。

  2. 摘要 (Summarisation) — 消费摘要任务，分类复杂度，路由至 Gemini 2.5 Flash-Lite（具备 Resilience4j 限流 + 断路器 + 重试机制），将英文摘要 + 股票代码/行业标签 + 审计行持久化到 llm_audit。

  3. 付费 API (Paid API) — 位于 X402PaywallInterceptor 之后的 Spring MVC 控制器。每次请求：读取 PAYMENT-SIGNATURE（或针对 0.2.x 客户端的旧版 X-PAYMENT 别名），通过设施验证签名，检查 Redis 防止重放，在 200 响应时结算，并通过 ResponseBodyAdvice 附加携带链上交易哈希的 PAYMENT-RESPONSE。如果 /settle 抛出异常或拒绝，响应体将被重写为 x402 v2 结算失败格式（HTTP 402，并将失败的 SettlementResponse base64 编码到 PAYMENT-RESPONSE 中，响应体为空），以防止设施中断导致付费数据被免费获取。拦截器对没有 @X402Paywall 的处理方法进行短路处理，因此 /v1/pricing、/.well-known/x402 和 OpenAPI 文档保持无需认证。

402 挑战遵循 x402 v2 传输规范：PAYMENT-REQUIRED 请求头携带 base64 编码的 PaymentRequired 有效载荷（包含用于 AI 智能体可发现性的 bazaar 扩展），同时响应体保留一份 v1 兼容的 JSON 副本，以确保旧客户端正常工作。

技术栈：Java 21, Spring Boot 3.4, PostgreSQL 16, Redis 7, Docker Compose, Cloudflare Tunnel, Cloudflare Workers。更多说明请参阅 docs/ARCHITECTURE.md。

仓库布局

.
├── src/                  # Spring Boot application source
├── sdk/python/           # `koreafilings` Python SDK (PyPI)
├── mcp/                  # `koreafilings-mcp` MCP server (PyPI)
├── landing/              # Marketing landing page (Cloudflare Workers)
├── testclient/           # Reference Python x402 client (testnet payer)
├── docs/
│   ├── ARCHITECTURE.md   # System design
│   ├── PRD.md            # Product requirements
│   ├── ROADMAP.md        # Six-week launch plan
│   └── STATUS.md         # Operator handoff notes
├── Dockerfile            # Multi-stage prod build (eclipse-temurin:21)
├── docker-compose.yml    # postgres + redis + app + cloudflared
└── build.gradle.kts      # Gradle (Kotlin DSL)

本地开发

git clone https://github.com/OldTemple91/korea-filings-api.git
cd korea-filings-api

cp .env.example .env
# Fill in:
#   POSTGRES_PASSWORD     (any strong password)
#   DART_API_KEY          (free, register at https://opendart.fss.or.kr/)
#   GEMINI_API_KEY        (free tier, https://aistudio.google.com/apikey)
#   X402_RECIPIENT_ADDRESS (your receiving wallet — only the address)

docker compose up -d postgres redis
./gradlew bootRun

要在本地实例上执行真实的 x402 支付，请将 testclient/.env.testclient.example 复制到 testclient/.env.testclient，填入钱包私钥（使用存有少量 Base 主网 USDC 的全新一次性钱包是安全做法），然后运行 python testclient/payer.py。若要针对公共测试网设施进行本地开发，请将 X402_FACILITATOR_URL 指向 https://www.x402.org/facilitator 并在 .env 中使用 Base Sepolia 参数。

状态

已在 Base 主网上线并验证链上结算（首次交易）。MVP 功能集：

  • DART 实时摄取（30 秒轮询）

  • Gemini 2.5 Flash-Lite 摘要，具备重要性评分 + 行业/股票代码标签

  • 带有 bazaar 扩展的 x402 v2 支付墙，支持智能体可发现调用

  • 通过 /.well-known/x402 进行发现

  • OpenAPI 3 规范位于 /v3/api-docs + 交互式 Swagger UI

  • PyPI 上的 Python SDK (koreafilings 0.3.1) 和 MCP 服务器 (koreafilings-mcp 0.3.0)

  • 免费名称 → 股票代码解析 (find_company) + 免费最新信息流 (list_recent_filings)，以便智能体在付费前浏览

  • 按结果付费的批量端点 (/v1/disclosures/by-ticker?ticker=…&limit=N)，在 402 中动态声明 0.005 × N USDC

  • 被 x402scan 索引

  • 通过 Cloudflare Tunnel 在 Linux VPS 上生产部署

  • 用于主网结算的 Coinbase CDP 设施（Ed25519 JWT 认证）

当前局限：目前服务生成的每份摘要仅基于披露元数据——标题、日期、申报人、DART 标志。这足以识别事件类型、重要性和股票代码/行业标签（“初步筛选”），但不足以提取具体数字，如配股规模、稀释百分比或合同价值。LLM 会诚实地承认这一点，使用“详细信息在披露正文中”等短语，而不是捏造数字。

后续计划：

  • v1.2 — 深度披露分析。 通过 DART 的 /document.xml ZIP 端点拉取披露正文，解析 XBRL 模板以获取六种最高价值的事件类型（配股、可转债发行、债务发行、收购、已签署供应合同、大股东披露），并将金额、稀释百分比、交易对手和日期提取到结构化的 keyFacts 字段中。新的付费端点 /v1/disclosures/deep?rcptNo=… 将处于更高的价格层级（约 0.020 USDC）——现有端点保持仅元数据且价格为 0.005 USDC，以便调用者在调用时选择深度。路线图详情请参阅 docs/ROADMAP.md。

  • POST /v1/disclosures/filter（行业 + 事件类型查询）

  • SSE /v1/disclosures/stream（实时推送）

  • TypeScript SDK

  • 韩语落地页

  • 结算时的 Slack / 电子邮件提醒

完整计划请参阅 docs/ROADMAP.md。

贡献

欢迎提交 Issue 和 PR——特别是：

  • Python SDK 到其他语言（TypeScript, Go, Rust）的移植

  • 额外的分析端点（价格反应、可比披露信息等）

  • 与非 x402 智能体框架的集成

  • 落地页的翻译

对于重大变更，请先开启一个 Issue 描述方向，以便我们在您构建之前进行可行性评估。

许可证

MIT。

Available Tools

5 tools
find_companyA

Search the KRX directory of Korean listed companies. Free.

Use this as the first step when you have a company name (English
or Korean) but not the six-digit KRX ticker. Pass the resulting
ticker to ``get_recent_filings`` (paid) or ``get_disclosure_summary``
(paid, when you also have a specific receipt number).

Args:
    query: Company name (English or Korean) or six-digit ticker.
        Examples: "Samsung Electronics", "삼성전자", "005930".
    limit: Max matches to return (1-50, default 20).

Returns:
    A list of company dicts with ``ticker``, ``corp_code``,
    ``name_kr``, ``name_en``, and ``market`` (KOSPI / KOSDAQ).
    Empty list when nothing matches; never raises on no-results.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses it is free, returns a list of dicts, and states behavior on no results ('Empty list... never raises'). Does not mention side effects but no issues expected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise with organized sections (intro, usage link, Args, Returns). Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (2 params, no enums, has output schema), description covers purpose, usage, params, return format, and edge case (empty list). No gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description adds examples for query (English, Korean, ticker) and specifies limit range (1-50, default 20), providing crucial context beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches the KRX directory for Korean listed companies, specifies the use case (getting a ticker from a company name), and distinguishes from siblings by mentioning passing to get_recent_filings or get_disclosure_summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this as the first step when you have a company name... but not the six-digit KRX ticker.' and provides follow-up usage, though does not explicitly state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_disclosure_summaryA

Fetch the AI-generated English summary of a Korean DART disclosure.

**This tool spends real USDC from the configured wallet** — 0.005
USDC per call as of v0.1, settled on-chain via x402. The wallet
pays only on a successful 200 response; 4xx/5xx failures do not
settle.

Args:
    rcpt_no: 14-digit DART receipt number, e.g. ``"20260424900874"``.
        You can discover receipt numbers from the DART portal at
        https://dart.fss.or.kr/ or from koreafilings.com's listing
        endpoints as they come online.

Returns:
    A dict with the summary content (``summary_en``), operational
    metadata (``importance_score`` 1–10, ``event_type``,
    ``ticker_tags``, ``sector_tags``, ``actionable_for``,
    ``generated_at``), and payment proof (``paid_tx``, ``network``,
    ``payer``). If the server served from its free-tier path the
    payment block is absent.

Raises:
    RuntimeError: when the SDK rejects the request. The message
        distinguishes payment failures (facilitator rejection,
        network mismatch, insufficient balance) from other API
        errors (404 unknown rcpt_no, 429 rate limit, 5xx upstream).
ParametersJSON Schema
NameRequiredDescriptionDefault
rcpt_noYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses the real USDC cost, settlement conditions, error handling, and return value structure including payment proof. This exceeds expectations for transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections and front-loaded with purpose and cost warning. It is somewhat lengthy but every sentence serves a clear purpose, earning a 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter and an output schema, the description covers input, output structure, errors, cost, and use case. It is complete and leaves no gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter rcpt_no is documented with a 14-digit format, an example, and sources for discovery. Schema description coverage is 0%, but the description compensates fully, adding significant meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches an AI-generated English summary of a Korean DART disclosure. It specifies the resource (disclosure summary) and action (fetch), and is distinct from sibling tools like find_company or get_pricing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use (need a summary), provides cost and failure details, and tells how to discover receipt numbers. It lacks explicit when-not or alternative tools, but the context is sufficiently clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pricingA

Fetch the current per-endpoint pricing for koreafilings.com.

This is a free call; it returns the x402 wallet address, network, USDC contract, and the price in USDC for each paid endpoint. Useful to confirm the payer will be settling on the expected chain before spending anything.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the call is free and returns specific fields (x402 wallet address, network, USDC contract, price in USDC). This gives good behavioral context, though it doesn't mention authentication or rate limits, which are likely unnecessary for a free, parameterless call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words. First sentence states purpose, second details output, third gives usage guidance. It is appropriately sized and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and the existence of an output schema (though not shown), the description mentions what the call returns and explains when to use it. It covers the necessary context for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%, so baseline is 4. The description adds no extra parameter info because none exist, but that's appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool fetches current per-endpoint pricing for koreafilings.com. The verb 'Fetch' and resource 'current per-endpoint pricing' are specific. Sibling tools are about filings and disclosures, so this tool is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description explicitly notes it's a free call and useful for confirming the payer will settle on the expected chain before spending. This implies when to use it, though it doesn't provide explicit exclusions or alternatives. Nevertheless, the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recent_filingsA

Fetch up to limit AI summaries for one Korean ticker.

**This tool spends real USDC from the configured wallet** — 0.005
USDC × ``limit`` per call (default 0.025 USDC). The wallet pays
only on a successful 200 response; 4xx/5xx failures do not settle.

If you only have a company name, call ``find_company`` first to
resolve the ticker.

Args:
    ticker: Six-digit KRX ticker, e.g. "005930" for Samsung Electronics.
    limit: Max filings to fetch (1-50, default 5). Each costs 0.005 USDC.

Returns:
    A dict with ``ticker``, ``count``, ``summaries`` (each summary
    carries the same shape as ``get_disclosure_summary``), and a
    ``payment`` block with the on-chain settlement tx hash.

Raises:
    RuntimeError: on payment rejection or API failure.
ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the burden, disclosing real USDC cost (0.005 per filing), payment on success only, return structure including payment tx hash, and RuntimeError on failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence is purposeful: purpose, cost warning, usage hint, parameter descriptions, return shape, error handling. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (paid API with cost, two parameters, custom return), the description covers behavior, cost, error handling, and return shape comprehensively, despite no annotations or rich output schema in prompt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description adds crucial details: ticker format with example, limit range (1-50) and default, and cost per unit, far exceeding schema's plain type info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Fetch' and resource 'AI summaries for one Korean ticker', distinguishing it from siblings like find_company (resolves name to ticker) and list_recent_filings (likely just lists without costs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to call find_company if only a company name is available, providing an alternative. No explicit when-not, but the cost implication implicitly guides against overuse.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_recent_filingsA

Browse recent DART filings across every listed Korean company. Free.

Returns metadata only — no AI summaries — so an agent can decide
which filings warrant a paid call. Each entry includes ``rcpt_no``
(for ``get_disclosure_summary``) and ``ticker`` (for
``get_recent_filings``).

Args:
    limit: Max filings to return (1-100, default 20).
    since_hours: Look back this many hours (1-168, default 24).

Returns:
    A list of filing-metadata dicts.
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
since_hoursNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states 'Returns metadata only' implying read-only behavior and mentions 'Free', but it does not explicitly confirm safety, idempotency, or authentication requirements. The description is mostly adequate but lacks explicit transparency on side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (6 sentences), well-structured with clear sections (purpose, return type, args, returns), and front-loads the primary purpose. Every sentence earns its place, with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 optional parameters) and the presence of an output schema, the description is adequately complete. It covers metadata-only return and cross-references other tools, providing sufficient context for an agent to use this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description fully documents both parameters (limit and since_hours) with ranges and defaults, compensating for 0% schema description coverage. This adds meaning beyond the bare input schema, enabling precise agent decisions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool browses recent DART filings for Korean companies and returns metadata only. However, it does not differentiate itself from the sibling tool 'get_recent_filings', which has a similar name and purpose, creating potential ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description hints at a usage flow by referencing get_disclosure_summary for paid calls, but it does not explicitly state when to use this tool versus alternatives like get_recent_filings. It provides some context without clear when-to-use or when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.1
    • Addedfind_company
    • Addedget_recent_filings
    • Addedlist_recent_filings
  2. 2 tool updatesv0.1.0
    • First observedget_disclosure_summary
    • First observedget_pricing
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 5 tools

Disambiguation4/5

Each tool has a broadly distinct role: pricing lookup, company search, free filing metadata browsing, paid ticker-based summaries, and paid receipt-based summary retrieval. The main confusion risk is between list_recent_filings and get_recent_filings, whose names are very similar though their descriptions clearly separate free metadata browsing from paid AI summary generation.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern: get_pricing, find_company, list_recent_filings, get_recent_filings, get_disclosure_summary. The verbs are standard retrieval actions and the naming is uniform and predictable.

Tool Count5/5

Five tools is well-scoped for this server: pricing discovery, company resolution, free filing browsing, and two paid summary-fetching operations. Each tool earns its place and the server avoids unnecessary bloat.

Completeness4/5

The core workflow is covered: resolve a company with find_company, browse recent filings for free with list_recent_filings, then fetch paid AI summaries by ticker or receipt number. Minor gaps exist such as no historical filing lookup beyond recent limits and no raw disclosure document access, but these do not break the primary use case.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • kr-crypto-intelligence

    bakyang2
    A
    license
    A
    quality
    C
    maintenance
    Korean crypto market data API for AI agents. Real-time Kimchi Premium (Upbit vs Binance), Korean exchange prices, USD/KRW FX rate. First verified Korean market data MCP server. Pay-per-use via x402 on Base.
    17
    2
    MIT

  • Disclosure Compass

    MLOpsEngineer
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that exposes seven read-only tools for querying Korean public company disclosures from the OpenDART system, returning normalized JSON.
    MIT

  • OpenDart MCP Server

    sayouzone
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that retrieves Korean stock fundamentals and financial data from OpenDART, enabling LLMs to access corporate disclosures, financial statements, and dividend information.
    Apache 2.0