toss-mcp

AI 코딩 에이전트에게 토스 개발자 문서, 기본 제공 아이콘, 공식 Apps in Toss 예제를 제공하는 MCP 서버

토스 개발자 문서(앱인토스, TDS React Native, TDS Mobile)의 최신 내용, 토스 기본 제공 아이콘, 공식 Apps in Toss 예제를 AI가 검색할 수 있도록 제공하는 Model Context Protocol (MCP) 서버입니다.

주요 기능

• AI 에이전트가 토스 공식 문서를 바로 검색해 답변에 활용할 수 있습니다.

• 문서 검색 시 공식 문서군, 내장 배포 가이드, 현장 노트별 필터를 적용할 수 있습니다.

• 공식 문서에 없는 콘솔/담당자 확인 사항은 큐레이션된 field_notes로 검색되며, 앱인토스 관련 쿼리에는 함께 반환됩니다.

• list_sources로 실제 수집 중인 llms.txt/llms-full.txt 원천과 청크 수를 확인할 수 있습니다.

• 최신 문서가 필요할 때 sync_sources로 수동 동기화할 수 있습니다.

• 앱인토스 번들의 환경값 검증부터 CLI 업로드, 콘솔 검토·출시까지 범용 배포 체크리스트를 제공합니다.

• 토스 아이콘 카탈로그를 검색해 아이콘 이름/URL을 빠르게 찾을 수 있습니다.

• 아이콘 타입(icon-*, icn-*, u1F...)에 맞는 권장 컴포넌트 사용법을 바로 안내받을 수 있습니다.

• 실행할 때마다 공식 예제 저장소 main의 최신 commit을 확인하고, 변경된 경우 안전한 텍스트 파일만 선별해 캐시를 갱신합니다.

• 공식 예제를 예제명·플랫폼·언어·SDK 버전별로 찾고 원본 파일의 원하는 줄 범위를 조회할 수 있습니다.

Related MCP server: PortOne Global MCP Server

빠른 시작

필수 조건

• Python 3.11+

• uv (uvx 사용 시)

원격 실행 (uvx)

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

• command: uvx

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

@main과 --refresh를 함께 사용하므로 MCP를 실행할 때마다 최신 toss-mcp commit을 확인하고 자동으로 업데이트합니다. 재현 가능한 특정 릴리스를 고정하려면 @main을 @v2.5.0으로 바꾸고 --refresh를 제거하세요.

Claude Code

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

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

Codex

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

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

Gemini CLI

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

