LiteFarm MCP Server

MCP (Model Context Protocol) Server für LiteFarm - Verbindet Claude Desktop mit deiner lokalen LiteFarm-Installation.

🎯 Überblick

Dieser MCP-Server ermöglicht es Claude Desktop, direkt mit deiner LiteFarm-Installation zu kommunizieren. Du kannst:

• ✅ Farmen verwalten (auflisten, erstellen, aktualisieren)
• ✅ Aufgaben verwalten (auflisten, erstellen, abschließen)
• ✅ Pflanzen/Crops durchsuchen und Details abrufen
• ✅ Standorte/Felder verwalten
• ✅ Komplexe Datenbank-Operationen direkt mit SQL (SQL Logic Sandbox)
• ✅ Alle Operationen in natürlicher Sprache über Claude

SQL Logic Sandbox

Der Server bietet zwei Zugriffsmethoden:

• API-basiert: Sichere, validierte Operationen über die LiteFarm REST API
• SQL-basiert: Direkte Datenbank-Operationen für komplexe Multi-Step-Workflows

Die SQL Logic Sandbox löst das Dependency-Chain-Problem von LiteFarm (Location → Crop → Management Plan → Task) durch atomare SQL-Transaktionen statt sequentieller API-Calls.

📋 Voraussetzungen

• Node.js >= 18.0.0
• LiteFarm läuft lokal auf http://localhost:5000
• PostgreSQL Database läuft auf Port 5433 (für SQL Logic Sandbox)
• Claude Desktop mit MCP-Unterstützung

⚠️ WICHTIG: LiteFarm CORS-Konfiguration

Dieser MCP-Server benötigt eine leicht modifizierte LiteFarm-Installation!

Das offizielle LiteFarm-Repository blockiert lokale Anfragen für MCP-Server. Du musst die CORS-Konfiguration in packages/api/src/server.ts anpassen:

const getAllowedOrigin = () => {
  const env = process.env.NODE_ENV || 'development';
  switch (env) {
    case 'development':
      return '*';
    case 'integration':
      return 'https://beta.litefarm.org';
    case 'production':
      return 'https://app.litefarm.org';
    default:
      return '*';  // ← WICHTIG: Default zu '*' für lokale Entwicklung
  }
};

Änderungen gegenüber Original:

• Runtime process.env.NODE_ENV statt Compile-Time environment
• Default-Fall: '*' statt 'https://app.litefarm.org'

Warum notwendig?

• ✅ Funktioniert mit und ohne NODE_ENV gesetzt
• ✅ MCP-Server können auf localhost:5000 zugreifen
• ✅ Keine Abhängigkeit von expliziter Environment-Variable

Alternative: Setze NODE_ENV=development in packages/api/.env (fehleranfälliger)

🧪 CORS-Test durchführen

Nach der CORS-Anpassung, teste ob die Konfiguration korrekt ist:

# Test 1: Health-Check
curl http://localhost:5000/health

# Test 2: CORS-Header prüfen
curl -H "Origin: http://localhost:3001" \
     -H "Access-Control-Request-Method: GET" \
     -H "Access-Control-Request-Headers: Content-Type" \
     -X OPTIONS \
     --verbose \
     http://localhost:5000/api/farms

# Erwartetes Ergebnis:
# < Access-Control-Allow-Origin: *

Wenn du Access-Control-Allow-Origin: * siehst → ✅ CORS korrekt konfiguriert!

🚀 Installation

Schritt 1: Repository Setup

cd C:\Users\YourUsername\graph-project\litefarm-mcp-server
npm install

Schritt 2: Konfiguration

Kopiere .env.example zu .env und fülle die Werte aus:

copy .env.example .env

Bearbeite .env:

# LiteFarm API Configuration
LITEFARM_API_URL=http://localhost:5000
LITEFARM_EMAIL=deine-email@example.com
LITEFARM_PASSWORD=dein-passwort
TRANSPORT=stdio

# Database Configuration (für SQL Logic Sandbox)
DB_HOST=localhost
DB_PORT=5433
DB_NAME=pg-litefarm
DB_USER=postgres
DB_PASSWORD=postgres

Schritt 3: Claude Desktop Integration

WICHTIG: Der Server läuft mit tsx direkt auf den TypeScript-Dateien, kein Build nötig!

Füge den Server zu deiner claude_desktop_config.json hinzu:

