K-Sign MCP Server

서버 이름	ksign (표시명: K-Sign)
설명	국립국어원 공공 수어 데이터(3만 건+)를 검색·조회하는 한국수어(KSL) MCP 서버. 수어 단어, 수형 설명, 이미지·영상 URL을 AI에게 제공합니다.
Git	https://github.com/a4file/k-sign-mcp-server
MCP Endpoint	https://k-sign-mcp-server.playmcp-endpoint.kakaocloud.io/mcp
인증	없음

Claude Desktop, ChatGPT MCP Client, 카카오 PlayMCP 등 MCP 클라이언트에서 사용할 수 있습니다.

기능

Tool	설명
search_sign	한국어 키워드로 수어 검색 (FTS5 + LIKE 폴백)
get_sign_detail	수어 ID로 상세 정보·이미지·영상 URL 조회

데이터 소스 (Phase 2)

국립국어원 KCISA Open API에서 실제 sldict.korean.go.kr 미디어 URL을 수집합니다.

데이터셋	API	약 件수
일상생활 수어	getCTE01701	~7,500
전문용어 수어	getCTE01702	~10,000
문화정보 수어	getCTE01703	~1,200
통합 수어정보	API_CNV_054	~19,000

API마다 인증키가 다를 수 있습니다. 아래 공공데이터 수집 참고.

아키텍처

Clean Architecture + DDD

src/
├── domain/sign/              # SignTerm, Repository, errors
├── application/sign/         # SearchSign, GetSignDetail UseCase
├── infrastructure/
│   ├── persistence/sqlite/   # SQLite + FTS5
│   ├── collectors/culture-sign/  # KCISA API 수집기
│   ├── transport/            # stdio / HTTP (Fastify)
│   └── di/
├── interfaces/mcp/           # MCP tool adapters
└── config/env.ts

• MCP SDK: @modelcontextprotocol/server 2.0.0-alpha.2
• DB: SQLite (기본) → PostgreSQL 교체 가능 (SignTermRepository 인터페이스)

요구 사항

• Node.js 22+
• npm 10+

빠른 시작

npm install
cp .env.example .env
npm run db:setup      # migrate + 공공 API 수집 (키 필요)
npm run dev           # stdio MCP

HTTP 모드 (배포/PlayMCP):

MCP_TRANSPORT=http npm run dev
# Health: GET http://localhost:8000/health
# MCP:    POST http://localhost:8000/mcp

프로덕션:

npm run build && npm start

환경 변수

서버

변수	기본값	설명
MCP_TRANSPORT	stdio	stdio | http
MCP_SERVER_NAME	k-sign-mcp-server	MCP 서버 이름
HTTP_HOST	0.0.0.0	HTTP 바인드 호스트
HTTP_PORT / PORT	8000	HTTP 포트 (KC는 PORT 우선)
DB_PROVIDER	sqlite	sqlite | postgres
SQLITE_PATH	./data/ksign.db	SQLite 경로
SEARCH_RESULT_LIMIT	20	검색 결과 상한
LOG_LEVEL	info	로그 레벨

공공데이터 수집

변수	설명
DATA_GO_KR_SERVICE_KEY	공통 키 (단일 키 모드)
DATA_GO_KR_SERVICE_KEY_DAILY	일상생활 수어
DATA_GO_KR_SERVICE_KEY_PROFESSIONAL	전문용어 수어
DATA_GO_KR_SERVICE_KEY_CULTURE	문화정보 수어
DATA_GO_KR_SERVICE_KEY_COMPREHENSIVE	통합 수어정보
KCISA_API_IP_FALLBACK	api.kcisa.kr DNS 실패 시 IP (기본 175.125.91.8)
COLLECT_ON_START	Docker 시작 시 자동 수집
COLLECT_PAGE_SIZE	페이지 크기 (기본 100)
COLLECT_REQUEST_DELAY_MS	요청 간격 ms (기본 200)
USE_SAMPLE_DATA	키 없을 때 샘플 5건 (데모용)

공공데이터 수집

1. API 키 발급

문화공공데이터광장 또는 공공데이터포털에서 API별 활용신청:

API	환경변수
일상생활 수어	DATA_GO_KR_SERVICE_KEY_DAILY
전문용어 수어	DATA_GO_KR_SERVICE_KEY_PROFESSIONAL
문화정보 수어	DATA_GO_KR_SERVICE_KEY_CULTURE
통합 수어정보	DATA_GO_KR_SERVICE_KEY_COMPREHENSIVE

키가 API마다 다를 때 (권장):

