de en es ja ko ru zh

koreafilings-mcp

Name: koreafilings-mcp
Author: OldTemple91

by OldTemple91

Overview Schema Source Related Servers Discussions Admin

Remote

Korea Filings

PyPI PyPI MCP License x402

Maschinenlesbare englische Zusammenfassungen koreanischer Unternehmensmitteilungen (DART · 전자공시), bezahlt pro Abruf in USDC über das x402-Protokoll auf Base. Entwickelt für KI-Agenten, Quant-Fonds und Forschungsplattformen, die programmatischen Zugriff auf koreanische Marktereignisse benötigen, ohne koreanische PDFs lesen zu müssen.

Live: https://koreafilings.com · API unter https://api.koreafilings.com · interaktive Dokumentation unter /swagger-ui.

Was es tut

Rohdaten von DART sind kostenlos, aber sie sind auf Koreanisch und für menschliche Sachbearbeiter strukturiert, nicht für LLMs. Korea Filings verwandelt jede Mitteilung in eine strukturierte, zwischengespeicherte, englisch zusammengefasste JSON-Nutzlast – Agenten lösen ein koreanisches Unternehmen kostenlos nach Namen auf und rufen dann eine Reihe von Zusammenfassungen für diesen Ticker in einem bezahlten x402-Aufruf ab. Jede Zusammenfassung sieht so aus:

{
  "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"
}

Der Cache ist der Burggraben – der erste Agent, der eine Mitteilung anfordert, zahlt die LLM-Kosten; jeder nachfolgende Agent für dieselbe rcpt_no greift auf eine nahezu kostenlose DB-Abfrage zu und zahlt dennoch die gleiche Pauschale von 0,005 USDC pro Zusammenfassung. Ticker-basierte Batch-Aufrufe treffen den gleichen Cache Zeile für Zeile, sodass ein Aufruf mit fünf Zusammenfassungen fünf Cache-Abfragen gegen eine einzige übertragene USDC-Zahlung bedeutet. Die Margen steigen mit zunehmender Akzeptanz.

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

Verwendung

Wählen Sie die Oberfläche, die zu Ihrem Stack passt. Alle drei verwenden im Hintergrund denselben x402-Ablauf; die Wallet, die den PAYMENT-SIGNATURE-Header signiert, ist die Identität. Keine API-Schlüssel. Keine Registrierung.

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-Server (Claude Desktop, Cursor, Continue, …)

uv tool install koreafilings-mcp

In der Konfiguration Ihres MCP-Clients:

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

Fünf Tools werden verfügbar – drei kostenlos für die Erkennung, zwei kostenpflichtig:

find_company(query) — kostenlos; Trigramm-Fuzzy-Suche von 3.961 KRX-notierten Unternehmen nach koreanischem Namen, englischem Namen oder Ticker.
list_recent_filings(limit) — kostenlos; marktweiter aktueller DART-Feed (nur Metadaten – lassen Sie den Agenten entscheiden, wofür er bezahlen möchte).
get_pricing() — kostenlos; Live-Wallet, Netzwerk, USDC-Vertrag, Preis pro Endpunkt.
get_recent_filings(ticker, limit) — kostenpflichtig 0,005 × Limit USDC; Batch-KI-Zusammenfassungen für einen Ticker, mit dem On-Chain-Settlement-Transaktions-Hash.
get_disclosure_summary(rcpt_no) — kostenpflichtig 0,005 USDC; einzelne KI-Zusammenfassung für eine bekannte Belegnummer.

Der natürliche Agenten-Ablauf ist find_company → get_recent_filings: ein kostenloser Aufruf, um einen Namen in einen Ticker aufzulösen, ein bezahlter Aufruf, um Zusammenfassungen für diesen Ticker abzurufen.

curl / direktes 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, ... },
#     { ... }, { ... } ]

Der Pauschal-Endpunkt /v1/disclosures/summary?rcptNo=… für 0,005 USDC ist weiterhin für Aufrufer verfügbar, die bereits eine 14-stellige Belegnummer haben – derselbe x402-Ablauf, nur amount = 5000 und ein Body mit einer einzelnen Zusammenfassung.

Preisgestaltung

Pro Aufruf, in USDC auf Base. Kostenlose Endpunkte (/v1/companies, /v1/companies/{ticker}, /v1/disclosures/recent) enthalten keine Zahlungsaufforderung, sodass ein Agent stöbern kann, bevor er bezahlt.

Endpunkt	Methode	Preis (USDC)
`/v1/disclosures/by-ticker?ticker=…&limit=N`	GET	0,005 × N
`/v1/disclosures/summary?rcptNo=…`	GET	0,005

Die Preisgestaltung pro Ergebnis für den By-Ticker-Endpunkt wird dynamisch in der 402-Challenge deklariert – für limit=N signiert der Server 0,005 × N USDC in accepts[0].amount, sodass der Aufrufer die genaue Gebühr sieht, bevor er die Wallet autorisiert. Der Pauschal-Endpunkt für einzelne Zusammenfassungen bleibt bei 0,005 USDC und ist die richtige Form, wenn ein Aufrufer bereits eine 14-stellige Belegnummer von woanders hat.

