gurddy mcp

offiziell

his repository contains a fully functional MCP (Model Context Protocol) server, providing solutions for Constraint Satisfaction Problems (CSP) and Linear Programming (LP). It is based on the gurddy package and supports solving a variety of classic problems.

GitHub

Dokumentation

Gurddy MCP Server

Ein umfassender Model Context Protocol (MCP) Server zur Lösung von Constraint Satisfaction Problems (CSP), Linearer Programmierung (LP), Minimax-Optimierung und SciPy-gestützten fortgeschrittenen Optimierungsproblemen. Aufgebaut auf der gurddy Optimierungsbibliothek mit SciPy-Integration, unterstützt er die Lösung verschiedener klassischer Probleme über zwei MCP-Transporte: stdio (für IDE-Integration) und streamable HTTP (für Web-Clients).

🚀 Schnellstart (Stdio): pip install gurddy_mcp dann in Ihrer IDE konfigurieren

🌐 Schnellstart (HTTP): docker run -p 8080:8080 gurddy-mcp oder siehe Bereitstellungsleitfaden

📦 PyPI-Paket: https://pypi.org/project/gurddy_mcp

Hauptfunktionen

🎯 CSP-Problemlösung

N-Damen-Problem: Platziere N Damen auf einem N×N Schachbrett ohne Angriffsmöglichkeiten
Graphfärbung: Weise Knoten Farben zu, sodass benachbarte Knoten unterschiedliche Farben haben
Kartenfärbung: Färbe geografische Regionen, wobei angrenzende Regionen unterschiedlich sein müssen
Sudoku-Löser: Löse standardmäßige 9×9 Sudoku-Rätsel
Logikrätsel: Einsteins Zebrarätsel und benutzerdefinierte Logikprobleme
Terminplanung: Kursplanung, Besprechungsplanung, Ressourcenzuweisung
Allgemeiner CSP-Löser: Unterstützung für benutzerdefinierte Constraint-Satisfaction-Probleme

📊 LP/Optimierungsprobleme

Lineare Programmierung: Kontinuierliche Variablenoptimierung mit linearen Nebenbedingungen
Gemischte ganzzahlige Programmierung: Optimierung mit ganzzahligen und kontinuierlichen Variablen
Produktionsplanung: Ressourcenbeschränkte Produktionsoptimierung mit Sensitivitätsanalyse
Portfolio-Optimierung: Investitionsallokation unter Risikobeschränkungen
Transportprobleme: Lieferketten- und Logistikoptimierung

🎮 Minimax/Spieltheorie

Nullsummenspiele: Löse Zwei-Spieler-Spiele (Schere-Stein-Papier, Münzabgleich, Kampf der Geschlechter)
Gemischtstrategische Nash-Gleichgewichte: Finde optimale probabilistische Strategien
Robuste Optimierung: Minimiere den Worst-Case-Verlust unter Unsicherheit
Maximin-Entscheidungen: Maximiere den Worst-Case-Gewinn (konservative Strategien)
Sicherheitsspiele: Verteidiger-Angreifer-Ressourcenzuweisung
Robustes Portfolio: Minimiere den maximalen Verlust über Marktszenarien hinweg
Produktionsplanung: Konservative Produktionsentscheidungen (maximiere den minimalen Gewinn)
Werbewettbewerb: Marktanteilsspiele und Wettbewerbsstrategien

🔬 SciPy-Integration

Nichtlineare Portfolio-Optimierung: Quadratische Risikomodelle mit SciPy-Optimierung
Statistische Parameterschätzung: Verteilungsanpassung mit Nebenbedingungen (MLE, Quantilabgleich)
Signalverarbeitungsoptimierung: FIR-Filterdesign mit Frequenzgangoptimierung
Hybride CSP-SciPy: Diskrete Standortauswahl + kontinuierliche Kapazitätsoptimierung
Numerische Integration: Optimierungsprobleme mit Integralen und komplexen Funktionen

🧮 Klassische Mathematikprobleme

24-Punkte-Spiel: Finde arithmetische Ausdrücke, um mit vier Zahlen 24 zu erreichen
Huhn-Kaninchen-Problem: Klassisches Beschränkungsproblem mit Köpfen und Beinen
Mini-Sudoku: 4×4 Sudoku-Löser mit CSP-Techniken
4-Damen-Problem: Vereinfachtes N-Damen-Problem für Bildungszwecke
0-1 Rucksackproblem: Klassisches Optimierungsproblem mit Gewichts- und Wertbeschränkungen

🔌 MCP-Protokollunterstützung

