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 정보 등을 포함

사용 예시:

// 산업기능요원 - 정보처리 업종 - 서울 강남구
{
  "eopjong_gbcd": "산업기능요원",
  "eopjong_cd": "정보처리",
  "sido_addr": "서울특별시",
  "sigungu_addr": "강남구"
}

// 전문연구요원 - 중소기업 - 채용공고 있음
{
  "eopjong_gbcd": "전문연구요원",
  "gegyumo_cd": "중소기업",
  "chaeyongym": "Y"
}

// 특정 회사명 검색
{
  "eopjong_gbcd": "산업기능요원",
  "eopche_nm": "네이버"
}

업종 코드 목록

제조업 (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: 의존성 자동 업데이트 제안 (매주)

릴리즈 생성 방법

# 버전 태그 생성 및 푸시
git tag v1.0.0
git push origin v1.0.0

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

설치

pnpm install

빌드

pnpm build

실행

pnpm start

개발 모드

pnpm dev

테스트

pnpm test

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

{
  "mcpServers": {
    "mma": {
      "command": "node",
      "args": ["/path/to/agent-for-agent/dist/index.js"]
    }
  }
}

프로젝트 구조

agent-for-agent/
├── src/
│   ├── index.ts          # MCP 서버 메인 엔트리포인트
│   ├── mma-api.ts        # MMA API 클라이언트 함수
│   ├── types.ts          # TypeScript 타입 정의
│   └── __tests__/
│       └── mma-api.test.ts  # 테스트 코드
├── dist/                 # 빌드 결과물 (TypeScript 컴파일 후)
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

기술 스택

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를 모킹하여 실제 네트워크 요청 없이 테스트합니다.

# 전체 테스트 실행
pnpm test

# Watch 모드로 테스트
pnpm test:watch

코드 품질

# Linting
pnpm lint

# Formatting
pnpm format

라이선스

MIT

주의사항

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

기여

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

참고 자료