AgroAgent

칠레 농업 틈새 시장을 겨냥한 AI 에이전트로, Model Context Protocol (MCP) 기반의 에이전트 아키텍처로 구축되었습니다. 모놀리식 백엔드 대신, 4개의 독립적인 MCP 서버가 특화된 도구를 노출하며, 오케스트레이터가 Anthropic SDK를 사용한 에이전트 루프를 통해 이를 조정합니다.

아키텍처

apps/
  web/            Next.js 16 + TypeScript + Tailwind v4 + Recharts
  orchestrator/   FastAPI -- MCP host + agent loop (Anthropic SDK) + rutas REST de dashboard
mcp-servers/
  mcp-weather/    tool: get_weather_forecast (Open-Meteo)
  mcp-prices/     tool: get_commodity_price (datos abiertos ODEPA)
  mcp-db/         tools: get_farmer_history, register_planting (PostgreSQL/SQLAlchemy async)
  mcp-rag/        tool: search_sag_documents (RAG sobre normativa SAG -- Pinecone + Voyage AI)
packages/
  shared-types/   Modelos Pydantic compartidos entre orchestrator y mcp-servers

오케스트레이터는 MCP 클라이언트로 4개 서버에 연결하여, 해당 도구 카탈로그를 하나로 통합한 후 다음을 노출합니다:

• POST /chat -- 대화형 엔드포인트 (Claude가 컨텍스트에 따라 사용할 도구를 결정)

• GET /weather, GET /farmers/{id}/history, GET /prices/trend -- 대시보드용 결정적 REST 경로로, LLM을 거치지 않고 도구를 직접 호출

이 프로젝트의 가치는 각 소스를 개별적으로 노출하는 것이 아니라, 에이전트가 이를 교차 분석하는 데 있습니다. 예를 들어, 농부의 작물 이력을 해당 지역의 예보 및 현재 제품 가격과 연계하여 구체적인 의사 결정을 제안하고, 해당되는 경우 정확한 SAG 결의안을 인용합니다.

Related MCP server: leafengines-mcp-server

스택

• 백엔드: Python 3.12+, FastAPI, mcp SDK (v2), SQLAlchemy async + asyncpg, Pinecone, Voyage AI, Anthropic SDK, uv (모노레포 워크스페이스)

• 프론트엔드: Next.js (App Router), TypeScript, Tailwind CSS v4, Recharts, pnpm

• 데이터: PostgreSQL (Docker), Open-Meteo API, ODEPA (CKAN datastore API), SAG 규범 문서

요구 사항

• Python 3.12+ 및 uv

• Node 20+ 및 pnpm

• Docker (PostgreSQL용)

• API 키: Anthropic, Pinecone, Voyage AI

설정

# Backend (Python workspace completo)
uv sync --all-packages

# Frontend
cd apps/web && pnpm install && cd ../..

# Base de datos
docker compose up -d postgres

apps/web/.env.local을 생성하세요:

NEXT_PUBLIC_ORCHESTRATOR_URL=http://localhost:3001

프로젝트 실행 (6개 프로세스)

# Terminal 1
uv run --package mcp-weather uvicorn mcp_weather.app:app --reload --port 4001

# Terminal 2
uv run --package mcp-prices uvicorn mcp_prices.app:app --reload --port 4002

# Terminal 3 (ajusta el puerto de Postgres si no usas el 5432 por defecto)
DATABASE_URL="postgresql+asyncpg://agroagent:agroagent@localhost:5432/agroagent" \
  uv run --package mcp-db uvicorn mcp_db.app:app --reload --port 4004

# Terminal 4
PINECONE_API_KEY="..." VOYAGE_API_KEY="..." \
  uv run --package mcp-rag uvicorn mcp_rag.app:app --reload --port 4005

# Terminal 5
ANTHROPIC_API_KEY="..." \
  uv run --package orchestrator uvicorn orchestrator.app:app --reload --port 3001

# Terminal 6
cd apps/web && pnpm dev

프론트엔드는 http://localhost:3000에서 확인할 수 있습니다.

아키텍처 결정 사항

• MCP 전송: streamable-HTTP 사용, stdio 미사용 -- 각 MCP 서버는 자체 포트/컨테이너를 가진 독립 서비스로, 실제 마이크로서비스 배포에 더 부합합니다.

• Python/FastAPI 백엔드 (NestJS/TypeScript 대신): 시장 수요와 폴리글랏 역량을 보여주기 위한 의도적 결정입니다 (프론트엔드는 TS/React로 유지).

• RAG: 청킹은 고정된 문자 수로 자르는 대신 칠레 법적 결의안의 번호 구조(2.1, 3.1.1 등)를 존중합니다. 각 청크의 메타데이터에는 결의안 번호가 포함되어 에이전트가 출처를 인용할 수 있습니다.

• 에이전트와 분리된 REST 경로: 대시보드는 결정적 데이터(기후, 이력, 가격)에 대해 LLM을 거치지 않습니다. 불필요한 비용과 지연을 방지하며, 두 계층 모두 동일한 기본 MCP 도구를 재사용합니다.

알려진 제한 사항 / 미해결 과제

• 인증 없음: farmer_id가 명시적으로 전달되며 사용자 세션이 없습니다.

• 새 농부를 생성하는 경로(POST /farmers)가 없습니다. 테스트 레코드는 수동으로 삽입되었습니다.

• mcp-rag는 텍스트 레이어가 없는 스캔된 PDF를 지원하지 않습니다(OCR 필요).

• 서비스별 개별 Dockerfile이 없습니다. docker-compose.yml은 PostgreSQL만 다룹니다.

• mcp-db의 작물 이름은 mcp-prices의 ODEPA 제품 이름과 정규화되어 있지 않습니다.