Skip to main content
Glama
deenesjakoruzh
OldTemple91

koreafilings-mcp

by OldTemple91
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Remote

Korea Filings

PyPI PyPI MCP License x402

韓国の企業開示情報（DART · 電子開示システム）の機械可読な英語要約を提供します。Base上のx402プロトコルを通じて、コールごとにUSDCで支払います。韓国語のPDFを読み込むことなく、韓国市場のイベントにプログラムからアクセスする必要があるAIエージェント、クオンツファンド、リサーチプラットフォーム向けに構築されています。

ライブ: https://koreafilings.com · API: https://api.koreafilings.com · インタラクティブドキュメント: /swagger-ui

機能

生のDARTデータは無料ですが、韓国語で書かれており、LLMではなく人間の開示担当者向けに構造化されています。Korea Filingsは、すべての開示情報を構造化され、キャッシュされた、英語で要約されたJSONペイロードに変換します。エージェントは韓国企業名を無料で解決し、そのティッカーの要約バッチを1回の有料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 に対する後続のエージェントは、ほぼゼロコストのDBルックアップで、同じ1要約あたり0.005 USDCの定額を支払います。ティッカーごとのバッチコールはキャッシュの行ごとにヒットするため、5つの要約のコールは、1回のUSDC送金に対して5つのキャッシュルックアップとなります。採用が進むにつれて利益率が向上します。

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

利用方法

スタックに合ったインターフェースを選択してください。3つすべてが内部で同じ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"
      }
    }
  }
}

5つのツールが利用可能になり、3つは発見用として無料、2つは有料です：

  • find_company(query) — 無料; 韓国名、英語名、またはティッカーによるKRX上場企業3,961社のトライグラムあいまい検索。

  • list_recent_filings(limit) — 無料; 市場全体の最新DARTフィード（メタデータのみ — 何に支払うかはエージェントが決定）。

  • get_pricing() — 無料; ライブウォレット、ネットワーク、USDCコントラクト、エンドポイントごとの価格。

  • get_recent_filings(ticker, limit) — 有料 0.005 × limit USDC; 1つのティッカーに対するAI要約のバッチ取得（オンチェーン決済トランザクションハッシュ付き）。

  • get_disclosure_summary(rcpt_no) — 有料 0.005 USDC; 既知の受付番号に対する単一のAI要約。

自然なエージェントフローは find_company → get_recent_filings です。名前をティッカーに解決する無料コールを1回行い、そのティッカーの要約を取得する有料コールを1回行います。

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 の場合、サーバーは accepts[0].amount に 0.005 × N USDCを署名するため、呼び出し元はウォレットを承認する前に正確な料金を確認できます。定額の単一要約エンドポイントは0.005 USDCのままであり、呼び出し元が他の場所から14桁の受付番号をすでに持っている場合に適しています。

機械可読な完全な価格記述子（現在のウォレット、ネットワーク、USDCコントラクト、すべての有料エンドポイント）は /v1/pricing にあり、エージェント主導の発見は /.well-known/x402 にあります。

Coinbase CDPファシリテーターを介して Baseメインネット で稼働中です。最初のオンチェーン決済は 0x681c995e… で永続化されています。これは、1回の transferWithAuthorization コールで、支払いウォレットからマーチャントウォレット 0x8467Be164C75824246CFd0fCa8E7F7009fB8f720 に0.005 USDCが送金されたものです。

アーキテクチャ

3つの論理サブシステムが1つのSpring Bootアプリケーションを共有しています：

  1. Ingestion — DART Open APIに対する30秒ごとのポーリングをスケジュールし、rcpt_no で重複排除を行い、生のメタデータをPostgresに永続化し、要約ジョブをエンキューします。

  2. Summarisation — 要約ジョブを消費し、複雑さを分類し、Gemini 2.5 Flash-Lite（Resilience4jのレート制限 + サーキットブレーカー + リトライ機能付き）にルーティングし、英語の要約 + ティッカー/セクタータグ + 監査行を llm_audit に永続化します。

  3. Paid API — X402PaywallInterceptor の背後にあるSpring MVCコントローラー。すべてのリクエストに対して：PAYMENT-SIGNATURE（または0.2.xクライアント用のレガシーな X-PAYMENT エイリアス）を読み取り、ファシリテーターで署名を検証し、Redisでリプレイをチェックし、200レスポンスで決済し、ResponseBodyAdvice を介してオンチェーンtxハッシュを運ぶ 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を1〜2ドル分入金した新しいバーナーウォレットが安全なパターンです）を入力し、python testclient/payer.py を実行します。パブリックテストネットファシリテーターに対してローカル開発を行う場合は、X402_FACILITATOR_URL を https://www.x402.org/facilitator に向け、.env でBase Sepoliaパラメーターを使用してください。

ステータス

検証済みのオンチェーン決済 (最初のtx) を伴い、Baseメインネット で稼働中です。MVP機能セット：

  • DARTリアルタイム取り込み（30秒ポーリング）

  • 重要度スコアリング + セクター/ティッカータグ付けを備えたGemini 2.5 Flash-Lite要約

  • エージェントが発見可能な呼び出しのための bazaar 拡張機能付きx402 v2ペイウォール

  • /.well-known/x402 を介した発見

  • /v3/api-docs でのOpenAPI 3仕様 + インタラクティブなSwagger UI

  • PyPI上のPython SDK (koreafilings 0.3.1) およびMCPサーバー (koreafilings-mcp 0.3.0)

  • 無料の名前 → ティッカー解決 (find_company) + 無料の最新フィード (list_recent_filings) により、エージェントは支払う前にブラウズ可能

  • 402で動的に宣言される0.005 × N USDCの、結果ごとの有料バッチエンドポイント (/v1/disclosures/by-ticker?ticker=…&limit=N)

  • x402scan によるインデックス

  • Cloudflare Tunnelを介したLinux VPSへの本番デプロイ

  • メインネット決済のためのCoinbase CDPファシリテーター（Ed25519 JWT認証）

現在の制限：現在サービスが生成するすべての要約は、タイトル、日付、提出者、DARTフラグなどの開示メタデータのみから生成されています。これはイベントタイプ、重要度、ティッカー/セクタータグ（「一次スクリーニング」）を表面化するには十分ですが、新株予約権付社債の規模、希薄化率、契約額などの具体的な数値を抽出するには不十分です。LLMは数値を捏造するのではなく、「詳細は開示本文にあります」といったフレーズでこれを正直に認めます。

今後の予定：

  • v1.2 — 詳細な開示分析。 DARTの /document.xml ZIPエンドポイントを介して開示本文を取得し、6つの最高価値イベントタイプ（RIGHTS_OFFERING, CONVERTIBLE_BOND_ISSUANCE, DEBT_ISSUANCE, ACQUISITION, SUPPLY_CONTRACT_SIGNED, MAJOR_SHAREHOLDER_FILING）の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
    C
    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