# smartfarm-mcp

스마트팜코리아 "스마트팜 빅데이터 제공 서비스" Open API(data.go.kr 15121334)를
MCP 도구로 감싼 서버. **LIVE 검증 완료** (HTTPS, serviceKey path 방식).
소비자(LLM)는 원시 코드(fldCode/sectCode/fatrCode)를 몰라도 `내부기온`·`습도`·
`co2` 같은 친화적 metric 이름으로 부른다.

## 빠른 시작
```bash
git clone <this-repo>
cd smartfarm-mcp
pip install -r requirements.txt

# 인증키: data.go.kr 15121334 활용신청 후 발급 → .env 에 넣기
cp .env.example .env
# .env 의 SMARTFARM_SERVICE_KEY 값을 본인 키로 수정

python test_local.py          # 키 있으면 LIVE, 없으면 MOCK
```
- **키 로드 우선순위**: 환경변수 `SMARTFARM_SERVICE_KEY` → `./.env` → 상위 `../.env`.
  `.env` 는 `.gitignore` 로 커밋에서 제외됩니다(키 유출 방지).
- 키 없이 구조만 보려면: `SMARTFARM_MOCK=1 python test_local.py`

## MCP 클라이언트 등록 (.mcp.json)
```json
{
  "mcpServers": {
    "smartfarm-mcp": {
      "command": "python",
      "args": ["/home/k821209/works/ai-breeding/smartfarm-mcp/server.py"]
    }
  }
}
```
(키는 `.env` 에서 자동 로드되므로 env 블록 불필요. 명시하려면
`"env": {"SMARTFARM_SERVICE_KEY": "..."}` 추가.)

## tool (LIVE 검증)
| tool | 설명 | op |
|---|---|---|
| server_info | 서버·데이터 개요 | — |
| list_farms | 농가·시설 목록(item 코드→이름) | getIdentityDataList |
| list_croppings(user_id) | 농가의 작기 목록 | getCroppingSeasonDataList/{userId} |
| get_cropping_environment(csn, page, metric?) | 작기 환경 시계열(디코딩) | CropseasonRestService/getCroppingSeasonEnvDataList |
| latest_climate(csn) | 가장 최근 내부 환경 1세트 | (위 2회 호출) |
| aggregate_cropping_environment(csn, metric, agg) | 기간 집계 mean/min/max | — |
| get_environment(facility, date, metric) | 시설·날짜 환경 시간별 시계열(itemCode 자동) | getEnvDataList |

## 환경 metric (sectCode, fatrCode)
EI/TI 내부기온℃ · EI/HI 내부습도% · EI/CI CO2ppm ·
EO/TE 외부기온℃ · EO/SR 일사 · EO/WS 풍속 · EO/WD 풍향
(EI/DT, EL/TL, NT/HL 은 의미 미확정 → raw 노출)

## 검증 예 (PFS_0000001 / 토마토 / cropping 4940)
- 환경: co2 508ppm · 내부습도 87.33% · 내부기온 19.67℃ (2021-10-01)
- 최근: 내부기온 25℃ · 습도 99% · co2 607ppm (2022-07-29)
- 집계: 내부기온 평균 18.05℃

## 완료 (모든 항목 라이브 검증)
- ✅ itemCode→작물명: 작기명 근거로 30여 종 매핑(토마토·딸기·파프리카·오이·국화·
  참외 등). 모호/복합 코드(060300·100500 등)는 의도적으로 제외(item=None).
- ✅ env metric 코드: 기술명세서 v2.0 으로 확정 (DT 노점온도·SR 일사량·TL 지온·
  HL 관수량). 전체 코드표는 공식 명세서 참조:
  https://smartfarmkorea.net/file/download.do?type=BLANK&fileName=openapiSmartfarm.zip
- ✅ get_environment(getEnvDataList): 라이브 검증 완료, itemCode 시설에서 자동 보강.

## 데모 (덱 슬13 "개인+기관 통합")
`latest_climate(내_작기)` + `db300.search_by_trait(기관 품종)`
→ "지금 우리 온실 조건에서 식량원 품종 중 무엇이 가장 잘 맞나?"