Stdio-Transport: Lokale IDE-Integration (Kiro, Claude Desktop, Cline usw.)
Streamable HTTP-Transport: Web-Clients und Fernzugriff mit optionalem Streaming
Einheitliche Schnittstelle: Dieselben Werkzeuge über beide Transporte hinweg
JSON-RPC 2.0: Vollständige Protokollkonformität
Auto-Genehmigung: Konfiguriere vertrauenswürdige Werkzeuge für nahtlose Ausführung

Installation

Von PyPI (Empfohlen)

# Install the latest stable version
pip install gurddy_mcp

# Or install with development dependencies
pip install gurddy_mcp[dev]

Aus dem Quellcode

# Clone the repository
git clone https://github.com/novvoo/gurddy-mcp.git
cd gurddy-mcp

# Install in development mode
pip install -e .

Installation überprüfen

# Test MCP stdio server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | gurddy-mcp

Verwendung

1. MCP Stdio Server (Primäre Schnittstelle)

Der Hauptbefehl gurddy-mcp ist ein MCP-Stdio-Server, der mit Werkzeugen wie Kiro integriert werden kann.

Option A: Verwendung von uvx (Empfohlen – Immer die neueste Version)

Die Verwendung von uvx stellt sicher, dass Sie immer die neueste veröffentlichte Version ohne manuelle Installation ausführen.

Konfiguration in ~/.kiro/settings/mcp.json oder .kiro/settings/mcp.json:

Empfohlen: Explizite neueste Version

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example",
        "info",
        "install",
        "solve_n_queens",
        "solve_sudoku",
        "solve_graph_coloring",
        "solve_map_coloring",
        "solve_lp",
        "solve_production_planning",
        "solve_minimax_game",
        "solve_minimax_decision",
        "solve_24_point_game",
        "solve_chicken_rabbit_problem",
        "solve_scipy_portfolio_optimization",
        "solve_scipy_statistical_fitting",
        "solve_scipy_facility_location"
      ]
    }
  }
}

Alternative: Ohne Versionsspezifikation (verwendet ebenfalls die neueste)

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example", "info", "install", "solve_n_queens", "solve_sudoku", 
        "solve_graph_coloring", "solve_map_coloring", "solve_lp", 
        "solve_production_planning", "solve_minimax_game", "solve_minimax_decision",
        "solve_24_point_game", "solve_chicken_rabbit_problem", 
        "solve_scipy_portfolio_optimization", "solve_scipy_statistical_fitting", 
        "solve_scipy_facility_location"
      ]
    }
  }
}

Auf bestimmte Version festlegen (falls erforderlich)

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp==<VERSION>"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example", "info", "install", "solve_n_queens", "solve_sudoku", 
        "solve_graph_coloring", "solve_map_coloring", "solve_lp", 
        "solve_production_planning", "solve_minimax_game", "solve_minimax_decision",
        "solve_24_point_game", "solve_chicken_rabbit_problem", 
        "solve_scipy_portfolio_optimization", "solve_scipy_statistical_fitting", 
        "solve_scipy_facility_location"
      ]
    }
  }
}

Warum uvx verwenden?

✅ Führt automatisch immer die neueste veröffentlichte Version aus
✅ Keine manuelle Installation oder Aktualisierung erforderlich
✅ Isolierte Umgebung pro Ausführung
✅ Keine Abhängigkeitskonflikte mit Ihrem System-Python

Voraussetzungen: Installieren Sie zuerst uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Option B: Verwendung des direkten Befehls (Nach der Installation)

Wenn Sie gurddy-mcp bereits über pip installiert haben:

{
  "mcpServers": {
    "gurddy": {
      "command": "gurddy-mcp",
      "args": [],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example", "info", "install", "solve_n_queens", "solve_sudoku", 
        "solve_graph_coloring", "solve_map_coloring", "solve_lp", 
        "solve_production_planning", "solve_minimax_game", "solve_minimax_decision",
        "solve_24_point_game", "solve_chicken_rabbit_problem", 
        "solve_scipy_portfolio_optimization", "solve_scipy_statistical_fitting", 
        "solve_scipy_facility_location"
      ]
    }
  }
}

Verfügbare MCP-Werkzeuge (16 insgesamt):