Der vollständige maschinenlesbare Preisdeskriptor (aktuelle Wallet, Netzwerk, USDC-Vertrag, jeder kostenpflichtige Endpunkt) befindet sich unter /v1/pricing; agentengesteuerte Erkennung ist unter /.well-known/x402 zu finden.

Live auf Base Mainnet über den Coinbase CDP-Vermittler. Das erste On-Chain-Settlement ist permanent unter 0x681c995e… – eine Zahler-Wallet hat 0,005 USDC an die Händler-Wallet 0x8467Be164C75824246CFd0fCa8E7F7009fB8f720 in einem einzigen transferWithAuthorization-Aufruf übertragen.

Architektur

Drei logische Subsysteme teilen sich eine Spring Boot-Anwendung:

Ingestion — plant einen 30-sekündigen Abruf der DART Open API, dedupliziert nach rcpt_no, speichert Rohmetadaten in Postgres und stellt einen Zusammenfassungsauftrag in die Warteschlange.
Summarisation — verarbeitet Zusammenfassungsaufträge, klassifiziert die Komplexität, leitet an Gemini 2.5 Flash-Lite weiter (mit Resilience4j Rate-Limiting + Circuit-Breaking + Retries), speichert englische Zusammenfassung + Ticker / Sektor-Tags + Audit-Zeile in llm_audit.
Paid API — Spring MVC-Controller hinter einem X402PaywallInterceptor. Jede Anfrage: PAYMENT-SIGNATURE lesen (oder den Legacy-Alias X-PAYMENT für 0.2.x-Clients), die Signatur mit dem Vermittler verifizieren, Redis auf Replay prüfen, bei einer 200er-Antwort abrechnen und PAYMENT-RESPONSE mit dem On-Chain-Transaktions-Hash über einen ResponseBodyAdvice anhängen. Wenn /settle einen Fehler wirft oder ablehnt, wird der Body in die x402 v2 Settle-Failure-Form umgeschrieben (HTTP 402 mit der fehlgeschlagenen SettlementResponse base64-kodiert in PAYMENT-RESPONSE und einem leeren Body), sodass ein Ausfall des Vermittlers keine bezahlten Daten unbezahlt preisgeben kann. Der Interceptor schaltet sich für Handler-Methoden ohne @X402Paywall kurz, sodass /v1/pricing, /.well-known/x402 und das OpenAPI-Dokument unauthentifiziert bleiben.

Die 402-Challenge folgt der x402 v2 Transport-Spezifikation: der PAYMENT-REQUIRED-Header trägt die base64-kodierte PaymentRequired-Nutzlast (mit der bazaar Erweiterung, die ein Eingabe-/Ausgabeschema für die Auffindbarkeit durch KI-Agenten deklariert), während der Body eine v1-kompatible JSON-Kopie behält, damit ältere Clients weiterhin funktionieren.

Stack: Java 21, Spring Boot 3.4, PostgreSQL 16, Redis 7, Docker Compose, Cloudflare Tunnel, Cloudflare Workers. Siehe docs/ARCHITECTURE.md für tiefere Notizen.

Repository-Layout

.
├── 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)

Lokale Entwicklung

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

Um eine echte x402-Zahlung gegen eine lokale Instanz auszuführen, kopieren Sie testclient/.env.testclient.example nach testclient/.env.testclient, tragen Sie den privaten Schlüssel einer Wallet ein (eine frische Burner-Wallet, die mit ein oder zwei Dollar Base Mainnet USDC finanziert ist, ist das sichere Muster) und führen Sie python testclient/payer.py aus. Für die lokale Entwicklung gegen den öffentlichen Testnet-Vermittler, zeigen Sie mit X402_FACILITATOR_URL auf https://www.x402.org/facilitator und verwenden Sie Base Sepolia-Parameter in Ihrer .env.

Status

Live auf Base Mainnet mit verifiziertem On-Chain-Settlement (erste Transaktion). MVP-Funktionsumfang:

DART Echtzeit-Ingestion (30-Sekunden-Abruf)
Gemini 2.5 Flash-Lite Zusammenfassung mit Wichtigkeitsbewertung + Sektor / Ticker-Tagging
x402 v2 Paywall mit bazaar-Erweiterung für agenten-auffindbaren Aufruf
Erkennung über /.well-known/x402
OpenAPI 3 Spezifikation unter /v3/api-docs + interaktive Swagger UI
Python SDK (koreafilings 0.3.1) und MCP-Server (koreafilings-mcp 0.3.0) auf PyPI
Kostenlose Namens → Ticker-Auflösung (find_company) + kostenloser aktueller Feed (list_recent_filings), damit Agenten vor der Zahlung stöbern können
Kostenpflichtiger Batch-Endpunkt pro Ergebnis (/v1/disclosures/by-ticker?ticker=…&limit=N) mit 0,005 × N USDC, dynamisch deklariert in der 402
Indexiert durch x402scan
Produktionseinsatz auf einem Linux VPS über Cloudflare Tunnel
Coinbase CDP-Vermittler (Ed25519 JWT-Auth) für Mainnet-Settlement

