# my-kifrs-mcp

K-IFRS/K-GAAP/감사기준서/질의응답(kifrs.com) + 감리지적사례/제재공시(fss.or.kr)를 감싼
개인용 MCP 서버.

## 왜 만들었나

기존 외부 `ifrs` MCP(mcp.ifrsnow.work)는 K-IFRS + 금감원 감리/제재 트랙 중심이라 K-GAAP과
감사기준서(ISA 번호)를 다루지 않는다. kifrs.com은 이 세 가지를 한 사이트에서 다루지만 공식
API가 없고 로그인이 필요한 React SPA라, JS 번들을 리버스엔지니어링해 내부 REST API를 직접
호출하는 방식으로 만들었다.

## 설치

```bash
npm install
npm run build
```

비밀번호는 `.env`나 코드 어디에도 저장하지 않는다. 첫 도구 호출 시 로그인이 안 되어 있으면
Puppeteer가 실제 Chromium 창을 띄우고, 사용자가 kifrs.com 화면에 직접 로그인한다. 세션은
`~/.my-kifrs-mcp/browser-profile`에 영속되어 재로그인 없이 재사용된다.

```bash
npm run test:login   # 로그인 흐름 수동 테스트(브라우저 창 뜸)
```

## Claude Code에 등록

```json
{
  "mcpServers": {
    "my-kifrs-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\IFRS 및 감사\\build\\index.js"]
    }
  }
}
```

## 도구 16개 (v0.3.0)

### 통합 검색
- **accounting_search** — 기준서(search_standards)·질의회신(search_qna)·감리지적사례
  (search_audit_case)·제재공시(search_sanction) 4개 트랙을 한 번에 병렬 검색(기존 ifrs MCP의
  동명 도구 벤치마크 — 순수 오케스트레이션, 새 검색 로직 없음). 회계 질문의 1차 진입점으로
  쓰고, 더 깊이 파려면 개별 도구로 이어서 호출.

### 로그인
- **check_login** — kifrs.com 로그인 상태 확인/진단. 안 되어 있으면 브라우저 창 자동 실행.

### 기준서 (K-IFRS/K-GAAP/감사기준서 공통)
- **search_standards** — 키워드가 어느 기준서에 몇 건 나오는지 전체 검색. KTBi/ECL/CSM 등
  업계 약칭은 쿼리 자동 확장(`expanded_from`/`expanded_to`)으로 표준 용어로 바꿔 검색. 그래도
  전문(全文)에 정확한 단어가 없어 0건이면, 관련 기준서 목차(get_standard_index)의 절 제목에서
  개념어를 찾아 `index_candidates`로 제시(벌크 크롤링·임베딩 없이, 온디맨드 목차 조회 1회로
  해결 — 아래 "시맨틱 검색 검토 및 보류" 참고). 미의결 초안은 기본 제외(`include_drafts=true`로
  포함 가능).
- **get_standard_index** — 기준서 목차(장·절 계층, 문단번호 범위).
- **get_paragraph** — 특정 문단 원문 + 관련 질의응답 번호. `save_paragraph_explanation`으로
  저장해둔 해설이 있으면 `cached_explanation` 필드로 함께 반환.
- **save_paragraph_explanation** — 특정 문단에 대한 해설(실무 적용·예시 등)을 로컬에 저장.
  기존 ifrs MCP의 "운영자 사전작성 해설"과 달리 실사용 중 점진적으로 쌓는 캐시 방식(저작권
  문제 없음 — 남의 해설을 복제하는 게 아니라 그때그때 새로 작성).

### 질의응답
- **search_qna** — 회계기준원·금융감독원·IFRS해석위원회 등 7개 카테고리 통합 검색(약칭 쿼리
  자동 확장 동일 적용). 결과에 `vintage_warning`(인용 기준서가 그 이후 개정됐을 가능성) 자동 표시.
  `standard_filter`(예: 1109 또는 [1109,1115])로 특정 기준서 인용 항목만 좁혀볼 수 있음
  (기존 ifrs MCP의 standard_filter 벤치마크).
- **get_qna** — 문서번호(예: `2020-I-KQA002`, 숫자 id 아님)로 전체 본문 조회.

