Employment MCP Server

MCP 학습용으로 만든 고용 데이터 서버 World Bank API를 사용해서 농업/산업/서비스 섹터별 고용률을 조회한다.

MCP란?

Model Context Protocol의 약자. LLM에게 외부 도구와 데이터 접근 권한을 제공하는 표준 프로토콜이다.

공식 문서의 비유

MCP는 "AI 애플리케이션을 위한 USB-C 포트" 같은 것이다. USB-C가 전자기기를 연결하는 표준화된 방법을 제공하듯, MCP는 AI 애플리케이션을 외부 시스템에 연결하는 표준화된 방법을 제공한다.

또한 Language Server Protocol(LSP)에서 영감을 받았다. LSP가 IDE에서 프로그래밍 언어 지원을 표준화한 것처럼, MCP는 AI 애플리케이션에 컨텍스트와 도구를 통합하는 방식을 표준화한다.

핵심 구성 요소 (Primitives)

MCP 서버는 3가지 primitives를 제공한다:

Resources (리소스)

서버가 관리하는 데이터나 컨텐츠
문서, 파일, API 응답 등
예: World Bank API에서 가져온 고용 데이터

Tools (도구)

LLM이 호출할 수 있는 함수
작업을 수행하거나 외부 시스템과 상호작용
예: get_employment_by_sector() 함수

Prompts (프롬프트)

재사용 가능한 프롬프트 템플릿
워크플로우 자동화의 진입점
서버가 제공하는 명령어 정의

이 프로젝트는 Tools 중심으로 구현되어 있다.

프로젝트 구조

server-employee/
├── server.py            # FastMCP 인스턴스 생성
├── tools/api.py         # 도구(tool) 정의
├── main.py              # stdio 모드 실행 (로컬)
├── main_http.py         # HTTP 서버 실행 (원격)
└── pyproject.toml       # 의존성 관리

파일별 역할:

server.py: FastMCP 객체 하나 생성. 다른 파일에서 import해서 사용
tools/api.py: @mcp.tool() 데코레이터로 함수를 등록
main.py: stdio 통신으로 Claude Desktop과 직접 연결
main_http.py: HTTP 서버로 원격 접속 가능하게 함

핵심 개념

1. FastMCP 인스턴스 (server.py)

mcp = FastMCP("server-employee")

MCP 서버의 진입점. 모든 도구가 이 객체에 등록된다.

2. Tool 등록 (tools/api.py)

@mcp.tool()
async def get_employment_by_sector(country: str, year: int):
    # World Bank API 호출

@mcp.tool() 데코레이터로 일반 함수를 MCP 도구로 변환한다.

worldbank GDP 서버 참고: 잘 짜여진 코드를 보고 패턴을 학습했다. ```

입력값 검증 (ISO 코드, 연도 범위)
API URL 구성
httpx로 비동기 요청
에러 처리
응답 포맷팅


### 3. 실행 모드

**stdio (main.py)**
- 로컬 전용
- Claude Desktop과 표준 입출력으로 통신
- 가장 간단한 방식

**HTTP (main_http.py)**
- 네트워크 접속 가능
- Starlette + uvicorn 사용
- 다른 컴퓨터에서 접속 가능

## 설치 및 실행

### 의존성 설치

uv sync ``` httpx, fastmcp, uvicorn 등이 설치된다.

로컬 실행

uv run python main.py

서버가 실행되지만 터미널에 아무것도 출력되지 않는다. stdio 모드로 대기 중이기 때문.

HTTP 서버 실행

uv run python main_http.py

http://0.0.0.0:8000에서 서버가 시작된다.

확인: ```bash curl http://localhost:8000/ping

{"ok": true, "status": "running"}


## Claude Desktop 연결

### 로컬 연결
`~/Library/Application Support/Claude/claude_desktop_config.json`:

{ "mcpServers": { "employment": { "command": "uv", "args": [ "--directory", "절대경로/server-employee", "run", "python", "main.py" ] } } } ```

