nunchi-translator-mcp

한국어 우선 README — 본문은 한국어 단락을 먼저, 영어 보조 단락을 그 다음에 배치합니다.

한 줄 요약

nunchi-translator-mcp는 눈치(Nunchi) 기반 코칭, 확장, 소셜 분석 도구를 노출하는 Model Context Protocol(MCP) 서버입니다. HTTP와 stdio 두 가지 전송 방식을 지원하며, 호스트 LLM 클라이언트에서 도구로 호출할 수 있습니다.

Related MCP server: Meetup Coordinator MCP

One-line Summary

nunchi-translator-mcp is a Model Context Protocol (MCP) server that exposes Nunchi-based coaching, expansion, and social-analysis tools. It ships with both HTTP and stdio transports so host LLM clients can register the tools directly.

상태 한눈에 보기 / Status at a Glance

빠른 흐름 / Quick Flow

1. 호스트 LLM 클라이언트가 MCP 클라이언트를 통해 nunchi-translator-mcp에 연결합니다.

2. http-server.ts(기본) 또는 stdio-server.ts 중 하나가 선택되어 MCP 핸드셰이크를 처리합니다.

3. src/mcp/server.ts가 등록된 도구 목록(코치·확장·소셜·메타데이터)을 클라이언트에 알립니다.

4. 클라이언트가 도구를 호출하면 nunchi-coach.ts, nunchi-expansion.ts, nunchi-social-tools.ts 중 해당 모듈이 zod 스키마로 입력을 검증합니다.

5. 결과가 MCP 응답으로 직렬화되어 호스트 모델에 반환됩니다.

목차 / Table of Contents

• 목적과 사용처 / Purpose and Audience

• 패키지 구성 / Package Contents

• 아키텍처 / Architecture

• 빠른 시작 / Quickstart

• 설정 / Configuration

• 명령어 / Commands Reference

• 로컬 개발 / Local Development

• 테스트 / Testing

• Docker 배포 / Container Build

• API와 진입점 / API and Entry Points

• 유지보수와 문의 / Maintainers and Contact

• 추가 문서 / Further Documentation

목적과 사용처 / Purpose and Audience

nunchi-translator-mcp는 한국어권 사용자 상호작용에서 눈치(상황 맥락 읽기)를 보조하는 MCP 도구를 제공합니다. LLM 에이전트가 대화·관계·상황 데이터를 해석할 때, 다음을 위한 도구 표면을 노출합니다.

• nunchi-coach : 한국어 대화에서 어조·맥락 코칭

• nunchi-expansion : 짧은 입력을 확장·정제

• nunchi-social-tools : 사회적 신호를 분석하는 보조 도구

• tool-metadata : 등록된 도구의 메타데이터 질의

주 사용자는 **MCP 호스트(예: Claude Desktop, IDE 플러그인)**를 통해 본 서버를 등록하고, 모델이 필요할 때 위 도구를 호출하도록 설정하는 개발자/운영자입니다.

This project targets MCP host application developers and operators who want to plug Korean-context-aware Nunchi tools into their LLM agents without re-implementing them per client.

패키지 구성 / Package Contents

아키텍처 / Architecture

본 서버는 단일 프로세스 MCP 서버이며, 전송 계층만 HTTP 또는 stdio로 갈립니다.

요청 흐름:

1. 클라이언트가 HTTP 또는 stdio로 MCP 초기화 요청 전송

2. mcp/server.ts가 등록된 도구 목록을 ListTools 응답으로 반환

3. 클라이언트가 특정 도구를 호출하면 해당 도구 모듈이 nunchi-schemas.ts로 입력을 검증

4. 도구 본 로직이 결과를 생성하고 SDK가 JSON-RPC 응답으로 직렬화

5. 호출자는 결과를 다시 모델 컨텍스트에 주입

빠른 시작 / Quickstart

1) 의존성 설치 / Install dependencies

bun install --frozen-lockfile

2) 개발 모드 (HTTP, 핫 리로드) / Dev (HTTP, hot reload)

bun run dev

3) stdio 모드로 실행 / Run in stdio mode

bun run mcp:stdio

4) 빌드 산출물 없이 즉시 검증 / One-shot verify

bun run verify

설정 / Configuration

본 서버는 src/config.ts를 통해 환경 변수를 읽습니다. 자세한 변수 목록은 src/config.ts를 직접 확인해 주세요. 컨테이너 기본값은 PORT=3000, NODE_ENV=production입니다.

민감한 값(예: 외부 LLM 호출 키)은 저장소 외부에서 주입해 주세요. 본 README는 예시로 비공개 IP나 컨테이너 번호를 하드코딩하지 않습니다.

명령어 / Commands Reference

로컬 개발 / Local Development

• 런타임은 Bun 1.3.10 이상을 권장합니다. Dockerfile과 동일한 베이스를 사용하면 환경 차이를 줄일 수 있습니다.

• 린트와 포맷은 Biome가 단일 소스입니다. 커밋 전 bun run format을 실행해 주세요.

• 새 도구를 추가할 때는 다음 순서를 권장합니다.

  1. src/mcp/nunchi-schemas.ts에 zod 스키마 정의

  2. 해당 기능 모듈(nunchi-coach.ts 등)에 핸들러 구현

  3. src/mcp/server.ts에서 도구 등록

  4. tests/에 단위 테스트 추가

  5. bun run verify로 일괄 검증

테스트 / Testing

• 테스트 프레임워크: Bun 내장 bun test

• 테스트 위치: tests/

• 현재 포함된 테스트:

  • config.test.ts — 설정 파싱 검증

  • http-mcp.test.ts — HTTP 전송 MCP 동작 검증

  • nunchi-coach.test.ts — 코칭 도구 동작 검증

bun test

새 도구를 등록한 경우, bun run verify로 정적 분석과 테스트를 함께 실행해 회귀를 방지하세요.

Docker 배포 / Container Build

멀티 스테이지 Dockerfile이 제공됩니다. 빌드 산출물만 담는 경량 이미지를 만듭니다.

docker build -t nunchi-translator-mcp:0.1.0 .
docker run --rm -p 3000:3000 nunchi-translator-mcp:0.1.0

Kakao Cloud Git 소스 빌드를 사용하는 경우 docs/kakao-cloud-git-source-build.md의 절차를 참고하세요.

API와 진입점 / API and Entry Points

MCP는 JSON-RPC 기반이지만 전송에 따라 진입 형태가 달라집니다.

각 도구의 입력·출력 스키마는 src/mcp/nunchi-schemas.ts와 src/mcp/tool-metadata.ts를 통해 자체 설명(self-describing)됩니다. 자세한 도구 시그니처는 소스 코드를 직접 확인하세요.

유지보수와 문의 / Maintainers and Contact

이 저장소는 사내 비공개 패키지(private: true)이며 외부 배포를 전제로 하지 않습니다. 운영 및 변경 요청은 저장소 소유 팀에 문의해 주세요.

• 저장소 소유 / Owner: 본 저장소를 운영하는 사내 팀

• 이슈 트래커: 저장소 내 Issues 탭 사용

• 보안 이슈: 공개 이슈 대신 사내 보안 채널 사용

추가 문서 / Further Documentation

• docs/kakao-cloud-git-source-build.md — Kakao Cloud Git 소스 빌드 절차

• CONTRIBUTING.md — 기여 가이드 (해당 문서 우선)

• LICENSE — 라이선스 전문

• MCP 프로토콜 사양: Model Context Protocol 공식 문서

라이선스 / License

LICENSE 파일을 참조하세요. 본 패키지는 private: true로 표시되어 있으므로 외부 재배포를 금합니다.