Disclosure Compass (공시나침반)

A focused Model Context Protocol server for public company disclosures from OpenDART (전자공시시스템 DART). Disclosure Compass (공시나침반) exposes one public Streamable HTTP MCP gateway with 10 read-only tools. Its routing tools select one of 16 internal specialist servers and execute any of their 82 read-only OpenDART tools. This keeps the PlayMCP-visible tools/list below the 20-tool limit while preserving the full 82-tool execution surface, without LLM, vector-search, or A2A runtime dependencies.

This project is independent open-source software and is not an official OpenDART product.

For the complete 16-domain/82-tool catalog, router contract, and Korean PlayMCP deployment runbook, see 구현·배포 운영 기록 and 카카오 PlayMCP 운영·갱신 핸드북.

Tools

Public gateway tools (10)

Internal specialist tools (82 across 16 specialist servers)

Every original dart_* tool belongs to exactly one internal specialist server. The public route_and_call_disclosure tool classifies a Korean request, selects that server and tool, then executes it. Callers that know the exact target can use call_disclosure_server_tool. The 16 domain IDs and full per-domain catalog are in the implementation record.

Specialist tools take one arguments object. Its accepted fields depend on the endpoint and include corp_code or corp_name, business_year, report_code, begin_date, end_date, corp_codes, receipt_number, fs_division, statement_type, index_code, and max_items. For example:

{
  "arguments": {
    "corp_code": "00126380",
    "begin_date": "20250101",
    "end_date": "20251231",
    "max_items": 10
  }
}

All tools are declared read-only, non-destructive, idempotent, and open-world. Every specialist result is capped at 50 rows. Binary filing and XBRL tools return bounded ZIP metadata rather than raw file contents. Upstream calls use strict connect/read timeouts and reject JSON responses larger than 2 MB or binary responses larger than 8 MB.

Related MCP server: opendart-fss-mcp

Disclosure request classification

classify_disclosure_request maps a non-empty Korean natural-language request of up to 500 characters to the most relevant OpenDART disclosure domains. top_k defaults to 3 and may be set from 1 through 16. The response contains the original query, total_categories, and score-ranked routes. Each route contains:

• category: the stable domain ID

• label_ko: the Korean domain label

• score: the normalized relevance score

• matched_terms: terms from the request that contributed to the route

• supported_tools: data tools currently exposed by this server for the domain

• specialist_tools: original tool names available on that domain's MCP server

This classifier performs deterministic term matching and does not itself call OpenDART. Use route_and_call_disclosure to classify and execute in one request, or use call_disclosure_server_tool for deterministic server/tool selection. The 16 specialist servers are real FastMCP instances in one deployable ASGI process. The public PlayMCP contract is the single /mcp gateway; specialist paths exist for diagnostics and compatibility but must not be registered as additional PlayMCP MCPs.

The classifier recognizes exactly these 16 domains:

Example request:

{
  "query": "연결 재무제표 매출액",
  "top_k": 1
}

Example response:

{
  "query": "연결 재무제표 매출액",
  "routes": [
    {
      "category": "financial_statement",
      "label_ko": "재무정보",
      "score": 1.0,
      "matched_terms": ["연결 재무제표", "재무제표", "매출액"],
      "supported_tools": ["get_financial_statement"],
      "specialist_tools": [
        "dart_fnlttSinglAcnt",
        "dart_fnlttMultiAcnt",
        "dart_fnlttXbrl",
        "dart_fnlttSinglAcntAll",
        "dart_xbrlTaxonomy",
        "dart_fnlttSinglIndx",
        "dart_fnlttCmpnyIndx"
      ]
    }
  ],
  "total_categories": 16
}

To execute a routed request directly, pass a company identifier and any period-specific fields to route_and_call_disclosure:

{
  "query": "삼성전자 전환사채 발행 결정을 찾아줘",
  "corp_code": "00126380",
  "begin_date": "20250101",
  "end_date": "20251231"
}

This selects the convertible_securities server and its dart_cvbdIsDecsn tool. Callers that already know the exact target can instead use call_disclosure_server_tool with server_id, tool_name, and an arguments object. Accepted fields depend on the endpoint and include corp_code or corp_name, business_year, report_code, begin_date, end_date, corp_codes, receipt_number, fs_division, statement_type, index_code, and max_items.

Requirements

• Python 3.11-3.13

• An OpenDART API key from https://opendart.fss.or.kr/

Run locally

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
export DART_API_KEY='your-runtime-secret'
opendart-mcp

The public gateway endpoint is http://localhost:8000/mcp and the health endpoint is http://localhost:8000/health. Specialist endpoints are available at http://localhost:8000/specialists/<domain-id>/mcp for diagnostics only. Set PORT to override port 8000.

The corp_code arguments are OpenDART eight-digit company identifiers, not six-digit stock codes. For example, OpenDART's public guide uses 00126380 for Samsung Electronics.

Docker / PlayMCP deployment

The image is compatible with Linux AMD64 and runs as a non-root user.

docker build --platform linux/amd64 -t opendart-mcp .
docker run --rm -p 8000:8000 \
  -e DART_API_KEY='your-runtime-secret' \
  opendart-mcp

Configure the deployment secret as DART_API_KEY; never bake it into the image or commit it. The server uses stateless HTTP so it does not require session affinity. In PlayMCP, register exactly one URL: /mcp. Its 10 visible tools are within the 20-tool limit; route_and_call_disclosure and call_disclosure_server_tool expose the 82 internal capabilities at execution time. Do not register /specialists/<domain-id>/mcp paths in PlayMCP.

If an approved gateway already owns the OpenDART secret, a temporary public edge deployment may set OPENDART_UPSTREAM_GATEWAY_URL to that gateway's MCP URL instead of copying DART_API_KEY. All public gateway helpers and router calls then use its call_disclosure_server_tool contract. Do not point this variable back to the same edge endpoint; direct OpenDART mode with DART_API_KEY is the long-term deployment mode.

Development checks

ruff check .
pytest -q
python -m compileall -q src tests

Tests use local fixtures and never call OpenDART or require an API key.

Data and operational notes

• Results are public disclosure data, but users should confirm material facts in the original filing before making decisions.

• OpenDART may update data between otherwise identical calls.

• The server does not store query inputs or results.

• Upstream rate limits and maintenance windows still apply.

License

MIT. See LICENSE.