info – Informationen und Fähigkeiten des Gurddy MCP-Servers abrufen
install – Das Gurddy-Paket installieren oder aktualisieren
run_example – Beispielprogramme ausführen (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems usw.)
solve_n_queens – N-Damen-Problem für jede Brettgröße lösen
solve_sudoku – 9×9 Sudoku-Rätsel mit CSP lösen
solve_graph_coloring – Graphfärbung mit konfigurierbaren Farben lösen
solve_map_coloring – Kartenfärbungsprobleme lösen (z. B. Australien, USA)
solve_lp – Lineare Programmierung (LP) oder gemischte ganzzahlige Programmierung (MIP) lösen
solve_production_planning – Produktionsoptimierung mit optionaler Sensitivitätsanalyse
solve_minimax_game – Zwei-Spieler-Nullsummenspiele (Nash-Gleichgewichte finden)
solve_minimax_decision – Robuste Optimierung (maximalen Verlust minimieren oder minimalen Gewinn maximieren)
solve_24_point_game – 24-Punkte-Spiel mit vier Zahlen unter Verwendung arithmetischer Operationen lösen
solve_chicken_rabbit_problem – Klassisches Huhn-Kaninchen-Problem mit Kopf- und Beinbeschränkungen lösen
solve_scipy_portfolio_optimization – Nichtlineare Portfolio-Optimierung mit SciPy lösen
solve_scipy_statistical_fitting – Statistische Parameterschätzung mit SciPy lösen
solve_scipy_facility_location – Standortproblem mit hybridem CSP-SciPy-Ansatz lösen

Testen Sie den MCP-Server:

# Test initialization
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | gurddy-mcp

# Test listing tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | gurddy-mcp

# Test info tools
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"info","arguments":{"":""}}}' | gurddy-mcp |jq 

# Test run example tools
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"run_example","arguments":{"example":"n_queens"}}}' | gurddy-mcp |jq

# Test sudoku tools
cat <<EOF | tr -d '\n'|gurddy-mcp|jq
{"jsonrpc":"2.0","id":123,"method":"tools/call","params":{
  "name":"solve_sudoku",
  "arguments":{
    "puzzle":[
      [5,3,0,0,7,0,0,0,0],
      [6,0,0,1,9,5,0,0,0],
      [0,9,8,0,0,0,0,6,0],
      [8,0,0,0,6,0,0,0,3],
      [4,0,0,8,0,3,0,0,1],
      [7,0,0,0,2,0,0,0,6],
      [0,6,0,0,0,0,2,8,0],
      [0,0,0,4,1,9,0,0,5],
      [0,0,0,0,8,0,0,7,9]
    ]
  }
}}
EOF

2. MCP HTTP Server

Starten Sie den HTTP-MCP-Server (MCP-Protokoll über streamable HTTP):

Lokale Entwicklung:

uvicorn mcp_server.mcp_http_server:app --host 127.0.0.1 --port 8080

Docker:

# Build the image
docker build -t gurddy-mcp .

# Run the container
docker run -p 8080:8080 gurddy-mcp

Zugriff auf den Server:

Root: http://127.0.0.1:8080/
Health-Check: http://127.0.0.1:8080/health
HTTP-Transport: http://127.0.0.1:8080/mcp/http (POST – unterstützt sowohl reguläre als auch Streaming-Antworten)

Testen des HTTP-MCP-Servers:

HTTP-Transport (nicht-streaming):

# List available tools
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"info","arguments":{}}}'

HTTP-Transport (Streaming mit Accept-Header):

# List tools with streaming response
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool with streaming response
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"solve_n_queens","arguments":{"n":4}}}'

HTTP-Transport (Streaming mit X-Stream-Header):

# Alternative way to enable streaming
curl -X POST http://127.0.0.1:8080/mcp/http \
  -H "Content-Type: application/json" \
  -H "X-Stream: true" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"info","arguments":{}}}'

Python-Client-Beispiel:

examples/streamable_http_client.py – HTTP-Transport-Client mit Streaming-Beispielen

MCP-Werkzeuge

Der Server bietet die folgenden MCP-Werkzeuge:

info

Informationen über das Gurddy-Paket abrufen.

{
  "name": "info",
  "arguments": {}
}

install

Das Gurddy-Paket installieren oder aktualisieren.

{
  "name": "install",
  "arguments": {
    "package": "gurddy",
    "upgrade": false
  }
}

run_example

Ein Gurddy-Beispiel ausführen.

{
  "name": "run_example",
  "arguments": {
    "example": "n_queens"
  }
}

Verfügbare Beispiele: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Das N-Damen-Problem lösen.

{
  "name": "solve_n_queens",
  "arguments": {
    "n": 8
  }
}

solve_sudoku

Ein 9x9 Sudoku-Rätsel lösen.

{
  "name": "solve_sudoku",
  "arguments": {
    "puzzle": [[5,3,0,...], [6,0,0,...], ...]
  }
}

