eagleisbatman/ssfr-mcp-server

🌾 SSFR MCP Server

Model Context Protocol (MCP) server providing Site-Specific Fertilizer Recommendations (SSFR) for Ethiopian farmers.

Integrates with the Next-gen Agro Advisory Service to deliver personalized fertilizer quantity and type advice based on location coordinates. Provides recommendations for wheat and maize crops including organic (compost, vermicompost) and inorganic (urea, NPS) fertilizers with expected yield predictions. Designed for integration with AI agents via OpenAI Agent Builder.

✨ Features

1 MCP Tool

Supported Crops (2)

• Wheat - Urea, NPS, Compost, Vermicompost, Expected Yield
• Maize - Urea, NPS, Compost, Vermicompost, Expected Yield

Geographic Coverage

IMPORTANT: This MCP server only works for locations within Ethiopia.

Ethiopia bounds:

• Latitude: 3.0°N to 15.0°N
• Longitude: 32.0°E to 48.0°E

Technical Features

• ✅ Input validation for coordinates and crop types
• ✅ 30-second timeout protection (prevents hanging requests)
• ✅ Graceful partial failure handling (if one layer fails, others still work)
• ✅ Response validation and error handling
• ✅ Graceful shutdown handling (SIGTERM/SIGINT)
• ✅ Safe numeric parsing with NaN validation
• ✅ TypeScript for production reliability
• ✅ StreamableHTTP MCP transport

Prerequisites

• Node.js >= 18.0.0
• No API token required (Next-gen Agro Advisory API is public)

Local Setup

# Clone and install
cd ssfr-mcp-server
npm install

# Start development server
npm run dev

# Test
curl http://localhost:3001/health

Expected Response:

{
  "status": "healthy",
  "service": "ssfr-mcp-server",
  "supportedCrops": ["wheat", "maize"],
  "supportedRegion": "Ethiopia"
}

⚙️ Configuration

Environment Variables

# Optional (defaults shown)
PORT=3001
SSFR_API_BASE_URL=https://webapi.nextgenagroadvisory.com
ALLOWED_ORIGINS=*

🚀 Deployment

This server can be deployed to any Node.js hosting platform:

• PaaS: Railway, Heroku, Render, Fly.io
• Cloud: AWS (EC2/Lambda), Google Cloud Run, Azure App Service
• Containerized: Docker, Kubernetes
• VPS: DigitalOcean, Linode, your own server

Railway Deployment

1. Push code to GitHub
2. Connect to Railway
3. Deploy - Railway auto-detects Node.js
4. Test: curl https://your-deployment-url/health

🔌 Integration

OpenAI Agent Builder

1. Deploy MCP Server (any platform)

2. Create Agent Workflow:

• Go to platform.openai.com
• Create new agent

3. Add MCP Server:

• Add Tool → Custom MCP Server
• Name: ssfr-fertilizer-recommendations
• Transport: StreamableHTTP
• URL: https://your-deployment-url/mcp

4. Configure System Prompt:

The agent should:

• Only call get_fertilizer_recommendation for Ethiopian locations (tool automatically validates)
• Use farmer-friendly language (hybrid approach: description + numbers + explanation)
• Format responses clearly for farmers

🏗️ Architecture

AI Agent (OpenAI/Claude/Custom)
    ↓ MCP Protocol (StreamableHTTP) + Custom Headers
Express.js MCP Server (This Repo)
    ↓ Reads X-Farm-Latitude, X-Farm-Longitude from headers
    ↓ HTTP REST
Next-gen Agro Advisory API
    - Provides: Fertilizer recommendations
    - Returns: Urea, NPS, Compost, Vermicompost quantities + Expected yield

📁 Project Structure

ssfr-mcp-server/
├── src/
│   ├── index.ts          # Main: 1 MCP tool + server setup
│   └── ssfr-client.ts    # Next-gen Agro Advisory API client
├── dist/                 # Compiled output (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript config
├── railway.json          # Railway deployment config
└── README.md             # This file

🛠️ Development

Commands

npm install     # Install dependencies
npm run build   # Compile TypeScript
npm run dev     # Development mode (hot reload)
npm start       # Production mode

📚 API Reference

Tool: get_fertilizer_recommendation

Purpose: Get fertilizer recommendations for wheat or maize

Parameters:

• crop (required): "wheat" or "maize"
• latitude (optional): Latitude coordinate
• longitude (optional): Longitude coordinate

Note: This tool automatically checks if the location is in Ethiopia. If coordinates are outside Ethiopia, it returns an error.

Returns:

{
  "crop": "wheat",
  "location": {
    "latitude": 12.9345,
    "longitude": 77.6266
  },
  "fertilizers": {
    "organic": {
      "compost": 20,
      "vermicompost": 16
    },
    "inorganic": {
      "urea": 265.67,
      "nps": 0
    }
  },
  "expected_yield": 3580.53,
  "data_source": "Next-gen Agro Advisory Service",
  "units": {
    "organic": "tons/ha",
    "inorganic": "kg/ha",
    "yield": "kg/ha"
  }
}

🐛 Troubleshooting

Server Won't Start

Error: Port already in use

# Use different port
PORT=3002 npm start

Location Not Supported

Error: Coordinates outside Ethiopia

• Verify coordinates are within Ethiopia bounds:
  • Latitude: 3.0°N to 15.0°N
  • Longitude: 32.0°E to 48.0°E
• Use is_ssfr_enabled tool first to check availability

API Errors

404 Not Found: Invalid layer name or coordinates 500 Internal Server Error: API service unavailable

Check Next-gen Agro Advisory API status.

📄 License

MIT License - see file

Site-Specific Fertilizer Recommendations for Ethiopian farmers 🌾