Aktuelle Einschränkung: Jede Zusammenfassung, die der Dienst heute erstellt, wird ausschließlich aus den Metadaten der Mitteilung generiert – Titel, Datum, Einreicher, DART-Flag. Das reicht aus, um Ereignistyp, Wichtigkeit und Ticker / Sektor-Tags zu erfassen („First-Pass-Screening“), aber nicht, um konkrete Zahlen wie die Größe des Bezugsrechtsangebots, Verwässerung in % oder Vertragswert zu extrahieren. Das LLM gibt dies ehrlich mit Phrasen wie „Details befinden sich im Text der Mitteilung“ zu, anstatt Zahlen zu erfinden.

Demnächst:

v1.2 — tiefe Analyse der Mitteilungen. Abruf des Mitteilungstextes über DARTs /document.xml ZIP-Endpunkt, Parsen der XBRL-Vorlagen für die sechs wertvollsten Ereignistypen (RIGHTS_OFFERING, CONVERTIBLE_BOND_ISSUANCE, DEBT_ISSUANCE, ACQUISITION, SUPPLY_CONTRACT_SIGNED, MAJOR_SHAREHOLDER_FILING) und Extraktion von Beträgen, Verwässerung in %, Gegenpartei und Daten in ein strukturiertes keyFacts-Feld. Neuer kostenpflichtiger Endpunkt /v1/disclosures/deep?rcptNo=… zu einer höheren Preisstufe (~0,020 USDC) – bestehende Endpunkte bleiben bei 0,005 USDC nur für Metadaten, sodass Aufrufer die Tiefe zum Zeitpunkt des Aufrufs wählen können. Roadmap-Details unter docs/ROADMAP.md.
POST /v1/disclosures/filter (Sektor + Ereignistyp-Abfrage)
SSE /v1/disclosures/stream (Echtzeit-Push)
TypeScript SDK
Koreanischsprachige Landingpage
Slack / E-Mail-Benachrichtigungen bei Settlement

Siehe docs/ROADMAP.md für den vollständigen Plan.

Mitwirken

Probleme und PRs sind willkommen – insbesondere:

Ports des Python SDK in andere Sprachen (TypeScript, Go, Rust)
Zusätzliche Analyse-Endpunkte (Preisreaktion, vergleichbare Mitteilungen, …)
Integrationen mit Nicht-x402-Agenten-Frameworks
Übersetzung der Landingpage in andere Sprachen

Für wesentliche Änderungen eröffnen Sie bitte zuerst ein Issue, in dem Sie die Richtung beschreiben, damit wir die Eignung prüfen können, bevor Sie bauen.

Lizenz

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

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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

Name	Required	Description	Default
`rcpt_no`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
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

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
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

Name	Required	Description	Default
`ticker`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
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

Name	Required	Description	Default
`limit`	No
`since_hours`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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.

3 tool updatesv0.1.1Apr 29, 2026
- Addedfind_company
- Addedget_recent_filings
- Addedlist_recent_filings
2 tool updatesv0.1.0Apr 28, 2026
- 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 2026-09-09 18:52 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

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Concierge Intel C
xyz.conc-exe
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Finance Blockchain
2
Inferventis — Financial Data, News & Web MCP A
io.github.jonathanpchapman
Live financial data MCP: FX, crypto, stocks, news, URL reader. x402 on Base: $0.001/call.
Finance Cryptocurrency Payments & Billing
202
1gateway
io.github.code0xff
x402 pay-per-call API gateway for AI agents (USDC on Base): Korean real estate, weather, holidays.
141
FinBridge AOAuth
kr.gronox.mcp
FinBridge is a hosted MCP server for Korean company disclosures, read in English. DART filings and normalized financial statements, business segments, insider reports and 13F holdings, with US, Japanese and European filers on the same schema for comparison. Search a company by its registered English name or its Korean name. Every answer names the filing, the receipt number and the date. Korean price delivery is planned and not currently served. Docs: https://www.gronox.kr/docs
Finance Open Data
1

Related MCP Servers

kr-crypto-intelligence
Cryptocurrency Finance Search
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.
Updated 2 months ago (2026-08-04 05:58 UTC)
17
2
MIT
DART 공시 브리핑 MCP 서버
Finance Government Data Search
iiacjay
F
license
Not graded
quality
D
maintenance
MCP server that searches and filters DART electronic disclosures for Korean companies, enabling AI agents to create investor briefing summaries.
Updated 3 months ago (2026-07-14 16:20 UTC)
-
Disclosure Compass
Finance Open Data Government Data
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.
Updated 3 months ago (2026-07-19 13:07 UTC)
MIT
OpenDart MCP Server
Finance Open Data
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.
Updated 8 months ago (2026-02-06 00:50 UTC)
Apache 2.0