solve_graph_coloring

Graphfärbungsproblem lösen.

{
  "name": "solve_graph_coloring",
  "arguments": {
    "edges": [[0,1], [1,2], [2,0]],
    "num_vertices": 3,
    "max_colors": 3
  }
}

solve_map_coloring

Kartenfärbungsproblem lösen.

{
  "name": "solve_map_coloring",
  "arguments": {
    "regions": ["A", "B", "C"],
    "adjacencies": [["A", "B"], ["B", "C"]],
    "max_colors": 2
  }
}

solve_lp

Ein lineares Programmierungs- (LP) oder gemischt-ganzzahliges Programmierungsproblem (MIP) mit PuLP lösen.

{
  "name": "solve_lp",
  "arguments": {
    "profits": {
      "ProductA": 30,
      "ProductB": 40
    },
    "consumption": {
      "ProductA": {"Labor": 2, "Material": 3},
      "ProductB": {"Labor": 3, "Material": 2}
    },
    "capacities": {
      "Labor": 100,
      "Material": 120
    },
    "integer": true
  }
}

solve_production_planning

Ein Produktionsplanungs-Optimierungsproblem mit optionaler Sensitivitätsanalyse lösen.

{
  "name": "solve_production_planning",
  "arguments": {
    "profits": {
      "ProductA": 30,
      "ProductB": 40
    },
    "consumption": {
      "ProductA": {"Labor": 2, "Material": 3},
      "ProductB": {"Labor": 3, "Material": 2}
    },
    "capacities": {
      "Labor": 100,
      "Material": 120
    },
    "integer": true,
    "sensitivity_analysis": false
  }
}

solve_minimax_game

Ein Zwei-Spieler-Nullsummenspiel mit Minimax (Spieltheorie) lösen.

{
  "name": "solve_minimax_game",
  "arguments": {
    "payoff_matrix": [
      [0, -1, 1],
      [1, 0, -1],
      [-1, 1, 0]
    ],
    "player": "row"
  }
}

Gibt die optimale gemischte Strategie und den Spielwert für den angegebenen Spieler zurück.

solve_minimax_decision

Ein Minimax-Entscheidungsproblem unter Unsicherheit lösen (robuste Optimierung).

{
  "name": "solve_minimax_decision",
  "arguments": {
    "scenarios": [
      {"A": -0.2, "B": -0.1, "C": 0.05},
      {"A": 0.3, "B": 0.2, "C": -0.02},
      {"A": 0.05, "B": 0.03, "C": -0.01}
    ],
    "decision_vars": ["A", "B", "C"],
    "budget": 100.0,
    "objective": "minimize_max_loss"
  }
}

Ziele: minimize_max_loss (robustes Portfolio) oder maximize_min_gain (konservative Produktion)

solve_24_point_game

Das 24-Punkte-Spiel mit vier Zahlen unter Verwendung arithmetischer Operationen lösen.

{
  "name": "solve_24_point_game",
  "arguments": {
    "numbers": [1, 2, 3, 4]
  }
}

Findet arithmetische Ausdrücke mit +, -, *, / und Klammern, um genau 24 zu erreichen.

solve_chicken_rabbit_problem

Das klassische Huhn-Kaninchen-Problem mit Kopf- und Beinbeschränkungen lösen.

{
  "name": "solve_chicken_rabbit_problem",
  "arguments": {
    "total_heads": 35,
    "total_legs": 94
  }
}

Bestimmt die Anzahl der Hühner (2 Beine) und Kaninchen (4 Beine) bei gegebenen Gesamtköpfen und -beinen.

solve_scipy_portfolio_optimization

Nichtlineare Portfolio-Optimierung mit SciPy und quadratischen Risikomodellen lösen.

{
  "name": "solve_scipy_portfolio_optimization",
  "arguments": {
    "expected_returns": [0.12, 0.18, 0.15],
    "covariance_matrix": [
      [0.04, 0.01, 0.02],
      [0.01, 0.09, 0.03],
      [0.02, 0.03, 0.06]
    ],
    "risk_tolerance": 1.0
  }
}

Optimiert Portfolio-Gewichte, um die Rendite abzüglich der Risikostrafe mittels Mean-Variance-Optimierung zu maximieren.

solve_scipy_statistical_fitting

Statistische Parameterschätzung mit SciPy und Verteilungsanpassung lösen.

{
  "name": "solve_scipy_statistical_fitting",
  "arguments": {
    "data": [1.2, 2.3, 1.8, 2.1, 1.9, 2.4, 1.7, 2.0],
    "distribution": "normal"
  }
}

