# kifrs-mcp-server

kifrs.com(K-IFRS/K-GAAP 기준서)을 Claude에서 바로 조회할 수 있게 해주는 원격 MCP 서버입니다.

제공 도구 3개:

- `kifrs_list_standards` — K-IFRS 기준서 번호/제목 목록
- `kifrs_get_standard(code, section)` — 특정 기준서의 `overview`(주요특징) / `body-introduction`(본문) / `revision`(제개정경과) 가져오기
- `kifrs_search(query)` — kifrs.com 내 키워드 검색 (정확한 번호를 모를 때, K-GAAP·감사기준서·내부회계 등도 이걸로 커버)

내부적으로 Firecrawl API를 호출해 kifrs.com의 JS 렌더링 페이지를 markdown으로 긁어옵니다. 로컬에서 `node server.js`로 핸드셰이크(initialize/tools/list/tools/call) 테스트까지 완료된 코드입니다.

---

## 0. 사전 준비물

1. **Firecrawl API 키** — https://www.firecrawl.dev 가입 후 대시보드에서 발급 (`fc-...` 형태). 무료 플랜으로도 충분히 테스트 가능합니다.
   - ⚠️ Claude.ai에 이미 연결해두신 Firecrawl 커넥터의 키와는 별개로, 이 서버용으로 새로 키를 발급받아 환경변수로 넣어주세요 (서버 코드가 직접 Firecrawl REST API를 호출하기 때문입니다).
2. **GitHub 계정** (코드 업로드용)
3. **Render.com 계정** (무료 웹 서비스 호스팅용) — 또는 평소 쓰시는 다른 Node 호스팅(Fly.io, Railway 등)도 무방합니다. 아래는 Render 기준으로 안내합니다.

---

## 1. 로컬 테스트 (선택, 권장)

```bash
npm install
FIRECRAWL_API_KEY=fc-여기에본인키 node server.js
```

다른 터미널에서:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kifrs_get_standard","arguments":{"code":"1016","section":"overview"}}}'
```

정상이면 1016호(유형자산) 기준서의 주요 특징이 markdown으로 돌아옵니다.

---

## 2. GitHub에 올리기

```bash
cd kifrs-mcp-server
git init
git add .
git commit -m "init kifrs mcp server"
git branch -M main
git remote add origin https://github.com/<본인계정>/kifrs-mcp-server.git
git push -u origin main
```

`.gitignore`에 `node_modules`와 `.env`가 포함되어 있으니 API 키가 실수로 올라갈 일은 없습니다.

---

## 3. Render.com에 배포

1. https://render.com 로그인 → **New > Web Service**
2. 방금 push한 GitHub 저장소 선택
3. 설정값:
   - **Runtime**: Node
   - **Build Command**: `npm install`
   - **Start Command**: `node server.js`
   - **Instance Type**: Free
4. **Environment** 탭에서 환경변수 추가:
   - `FIRECRAWL_API_KEY` = `fc-본인키`
5. **Create Web Service** 클릭 → 배포 완료되면 `https://kifrs-mcp-server-xxxx.onrender.com` 같은 URL이 생성됩니다.
6. 브라우저로 `https://kifrs-mcp-server-xxxx.onrender.com/` 접속해서 "kifrs-mcp-server is running" 문구가 보이면 정상 배포 완료.

> 무료 플랜은 일정 시간 미사용 시 슬립 상태가 되어 첫 요청 응답이 몇 초 느릴 수 있습니다. 사용 빈도가 높다면 유료 플랜(Starter)으로 올리는 걸 권장합니다.

---

## 4. Claude.ai에 커스텀 커넥터로 등록

1. Claude.ai 접속 → **설정(Settings) > Connectors**
2. **Add custom connector** 클릭
3. **Remote MCP server URL**에 다음을 입력:
   ```
   https://kifrs-mcp-server-xxxx.onrender.com/mcp
   ```
   (`/mcp` 경로를 꼭 붙이세요)
4. **Add** 클릭 → 연결 완료
5. 대화창 하단 **"+"** 버튼 → **Connectors**에서 `kifrs-lookup` 토글 On

이후로는 "1016호 유형자산 인식조건 알려줘", "1113호 DLOM 관련 내용 찾아줘" 같은 요청에 Claude가 이 도구들을 직접 호출합니다.

---

## 주의사항

- **저작권/이용약관**: kifrs.com은 한국회계기준원 콘텐츠를 제공하는 민간 플랫폼입니다. 개인 업무 참고용으로만 사용하시고, 대량 크롤링이나 재배포는 피하시는 게 안전합니다. `kifrs_search`/`kifrs_get_standard`는 필요한 페이지만 그때그때 가져오도록 설계했습니다 (전체 사이트를 미리 긁어 저장하지 않음).
- **Firecrawl 크레딧**: scrape 1회당 1크레딧, search는 결과 10개당 2크레딧 소비됩니다(2026년 6월 기준 무료 플랜 월 500~1000크레딧). 사용량이 많아지면 유료 플랜 검토.
- **K-GAAP/감사기준서/내부회계 조회 방식**: `kifrs_list_standards`는 K-IFRS(1001~1118호)만 하드코딩되어 있습니다. K-GAAP(일반기업회계기준 1~32장)은 `overview`/`body-introduction`/`revision` 같은 단축 경로 자체가 사이트에 없어서(실제 테스트 결과 빈 페이지) `kifrs_get_standard`로는 가져올 수 없습니다 — 대신 `kifrs_search`(예: "일반기업회계기준 10장 유형자산 인식조건")로 검색하면 해당 장의 전체 본문과 질의회신까지 정확히 찾아옵니다. 감사기준서·내부회계 기준서도 마찬가지로 `kifrs_search`를 사용하세요.
- 서버 코드는 stateless 모드(요청마다 새 인스턴스)로 동작해 동시 사용자 충돌 걱정 없이 가볍게 운영됩니다.