### 감리지적사례·제재공시 (fss.or.kr)
- **search_audit_case** — 금융감독원 심사·감리지적사례 검색. `keyword_variants`(최대 5개)로
  회사명 추정·관련기준서·쟁점 키워드 등 여러 각도의 검색어를 함께 넣어 재현율을 높일 수 있음
  (기존 ifrs MCP의 다중 검색 변형 벤치마크 — 각 검색어 1페이지씩 조회 후 중복 제거 병합).
- **get_audit_case** — 상세 + 첨부 PDF 본문(실제 지적사유·판단근거) 추출. 스캔본으로 추정돼
  텍스트 품질이 낮으면 `pdf_quality_warning` 표시(`pdf_page_count`도 함께 반환).
- **search_sanction** — 금융감독원 검사결과제재(제재공시) 검색. `keyword_variants` 동일 지원.
- **get_sanction** — 상세 + 첨부 PDF 본문(실제 위반사실·제재금액) 추출. ⚠ "제재 처분 확인
  사실"이며 강한 유죄 확정 표현으로 옮기지 말 것. `pdf_quality_warning`/`pdf_page_count` 동일 적용.

### 검증·피드백
- **verify_citation** — 단건 인용문이 실제 원문(기준서 문단/질의응답)에 있는지 exact/
  normalized/not_found 3단계 검증.
- **verify_citations** — 긴 텍스트에서 기준서 인용·질의응답 문서번호를 자동 추출해 일괄
  실존 확인.
- **expand_citations** — 긴 텍스트에서 인용을 자동 추출해 실제 원문(기준서 문단/질의응답
  본문)을 가져와 인용 직후(`placement=inline`) 또는 답변 끝 부록(`appendix`)으로 붙여 반환.
  기존 ifrs MCP의 동명 도구 벤치마크(verify_citations는 존재 확인만, 이건 본문까지 부착).
- **submit_feedback** — 답변 품질 별점(1~5)·코멘트를 로컬(`~/.my-kifrs-mcp/feedback.db`)에
  저장. 외부 전송 없음. `tokens`(다른 도구 응답에 자동으로 붙는 `_feedback_token`)로 실제
  어느 검색/조회에 대한 피드백인지 서버가 검증(기존 ifrs MCP의 토큰 기반 피드백 벤치마크) —
  기존엔 related_tool/query_context가 LLM 자기서술이라 신뢰할 수 없었던 걸 보완.

## 안전장치 — 초안(ing) 배제

아직 공식 의결되지 않은 초안(예: 지속가능성공시기준 4001/4002/4101)이 확정 기준서처럼
답변에 섞이지 않도록:
- `search_standards`는 초안을 기본적으로 결과에서 제외한다.
- `get_standard_index`/`get_paragraph`로 초안 stdNum을 직접 조회하면 `draft_warning`
  필드로 명확히 경고한다.

판정 기준: kifrs.com 데이터 자체의 의결일이 "202X" 같은 미확정 플레이스홀더이거나, 제목에
"공개초안"/"제정안"/"개정안"/"의견조회"/"검토의견" 등이 포함된 경우(`src/lib/
kifrs-standards-map.ts`의 `checkDraftStatus`).

## 아키텍처 메모

- **인증**: kifrs.com은 쿠키 기반(`authToken`/`refreshToken`). Puppeteer 브라우저 페이지
  컨텍스트 안에서 fetch를 실행해 쿠키를 자동 활용 — 토큰 저장 위치를 몰라도 동작한다.
- **fss.or.kr 접근**: 로그인 불필요한 공개 게시판이지만, User-Agent 없는 요청은 서버가
  연결을 끊는다(WAF 추정) — 브라우저 UA 헤더만 추가하면 정상 응답한다.
- **기준서 통합 맵**: `STD_NUM_TITLES`(K-GAAP 1~99 + K-IFRS 1000+ + 감사기준서 200~1200 +
  내부회계관리제도 3000+ 등)는 kifrs.com JS 번들의 `stdMap` 상수에서 추출한 정적 데이터.
- **문단번호 형식**: K-IFRS/감사기준서는 숫자("9"), K-GAAP은 "장.문단" 점 표기("13.1").
- **BrowserSession 동시성**: `search_qna`처럼 `Promise.all`로 여러 카테고리를 동시 조회하면
  Puppeteer 브라우저 launch가 레이스 상태가 될 수 있어(실측: 7개 중 1개만 성공), `prepare()`
  단계를 Promise로 메모이즈해 직렬화한다. 새 도구를 추가할 때 여러 `client.getJson()` 호출을
  병렬로 묶는다면 이 직렬화가 유지되는지 유의할 것.