Pfad: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "litefarm": {
      "command": "node",
      "args": [
        "C:\\Users\\YourUsername\\graph-project\\Litefarm-mcp-server\\node_modules\\tsx\\dist\\cli.mjs",
        "C:\\Users\\YourUsername\\graph-project\\Litefarm-mcp-server\\index.ts"
      ],
      "cwd": "C:\\Users\\YourUsername\\graph-project\\Litefarm-mcp-server",
      "env": {
        "LITEFARM_API_URL": "http://localhost:5000",
        "LITEFARM_EMAIL": "deine-email@example.com",
        "LITEFARM_PASSWORD": "dein-passwort"
      }
    }
  }
}

Wichtig:

• Passe die Pfade und Credentials an!
• Verwende absolute Pfade mit doppelten Backslashes (\\)
• Der cwd Parameter muss auf das Projektverzeichnis zeigen
• Die args müssen sowohl tsx als auch index.ts mit absolutem Pfad enthalten

🎮 Nutzung

In Claude Desktop

Nach dem Restart von Claude Desktop kannst du Fragen stellen wie:

"Zeige mir alle meine Farmen"
"Erstelle eine neue Farm namens 'Green Valley Farm'"
"Liste alle offenen Aufgaben für Farm ABC123"
"Welche Crops sind verfügbar?"
"Markiere Task #42 als abgeschlossen"

Verfügbare Tools

Farm Management (API)

• litefarm_list_farms - Alle Farmen auflisten
• litefarm_get_farm - Farm-Details abrufen
• litefarm_create_farm - Neue Farm erstellen
• litefarm_update_farm - Farm aktualisieren

Task Management (API)

• litefarm_list_tasks - Aufgaben auflisten
• litefarm_create_task - Neue Aufgabe erstellen
• litefarm_complete_task - Aufgabe abschließen

Crop Management (API)

• litefarm_list_crops - Pflanzen auflisten
• litefarm_get_crop - Pflanze-Details abrufen

Database Tools (SQL Logic Sandbox)

• db_get_schema - Datenbank-Schema inspizieren (Tabellen, Spalten, Foreign Keys)
• db_execute_sql - SQL-Queries direkt ausführen (mit automatischem Rollback bei Fehlern)

Vorteile der SQL Tools:

• Komplexe Multi-Step-Operationen in einer atomaren Transaktion
• Dependency-Chain-Problem gelöst (Location → Crop → Plan → Task)
• Automatisches Rollback bei Fehlern
• PL/pgSQL Support für Variablen und Conditional Logic

Siehe SQL_LOGIC_SANDBOX_README.md für Details und Beispiele.

⚡ Performance-Optimierungen

Der MCP Server enthält integrierte Performance-Optimierungen zur Reduzierung der API-Last:

• In-Memory Caching: Häufig abgefragte Daten (Farms, Crops) werden gecacht

  • Farm-Listen: 5 Minuten TTL
  • Crop-Daten: 10 Minuten TTL
  • Automatische Cache-Invalidierung bei Änderungen

• Rate Limiting: Begrenzt gleichzeitige API-Requests

  • Max. 5 parallele Requests
  • Max. 10 Requests pro Sekunde
  • Verhindert API-Überlastung

Resultat: ~60-70% weniger API-Requests und deutlich reduzierte CPU-Last auf dem LiteFarm API-Server.

Siehe PERFORMANCE_OPTIMIZATION.md für Details und geplante Optimierungen.

Performance-Test ausführen

npm run test:performance

🔍 Troubleshooting

CORS-Fehler: "No 'Access-Control-Allow-Origin' header"

Problem: MCP-Server kann nicht auf LiteFarm zugreifen, CORS blockiert Anfragen

Ursache: CORS-Änderung in LiteFarm nicht durchgeführt oder NODE_ENV falsch gesetzt

Lösung:

# 1. Prüfe aktuelle getAllowedOrigin Funktion in LiteFarm
cd /path/to/LiteFarm/packages/api/src
grep -A 12 "const getAllowedOrigin" server.ts

# 2. Wenn nicht modifiziert, führe CORS-Änderung durch (siehe oben)

# 3. LiteFarm Backend neu starten
cd /path/to/LiteFarm/packages/api
npm run dev

# 4. Teste CORS-Header
curl -H "Origin: http://localhost:3001" -X OPTIONS http://localhost:5000/api/farms
# Sollte "Access-Control-Allow-Origin: *" zurückgeben

Server startet nicht

Problem: Missing required environment variables

Lösung:

# Prüfe ob .env existiert
dir .env

# Falls nicht, kopiere .env.example
copy .env.example .env

# Bearbeite .env mit deinen Credentials
notepad .env

Verbindung zu LiteFarm fehlschlägt

Problem: Failed to connect to LiteFarm API

Lösung:

# 1. Prüfe ob LiteFarm läuft
curl http://localhost:5000

