toss-mcp

AI 코딩 에이전트에게 토스 개발자 문서 및 토스 기본 제공 아이콘 정보를 제공하는 MCP 서버

토스 개발자 문서(앱인토스, TDS React Native, TDS Mobile)에 대한 최신 내용 및 토스에서 제공하는 아이콘 들에 대한 정보를 AI가 검색할 수 있도록 제공하는 Model Context Protocol (MCP) 서버입니다.

주요 기능

• AI 에이전트가 토스 공식 문서를 바로 검색해 답변에 활용할 수 있습니다.
• 문서 검색 시 소스별 필터(apps_in_toss, tds_react_native, tds_mobile)를 적용할 수 있습니다.
• 최신 문서가 필요할 때 sync_sources로 수동 동기화할 수 있습니다.
• 토스 아이콘 카탈로그를 검색해 아이콘 이름/URL을 빠르게 찾을 수 있습니다.
• 아이콘 타입(icon-*, icn-*, u1F...)에 맞는 권장 컴포넌트 사용법을 바로 안내받을 수 있습니다.

빠른 시작

필수 조건

• Python 3.11+
• uv (uvx 사용 시)

원격 실행 (uvx)

아래 클라이언트 설정은 모두 동일한 실행 정보를 사용합니다.

• command: uvx
• args: ["--from", "git+https://github.com/chabinhwang/toss-mcp@main", "toss-mcp"]

Claude Code

설정 파일: ~/.claude/settings.json (mcpServers에 추가)

{
  "toss-docs": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/chabinhwang/toss-mcp@main", "toss-mcp"]
  }
}

Codex

설정 파일: ~/.codex/config.toml (mcp_servers에 추가)

[mcp_servers.toss-docs]
command = "uvx"
args = ["--from", "git+https://github.com/chabinhwang/toss-mcp@main", "toss-mcp"]

Gemini CLI

설정 파일: ~/.gemini/settings.json (mcpServers에 추가)

{
  "mcpServers": {
    "toss-docs": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/chabinhwang/toss-mcp@main", "toss-mcp"]
    }
  }
}

Claude Desktop

설정 파일:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers에 아래를 추가:

{
  "mcpServers": {
    "toss-docs": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/chabinhwang/toss-mcp@main", "toss-mcp"]
    }
  }
}

로컬 설치 (개발용)

git clone https://github.com/chabinhwang/toss-mcp.git
cd toss-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

설정 파일: MCP 클라이언트의 mcpServers 항목

{
  "toss-docs": {
    "command": "/absolute/path/to/toss-mcp/.venv/bin/toss-mcp"
  }
}

제공 도구

search_docs

토스 개발자 문서를 키워드로 검색합니다.

검색어: "앱인토스 결제 API"

파라미터	타입	필수	설명
query	string	O	검색어 (공백으로 구분된 키워드)
source	string	X	소스 필터 (아래 표 참고)

소스 목록

값	설명
apps_in_toss	앱인토스
tds_react_native	TDS React Native
tds_mobile	TDS Mobile

sync_sources

문서를 수동으로 동기화합니다. 최신 문서가 필요할 때 사용합니다.

파라미터	타입	필수	설명
force	boolean	X	true이면 캐시 무시 후 강제 재수집

search_icons

토스 아이콘 카탈로그(toss_icons.json.gz)를 검색하고, 아이콘 타입별 추천 사용 코드를 안내합니다.

검색어: "icon-search-bold-mono"

파라미터	타입	필수	설명
query	string	O	검색어 (아이콘 이름/URL 일부, 공백으로 구분된 키워드)
icon_type	string	X	타입 필터 (icon-*, icn-*, emoji/image)
max_results	number	X	최대 결과 수 (기본 10, 최대 30)

빠른 판단 규칙

• 이름이 icon-/icn-면 name 기반 컴포넌트 (Icon, IconButton, Asset.Icon)
• 이름이 u1F...면 URL 기반 (Asset.Image, Asset.ContentImage)

기술적 특징

• 토스 개발자 문서 3개 소스 자동 수집 (앱인토스, TDS React Native, TDS Mobile)
• 마크다운 헤더 기반 지능형 청킹 (H1 → H2 → H3 재귀 분할)
• 2단계 키워드 검색 (정확 매칭 우선, 부분 매칭 폴백)
• ETag 기반 변경 감지 + 로컬 캐시로 빠른 재시작
• 비동기 병렬 수집 (동시 8개 요청)
• 아이콘 카탈로그 압축 리소스(toss_mcp/data/toss_icons.json.gz) 로드 지원

동작 방식

llms.txt / llms-full.txt 다운로드
       ↓
  링크 파싱 (seed) 또는 그대로 사용 (full)
       ↓
  하위 페이지 병렬 수집 (동시 8개)
       ↓
  마크다운 헤더 기반 청킹 (최대 3,000자)
       ↓
  로컬 캐시 저장 (~/.toss-mcp-cache/)
       ↓
  키워드 검색 제공

• 캐시: 시작 시 소스별 ETag를 비교해 변경 여부를 확인하고, 변경이 없으면 캐시에서 즉시 로드합니다. 변경이 감지된 경우에만 전체 재수집합니다.
• 재동기화: sync_sources(force=True) 호출 또는 캐시 디렉토리 삭제 후 재시작하면 됩니다.

성능 벤치마크

2026-03-13 기준으로, 현재 로컬에서 실행 중인 MCP와 분리하기 위해 매 실행마다 임시 HOME을 사용해 캐시를 격리한 뒤 실측했습니다.

• 실행 경로: 실제 서버 시작 시점과 동일하게 lifespan 기준 _init_chunks() + _init_icons()까지 측정
• 반복 횟수: 각 시나리오 10회
• 시나리오 A: full_recollect_boot 캐시가 없는 상태로 부팅해서 llms.txt / llms-full.txt와 하위 문서를 전부 다시 수집
• 시나리오 B: etag_compare_boot 같은 임시 캐시에서 한 번 받아둔 뒤 다시 부팅해서 ETag만 비교하고, 변경이 없으면 재다운로드 없이 캐시 사용
• 참고: etag_compare_boot는 10/10회 모두 실제로 "변경 없음, 캐시 사용" 경로를 탔습니다.

시나리오	평균	중앙값	최소	최대
full_recollect_boot	4.048s	3.878s	3.667s	5.363s
etag_compare_boot	0.851s	0.803s	0.723s	1.168s

• 평균 기준 차이: 3.197s
• 중앙값 기준 차이: 3.075s
• 평균 기준으로 etag_compare_boot가 약 4.8배 빠름
• 해석: 토스 MCP는 전체 재수집보다, 지금 코드처럼 ETag 비교 후 변경이 없으면 캐시를 사용하는 부팅 경로가 훨씬 빠릅니다.

프로젝트 구조

toss-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
└── toss_mcp/
    ├── __init__.py
    ├── main.py          # MCP 서버 엔트리포인트
    ├── collector.py     # 문서 수집 (httpx 비동기)
    ├── chunker.py       # 마크다운 청킹
    ├── searcher.py      # 키워드 검색
    ├── icons.py         # 아이콘 카탈로그 로드/검색 + 타입별 추천
    ├── cache.py         # JSON 캐시 + 해시 관리
    └── data/
        └── toss_icons.json.gz

라이선스

MIT License