- **프로세스 종료 정리**: `index.ts`가 SIGINT/SIGTERM/stdin close 시 `client.close()`로
  Puppeteer Chrome을 명시적으로 닫는다 — 이게 없으면 좀비 Chrome이 `userDataDir` 잠금을 쥔 채
  남아 다음 실행이 "browser already running"으로 전부 실패한다.

## 알려진 한계

- FSS 감리지적사례·제재공시의 실질 내용은 대부분 첨부 PDF 안에 있다(상세 페이지 자체는
  메타데이터만). `get_audit_case`/`get_sanction`이 자동으로 PDF 텍스트를 추출한다.
- KASB(kasb.or.kr)의 감사보고서 게시판 등 기준서 외 자료는 검토했으나, 다운로드가 JS
  `fileDownload()` 함수 호출 방식이라 리버스엔지니어링 비용 대비 실익이 낮아 보류함(2026-07-10).
- 참고서적 검색(book_contexts류)은 저작권 있는 상업 출판물 스크레이핑 우려로 의도적으로
  구현하지 않음.

## 시맨틱 검색 검토 및 보류 (2026-07-10)

`search_standards`/`search_qna`가 kifrs.com 자체 API(단순 substring 검색)에 의존하는 한,
"KTBi"처럼 원문에 정확히 없는 개념어는 쿼리 확장을 아무리 잘 만들어도 구조적으로 못 찾는
한계가 있다. 이를 해결하기 위해 로컬 임베딩(transformers.js, 완전 오프라인) + FTS5
trigram + RRF 하이브리드 검색을 실제로 구축·검증했다(34개 문단 실측 — "사업모형 분류" 등
질의에서 정확한 문단을 상위로 찾아냄, 검증 중 버그 2건도 발견·수정).

**그러나 보류함** — 이를 위해서는 전체 기준서 문단을 사전에 벌크 크롤링해야 하는데,
kifrs.com 이용약관 제15조②가 "에이전트·로봇·크롤러·스크립트... 등의 자동화된 수단"을 이용한
데이터 수집을 사전 동의 없이 금지하고 있음을 실제로 확인했다(개인적·비영리 목적이어도 예외
없음, 위반 시 회원자격 정지/상실 — 제15조④). 규모와 무관하게 문언상 금지 대상이라 판단해
벌크 크롤링 기능은 만들지 않기로 했다(검증에 썼던 34개 문단 샘플도 삭제함).

**대신** `search_standards`가 0건일 때 관련 기준서의 목차(`get_standard_index`, 온디맨드
1회 조회 — 사람이 목차를 직접 펼쳐보는 것과 같은 수준)에서 절 제목을 훑어 개념어를 찾는
`index_candidates` 방식으로 검색 편의성만 보완했다. 벌크 크롤링 없이도 "KTBi" 같은 케이스를
실제로 해결함(→ 관련 절 "사업모형"/"원리금 지급만으로 구성된 계약상 현금흐름"을 정확히 찾음).

참고로 K-IFRS **본문(조문) 자체**의 저작권은 별개 문제로, IFRS Foundation이 한국어판 기준서
본문에 대해 "한국 내 어떤 용도로든 복제 허용"으로 저작권을 명시적으로 포기했음을 확인했다
(db.kasb.or.kr의 저작권 고지 참고, 단 결론도출근거/적용사례 등 부속자료는 제외). 이건
이용약관상 자동화 수집 금지와는 별개의 문제라, 지금 이 MCP처럼 로그인 계정으로 온디맨드
조회하는 정도의 사용 패턴에서는 콘텐츠 자체의 저작권 리스크는 낮다고 판단한다.

## 테스트

```bash
npm run build
node scripts/smoke-test.mjs         # puppeteer 기본 동작(로그인 불필요)
node scripts/smoke-test-tools.mjs   # 기준서·질의응답 5개 도구(로그인 필요)
node scripts/smoke-test-verify.mjs  # 인용 검증·재시도·vintage_warning
```