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를 직접 호출하는 방식으로 만들었다.

Related MCP server: Korean Law MCP

설치

npm install
npm run build

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

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

Claude Code에 등록

{
  "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 199 + K-IFRS 1000+ + 감사기준서 2001200 + 내부회계관리제도 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처럼 로그인 계정으로 온디맨드 조회하는 정도의 사용 패턴에서는 콘텐츠 자체의 저작권 리스크는 낮다고 판단한다.

테스트

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