# 2. Prüfe ob API läuft
curl http://localhost:5000/api-docs

# 3. Teste Login manuell (in PowerShell)
$body = @{
    email = "deine-email@example.com"
    password = "dein-passwort"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:5000/api/login" -Method POST -Headers @{"Content-Type"="application/json"} -Body $body

Claude Desktop erkennt Server nicht

Lösung:

# 1. Prüfe Build
npm run build

# 2. Teste Server direkt
node dist/index.js

# 3. Prüfe Claude Config
notepad %APPDATA%\Claude\claude_desktop_config.json

# 4. Restart Claude Desktop komplett
taskkill /F /IM Claude.exe
start "" "C:\Users\flori\AppData\Local\Programs\Claude\Claude.exe"

🧪 Development

Development Mode

# Build + Start in einem Schritt
npm run dev

# Watch Mode (automatisches Rebuild)
npm run watch

Logs prüfen

Der Server loggt nach stderr:

# Server direkt ausführen um Logs zu sehen
node dist/index.js 2> server.log

Testing

# Mit MCP Inspector testen
npx @modelcontextprotocol/inspector node dist/index.js

📁 Projekt-Struktur

Litefarm-mcp-server/
├── index.ts                       # Haupt-Server (Einstiegspunkt)
├── types.ts                       # TypeScript Types
├── constants.ts                   # Konstanten
├── litefarm-client.ts             # API Client für LiteFarm
├── tool-utils.ts                  # Gemeinsame Tool-Funktionen
├── farm-tools.ts                  # Farm Management Tools
├── task-tools.ts                  # Task Management Tools
├── crop-tools.ts                  # Crop Management Tools
├── db-tools.ts                    # Database Tools (SQL Logic Sandbox)
├── create-test-user.js            # Script zum Erstellen eines Test-Users
├── test-login.js                  # Script zum Testen der Login-Funktion
├── package.json
├── tsconfig.json
├── .env.example                   # Beispiel-Konfiguration
├── README.md                      # Diese Datei
├── SQL_LOGIC_SANDBOX_README.md    # SQL Logic Sandbox Dokumentation
└── LEARNINGS.md                   # Dokumentation aller Probleme & Lösungen

Hinweis: Die Dateien liegen im Root-Verzeichnis, nicht in einem src/ oder tools/ Unterordner!

🔐 Sicherheit

• Credentials: Niemals .env in Git committen!
• API-Keys: Werden nur lokal gespeichert
• Netzwerk: Server kommuniziert nur mit lokalem LiteFarm
• SQL Sandbox: Nur Read/Write-Operationen erlaubt (kein DDL: CREATE TABLE, DROP, etc.)
• Transaktionen: Automatisches Rollback bei Fehlern verhindert Daten-Inkonsistenzen

🐛 Bekannte Probleme

Windows-spezifisch

• Pfade: Nutze \\ statt / in Windows-Pfaden
• PowerShell: Manche npm-Scripts brauchen cmd /c npm run ...

LiteFarm API

• Token Expiry: Tokens laufen nach Zeit ab - Server erneuert automatisch
• Rate Limiting: Bei zu vielen Requests 429-Fehler möglich

🎯 Nächste Schritte

Erweiterungen (Optional)

1. Weitere Tools hinzufügen:

   • User Management
   • Document Upload
   • Reports/Analytics

2. HTTP-Transport für n8n-Integration:

   TRANSPORT=http
   PORT=3000
   

3. SQL Logic Sandbox Erweiterungen:

   • Read-only Mode für sicherere Operationen
   • Query Templates für häufige Operationen
   • Transaction History/Audit Log

4. Evaluations erstellen (siehe MCP Builder Skill)

📚 Ressourcen

• LiteFarm API Docs: http://localhost:5000/api-docs
• SQL Logic Sandbox Docs: SQL_LOGIC_SANDBOX_README.md
• MCP Docs: https://modelcontextprotocol.io
• MCP Code Execution Article: https://www.anthropic.com/engineering/code-execution-with-mcp
• TypeScript MCP SDK: https://github.com/modelcontextprotocol/typescript-sdk
• PostgreSQL PL/pgSQL: https://www.postgresql.org/docs/current/plpgsql.html

💡 Support

Bei Problemen:

1. Prüfe die Troubleshooting Sektion
2. Schaue in server.log nach Fehlern
3. Teste LiteFarm API direkt mit Swagger UI

---

Status: ✅ Produktionsreif (mit SQL Logic Sandbox) Version: 1.0.0 Branch: feature/sql-logic-sandbox Erstellt: November 2025