Passt statistische Verteilungen („normal“, „exponential“, „uniform“) an Daten an und liefert Anpassungstests.

solve_scipy_facility_location

Standortproblem mit hybridem CSP-SciPy-Ansatz lösen.

{
  "name": "solve_scipy_facility_location",
  "arguments": {
    "customer_locations": [[0, 0], [10, 10], [5, 15]],
    "customer_demands": [100, 150, 80],
    "facility_locations": [[2, 3], [8, 12], [6, 8]],
    "max_facilities": 2,
    "fixed_cost": 100.0
  }
}

Kombiniert diskrete Standortauswahl (CSP) mit kontinuierlicher Kapazitätsoptimierung (SciPy), um die Gesamtkosten zu minimieren.

Docker-Bereitstellung

Bauen und Ausführen

# Build the image
docker build -t gurddy-mcp .

# Run the container
docker run -p 8080:8080 gurddy-mcp

# Or with environment variables
docker run -p 8080:8080 -e PORT=8080 gurddy-mcp

Docker Compose

version: '3.8'
services:
  gurddy-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - PYTHONUNBUFFERED=1
    restart: unless-stopped

Beispielausgabe

N-Damen-Problem

POST /solve-n-queens
{
"n": 8
}

Projektstruktur

mcp_server/
├── handlers/
│   └── gurddy.py           # Core solver implementation (16 MCP tools)
│                          # - solve_24_point_game, solve_chicken_rabbit_problem
│                          # - solve_scipy_portfolio_optimization, solve_scipy_statistical_fitting
│                          # - solve_scipy_facility_location, and 11 other solvers
├── tools/                  # MCP tool wrappers
├── examples/               # Rich Problem Examples
│   ├── n_queens.py         # N-Queens Problem
│   ├── graph_coloring.py   # Graph Coloring Problem
│   ├── map_coloring.py     # Map Coloring Problem
│   ├── logic_puzzles.py    # Logic Puzzles
│   ├── scheduling.py       # Scheduling Problem
│   ├── scipy_optimization.py # SciPy Integration Examples
│   │                      # - Portfolio optimization, statistical fitting, facility location
│   ├── classic_problems.py # Classic Math Problems
│   │                      # - 24-point game, chicken-rabbit problem, mini sudoku
│   ├── optimized_csp.py    # Advanced CSP techniques
│   ├── optimized_lp.py     # Linear programming examples
│   └── minimax.py          # Game theory and robust optimization
├── mcp_stdio_server.py     # MCP Stdio Server (for IDE integration)
└── mcp_http_server.py      # MCP HTTP Server (for web clients)

examples/
└── http_mcp_client.py      # Example HTTP MCP client

Dockerfile                  # Docker configuration for HTTP server

MCP-Transporte

Transport	Befehl	Protokoll	Anwendungsfall
Stdio	`gurddy-mcp`	MCP über stdin/stdout	IDE-Integration (Kiro, Claude Desktop usw.)
Streamable HTTP	`uvicorn mcp_server.mcp_http_server:app`	MCP über HTTP mit optionalem Streaming	Web-Clients, Fernzugriff, Docker-Bereitstellung

Alle Transporte implementieren dasselbe MCP-Protokoll und bieten identische Werkzeuge.

HTTP-Transport-Funktionen

HTTP-Transport (/mcp/http Endpunkt):

Einzelnes Anfrage-Antwort-Muster
Optionales Streaming: Fügen Sie den Accept: text/event-stream oder X-Stream: true Header hinzu
Einfacher für einmalige Anfragen
Kompatibel mit Standard-HTTP-Clients
Kein Verbindungsstatus zu verwalten
Unterstützt sowohl reguläre JSON-Antworten als auch SSE-formatierte Streaming-Antworten

Beispielausgabe

N-Damen-Problem

$ gurddy-mcp-cli run-example n_queens

Solving 8-Queens problem...

8-Queens Solution:
+---+---+---+---+---+---+---+---+
| Q |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   | Q |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   | Q |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   | Q |   |   |
+---+---+---+---+---+---+---+---+
|   |   | Q |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   | Q |   |
+---+---+---+---+---+---+---+---+
|   | Q |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | Q |   |   |   |   |
+---+---+---+---+---+---+---+---+
Queen positions: (0,0), (1,4), (2,7), (3,5), (4,2), (5,6), (6,1), (7,3)

Logikrätsel

$ python -m mcp_server.server run-example logic_puzzles

