@minjunkwon/korea-welfare-mcp-server/README.md

MCP server for Korean Central Government Welfare Services - provides intelligent search and information retrieval for Korean social welfare programs

# Korea Welfare MCP Server

한국 중앙정부 복지서비스 정보를 조회할 수 있는 MCP (Model Context Protocol) 서버입니다.

## 개요

이 MCP 서버는 한국 공공데이터포털에서 제공하는 중앙부처 복지서비스 API를 활용하여 복지서비스 목록 조회 및 상세 정보를 제공합니다. Claude와 같은 AI 어시스턴트가 한국의 복지 정보를 실시간으로 조회하고 사용자에게 적절한 복지서비스를 안내할 수 있도록 돕습니다.

## 기능

### 1. 복지서비스 목록 조회 (`search_welfare_services`)
- 생애주기별 복지서비스 검색 (영유아, 아동, 청소년, 청년, 중장년, 노년, 임신·출산)
- 가구유형별 검색 (다문화·탈북민, 다자녀, 보훈대상자, 장애인, 저소득, 한부모·조손)
- 관심주제별 검색 (신체건강, 정신건강, 생활지원, 주거, 일자리, 문화·여가 등)
- 검색어 기반 조회
- 나이별 필터링
- 온라인 신청 가능 여부 필터링
- 페이징 지원

### 2. 복지서비스 상세 조회 (`get_welfare_detail`)
- 서비스 ID를 통한 상세 정보 조회
- 대상자 상세 내용, 선정 기준, 급여 서비스 내용
- 문의처, 관련 사이트, 근거 법령, 서식/자료 링크 제공

### 3. 코드 정의 조회 (`get_code_definitions`)
- API에서 사용되는 코드 체계 조회
- 생애주기, 가구유형, 관심주제 코드 매핑

## 설치 및 설정

### 1. 패키지 설치
```bash
npm install
```

### 2. API 키 설정
`src/api.ts` 파일에서 `SERVICE_KEY` 값을 실제 공공데이터포털에서 발급받은 서비스 키로 교체하세요.

```typescript
const SERVICE_KEY = 'YOUR_ACTUAL_SERVICE_KEY_HERE';
```

### 3. 빌드
```bash
npm run build
```

### 4. 실행
```bash
npm start
```

또는 개발 모드로 실행:
```bash
npm run dev
```

## MCP 설정

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

```json
{
  "mcpServers": {
    "korea-welfare": {
      "command": "node",
      "args": ["/path/to/korea-welfare-mcp-server/dist/index.js"]
    }
  }
}
```

## 사용 예시

### 복지서비스 검색
```typescript
// 영유아 대상 복지서비스 검색
search_welfare_services({
  lifeCycle: "001", // 영유아
  numOfRows: 20,
  orderBy: "popular"
})

// 저소득층 대상 일자리 관련 서비스 검색
search_welfare_services({
  householdType: "050", // 저소득
  interestTheme: "050", // 일자리
  onlineApplicationAvailable: "Y"
})
```

### 상세 정보 조회
```typescript
// 특정 서비스의 상세 정보 조회
get_welfare_detail({
  serviceId: "WLF00001188"
})
```

## API 매개변수

### 생애주기 코드
- `001`: 영유아
- `002`: 아동
- `003`: 청소년
- `004`: 청년
- `005`: 중장년
- `006`: 노년
- `007`: 임신·출산

### 가구유형 코드
- `010`: 다문화·탈북민
- `020`: 다자녀
- `030`: 보훈대상자
- `040`: 장애인
- `050`: 저소득
- `060`: 한부모·조손

### 관심주제 코드
- `010`: 신체건강
- `020`: 정신건강
- `030`: 생활지원
- `040`: 주거
- `050`: 일자리
- `060`: 문화·여가
- `070`: 안전·위기
- `080`: 임신·출산
- `090`: 보육
- `100`: 교육
- `110`: 입양·위탁
- `120`: 보호·돌봄
- `130`: 서민금융
- `140`: 법률
- `160`: 에너지

## 데이터 출처

이 MCP 서버는 한국 공공데이터포털에서 제공하는 "중앙부처 복지서비스" API를 사용합니다.
- API 제공: 보건복지부
- 데이터 갱신: 실시간
- 서비스 URL: http://apis.data.go.kr/B554287/NationalWelfareInformationsV001

## 라이선스

MIT License

## 기여

버그 리포트나 기능 제안은 GitHub Issues를 통해 해주시기 바랍니다.