MMA MCP Server

병무청 병역일터(Military Manpower Administration) API를 위한 Model Context Protocol (MCP) 서버입니다.

기능

이 MCP 서버는 병무청 병역일터에서 병역특례 지정업체 정보를 조회할 수 있는 도구를 제공합니다.

search_designated_entities

병역특례 업체 검색 및 조회 기능을 제공합니다.

파라미터:

필수 파라미터

• eopjong_gbcd (string): 복무 형태 선택 (필수)

  • '산업기능요원' - 산업기능요원

  • '전문연구요원' - 전문연구요원

  • '승선근무예비역' - 승선근무예비역

선택 파라미터

• al_eopjong_gbcd (array): 업종 그룹 코드 리스트

  • 예: ['정보처리', '게임SW', '전자']

• eopjong_gbcd_list (array): 업종 선택 목록

  • 업종 코드 배열

• gegyumo_cd (string): 기업 규모

  • '' - 전체 (기본값)

  • '대기업' - 대기업

  • '중소기업' - 중소기업

  • '중견기업' - 중견기업

  • '농어민후계' - 농어민 후계자

  • '기타' - 기타

• eopjong_cd (string | array): 업종 코드

  • 단일 값 또는 배열로 전달 가능

  • 예: '정보처리' 또는 ['정보처리', '전자']

• eopche_nm (string): 회사 이름

  • 특정 회사명으로 검색

  • 빈 값은 전체 조회

• sido_addr (string): 시/도 선택

  • 예: '서울특별시', '경기도', '부산광역시' 등

• sigungu_addr (string): 시/군/구 주소

  • sido_addr의 하위 지역

  • 예: '강남구', '수원시' 등

  • 빈 값은 해당 시/도 전체 조회

• chaeyongym (string): 병무청 채용 공고 등록 업체 여부

  • '' - 전체 (기본값)

  • 'Y' - 채용 공고 등록 업체만

• bjinwonym (string | array): TO 유무

  • 'H' - 현역 TO 있음

  • 'B' - 보충역 TO 있음

  • ['H', 'B'] - 현역/보충역 모두 조회

반환값:

• CSV 형식의 검색 결과 (헤더 포함)

• 최대 30개의 업체 정보

• 각 행은 업체명, 업종, 위치, TO 정보 등을 포함

사용 예시:

업종 코드 목록

제조업 (Manufacturing)

• 철강, 기계, 전기, 전자, 화학, 섬유, 신발

• 시멘요업, 생활용품, 통신기기

• 정보처리, 게임SW, 영상게임

• 의료의약, 식음료

• 농산물가공, 수산물가공, 임산물가공, 동물약품

• 애니메이션

광업 (Mining)

• 석탄채굴, 일반광물채굴, 선광제련

에너지 (Energy)

• 에너지

건설업 (Construction)

• 국내건설, 국외건설

운수업 (Transportation)

• 내항화물, 외항화물, 내항선박관리, 외항선박관리

수산업 (Fisheries)

• 근해, 원양

CI/CD

이 프로젝트는 GitHub Actions를 사용하여 자동화된 CI/CD 파이프라인을 제공합니다.

자동화 워크플로우

• CI (Continuous Integration): main, develop 브랜치에 push하거나 PR 생성 시 자동으로 린트, 테스트, 빌드를 실행합니다.

• Release: v*.*.* 형식의 태그를 push하면 자동으로 GitHub Release를 생성하고 빌드 결과물을 첨부합니다.

• CodeQL: 보안 취약점 자동 분석 (매주 월요일 + PR/Push 시)

• Dependabot: 의존성 자동 업데이트 제안 (매주)

릴리즈 생성 방법

자세한 내용은 .github/workflows/README.md를 참조하세요.

설치

빌드

실행

개발 모드

테스트

MCP 클라이언트 설정

Claude Desktop 또는 다른 MCP 클라이언트에서 이 서버를 사용하려면, 설정 파일에 다음을 추가하세요:

Claude Desktop 설정

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

프로젝트 구조

기술 스택

• Runtime: Node.js 18+

• Language: TypeScript 5.x

• Framework: MCP SDK (@modelcontextprotocol/sdk)

• HTTP Client: Native Fetch API

• Excel Parser: xlsx (SheetJS)

• Validation: Zod

• Testing: Jest + ts-jest

• Code Quality: ESLint, Prettier

• Package Manager: pnpm

개발 가이드

타입 시스템

이 프로젝트는 TypeScript의 strict mode를 사용하며, 모든 타입이 types.ts에 정의되어 있습니다.

API 클라이언트

mma-api.ts는 병무청 API와 통신하는 로직을 포함합니다:

• Form data 생성 및 인코딩

• HTTP 요청 처리

• Excel 파일 파싱 및 CSV 변환

• 에러 핸들링

테스트

테스트는 Jest를 사용하며, fetch API를 모킹하여 실제 네트워크 요청 없이 테스트합니다.

코드 품질

라이선스

MIT

주의사항

이 서버는 병무청 병역일터의 공개 API를 사용합니다. API 사용 시 해당 사이트의 이용 약관을 준수해야 합니다.

기여

버그 리포트나 기능 제안은 이슈로 등록해주세요.

참고 자료

• Model Context Protocol (MCP)

• 병무청 병역일터

• MCP SDK Documentation