{
  "mcpServers": {
    "toss-docs": {
      "command": "uvx",
      "args": ["--refresh", "--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": ["--refresh", "--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

토스 개발자 문서와 내장 보완 자료를 키워드로 검색합니다. 공식 send-message 스펙에 없는 이동 URL {{ 변수 }} 치환처럼 콘솔/담당자 확인 사항은 field_notes에 있습니다. apps_in_toss만 필터해도 관련 현장 노트는 함께 반환됩니다.

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

소스 목록

list_sources

검색 가능한 소스, 공식 index/full 원천 URL, 수집 방식, 현재 검색 청크 수를 보여줍니다.

현재 공식 원천

index와 full은 모두 변경 감지에 사용하지만, 같은 내용을 검색 결과에 중복 저장하지는 않습니다. 확인 결과 tossmini-docs.toss.im 도메인 루트와 /tds-web/에는 현재 별도 llms.txt/llms-full.txt가 없습니다.

별도 공식 개발 문서인 토스페이먼츠 개발자센터도 확인했지만, 앱인토스/TDS와 다른 제품군이고 전용 공식 MCP를 제공하므로 이 서버에는 합치지 않았습니다. 이 서버의 범위는 앱인토스 미니앱과 그 TDS 문서로 유지합니다. 공식 문서에 없는 콘솔/담당자 확인 사항은 field_notes로 큐레이션하며, 커뮤니티를 크롤하지 않습니다. 현재 send-message 이동 URL {{ 변수 }} 치환 노트의 근거는 랜딩 URL 동적 파라미터, 발송 건별 동적 랜딩 URL입니다.

sync_sources

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

search_icons

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

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

빠른 판단 규칙

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

• 이름이 u1F...면 URL 기반 (Asset.Image, Asset.ContentImage)

list_examples

검색 가능한 Apps in Toss 공식 예제와 SDK 버전을 보여줍니다.

search_examples

공식 예제의 README와 선별된 소스 코드를 검색합니다.

각 결과에는 원본 저장소 경로, 줄 번호, commit SHA, SDK 버전, Apache-2.0 라이선스가 표시됩니다.

get_example_file

search_examples가 반환한 경로에서 원하는 줄 범위를 조회합니다. 한 번에 최대 400줄까지 반환합니다.

sync_examples

공식 예제 저장소 main의 최신 commit을 수동 확인합니다. force=true이면 같은 commit도 다시 다운로드하고 라이선스와 파일을 재검증합니다.

기술적 특징

• 토스 개발자 공식 문서 3개 문서군·6개 index/full 원천 자동 추적

• ETag → Last-Modified → 본문 SHA256 순서의 변경 감지(ETag 없는 원천 지원)

• 앱인토스 개별 Markdown 페이지 수집 실패 시 루트 llms-full.txt 폴백

• 마크다운 헤더 기반 지능형 청킹 (H1 → H2 → H3 재귀 분할)

• 줄바꿈 없는 긴 HTML/table 행까지 청크 최대 3,000자 보장

• 2단계 키워드 검색 (정확 매칭 우선, 부분 매칭 폴백)

• 원천 validator 기반 변경 감지 + 로컬 캐시로 빠른 재시작

• 비동기 병렬 수집 (동시 8개 요청)

• 패키지 내장 범용 앱인토스 배포 실전 가이드

• 아이콘 카탈로그 압축 리소스(toss_mcp/data/toss_icons.json.gz) 로드 지원

• 공식 예제 GitHub API ETag + 최신 commit SHA 변경 감지

• Apache-2.0 검증 후 README·package manifest·소스 코드만 allowlist 수집

• 이미지·로고·환경 파일·인증서·lockfile·생성 파일 제외

• 함수·hook·컴포넌트와 줄 범위를 보존하는 코드 전용 청킹

• 검증 또는 네트워크 장애 시 마지막 정상 예제 스냅샷 유지

동작 방식

공식 index/full 원천 6개 변경 감지
       ↓
  앱인토스: index 링크의 개별 페이지 병렬 수집
  TDS 2종: full 문서 수집
       ↓ (개별 페이지 누락 시 앱인토스 full 폴백)
  마크다운 헤더 기반 청킹 (최대 3,000자)
       ↓
  공식 문서 로컬 캐시 (~/.toss-mcp-cache/)
       +
  패키지 내장 배포 가이드
       ↓
  소스 필터 가능한 키워드 검색

공식 예제 main commit 조건부 확인
       ↓ (SHA 변경 시)
  GitHub tarball 다운로드
       ↓
  Apache-2.0/NOTICE + 경로·크기 검증
       ↓
  allowlist 텍스트 선별 + 코드 청킹
       ↓
  원자적 예제 캐시 교체

• 캐시: 시작 시 각 문서군의 index와 full 원천 validator를 비교하고, 변경이 없으면 캐시에서 로드합니다. ETag나 Last-Modified가 없으면 본문 SHA256을 비교합니다.

• 부분 장애: 갱신 중 특정 문서군 수집에 실패하면 해당 문서군의 기존 캐시를 유지합니다.

• 내장 가이드: 배포 가이드와 현장 노트는 패키지에서 매번 로드하므로 공식 문서 캐시에 섞이거나 오래된 캐시에 가려지지 않습니다. 현장 노트는 커뮤니티를 크롤하지 않고, 담당자 확인이 있는 항목만 큐레이션합니다.

• 재동기화: sync_sources(force=True) 호출 또는 캐시 디렉토리 삭제 후 재시작하면 됩니다.

• 공식 예제 최신화: 매 실행 시 최신 SHA를 확인합니다. 실패하거나 라이선스가 달라지면 새 스냅샷을 거부하고 마지막 정상 캐시를 유지합니다.

• 공식 예제 출처: 검색 결과마다 commit 고정 원본 URL과 Apache-2.0 고지를 포함합니다.

공식 원천 실수집 검증

2026-08-10에 캐시 없는 상태로 공식 원천을 직접 수집하고 검색까지 확인한 결과입니다. 문서가 추가·삭제되면 개수는 달라질 수 있습니다.

• 6개 index/full 원천이 모두 HTTP 200으로 응답하고 수집됐습니다.

• 연속으로 validator를 계산했을 때 6개 모두 같은 값으로 판정됐습니다.

• ait deploy 검토 요청, 미니앱 출시 롤백, IconButton 검색을 각 대상 소스에서 확인했습니다.

프로젝트 구조

toss-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── THIRD_PARTY_NOTICES.md
└── toss_mcp/
    ├── __init__.py
    ├── main.py          # MCP 서버 엔트리포인트
    ├── collector.py     # 문서 수집 (httpx 비동기)
    ├── chunker.py       # 마크다운 청킹
    ├── searcher.py      # 키워드 검색
    ├── example_collector.py # GitHub 최신 SHA·라이선스·allowlist 수집
    ├── example_chunker.py   # Markdown/TS/TSX/JS 예제 청킹
    ├── example_searcher.py  # 예제 검색·카탈로그
    ├── examples.py      # 최신성 확인 + 스냅샷 구성
    ├── icons.py         # 아이콘 카탈로그 로드/검색 + 타입별 추천
    ├── knowledge.py     # 패키지 내장 보완 가이드 로드
    ├── cache.py         # JSON 캐시 + 해시 관리
    └── data/
        ├── toss_icons.json.gz
        ├── deployment_guide.md
        ├── field_notes/
        │   └── send-message-landing-url.md
        └── licenses/
            └── apps-in-toss-examples-APACHE-2.0.txt

라이선스

toss-mcp 자체 코드는 MIT License입니다.

런타임에 선별·캐시하는 toss/apps-in-toss-examples의 예제 자료는 Apache License 2.0이며, 해당 조건은 MIT로 대체되지 않습니다. 자세한 출처와 고지는 THIRD_PARTY_NOTICES.md를 참고하세요.

이 프로젝트는 독립적인 오픈소스 프로젝트이며 Toss의 보증이나 제휴를 의미하지 않습니다.