list_recent_filings
Retrieve recent DART filings from Korean companies to identify which disclosures worth paying for. Returns metadata including rcpt_no and ticker, enabling informed decisions on paid summary calls.
Instructions
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.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since_hours | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- MCP tool handler for 'list_recent_filings'. Decorated with @mcp.tool(), it creates a temporary Client (with a dummy private key), calls probe.list_recent_filings(), and maps the result to a list of dicts with rcpt_no, ticker, corp_name, report_nm, rcept_dt, dart_url.
@mcp.tool() def list_recent_filings(limit: int = 20, since_hours: int = 24) -> list[dict[str, Any]]: """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. """ network = os.environ.get("KOREAFILINGS_NETWORK", "base-sepolia").strip() or "base-sepolia" base_url = os.environ.get("KOREAFILINGS_BASE_URL", "https://api.koreafilings.com").strip() probe = Client(private_key="0x" + "00" * 32, network=network, base_url=base_url) try: filings = probe.list_recent_filings(limit=limit, since_hours=since_hours) finally: probe.close() return [ { "rcpt_no": f.rcpt_no, "ticker": f.ticker, "corp_name": f.corp_name, "report_nm": f.report_nm, "rcept_dt": f.rcept_dt.isoformat(), "dart_url": f"https://dart.fss.or.kr/dsaf001/main.do?rcpNo={f.rcpt_no}", } for f in filings ] - mcp/src/koreafilings_mcp/server.py:134-134 (registration)Registration of the 'list_recent_filings' tool via the @mcp.tool() decorator on line 134 in the FastMCP server instance.
@mcp.tool() - SDK Client.list_recent_filings method — makes an HTTP GET to /v1/disclosures/recent with limit/since_hours params, returns List[RecentFiling] parsed from the response JSON.
def list_recent_filings( self, limit: int = 20, since_hours: int = 24, ) -> List[RecentFiling]: """Browse recent DART filings across every listed company. Free. Returns metadata only — no AI summaries. Use this to discover what is happening today, then call :meth:`get_recent_filings` or :meth:`get_summary` to pay for the summaries you actually want. """ resp = self._http.get( f"{self._base_url}/v1/disclosures/recent", params={ "limit": min(max(limit, 1), 100), "since_hours": min(max(since_hours, 1), 168), }, ) if resp.status_code != 200: raise ApiError(resp.status_code, _safe_json(resp)) body = resp.json() or {} return [RecentFiling.model_validate(f) for f in body.get("filings", [])] - RecentFiling Pydantic model — defines the schema for each filing returned by list_recent_filings, including rcpt_no (alias rcptNo), ticker, corp_name, report_nm, rcept_dt.
class RecentFiling(BaseModel): """Lightweight metadata for a recent DART filing — no AI summary. Returned by the free :meth:`Client.list_recent_filings`. Use the ``rcpt_no`` to fetch a single summary via :meth:`Client.get_summary`, or the ``ticker`` to fetch a batch via :meth:`Client.get_recent_filings`. """ model_config = ConfigDict(populate_by_name=True, frozen=True) rcpt_no: str = Field(alias="rcptNo") ticker: Optional[str] = None corp_name: str = Field(alias="corpName") report_nm: str = Field(alias="reportNm") rcept_dt: date = Field(alias="rceptDt")