README.md•3.46 kB
# Bizinfo HTTP Server
기업마당 지원사업 데이터를 HTTP API로 노출하는 예제 프로젝트입니다. 외부에서는 단순한 REST 인터페이스를 통해 지역/대상/키워드 기반 검색과 자연어 질의를 처리할 수 있습니다.
## 주요 기능
- `GET /search` 엔드포인트로 지역/대상/키워드를 이용한 지원사업 검색
- `POST /search` JSON 본문을 이용한 동일 파라미터 검색
- `POST /search-natural` 자연어 한 문장으로 조건 파싱 후 검색 수행
- `GET /health` 헬스 체크
## 실행 방법
```bash
npm install
npm start
```
기본적으로 `PORT=3000`, `HOST=0.0.0.0`로 동작합니다. 다른 포트나 호스트를 사용하려면 환경 변수를 설정하세요.
```bash
PORT=8080 HOST=127.0.0.1 npm start
```
### 환경 변수
- `BIZINFO_API_KEY` – 기업마당 Open API 키. 설정하지 않으면 패키지에 포함된 데모 키(`QP6yn2`)를 사용합니다.
프로젝트 루트(또는 서버를 실행하는 현재 작업 디렉터리)에 `.env` 파일을 만들어 사용할 수도 있습니다.
```env
BIZINFO_API_KEY=나의_API_키
```
## 예시 요청
```bash
# 1) 쿼리 스트링으로 직접 검색
curl "http://localhost:3000/search?region=광주&target=소상공인&keywords=AI"
# 2) POST /search
curl -X POST "http://localhost:3000/search" \
-H "Content-Type: application/json" \
-d '{"region":"서울","target":"청년","page":1,"page_size":5}'
# 3) 자연어 질의
curl -X POST "http://localhost:3000/search-natural" \
-H "Content-Type: application/json" \
-d '{"prompt":"부산 소상공인 지원사업 5건만 알려줘"}'
```
모든 응답은 JSON 형식이며 `items` 배열(구조화된 결과)과 `summary` 필드를 포함합니다.
## CLI로 빠르게 결과 확인하기
서버를 띄우지 않고도 기존 CLI 진입점을 통해 자연어 검색이 가능합니다.
```bash
# 설치 없이 실행
npx @kwangdss/bizinfo-mcp "광주 소상공인 사업 알려줘"
# 전역 설치 후 사용
npm install -g @kwangdss/bizinfo-mcp
bizinfo "서울 청년 창업 사업 알려줘"
```
CLI는 내부적으로 같은 로직을 사용해 기업마당 API를 호출합니다. 별도의 서버 없이 바로 결과를 볼 수 있습니다.
## MCP 서버로 사용하기
Model Context Protocol 클라이언트(예: Claude Desktop)의 설정 파일에 아래와 같이 추가하면 됩니다.
```json
{
"mcpServers": {
"bizinfo": {
"command": "npx",
"args": [
"-y",
"@kwangdss/bizinfo-mcp@latest",
"bizinfo-mcp-server"
]
}
}
}
```
환경 변수는 MCP 클라이언트가 실행되는 디렉터리 기준의 `.env` 파일 또는 시스템 환경 변수에서 읽어옵니다.
- `BIZINFO_API_KEY` – 기업마당 Open API 키 (선택)
## 클라이언트 스크립트
`npm run client`는 로컬에서 HTTP 서버가 동작 중일 때 검색 요청을 보낼 수 있는 간단한 스크립트입니다.
```bash
npm start & # 백그라운드로 서버 실행
node client.mjs --region=부산 --target=소상공인 --keywords=AI
```
`--base-url` 옵션 또는 `BIZINFO_HTTP_URL` 환경 변수를 사용해 다른 서버 주소를 지정할 수 있습니다.
## 배포
```bash
npm login
npm publish --access public
```
배포 후에는 HTTP 서버 또는 CLI를 통해 누구나 기업마당 지원사업을 조회할 수 있습니다.
## 라이선스
MIT