🌾 FarmSubsidy Korea (농업보조금 알리미) MCP

한국의 농업 관련 보조금·지원금 공고를 정부 소스 여러 곳에서 통합(aggregation) 해서 제공하는 MCP 서버입니다. 카카오 PlayMCP — AGENTIC PLAYER 10 공모전 출품작.

• 접수중/접수예정/마감임박 공고를 키워드·지역·상태로 검색

• 접수 마감일·시작일을 톡캘린더 MCP(CreateEvent)에 바로 넘길 수 있는 일정 데이터로 변환 → 알림/일정 등록 시나리오

• Streamable HTTP(stateless), MCP 스펙 2025-03-26+ 준수, PlayMCP 심사 요건(annotations 5종, TextContent/Markdown, 24KB 제한, 응답속도) 반영

데이터 소스

수집은 서버 기동 시 1회 + 10분 주기 백그라운드로 수행하고, tool 호출은 항상 메모리 캐시에서 즉시 응답합니다(PlayMCP 응답속도 기준: 평균 100ms, p99 3s). 일부 소스 장애 시 나머지 소스로 계속 서비스합니다.

Related MCP server: gov-support-mcp

제공 도구 (6종, 전부 읽기 전용)

톡캘린더 연동 시나리오: 사용자가 "스마트팜 보조금 마감일 캘린더에 등록해줘"라고 하면, 에이전트가 ① search_farm_subsidies → ② build_calendar_events → ③ 톡캘린더 MCP의 CreateEvent를 순서대로 호출하는 MCP 체이닝으로 완성됩니다.

API 키 발급 (둘 다 즉시 발급, 무료)

1. 보조금24: data.go.kr 15113968 → 로그인 → "활용신청" (자동승인) → 마이페이지에서 일반 인증키(Decoding) 복사 → GOV24_API_KEY

2. 기업마당: API 상세 페이지 하단 폼에서 정보 입력 후 등록 → 화면/이메일로 인증키 수령 → BIZINFO_API_KEY

cp .env.example .env   # 키 입력

키가 없어도 서버는 뜨고 농식품부 RSS 소스만으로 동작합니다(해당 소스는 접수기간 정보가 제한적).

로컬 실행

npm install
npm run build
npm start        # http://localhost:8080/mcp (POST), /healthz
npm test         # 별도 터미널에서 스모크 테스트 (6개 도구 호출 검증)

배포 — 카카오클라우드 "PlayMCP in KC"

공모전 예선은 PlayMCP in KC(컨테이너 배포 서비스) 사용이 필수입니다. 예선 접수 기간(6/15~7/14)에만 서버 발급 가능, 계정당 2대.

방법 A. Git 소스 빌드 (권장 — 가장 간단)

1. 이 프로젝트를 GitHub 저장소에 push (Dockerfile 포함되어 있음)

2. PlayMCP in KC 콘솔에서 Git URL + 브랜치 입력 (private면 PAT 입력)

3. Status가 Active가 되면 Endpoint URL 발급

방법 B. 컨테이너 이미지 등록

docker build --platform linux/amd64 -t <docker허브ID>/farm-subsidy-mcp:0.1.0 .   # 반드시 linux/amd64
docker push <docker허브ID>/farm-subsidy-mcp:0.1.0

콘솔에서 호스트(docker.io)/이미지명/태그 입력.

환경변수(GOV24_API_KEY, BIZINFO_API_KEY)는 배포 콘솔의 환경변수 설정에 입력하세요.

PlayMCP 등록 절차

1. playmcp.kakao.com/console → "새로운 MCP 서버 등록"

2. Endpoint URL 입력 (https://<발급도메인>/mcp) → "정보 불러오기" 로 tool 목록 fetch 확인

3. MCP 식별자·대화 예시(starter messages)·대표 이미지 입력 → 임시 등록으로 실제 대화 테스트

4. "등록 및 심사 요청" → 승인 후 "나에게만 공개" → "전체 공개"로 반드시 전환

5. 공모전 페이지 하단 버튼으로 예선 참여 접수 (1회만 가능)

심사 일정 주의

• 심사는 영업일 최대 7일 (평균 1~2일). 7/7까지 심사 요청하면 7/10까지 심사 완료 보장 — 마감(7/14) 직전 요청은 위험.

등록 시 입력 추천값

• 대화 예시: "이번 주에 마감되는 농업 보조금 알려줘" / "전북 스마트팜 지원사업 찾아줘" / "청년농 보조금 마감일 톡캘린더에 등록해줘" / "오늘의 농업 보조금 브리핑"

아키텍처

src/
  index.ts        Express + Streamable HTTP (stateless, POST /mcp, GET /healthz)
  server.ts       MCP 도구 6종 정의 (annotations, Markdown 응답, 24KB 캡)
  aggregate.ts    멀티소스 수집·중복제거·정렬 + 백그라운드 갱신(10분) + stale-while-revalidate
  sources/
    nongupez.ts   농업e지 사업검색 API (인증 불필요, JSON POST)
    gov24.ts      보조금24 API (서버측 분야필터 → 실패 시 클라이언트 필터 폴백)
    bizinfo.ts    기업마당 API (농업 키워드 필터)
    mafra.ts      농식품부 RSS (의존성 없는 XML 파싱)
    keywords.ts   농업 판별 키워드/기관 사전
  util.ts         날짜 정규화·기간 파싱·상태 계산·HTML 제거·TTL 캐시
  test/smoke.ts   MCP 클라이언트 스모크 테스트