DATA_GO_KR_SERVICE_KEY_DAILY=...
DATA_GO_KR_SERVICE_KEY_PROFESSIONAL=...
DATA_GO_KR_SERVICE_KEY_CULTURE=...
DATA_GO_KR_SERVICE_KEY_COMPREHENSIVE=...

개별 키를 하나라도 넣으면 DATA_GO_KR_SERVICE_KEY로 나머지가 자동 대체되지 않습니다. 키가 있는 API만 수집됩니다.

2. 수집 실행

npm run db:migrate    # 스키마만
npm run db:collect    # API 수집 → DB 저장
npm run db:setup      # migrate + collect

504 타임아웃 등 일시 오류는 자동 재시도하며, 실패 시 이미 수집한 페이지는 유지합니다.

PlayMCP in KC 배포

항목	값
MCP 식별자	ksign
Git 저장소	https://github.com/a4file/k-sign-mcp-server
Active Endpoint	https://k-sign-mcp-server.playmcp-endpoint.kakaocloud.io/mcp

Git 소스 빌드 (환경변수 입력 칸 없음)

KC Git 소스 빌드 화면에는 PAT·Git URL만 있고 런타임 환경변수 입력란이 없습니다.
이 저장소는 이미 수집된 SQLite DB(docker/seed/ksign.db, 약 3.7만 건)를 Docker 이미지에 포함하므로, KC에서 API 키 없이도 검색이 동작합니다.

1. PlayMCP 콘솔 → Git 소스 빌드
2. Git URL: https://github.com/a4file/k-sign-mcp-server (공개 저장소 → PAT 불필요)
3. 브랜치: main, Dockerfile: Dockerfile
4. 등록 후 빌드·배포 완료되면 Endpoint로 MCP 연결

데이터를 다시 수집해 이미지에 반영하려면 로컬에서:

npm run db:setup
npm run db:export-seed   # data/ksign.db → docker/seed/ksign.db
git add docker/seed/ksign.db && git commit && git push

KC에서 환경변수를 넣을 수 있는 다른 경로가 생기면, 아래 키로 COLLECT_ON_START=true 시 컨테이너 기동 시 재수집도 가능합니다.

DATA_GO_KR_SERVICE_KEY_DAILY=...
DATA_GO_KR_SERVICE_KEY_PROFESSIONAL=...
DATA_GO_KR_SERVICE_KEY_CULTURE=...
DATA_GO_KR_SERVICE_KEY_COMPREHENSIVE=...
COLLECT_ON_START=true

.env는 git에 올리지 마세요.

Docker

docker compose up --build

• Health: GET http://localhost:8000/health
• MCP: POST http://localhost:8000/mcp

Claude Desktop 연동

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "k-sign": {
      "command": "node",
      "args": ["/absolute/path/to/k-sign-mcp-server/dist/index.js"],
      "env": {
        "SQLITE_PATH": "/absolute/path/to/k-sign-mcp-server/data/ksign.db"
      }
    }
  }
}

MCP Tool 예시

search_sign

{ "keyword": "안녕하세요" }

{
  "results": [
    {
      "id": "ksign-daily-…",
      "word": "안녕하세요",
      "description": "인사 표현",
      "imageUrl": "http://sldict.korean.go.kr/multimedia/…jpg",
      "videoUrl": "http://sldict.korean.go.kr/multimedia/…mp4"
    }
  ]
}

get_sign_detail

{ "signId": "ksign-daily-…" }

테스트

npm test
npm run test:coverage

Git 커밋 설정 (a4file 계정)

Vercel/GitHub 연동은 a4file 프로필 하나만 사용합니다. 커밋이 a4file-ai로 잡히지 않도록 저장소 루트에서 한 번 실행하세요:

./scripts/setup-git.sh

이 스크립트는:

• 커밋 작성자를 a4file GitHub noreply 이메일로 설정 (116946770+a4file@users.noreply.github.com)
• Co-authored-by: Cursor / a4file-ai 트레일러를 커밋 메시지에서 자동 제거하는 Git hook 활성화

푸시는 gh auth login으로 a4file 계정이 active인지 확인 후 진행하세요.

npm 스크립트

스크립트	설명
npm run dev	개발 서버 (tsx watch)
npm run build	TypeScript 빌드
npm run db:migrate	DB 스키마 생성
npm run db:collect	공공 API 수집
npm run db:setup	migrate + collect

PostgreSQL 전환 (향후)

1. PostgresSignTermRepository 구현 완료 상태
2. .env: DB_PROVIDER=postgres, POSTGRES_URL=…

라이선스

MIT