경로는 본인 환경에 맞게 수정 필요. Claude Desktop 재시작 후 적용됨.

원격 연결

서버 실행 후: ``json { "mcpServers": { "employment-remote": { "url": "http://localhost:8000/mcp" } } } ``

다른 컴퓨터에서 접속: localhost를 서버 IP로 변경 예: http://192.168.0.10:8000/mcp

제공 도구

총 4개의 도구를 구현했다. 모두 World Bank API를 사용한다.

get_employment_by_sector

3개 섹터(농업/산업/서비스)의 고용률을 한 번에 조회한다.

get_employment_by_sector(country="US", year=2020)

파라미터:

country: ISO 2/3자 국가 코드 (US, KR, IN 등)
year: 연도 (1960~2100)

응답 예시: ``json { "country": "United States", "year": 2020, "employment": { "agriculture": {"percentage": 1.35}, "industry": {"percentage": 19.62}, "services": {"percentage": 79.03} } } ``

get_agriculture_employment

농업 섹터만 조회한다. ```python get_agriculture_employment(country="IN", year=2020)

인도: 42.6% (농업 비중 높음)


### get_industry_employment
산업(제조업 등) 섹터만 조회한다.

get_industry_employment(country="KR", year=2020) ```

get_services_employment

서비스업 섹터만 조회한다. ``python get_services_employment(country="US", year=2020) ``

World Bank Indicators

사용하는 지표:

SL.AGR.EMPL.ZS: Employment in agriculture (% of total)
SL.IND.EMPL.ZS: Employment in industry (% of total)
SL.SRV.EMPL.ZS: Employment in services (% of total)

World Bank에는 수천 개의 indicator가 있지만, 이 프로젝트에서는 위 3개만 사용한다.

원격 접속

로컬 네트워크

HTTP 서버 실행: uv run python main_http.py
IP 확인: ifconfig (Mac) / ipconfig (Windows)
접속: http://192.168.0.10:8000/mcp

인터넷 공개

ngrok 사용: ```bash ngrok http 8000

https://xxxx.ngrok.io/mcp

무료 버전은 세션마다 URL이 변경됨.

**기타 방법:**
- 클라우드 배포 (AWS, GCP, Heroku 등)
- 포트포워딩 (라우터 설정)

## 학습 노트

### 구조 설계
1. **server.py 분리**: 여러 파일에서 같은 mcp 객체 공유. import로 재사용 가능.

2. **async/await 사용**: API 호출 대기 시간에 다른 작업 가능. 동시 요청 처리에 유리.

3. **헬퍼 함수**: `fetch_worldbank_indicator`를 만들어 3개 함수에서 재사용. 코드 중복 제거.

### 배운 점
- 입력값 검증의 중요성: ISO 코드 형식과 연도 범위를 체크해야 함
- World Bank API 응답이 항상 데이터를 가지고 있지 않음. null 체크 필수
- HTTP 서버에서 `host="0.0.0.0"` 사용해야 외부 접속 가능. `127.0.0.1`은 로컬만
- Claude Desktop은 원격 HTTP MCP를 지원하지 않음. Claude Web에서만 가능

## 주의사항

- **보안**: 현재 인증 없음. 실사용 시 API 키/토큰 필요
- **방화벽**: 8000 포트 개방 필요
- **데이터**: World Bank가 모든 국가/연도 데이터를 보유하지 않음

## 참고 자료

### MCP 관련
- [MCP 공식 문서](https://modelcontextprotocol.io/)
- [MCP 서버 구축 가이드](https://modelcontextprotocol.io/docs/develop/build-server)
- [MCP Architecture](https://modelcontextprotocol.io/specification/2025-06-18/architecture/index)
- [MCP Prompts 개념](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts)
- [FastMCP GitHub](https://github.com/jlowin/fastmcp)

### API 관련
- [World Bank API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation)

server-employee