# mcp-server-fss-dart

A Model Context Protocol (MCP) server for FSS Open DART (금융감독원 전자공시시스템) with token-efficient footnote parsing, financial anomaly detection, and historical stock price correlation.

## Features

This MCP server equips AI Agents (like Claude Code, Cursor, Windsurf, or Gemini) with the following tools to audit Korean companies:

1. **`get_corporate_details`**: Resolves a corporate name or stock ticker to its DART corporate code.
2. **`get_financial_anomalies`**: Evaluates primary accounting metrics (Debt-to-Equity ratio, Current ratio, Net Income) and flags potential accounting red-flags.
3. **`get_footnote_section`**: Semantic footnote query that unzips and extracts relevant report chunks matching keywords like "litigation" (소송), "debt guarantee" (지급보증), or "related party" (특수관계자) to prevent token bloat.
4. **`get_stock_chart`**: Fetches historical stock price trends and Simple Moving Averages (SMA) from Yahoo Finance to correlate financial anomalies with market activity.

---

## 설치 및 설정 (Installation)

### Prerequisites

- Python 3.10 or higher
- An Open DART API Key from [FSS Open DART](https://opendart.fss.or.kr)

### 1. Installation

Clone this repository and install the dependencies:

```bash
git clone https://github.com/<your-username>/mcp-server-fss-dart.git
cd mcp-server-fss-dart
pip install .
```

### 2. Configuration for Claude Desktop

Add the following block to your Claude Desktop configuration file (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "fss-dart": {
      "command": "python3",
      "args": ["-m", "mcp_server_fss_dart.server"],
      "env": {
        "DART_API_KEY": "YOUR_40_DIGIT_DART_API_KEY_HERE"
      }
    }
  }
}
```

---

## 한국어 안내 (Korean Guide)

본 프로젝트는 AI 에이전트가 금융감독원 Open DART API를 통해 한국 기업의 공시자료와 감사보고서 주석을 분석할 수 있도록 돕는 MCP(Model Context Protocol) 서버입니다. 

### 특징

* **토큰 효율적 주석 분석**: 대용량 감사보고서 주석 중에서 "소송", "보증", "특수관계자" 등 핵심 악재 키워드 매칭 문맥만 핀포인트로 파싱하여 AI 에이전트에 공급합니다.
* **이상징후 사전 탐지**: 부채비율 200% 초과, 유동비율 100% 미만, 당기순이익 적자 등의 재무적 위험 신호를 자동으로 계산하여 감지 플래그로 반환합니다.
* **실시간 주가 차트 연동**: 야후 파이낸스(Yahoo Finance)를 통해 실시간 주가 추이와 이동평균선(SMA5, SMA20)을 가져와 기업의 공시 리스크와 주가 변동의 연관 관계를 분석합니다.

### 실행 방법

상기 설정(Configuration)을 완료한 후, Claude Desktop 또는 MCP 지원 클라이언트를 실행하면 대화창에서 AI에게 다음과 같이 지시할 수 있습니다.

> *"카카오(035720)의 재무 상태를 분석하고, 2025년도 감사보고서 주석에서 소송 관련 내용이 있는지 찾아줘. 그리고 최근 주가 차트도 요약해 줘."*

## License

This project is licensed under the MIT License.