Solving Simple Logic Puzzle:
Solution:
Position 1: Alice has Cat in Green house
Position 2: Bob has Dog in Red house  
Position 3: Carol has Fish in Blue house

Solving the Famous Zebra Puzzle (Einstein's Riddle)...
ANSWERS:
Who owns the zebra? Ukrainian (House 5)
Who drinks water? Japanese (House 2)

HTTP-API-Beispiele

Klassische Problemlösung

Australische Kartenfärbung

import requests

response = requests.post("http://127.0.0.1:8080/solve-map-coloring", json={ 
"regions": ['WA', 'NT', 'SA', 'QLD', 'NSW', 'VIC', 'TAS'], 
"adjacencies": [ 
['WA', 'NT'], ['WA', 'SA'], ['NT', 'SA'], ['NT', 'QLD'], 
['SA', 'QLD'], ['SA', 'NSW'], ['SA', 'VIC'], 
['QLD', 'NSW'], ['NSW', 'VIC'] 
], 
"max_colors": 4
})

8-Damen-Problem

response = requests.post("http://127.0.0.1:8080/solve-n-queens",
json={"n": 8})

Verfügbare Beispiele

Alle Beispiele können mit gurddy-mcp run-example <name> oder python -m mcp_server.server run-example <name> ausgeführt werden:

CSP-Beispiele ✅

n_queens – N-Damen-Problem (4, 6, 8 Damen mit visueller Brettanzeige)
graph_coloring – Graphfärbung (Dreieck, Quadrat, Petersen-Graph, Radgraph)
map_coloring – Kartenfärbung (Australien, westliche US-Bundesstaaten, Europa)
scheduling – Terminplanungsprobleme (Kursplanung, Besprechungsplanung, Ressourcenzuweisung)
logic_puzzles – Logikrätsel (Einfaches Logikrätsel, Einsteins Zebrarätsel)
optimized_csp – Fortgeschrittene CSP-Techniken (Sudoku-Löser)

LP-Beispiele ✅

lp / optimized_lp – Beispiele für lineare Programmierung:
- Portfolio-Optimierung mit Risikobeschränkungen
- Transportproblem (Lieferkettenoptimierung)
- Analyse der Beschränkungslockerung
- Leistungsvergleich über Problemgrößen hinweg

Minimax-Beispiele ✅

minimax – Minimax-Optimierung und Spieltheorie:
- Schere-Stein-Papier (Nullsummenspiel)
- Münzabgleich (Koordinationsspiel)
- Kampf der Geschlechter (gemischtstrategisches Gleichgewicht)
- Robuste Portfolio-Optimierung (maximalen Verlust minimieren)
- Produktionsplanung (minimalen Gewinn maximieren)
- Sicherheitsressourcenzuweisung (Verteidiger-Angreifer-Spiel)
- Werbewettbewerb (Marktanteilsspiel)

SciPy-Integrationsbeispiele ✅

scipy_optimization - Erweiterte Optimierung mit SciPy:
- Nichtlineare Portfolio-Optimierung mit quadratischen Risikomodellen
- Statistische Parameterschätzung (Verteilungsanpassung mit Nebenbedingungen)
- Signalverarbeitungsoptimierung (FIR-Filter-Design)
- Hybride CSP-SciPy-Standortplanung (diskrete + kontinuierliche Optimierung)
- Numerische Integration in Optimierungszielen

Klassische Mathematikaufgaben ✅

classic_problems - Lehrreiche Problemlösungen aus der Mathematik:
- 24-Punkte-Spiel (arithmetische Ausdrücke, um 24 zu erreichen)
- Hühner-Kaninchen-Problem (klassische Nebenbedingungserfüllung)
- 4×4 Mini-Sudoku (vereinfachte CSP-Demonstration)
- 4-Damen-Problem (lehrreiche N-Damen-Variante)
- 0-1-Rucksackproblem (klassische Optimierung)

Unterstützte Problemtypen

🧩 CSP-Probleme

N-Damen: Klassisches N-Damen-Problem für jede Brettgröße (N=4 bis N=100+)
Graphenfärbung: Knotenfärbung für beliebige Graphen (Dreieck, Petersen, Rad, etc.)
Kartenfärbung: Geografische Gebietsfärbung (Karten von Australien, USA, Europa)
Sudoku: Standard 9×9 Sudoku-Rätsel mit Constraint-Propagation
Logikrätsel: Einsteins Zebrarätsel und benutzerdefinierte logische Denkaufgaben
Terminplanung: Kursplanung, Besprechungsräume, Ressourcenzuweisung mit Zeitbeschränkungen

📈 Optimierungsprobleme

Lineare Programmierung: Kontinuierliche Variablenoptimierung mit linearen Nebenbedingungen
Ganzzahlige Programmierung: Diskrete Variablenoptimierung (Produktionsmengen, Zuweisungen)
Gemischte ganzzahlige Programmierung: Kombinierte kontinuierliche und diskrete Variablen
Produktionsplanung: Mehrprodukt-Optimierung mit Ressourcenbeschränkungen
Portfolio-Optimierung: Investitionsallokation mit Risiko- und Renditebeschränkungen
Transport: Lieferkettenoptimierung (Lagerhäuser zu Kunden)

🎲 Spieltheorie & Robuste Optimierung

Nullsummenspiele: Schere-Stein-Papier, Münzabgleich, Kampf der Geschlechter
Nash-Gleichgewichte in gemischten Strategien: Optimale probabilistische Strategien für beide Spieler
Minimax-Entscheidungen: Minimierung des Worst-Case-Verlusts über Unsicherheitsszenarien
Maximin-Entscheidungen: Maximierung des Worst-Case-Gewinns (konservative Strategien)
Robustes Portfolio: Minimierung des maximalen Verlusts über Marktszenarien
Sicherheitsspiele: Verteidiger-Angreifer-Ressourcenzuweisungsprobleme

🔬 SciPy-gestützte erweiterte Optimierung

Nichtlineare Portfolio-Optimierung: Quadratische Risikomodelle mit Sharpe-Ratio-Maximierung
Statistische Parameterschätzung: MLE und quantilbasierte Verteilungsanpassung mit Nebenbedingungen
Signalverarbeitung: FIR-Filter-Design mit Frequenzgangoptimierung
Hybride Optimierung: Kombination von Gurddy CSP mit kontinuierlicher SciPy-Optimierung
Numerische Integration: Optimierungsprobleme mit komplexen mathematischen Funktionen

🧮 Klassische lehrreiche Probleme

24-Punkte-Spiel: Finden arithmetischer Ausdrücke mit vier Zahlen, um 24 zu erreichen
Hühner-Kaninchen-Problem: Klassische Nebenbedingungserfüllung mit Köpfen und Beinen
Mini-Sudoku: 4×4 Sudoku-Lösung mit CSP-Techniken
N-Damen-Varianten: Lehrreiche Versionen des klassischen Problems
Rucksackprobleme: 0-1-Rucksackoptimierung mit Gewichts- und Wertbeschränkungen

Leistungsmerkmale

Schnelle Lösung: Millisekunden-Antwort für kleine bis mittlere Probleme (N-Damen N≤12, Graphen <50 Knoten)
Skalierbar: Bewältigt große Probleme (N-Damen N=100+, LP mit 1000+ Variablen)
Speichereffizient: Backtracking-Suche und Constraint-Propagation minimieren die Speichernutzung
Erweiterbar: Benutzerdefinierte Nebenbedingungen, Zielfunktionen und Problemtypen
Nebenläufigkeitssicher: HTTP-API unterstützt gleichzeitige Anfrageverarbeitung
Produktionsreif: Docker-Bereitstellung, Health Checks, Fehlerbehandlung

Leistungsbenchmarks

Typische Ausführungszeiten auf Standardhardware:

CSP-Beispiele: 0,4-0,5 s (N-Damen, Graphenfärbung, Logikrätsel)
LP-Beispiele: 0,8-0,9 s (Portfolio, Transport, Produktionsplanung)
Minimax-Beispiele: 0,3-0,5 s (Spiel-Lösung, Robuste Optimierung)
SciPy-Beispiele: 0,5-1,2 s (Nichtlineare Optimierung, Statistische Anpassung)
Klassische Probleme: 0,1-0,3 s (24-Punkte, Hühner-Kaninchen, Mini-Sudoku)
Sudoku: <0,1 s für Standard 9×9 Rätsel
Große N-Damen: ~2-3 s für N=100

Fehlerbehebung

Häufige Fehler

"gurddy package not available": Installation mit python -m mcp_server.server install
"No solution found": Unter den gegebenen Nebenbedingungen existiert keine Lösung; versuchen Sie, die Nebenbedingungen zu lockern
"Invalid input types": Überprüfen Sie die Datentypen der Eingabeparameter
"Unknown example": Verwenden Sie python -m mcp_server.server run-example --help, um verfügbare Beispiele anzuzeigen

Installationsprobleme

# install individually
pip install gurddy pulp>=2.6.0 scipy>=1.9.0 numpy>=1.21.0

# Check installation
python -c "import gurddy, pulp, scipy, numpy; print('All dependencies installed')"

Beispiel-Debugging

Führen Sie Beispiele direkt zum Debuggen aus:

# After installing gurddy_mcp
python -c "from mcp_server.examples import n_queens; n_queens.main()"

# Or from source - CSP examples
python mcp_server/examples/n_queens.py
python mcp_server/examples/graph_coloring.py
python mcp_server/examples/logic_puzzles.py
python mcp_server/examples/optimized_csp.py

# LP and optimization examples
python mcp_server/examples/optimized_lp.py

# Game theory and minimax examples
python mcp_server/examples/minimax.py

# SciPy integration examples (includes portfolio, statistical fitting, facility location)
python mcp_server/examples/scipy_optimization.py

# Classic math problems (includes 24-point game, chicken-rabbit problem)
python mcp_server/examples/classic_problems.py

# Test individual MCP tools directly
python -c "from mcp_server.handlers.gurddy import solve_24_point_game; print(solve_24_point_game([1,2,3,4]))"
python -c "from mcp_server.handlers.gurddy import solve_chicken_rabbit_problem; print(solve_chicken_rabbit_problem(35, 94))"
python -c "from mcp_server.handlers.gurddy import solve_scipy_portfolio_optimization; print(solve_scipy_portfolio_optimization([0.12, 0.18], [[0.04, 0.01], [0.01, 0.09]]))"

SciPy-Integrationsanforderungen

Die SciPy-Integrationsbeispiele erfordern zusätzliche Abhängigkeiten:

# Install SciPy and NumPy 
pip install scipy>=1.9.0 numpy>=1.21.0

# Verify SciPy integration
python -c "import scipy.optimize, numpy; print('SciPy integration ready')"

SciPy-Beispiele umfassen:

Nichtlineare Portfolio-Optimierung: Quadratische Risikomodelle mit Sharpe-Ratio-Maximierung
Statistische Parameterschätzung: Verteilungsanpassung mit MLE- und Quantilmethoden
Signalverarbeitung: FIR-Filter-Design mit Frequenzgangoptimierung
Hybrides CSP-SciPy: Standortplanung mit Kombination aus diskreter und kontinuierlicher Optimierung
Numerische Integration: Komplexe Optimierungsprobleme mit Integralen

Entwicklung

Architektur

Das Projekt verwendet eine zentralisierte Tool-Registry mit automatisch generierten Schemata, um Konsistenz zwischen stdio- und HTTP-Servern sicherzustellen:

Tool-Definitionen: mcp_server/tool_definitions.py (nur grundlegende Metadaten)
Automatisch generierte Registry: mcp_server/tool_registry.py (Schemata aus Funktionssignaturen generiert)
Stdio-Server: mcp_server/mcp_stdio_server.py (für IDE-Integration)
HTTP-Server: mcp_server/mcp_http_server.py (für Web-Clients)
Handler: mcp_server/handlers/gurddy.py (Tool-Implementierungen)
Schema-Generator: scripts/generate_registry.py (generiert automatisch Schemata aus Funktionssignaturen)

Hinzufügen eines neuen Tools

Handler implementieren in mcp_server/handlers/gurddy.py:

def my_new_tool(param1: str, param2: int = 10) -> Dict[str, Any]:
    """Tool implementation with proper type hints."""
    return {"result": "success"}

Grundlegende Metadaten hinzufügen in mcp_server/tool_definitions.py:

{
    "name": "my_new_tool",
    "function": "my_new_tool",
    "description": "Description of what the tool does",
    "category": "optimization",
    "module": "handlers.gurddy"
}

Schemata generieren und verifizieren:

# Auto-generate schemas from function signatures
python scripts/generate_registry.py

# Verify consistency
python scripts/verify_consistency.py
pytest tests/test_consistency.py -v

Das war's! Das Schema wird automatisch aus den Typhinweisen Ihrer Funktion generiert, und sowohl stdio- als auch HTTP-Server werden das neue Tool übernehmen.

Benutzerdefinierte Nebenbedingungen

# Define a custom constraint in gurddy
def custom_constraint(var1, var2):
    return var1 + var2 <= 10

model.addConstraint(gurddy.FunctionConstraint(custom_constraint, (var1, var2)))

Testen

# Run all tests
pytest

# Run specific test suites
pytest tests/test_consistency.py -v
pytest tests/test_tool_registry.py -v

# Verify tool registry consistency
python scripts/verify_consistency.py

Lizenz

Dieses Projekt ist unter einer Open-Source-Lizenz lizenziert. Einzelheiten finden Sie in der LICENSE-Datei.