<p align="center">
  <img src="https://raw.githubusercontent.com/dolseom/gongsi-mcp/main/docs/hero.jpg" alt="gongsi-mcp — 공시담당자를 위한 공정위 공시 컴플라이언스 MCP 서버" width="100%" />
</p>

# gongsi-mcp

> 투자 관점 DART MCP가 "이 회사 사도 되나"에 답한다면,
> **gongsi-mcp 는 "이거 공시해야 하나, 언제까지, 안 하면 얼마"에 답합니다** — 근거 조문·계산식과 함께.

**회사 이름도 인증키도 없이**, 거래금액·자본·날짜·상장 여부만 말하면 됩니다. Claude 에 평소 말하듯 물으면 알아서 맞는 도구를 부릅니다. 공정거래위원회 기업집단 공시(대규모내부거래 · 기업집단현황 · 비상장사 중요사항)를 **제출하는 사람**을 위한 MCP 서버입니다.

[![npm version](https://img.shields.io/npm/v/gongsi-mcp.svg)](https://www.npmjs.com/package/gongsi-mcp)
[![Node 22.13+](https://img.shields.io/badge/Node.js-22.13%2B-green)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Website](https://img.shields.io/badge/website-dolseom.com-1f5eff)](https://dolseom.com)

> **English summary** — gongsi-mcp is an open-source MCP server that lets Claude answer Korea Fair Trade Commission (KFTC) conglomerate disclosure questions: whether a transaction must be disclosed, the filing deadline, and the expected fine if late. Every answer returns the provision, formula and inputs so a person can verify it, and unverified conditions are reported instead of hidden. 17 tools, 430 official KFTC Q&As. Duty, deadline and fine checks need no API key. Install: `claude mcp add gongsi-mcp -- npx -y gongsi-mcp`. More at [dolseom.com](https://dolseom.com).

> "이거 공시사항이야?"라는 전화를 받은 순간부터 점검을 통과할 때까지,
> 물어볼 사람이 없어도 혼자서 확신을 가질 수 있도록.

---

## 이렇게 씁니다

💬 **"비상장 계열사에 80억 자금대여 의결했어 (자본총계 1,200억). 공시 대상이야? 기한은?"**
> 공시 **대상**입니다. 기준금액 = min(100억, max(5억, 자본총계 1,200억 × 5%)) = **60억** ≤ 거래 80억.
> 이사회 의결일(7/22) 다음 날부터 **7영업일** — 기한 **7/31**. 근거: 대규모내부거래 고시 §6①.
> *웹에 퍼진 "1일 이내"는 오정보입니다 — 고시 원문은 상장 3영업일 / 비상장 7영업일. 실제 공시 사례와 대조 검증된 계산입니다.*

💬 **"30억 내부거래 공시를 5일 늦게 냈어. 과태료 얼마 나와?"**
> 예상 **165만원**. 산식 전문을 함께 드립니다:
> `(기본금액 500만원 + 일수가산 50만원) × 거래금액 적용비율 60%(20억~40억 구간) = 기준금액 330만원 − 지연 7일 이하 감경 50% = 165만원`
> 거래금액을 안 알려주시면 "이 값은 상한선(최대 275만원)"이라고 명시합니다 — 조용히 과대·과소 산정하지 않습니다.

💬 **"기한 놓친 지 3일째인데 아직 공시 전이야. 지금 내면 뭐가 달라져?"**
> **자진시정 골든타임**(기한 다음 날부터 10영업일)이 아직 열려 있습니다 — 종료일·남은 영업일·면제 요건(신규 지정 30일 내, 사소한 부주의 등)을 알려드립니다. 골든타임이 지나도 지연 3일 이하는 75% 감경 구간이라, 하루라도 빨리 내는 게 유리하다는 계산까지.

위 세 답은 **인증키 없이** 나옵니다. 회사 자료(공시 원문·재무·계열사)를 조회하는 질문에는 무료 OpenDART 키가 필요합니다 — [30초 설치](#30초-설치).

<details>
<summary><b>더 보기 — 회사 이름 없이 · 단위 빠진 질문 · 기한 감사 · 미공시 탐지 · 제출본 점검 · 선례 · 공정위 문답 · 연간 달력 · 공휴일 (9개, 전부 실측 사례)</b></summary>

<br>

💬 **"회사 이름은 말 못 해. 자본총계 1,200억에 계열사와 80억 자금거래인데 공시 대상이야? 이사회 날짜는 아직 안 잡혔어"**
> 공시 **대상**입니다 — 기준금액 60억 ≤ 거래 80억. 회사명·인증키는 필요 없습니다. 공시기한은 **이사회 의결일과 상장 여부**를 알려주시면 계산합니다. 날짜가 없으니 지연 여부·과태료는 계산하지 않았습니다("기한 내"도 "지연"도 아닙니다). *(0.3.0+ — 패키징한 설치본을 stdio 로 호출해 받은 응답: 대상 판정 완료 · 기한 미확정 · 과태료 없음)*

💬 **"비상장 계열사가 7월 22일 이사회에서 자금대여를 의결했어. 자본은 아직 확인 못 했어. 대규모내부거래라면 언제까지 공시해?"**
> **대규모내부거래에 해당한다면** 기한은 **7/31** 입니다 — 의결일 다음 날부터 비상장 7영업일(고시 §6①). 기한은 자본과 무관하게 계산되고, 대상 여부는 자본총계(또는 자본금)·금액이 없어 **판정하지 않았습니다** — 두 계산의 상태를 따로 돌려주고, 더 필요한 입력을 "대상 판정용 / 기한 계산용"으로 나눠 알려줍니다. 실제 공시일까지 주면 지연일수·과태료도 계산하지만, 대상이 확정되지 않은 동안에는 "**공시 대상으로 확정될 경우**의 값"이라고 붙입니다. *(0.3.0+)*

💬 **"자본총계 1200억인 비상장 계열사가 다른 계열사에 30 빌려주려고 해. 공시해야 돼?"**
> "30"에 단위가 없어 하나로 정해 단정하지 않고 **해석별로 나눠** 답합니다 — 기준금액 60억 기준으로 30억원이어도, 3,000만원이어도 대상이 아닙니다. 그리고 단위 확인을 요청합니다. *(0.3.0+ — 합성 질문 종단 평가에서 받은 답변 요약)*

💬 **"우리 회사 6~7월 대규모내부거래 공시, 지연된 거 있는지 감사해줘"**
> 해당 기간 공시 **5건 전수** 대조 완료 — 원본 접수일 vs 원문 이사회 의결일 기준 **전부 기한 내**입니다. 집단 단위 감사도 됩니다(실측: 삼성 67개 계열사 조인). 대규모내부거래 위반의 94~95%가 "기한" 유형(공정위 실측) — 이 도구가 잡는 게 바로 그것입니다.

💬 **"기업집단현황공시에 적힌 거래내역이랑 대규모내부거래 공시를 대조해서, 공시 안 하고 넘어간 거래가 있는지 봐줘"**
> 접수분만 보는 기한 감사가 **원리상 못 하는 일** — 공시 자체가 없는 거래를 보는 — 의 유일한 경로입니다. 실제 제출된 연1회 공시 1건으로 돌린 결과: 자금 차입 **3건은 전부 차입일 직전에 해당 유형 공시가 접수**돼 있었습니다(건별 근접 대조 −5일·−4일·−2일) — 미공시 후보 **0건**. 상품·용역에서 연간 **2,054.5억원 거래 1건**이 남았지만 "미공시"라고 하지 않고 **조건부 후보**로 냅니다 — 이 유형의 공시의무는 상대방이 "자연인인 동일인이 단독으로 또는 친족과 합하여 20% 이상 출자한 계열회사"일 때만 성립하는데(법 §26①4호·령 §33②) **지분 데이터가 없어 요건을 확인할 수 없기 때문**입니다. 유가증권 36쌍도 공시 존재 4 / 기준 미달 24 / **판정 불가 8** 로 갈라서 돌려줍니다 — 확인 못 한 8건을 "문제 없음"에 섞지 않습니다. 결과가 커서(실물 22만 자) 첫 응답은 **요약·조치 목록·필수 경고**만 오고, 판정 근거·caveat 전문은 `read_detection_result` 로 이어서 읽습니다 — 파일을 열 수 없는 대화창에서도 근거까지 닿습니다. *(요약·상세 읽기는 0.3.0+)*

💬 **"기업집단현황공시 제출본, 숫자 틀린 데 없는지 점검해줘"**
> 재무현황 표에서 **불일치 3건**을 찾았습니다 — 예: ○○사 자산총계가 유동+비유동 합계와 7.28억 차이. 각 건의 행·기대값·실제값을 제시하니 원본과 대조해 정정 여부를 판단하세요. **DART 에 접수된 공시의 접수번호로** 점검합니다 — 아직 제출하지 않은 엑셀·HWP 초안은 읽지 못합니다. *(실제 제출된 공시에서 검출된 실측 사례, 오탐 0. 공시의무 위반 건수의 84%가 이 공시(J004)에서 나옵니다)*

💬 **"사모사채 발행 공시, 다른 회사는 어떻게 썼는지 5년치 선례 찾아줘"**
> 3개사 선례를 원문과 함께 가져왔습니다. 어디까지 훑었는지(`coverage`)도 함께 — 훑지 않은 구간을 "없다"고 말하지 않습니다.

💬 **"계열사 발행어음이 만기 자동연장됐는데, 이것도 공시해야 해?"**
> 규칙만으로 판정하기 어려운 경계사례라, **공정위 공시 업무 매뉴얼(2026. 4.)의 해당 공식 문답을 원문 그대로** 출처·연도와 함께 인용해 드립니다.

💬 **"올해 우리가 언제 뭘 공시해야 하는지 달력으로 뽑아줘"**
> 2026년에 기한이 도래하는 정기공시 **19건**을 D-day 와 함께 시간순으로. 기업집단현황공시 연1회는 법정 기한 5/31이 **일요일이라 실제 기한은 6/1**이고, 그날 1분기 공시·비상장 주요주주 지분변동까지 **3건이 겹칩니다**(연1회와 1분기는 같은 날이라 단일 서식 1건으로 함께 제출 — 두 번 내는 게 아닙니다). 분기 공시 항목의 기준일이 "공시기한일의 **직전 분기**"라는, 담당자가 가장 자주 틀리는 지점도 항목마다 붙습니다. 그리고 **달력이 비었다고 공시할 게 없다는 뜻이 아니라고** 먼저 말합니다 — 대규모내부거래 개별거래·비상장 중요사항 등 사유 발생형 4종은 애초에 달력에 올릴 수 없어 따로 알려드립니다.

💬 **"2027년 5월 1일이 기한 말일이면 실제로 언제까지 내면 돼?"**
> **5/4(화)** 까지입니다. 5/1 노동절(2026-04-30 규정 개정으로 신설) · 5/2 일요일 · 5/3 대체공휴일을 건너뛴 결과 — 건너뛴 날짜와 사유·근거 조문을 동봉합니다. *(모델의 달력 지식이 아니라 공식 공고와 대조 검증된 데이터로 계산)*

</details>

---

## 왜 믿을 수 있나

공시 업무에서 틀린 답보다 무서운 건 **근거 없는 확신**입니다. 이 도구는 세 가지를 지킵니다.

- **법령은 원문으로만 봅니다.** 웹과 챗봇에 퍼진 "공시기한 1일 이내", "50억 기준"은 오정보입니다 — 고시 원문은 상장 3영업일 / 비상장 7영업일, 기준금액은 자본의 5%(5억~100억)입니다. 모든 답에 조문·계산식·입력값을 붙여 담당자가 직접 재확인할 수 있게 합니다. 규칙으로 안 풀리는 경계사례는 **공정위 공식 문답 430건**(2026. 4. 공시 업무 매뉴얼 포함)을 원문 그대로 인용합니다.
- **날짜는 검증된 달력으로 셉니다.** 기한 계산의 기초인 공휴일 데이터를 2026·2027년 공식 공고와 대조했습니다(노동절 신설·대체공휴일 반영). 모델의 기억이 아니라 데이터로 계산하고, 미검증 연도는 응답에 경고를 붙입니다.
- **확인 못 한 것을 "없음"이라 말하지 않습니다.** 검색이 잘리면 잘렸다고, 대사가 안 되면 안 됐다고, 지분 요건을 못 봤으면 "조건부 후보"라고 씁니다. 감사·판정 도구가 저지를 수 있는 최악의 실수 — 확인하지 않았는데 "문제 없음"이라 안심시키는 것 — 을 설계 단계에서 막았습니다. [설계 원칙](#설계-원칙--이-도구가-가장-피하는-실패는-거짓-안심) 참고.

그리고 **자동 제출은 만들지 않았습니다.** 판정·근거·초안까지가 도구의 몫이고, 제출은 담당자의 몫입니다.

---

## 30초 설치

Node.js 22.13 이상만 있으면 됩니다. 대상 판정·기한·과태료·영업일 계산은 **키 없이** 바로 됩니다.

**Claude Code**

```bash
npx -y gongsi-mcp setup
claude mcp add gongsi-mcp -- npx -y gongsi-mcp
```

setup 마법사가 인증키를 실제 API 호출로 검증해 `~/.gongsi-mcp/.env` 에 저장하고, 룰 엔진 자가검증(실제 공시 사례 재현)까지 돌립니다. 키가 아직 없으면 건너뛰고 나중에 다시 실행해도 됩니다.

**Claude Desktop** — 설정 파일에 아래를 추가하고 앱을 재시작합니다 (Windows `%APPDATA%\Claude\claude_desktop_config.json`, Mac `~/Library/Application Support/Claude/claude_desktop_config.json`).

```json
{
  "mcpServers": {
    "gongsi-mcp": {
      "command": "npx",
      "args": ["-y", "gongsi-mcp"],
      "env": { "DART_API_KEY": "OpenDART에서 발급받은 키" }
    }
  }
}
```

| 쓰려는 기능 | 필요한 키 |
|---|---|
| 공시의무 판정 · 기한 · 과태료 · 영업일 · 정기공시 달력 · 정정 리스크 · 공정위 문답 | **없음** |
| 공시 검색 · 원문 · 선례 · 재무 · 제출본 점검 · 기한 감사 · 미공시 탐지 | `DART_API_KEY` — [OpenDART](https://opendart.fss.or.kr) 무료 발급 (즉시, 일 20,000건) |
| 기업집단 단위 조회·감사 (소속회사 전수 등) | 위에 더해 `EGROUP_API_KEY` — 공공데이터포털 기업집단포털 API 활용신청 |

Cursor·MS 스토어판 Claude Desktop·Windows 에서 `npx` 를 못 찾는 경우·소스 클론은 [설치 상세](#설치-상세)에 있습니다.

---

## 이런 사람에게

- 기업집단 소속 회사의 **공시담당자·공정거래팀** — 대상 판정, 기한 관리, 제출본 점검이 일상인 사람
- "GPT한테 물어봤더니 이상한 말만 해서" 근거 조문이 있는 답이 필요한 사람
- 물어볼 선배가 없는 **신규 담당자** (공정위가 공식 지목한 위반 1순위 원인이 "신규 담당자 업무 미숙")

**다른 도구가 낫다면** — 투자·재무 분석(재무비교·내부자거래·XBRL)은 투자 관점 DART MCP 가 훨씬 잘합니다(관점이 정반대라 같이 설치해도 됩니다). 거래소(KRX) 공시 규정 판정은 다루지 않습니다. 서식 자동 작성·자동 제출은 의도적으로 만들지 않았습니다.

---

## 한계 — 먼저 알고 쓰세요

- **판정은 참고 정보입니다.** 법령·고시 원문에 근거하지만 법률 자문·공정위 유권해석이 아닙니다. 최종 확인은 소관 부서에. 오답을 발견하면 [Issues](https://github.com/dolseom/gongsi-mcp/issues)에 남겨 주세요.
- **이 도구는 근거·원문·계산을 검증해서 주는 도구입니다. Claude 가 그걸 요약해 쓴 최종 문장은 원문과 대조하세요.** 판정·기한·과태료 계산과 원문 인용은 검증되어 있습니다. 하지만 답변을 요약하거나 표로 정리하거나 경우를 나누는 과정에서 "~인 경우" 같은 조건이 빠지거나 바뀔 수 있습니다. 실무자 실제 질문 18개를 두 번씩 답하게 한 36건 평가(2026-09)에서 도구를 쓴 답변은 A 13 · 오답 F 10이었습니다. 도구 없는 Claude 단독 답변은 같은 문항 평가에서 A 0이었습니다. 결론을 쓰기 전에 답변에 인용된 원문, 그리고 `check_disclosure_duty` 가 주는 적용 요건 체크리스트(`review.answer`)와 맞는지 확인하세요.
- **제출본 점검은 DART 에 접수된 공시만** 봅니다(접수번호 입력). 아직 제출하지 않은 엑셀·HWP 초안은 읽지 못합니다.
- **DART 일반 조회 커버리지는 좁습니다** — 재무·검색·원문 등 범용 도구 6개뿐이고, XBRL·지분공시·임원보수 같은 투자 분석 엔드포인트는 없습니다.
- **기업집단포털은 연 1회(매년 5/1 기준) 갱신**이라 연중 신규 편입은 늦게 반영됩니다. 응답에 기준 시점을 명시합니다.
- **대규모 기간·집단 전체 감사**는 MCP 클라이언트의 60초 제한 때문에 분할 안내를 돌려줍니다(원문 캐시가 쌓이면 재감사는 빨라집니다). 집단 전수 미공시 탐지 같은 질문은 답까지 수 분이 걸릴 수 있습니다.
- **미공시 탐지의 상세 결과는 서버 메모리에 30분**만 보관됩니다(최대 4건). 만료·서버 재시작 뒤 근거를 다시 보려면 탐지를 다시 실행해야 합니다. 요청을 중간에 취소하면 결과를 보관하지 않지만 이미 시작된 DART 조회는 끝까지 진행돼 일일 호출 한도는 소모됩니다.
- 공휴일 데이터는 2026·2027년분만 공식 공고와 대조했습니다. 다른 연도는 응답에 경고가 붙습니다.

---

## 기존 DART MCP와의 차별점

공개 DART MCP 5종 조사 결과(2026-07 기준) 전부 투자·재무 관점이었고, **공정위 기업집단 공시 판정을 다루는 것도, 공정위 기업집단포털 API를 쓰는 것도 없었습니다.**

| 기능 | 일반 DART MCP | **gongsi-mcp** |
|---|:---:|:---|
| 관점 | 공시를 **읽는** 사람 (투자자) | 공시를 **제출하는** 사람 (공시담당자·공정거래팀) |
| 공정위 공시(J) 대상 판정 · 기준금액 계산 | ❌ | ✅ 기준금액 min(100억, max(5억, 자본×5%)) 자동 계산 — 근거 조문·계산식·입력값 전부 동봉 |
| 공시기한 계산 (영업일·공휴일) | ❌ | ✅ 상장 3영업일 / 비상장 7영업일 등 유형별 기한. 공휴일 데이터는 2026·2027 공식 공고와 대조 검증 (노동절 신설·대체공휴일 반영) |
| 예상 과태료 (별표9 + 고시 2종) | ❌ | ✅ 기본금액 + 일수가산 + 거래금액별 적용비율(50~100%) + 가중·감경 + 상한까지 — 산식 전문 제공, 미확정이면 "상한선" 명시 |
| 공정위 기업집단포털 결합 | ❌ (사용 사례 전무) | ✅ 법인등록번호로 DART와 조인 — 계열사 전수 목록·집단 재무·동일인 정보 |
| 공정위 공식 Q&A 근거 제시 | ❌ | ✅ 430건 (2026. 4. 공시 업무 매뉴얼 주요 사례 포함) — 규칙으로 판정 안 되는 경계사례에 공식 답변 인용, 폐지된 옛 기준은 경고 |
| 기한 감사 (접수일 vs 의결일) | ❌ | ✅ 원본 접수분과 원문 이사회 의결일을 전수 대조 — 지연 후보에 예상 과태료·자진시정 골든타임 동봉 |
| 정기공시 캘린더 · 미제출 점검 | ❌ | ✅ 연간 마감일을 D-day·기준일·겹치는 날까지 계산 + 정기공시(J004·J009)를 **실제로 냈는지** 회사별 점검 — 무조건 의무라 접수분 부재가 곧 신호 |
| **미공시** 교차탐지 (J004↔J001) | ❌ | ✅ 기업집단현황공시의 실제 거래내역을 대규모내부거래 공시와 대조 — 접수분만 보는 감사가 원리상 못 하는 "공시 자체가 없는 거래"를 신뢰도별 후보로 |
| 정정 이전 원본 보존 | 대부분 최종본만 | ✅ 검색 기본값이 원본 접수분 — 최종본만 보면 지연 판정 자체가 불가능하기 때문 |
| 제출본 정합성 자가점검 | ❌ | ✅ 접수번호로 제출본을 재검산 — 자산=부채+자본 항등식 · 소계 재합산 · 부채비율 재계산 · 대표회사↔개별회사 문서 간 대사 (미제출 초안 파일은 대상 아님) |
| 검색 절단·부분결과 명시 | 도구마다 다름 | ✅ 모든 응답에 `diagnostics`·`coverage` — 확인 못 한 범위를 "없음"으로 말하지 않음 |

---

## 도구 (17개)

0.3.0 기준입니다. 0.2.0 에는 `read_detection_result` 가 없어 16개입니다. 도구 이름을 외울 필요는 없습니다 — 질문하면 Claude 가 고릅니다.

**판정·리스크 (공정위 공시 특화 — 이 서버에만 있는 것)**

| 도구 | 설명 |
|---|---|
| `check_disclosure_duty` | 공시의무 판정 + 기한 계산 + 예상 과태료 — 근거 조문·계산식 동봉, 인증키 불필요. 거래 상황을 서술하면 유사 공정위 공식 Q&A도 근거로 첨부. 기한을 놓쳤으면 자진시정 10영업일 골든타임(면제 사유·남은 영업일)을 안내. 비상장사 중요사항은 대상회사 판정(자산 100억·동일인 지분 20%)과 무조건 공시 사유 7종까지. 입력이 일부 없어도 되는 계산(대상 판정·기한)부터 돌려주고 부족한 입력을 용도별로 알려줌 *(0.3.0+)* |
| `assess_correction_risk` | "정정하면 과태료 나온다?" — 커뮤니티 썰 진단. 과태료 고시의 위반행위 열거에 정정은 없다는 원문 근거와 함께, 오류 성격별(단순 오기·계산 실수·내용 누락·거짓 기재·거래 변경) 리스크와 골든타임 일정 제시 |
| `check_j004_consistency` | 기업집단현황공시(J004) **접수된 제출본** 자가점검(접수번호 입력 — 미제출 초안 파일은 읽지 못함) — 재무표 항등식·소계 재합산·부채비율 재계산·단위 오류 힌트 + 대표회사↔개별회사 공시 대사. 대사가 수행되지 못한 건은 "정합"으로 세지 않고 별도 verdict 로 보고 |
| `audit_group_disclosures` | 기업집단·회사의 대규모내부거래(J001) 기한 감사 — 원본 접수일 vs 원문 의결일 대조, 지연 후보에 예상 과태료·자진시정 골든타임 동봉. 접수분만 보므로 **미공시는 원리상 탐지하지 못한다**고 응답에 고지 |
| `audit_periodic_disclosures` | 기업집단현황공시(J004)·하도급대금 결제조건(J009) **정기공시를 실제로 냈는지, 기한을 지켰는지** 회사별 점검 — 기한이 달력으로 고정돼 있어 원문 없이 접수일만으로 판정합니다. J001 감사가 못 하는 **미제출 탐지**가 됩니다(무조건 의무라 접수분 부재 자체가 신호). 판정하지 않는 것들은 `scope_caveats` 로 전부 나열 |
| `detect_undisclosed_transactions` | **미공시 교차탐지 (J004↔J001)** — 기업집단현황공시에 적힌 실제 거래내역을 대규모내부거래 공시와 대조해 "거래는 했는데 공시가 없는" 후보를 찾습니다. 자금 차입은 건별 차입일 근접 대조, 상품·용역은 상대방 지분요건(법 §26①4호) 미확인이라 조건부 후보, 유가증권 매트릭스는 연간 총액뿐이라 확인 대상까지 — 신뢰도별로 분리해 돌려주고 **전부 "후보"이지 확정이 아닙니다**. 결과가 커서 첫 응답은 크기 예산(24,576바이트 — 호스트 한도가 아니라 여유 있게 잡은 제품 상한) 안의 요약(조치 목록 앞부분·집계·필수 경고)이고, 근거 전문은 `read_detection_result` 로 읽습니다. 요청을 취소하면 결과를 보관하지 않습니다 *(요약·취소 처리는 0.3.0+)* |
| `read_detection_result` | *(0.3.0+)* 탐지 요약의 `detail_access.result_id` 를 입력 `result_id` 로 넣어 판정 근거·caveat 전문을 조각 단위로 이어 읽기 — 조각을 이어붙이면 원본과 정확히 같습니다. 키 불요, 탐지를 다시 돌리지 않음. ⚠️ 상세는 **서버 프로세스 메모리에 30분**만 보관(최대 4건) — 만료·서버 재시작 뒤에는 탐지를 다시 실행해야 합니다 |
| `disclosure_calendar` | "올해 우리가 언제 무엇을 공시해야 하나" — 기한이 달력으로 고정된 정기공시 마감일을 D-day 와 함께 시간순으로. 비영업일이면 조정된 실제 기한, 항목별 기준일(분기는 "직전 분기"), 같은 날 겹치는 지점(collisions)까지. 사유 발생형 공시는 달력에 올릴 수 없다고 `not_in_calendar` 로 명시. 인증키 불필요 |
| `search_ftc_qna` | 공정위 공식 Q&A 430건 검색(2026. 4. 27. 공시 업무 매뉴얼 주요 사례 포함) — 규칙으로 판정 안 되는 경계사례에 공정위 공식 답변을 근거로 제시. 옛 문서의 폐지된 기준은 caveat 로 표시 |
| `calc_business_days` | 영업일·공휴일·기한 날짜 계산 — 기한 말일이 주말·공휴일이면 언제까지인지, N영업일/N달력일 기한, 남은 영업일. 건너뛴 날짜·근거 조문 동봉, 인증키 불필요 |

**검색·원문·선례 (범용)**

| 도구 | 설명 |
|---|---|
| `search_disclosures` | 공시 검색 — 공정위 프리셋 내장, 적응형 분할 전수 수집, 절단·부분결과를 조용히 넘기지 않음 |
| `read_disclosure` | 공시 원문을 표 구조 보존 마크다운으로 — 이사회 의결일 자동 추출 |
| `find_precedents` | 같은 유형 공시를 회사당 1건씩 원문과 함께, 최대 5년치. `coverage` 가 훑은 범위와 전수 여부를 보고 |
| `resolve_entity` | 회사·기업집단 통합 식별 — 동명 법인을 임의로 고르지 않음 |
| `get_group_structure` | 기업집단 개요 + 소속회사 전수 + 재무현황 (공정위 포털 결합) |
| `get_financials` | 재무제표 조회 — 자본총계·자본금이 판정 도구 입력으로 직결 |
| `server_info` | 서버 상태 진단 — 버전, 키 인식 여부, 오늘 호출 잔량, 캐시 규모, 공휴일 데이터 검증 연도. "키를 넣었는데 인식이 안 돼요"의 진단 창구 |

---

## 설치 상세

키가 필요한 도구를 키 없이 부르면 도구가 발급 절차를 그 자리에서 안내합니다. 회사명은 **자료를 조회할 때만** 필요합니다.

### 버전별 차이

| 버전 | Node.js | 들어 있는 것 |
|---|---|---|
| **0.2.0** (npm 배포 2026-08-30) | 22.5+ | 도구 16개 |
| **0.3.0** (npm 배포 2026-09-15) | **22.13+** | 도구 17개 — 위에 더해 일부 입력만으로 되는 판정(`missing_inputs`·`components`·`review`), 미공시 탐지 요약 + `read_detection_result`, 탐지 이어보기(`continuation_token`)·시간 예산, 탐지 취소 시 결과 미보관, 0.2.0 이후 미공시 탐지 정확도 개선 |
| **0.3.1** | 22.13+ | 도구 17개(변동 없음) — 미공시 탐지의 **매트릭스 파서 수정**: 거래상대방이 `금융회사`·`비금융회사` 같은 묶음 이름으로 읽히던 문제, 상대방이 1개사뿐인 표가 통째로 빠지던 문제. 점검하지 않은 자금거래 표(한도 약정 차입·리스 부채)를 표 수·행 수로 표시. 기업집단포털 목록을 끝까지 못 받으면 부분 목록 대신 오류. 0.3.0 사용자는 올리는 것을 권합니다 — [릴리스 노트](https://github.com/dolseom/gongsi-mcp/blob/main/docs/releases/v0.3.1.md) |

`main` 에 올라간 변경이 곧 npm 배포는 아닙니다 — npm 배포는 버전 태그로 따로 하고, npm 에 올라간 최신 버전은 `npm view gongsi-mcp version` 으로 확인합니다. 어느 쪽이든 실행 중인 버전은 `server_info` 의 `version` 에 표시됩니다.

**0.2.0 에서 올릴 때** — Node.js 22.13 이상이 필요하고, 이미 떠 있는 서버는 옛 버전이므로 MCP 클라이언트를 다시 시작해야 새 버전이 적용됩니다. `detect_undisclosed_transactions` 의 첫 응답은 전체 결과가 아니라 **요약**으로 바뀌었습니다 — 전문은 요약의 `detail_access.result_id` 를 `read_detection_result` 의 입력 `result_id` 에 넣어 읽습니다. `check_disclosure_duty` 는 입력이 일부 빠져도 오류로 끝내지 않고 **계산할 수 있는 부분을 돌려주며**, 확정하지 못한 계산은 `missing_inputs`·`components` 로 표시합니다 — 예: 금액·자본 등 대상 요건이 충족된 경우, 이사회 의결일이 없으면 대상 판정은 `verdict: required` 로 나오고 기한만 `components.deadline.status: insufficient_data` 입니다(의결일이 없다는 것만으로 `required` 가 되지는 않습니다). 응답을 직접 파싱하는 연동이 있다면 [0.3.0 릴리스 노트](https://github.com/dolseom/gongsi-mcp/blob/main/docs/releases/v0.3.0.md)의 호환성 절을 먼저 보세요.

### 방법 1: setup 마법사 + Claude Code (권장)

```bash
npx -y gongsi-mcp setup
claude mcp add gongsi-mcp -- npx -y gongsi-mcp
```

마법사가 키를 실호출로 검증하고 `~/.gongsi-mcp/.env` 에 저장 — 서버가 자동으로 읽는 위치라 등록 시 env 를 다시 줄 필요가 없습니다.
비대화 모드: `npx gongsi-mcp setup --dart-key <키> [--egroup-key <키>] --no-input`

### 방법 2: Claude Desktop / Cursor 등 (설정 파일)

설정 파일에 추가 (`YOUR_API_KEY` 교체):

| 앱 | 설정 파일 위치 |
|---|---|
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Cursor | 프로젝트 `.cursor/mcp.json` |

```json
{
  "mcpServers": {
    "gongsi-mcp": {
      "command": "npx",
      "args": ["-y", "gongsi-mcp"],
      "env": {
        "DART_API_KEY": "OpenDART에서 발급받은 키"
      }
    }
  }
}
```

> **Windows에서 실행 실패 시**: 클라이언트가 `npx` 를 못 찾는 경우 `"command": "cmd", "args": ["/c", "npx", "-y", "gongsi-mcp"]` 로 래핑하세요.
>
> **MS 스토어판 Claude Desktop**: 설정 파일이 가상화 경로에 있습니다 — `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json`. `%APPDATA%\Claude` 를 고쳐도 앱이 읽지 않습니다.

### 방법 3: 소스 클론 (개발)

```bash
git clone https://github.com/dolseom/gongsi-mcp.git && cd gongsi-mcp
npm install && npm run build
node dist/src/cli.js setup
claude mcp add gongsi-mcp -- node <절대경로>/dist/src/cli.js
```

이미 클론했다면 `git pull && npm install && npm run build` 뒤 MCP 클라이언트를 다시 시작하세요.

요구사항: **Node.js 22.13+** (런타임 의존성 2개 — MCP SDK, zod. SQLite는 Node 내장 `node:sqlite` 사용 — v22.13.0부터 `--experimental-sqlite` 플래그 없이 동작)

---

## 설계 원칙 — 이 도구가 가장 피하는 실패는 "거짓 안심"

감사·판정 도구의 최악의 출력은 틀린 경고가 아니라 **확인하지 못했는데 "문제 없음"이라고 말하는 것**입니다. 담당자가 그 말을 믿고 공시를 안 하면 과태료가 나옵니다. 그래서:

- **모든 판정에 근거 동봉** — 조문·계산식·원천 데이터 없이 결론만 주지 않는다
- **절단을 조용히 넘기지 않는다** — 모든 검색 응답에 `diagnostics`(truncated·partial_results·분할 내역), 선례 검색에 `coverage`(훑은 구간·전수 여부) 동봉
- **확인 못 한 것은 "없음"이 아니라 "미확인"으로** — 대사 실패는 "정합"이 아니고, 예산 초과로 못 훑은 구간은 "그런 공시 없음"이 아니다
- **정정 이전 원본을 보존한다** — 검색 기본값이 원본 접수분. 최종본만 보면 지연 판정이 불가능하다
- **법령 세부는 원문으로만** — 웹에 퍼진 "공시기한 1일"·"50억 기준" 같은 오정보를 원문 대조로 걸러냄
- **자동 제출 기능은 만들지 않는다** — 초안·판정·근거까지만. 최종 제출은 담당자의 몫

검증(0.3.1 소스, 2026-09-22): 테스트 759개(32파일) · 실물 J004 44문서 파서 전수 스캔 · 패키징한 설치본 stdio 스모크 9종 · 공휴일 데이터 공식 공고 대조(2026·2027) · 실제 공시 사례 재현 · 3자 교차검토(치명 경로 전수 수정) · 자연어 종단 평가([eval/e2e](eval/e2e/README.md)).

---

## 참고

- [OpenDART](https://opendart.fss.or.kr) — 금융감독원 전자공시 API
- [공정위 기업집단포털](https://www.egroup.go.kr) — 지정 집단·소속회사·재무 (공공데이터포털 API)

## 라이선스

[MIT](./LICENSE)