Name: 兵役特例企业搜索MCP服务器
Author: antegral

使用说明

MMA MCP Server

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

기능

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

`search_designated_entities`

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

파라미터:

필수 파라미터

service_type (string): '산업기능요원', '전문연구요원', '승선근무예비역' 중 하나

선택 파라미터

company_size (string): '', '대기업', '중소기업', '중견기업', '농어민후계', '기타'
industry_sectors (string | string[]): 업종 이름, 예: '정보처리' 또는 ['정보처리', '게임SW']
company_name (string): 업체명 검색어
city_province (string): 시/도 이름, 예: '서울특별시'
city_district (string): 시/군/구 검색어
is_hiring (boolean): true이면 병무청 채용 공고 등록 업체로 제한
military_service_status (string | string[]): '현역', '보충역' 또는 두 값의 배열

위 이름은 MCP 도구 인자입니다. 병무청 form POST 필드로의 변환은 서버에서 처리합니다.

반환값:

CSV 형식의 검색 결과 (헤더 포함)
최대 30개의 업체 정보
각 행은 업체명, 업종, 위치, TO 정보 등을 포함

사용 예시:

// 산업기능요원 - 정보처리 업종 - 서울 강남구
{
  "service_type": "산업기능요원",
  "industry_sectors": "정보처리",
  "city_province": "서울특별시",
  "city_district": "강남구"
}

// 전문연구요원 - 중소기업 - 채용공고 있음
{
  "service_type": "전문연구요원",
  "company_size": "중소기업",
  "is_hiring": true
}

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

업종 코드 목록

제조업 (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

내부 HTTP 실행

pnpm serve

node dist/http.js는 0.0.0.0:8936에서 내부 전용 POST /mcp를 제공합니다. stdio와 HTTP는 같은 서버 팩토리와 도구 등록을 사용하며, 네이티브 도구는 search_designated_entities 하나입니다. resources와 prompts는 등록하지 않습니다.

HTTP는 MCP 2025-11-25만 허용하며 SDK의 stateless JSON 응답 모드를 사용합니다. 세션, 쿠키, SSE 및 bearer 인증은 제공하지 않습니다. 모든 요청의 Host는 정확히 mcp.antegral.net이어야 하며, Origin은 없거나 https://mcp.antegral.net이어야 합니다. 이 검사는 GET /healthz, GET /readyz에도 적용됩니다. 프로브는 동시 요청 한도와 별도로 처리하며 종료 중 readiness는 503을 반환합니다.

MCP 요청은 한 번에 하나만 처리하며 JSON-RPC 배치를 거부합니다. 요청 본문 한도는 256 KiB, 헤더 및 본문 수신 제한은 각각 5초, 전체 교환 제한은 75초, 종료 제한은 35초입니다. 연결 종료와 요청 취소는 실제 병무청 fetch 및 응답 스트림에도 전달됩니다. 병무청 다운로드는 60초와 16 MiB로 제한하며 HTTP 오류를 성공 데이터로 바꾸거나 재시도하지 않습니다.

Node.js 24 기반 컨테이너는 UID/GID 10001:10001로 실행합니다. 애플리케이션 자격 증명, 브라우저, 데이터베이스 또는 영구 볼륨은 필요하지 않습니다. 루트 파일 시스템은 읽기 전용으로 둘 수 있으며 쓰기 가능한 임시 경로는 /tmp입니다. 병무청 공개 Excel 다운로드에 대한 HTTPS 통신은 필요합니다.

AMS는 https://antegral.net/mcp의 네 번째 비공개 백엔드로 배포했으며, 게이트웨이 도구 이름은 ams.search_designated_entities, 필요 역할은 mcp-ams입니다. 공유 public client 394048911884420192와 저장된 callback은 변경하지 않았습니다. AMS 및 게이트웨이 ArgoCD 앱은 Synced/Healthy 상태이며, 내부 서비스는 게이트웨이에서만 접근하도록 격리했습니다. 배포 상태와 네트워크 격리 확인은 공개 OAuth/MCP 및 실제 병무청 조회 성공을 뜻하지 않습니다.

공개 컨테이너 이미지는 ghcr.io/antegral/ams-mcp:sha-432f6c1@sha256:bf052f78092833e113a837f4dd2dbf9baaede4bc57a252a963051ac22901a318입니다. 게시 실행 기록은 소스 432f6c17a2cb92f0344c85f8eaae6bf39dae34bb를 고정하여 linux/amd64 및 linux/arm64 이미지를 빌드했습니다. 레지스트리의 OCI 인덱스와 두 아키텍처의 소스 라벨을 익명으로 확인했으며, 이미지 pull 자격 증명은 필요하지 않습니다. 이 게시에 사용한 임시 워크플로우와 브랜치는 게시 후 제거했습니다. 기존 품질 CI는 변경하지 않았습니다.

최종 공개 OAuth/MCP 시나리오는 한 번 실행했습니다. 공유 등록 조회는 HTTP 200으로 기존 설정과 일치했지만, https://auth.antegral.net/.well-known/openid-configuration의 공개 OIDC discovery 요청이 HTTP 403을 반환하여 중단했습니다. 이 요청에는 인증 헤더, PAT, 쿠키 또는 내부 Host 재정의를 사용하지 않았습니다. 응답 헤더와 본문이 보존되지 않아 403의 원인은 확인하지 못했습니다. 토큰 발급, 게이트웨이 MCP 호출 및 실제 AMS 병무청 조회에 도달하지 않았으므로 네이티브 조회 동작은 검증하지 못했습니다. 시나리오는 재실행하지 않았습니다.

개발 모드

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 서버 메인 엔트리포인트
│   ├── http.ts           # 내부 전용 HTTP 엔트리포인트
│   ├── server.ts         # 공유 서버 팩토리 및 네이티브 도구 등록
│   ├── 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 사용 시 해당 사이트의 이용 약관을 준수해야 합니다.

기여

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