gurddy mcp Server

officiel

Ce dépôt contient un serveur MCP (Model Context Protocol) entièrement fonctionnel, fournissant des solutions pour les problèmes de satisfaction de contraintes (CSP) et la programmation linéaire (LP). Il est basé sur le package gurddy et prend en charge la résolution de divers problèmes classiques.

GitHub
2

Documentation

Serveur MCP Gurddy

PyPI version Python Support License: MIT Live Demo

Un serveur complet de protocole de contexte de modèle (MCP) pour résoudre les problèmes de satisfaction de contraintes (CSP), la programmation linéaire (LP), l'optimisation Minimax et les problèmes d'optimisation avancée basés sur SciPy. Construit sur la bibliothèque d'optimisation gurddy avec intégration SciPy, il prend en charge la résolution de divers problèmes classiques via deux transports MCP : stdio (pour l'intégration IDE) et HTTP streamable (pour les clients web).

🚀 Démarrage rapide (Stdio) : pip install gurddy_mcp puis configurez dans votre IDE

🌐 Démarrage rapide (HTTP) : docker run -p 8080:8080 gurddy-mcp ou consultez le guide de déploiement

📦 Paquet PyPI : https://pypi.org/project/gurddy_mcp

Fonctionnalités principales

🎯 Résolution de problèmes CSP

  • Problème des N-Reines : Placer N reines sur un échiquier N×N sans attaques
  • Coloration de graphe : Attribuer des couleurs aux sommets de sorte que les sommets adjacents diffèrent
  • Coloration de carte : Colorier des régions géographiques avec des régions adjacentes différentes
  • Solveur de Sudoku : Résoudre des puzzles de Sudoku 9×9 standard
  • Puzzles logiques : Le puzzle du zèbre d'Einstein et des problèmes logiques personnalisés
  • Planification : Planification de cours, de réunions, allocation de ressources
  • Solveur CSP général : Prise en charge des problèmes de satisfaction de contraintes personnalisés

📊 Problèmes LP/Optimisation

  • Programmation linéaire : Optimisation de variables continues avec contraintes linéaires
  • Programmation en nombres entiers mixtes : Optimisation avec variables entières et continues
  • Planification de production : Optimisation de la production sous contraintes de ressources avec analyse de sensibilité
  • Optimisation de portefeuille : Allocation d'investissement sous contraintes de risque
  • Problèmes de transport : Optimisation de la chaîne d'approvisionnement et de la logistique

🎮 Minimax/Théorie des jeux

  • Jeux à somme nulle : Résoudre des jeux à deux joueurs (Pierre-Feuille-Ciseaux, Matching Pennies, Bataille des sexes)
  • Équilibres de Nash en stratégie mixte : Trouver des stratégies probabilistes optimales
  • Optimisation robuste : Minimiser la perte du pire cas sous incertitude
  • Décisions Maximin : Maximiser le gain du pire cas (stratégies conservatrices)
  • Jeux de sécurité : Allocation de ressources défenseur-attaquant
  • Portefeuille robuste : Minimiser la perte maximale à travers les scénarios de marché
  • Planification de production : Décisions de production conservatrices (maximiser le profit minimum)
  • Concurrence publicitaire : Jeux de parts de marché et stratégies concurrentielles

🔬 Intégration SciPy

  • Optimisation de portefeuille non linéaire : Modèles de risque quadratiques avec optimisation SciPy
  • Estimation de paramètres statistiques : Ajustement de distribution avec contraintes (MLE, correspondance des quantiles)
  • Optimisation du traitement du signal : Conception de filtre FIR avec optimisation de la réponse en fréquence
  • CSP-SciPy hybride : Sélection d'installations discrètes + optimisation continue de la capacité
  • Intégration numérique : Problèmes d'optimisation impliquant des intégrales et des fonctions complexes

🧮 Problèmes mathématiques classiques

  • Jeu des 24 points : Trouver des expressions arithmétiques pour atteindre 24 en utilisant quatre nombres
  • Problème des poulets et des lapins : Problème de contrainte classique avec têtes et pattes
  • Mini Sudoku : Solveur de Sudoku 4×4 utilisant des techniques CSP
  • Problème des 4 reines : N-Reines simplifié à des fins éducatives
  • Sac à dos 0-1 : Problème d'optimisation classique avec contraintes de poids et de valeur

🔌 Prise en charge du protocole MCP

  • Transport Stdio : Intégration IDE locale (Kiro, Claude Desktop, Cline, etc.)
  • Transport HTTP streamable : Clients web et accès à distance avec streaming optionnel
  • Interface unifiée : Mêmes outils sur les deux transports
  • JSON-RPC 2.0 : Conformité totale au protocole
  • Approbation automatique : Configurer des outils de confiance pour une exécution transparente

Installation

Depuis PyPI (Recommandé)

# Install the latest stable version
pip install gurddy_mcp

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

Depuis la source

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

# Install in development mode
pip install -e .

Vérifier l'installation

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

Utilisation

1. Serveur MCP Stdio (Interface principale)

La commande principale gurddy-mcp est un serveur MCP stdio qui peut être intégré avec des outils comme Kiro.

Option A : Utiliser uvx (Recommandé - Toujours la dernière version)

Utiliser uvx garantit que vous exécutez toujours la dernière version publiée sans installation manuelle.

Configurer dans ~/.kiro/settings/mcp.json ou .kiro/settings/mcp.json :

Recommandé : Dernière version explicite

{
  "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 : Sans spécificateur de version (utilise également la dernière)

{
  "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"
      ]
    }
  }
}

Épingler à une version spécifique (si nécessaire)

{
  "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"
      ]
    }
  }
}

Pourquoi utiliser uvx ?

  • ✅ Exécute toujours automatiquement la dernière version publiée
  • ✅ Aucune installation ou mise à niveau manuelle nécessaire
  • ✅ Environnement isolé par exécution
  • ✅ Aucun conflit de dépendances avec votre Python système

Prérequis : Installer d'abord 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 : Utiliser la commande directe (Après installation)

Si vous avez déjà installé gurddy-mcp via pip :

{
  "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"
      ]
    }
  }
}

Outils MCP disponibles (16 au total) :

  • info - Obtenir des informations et les capacités du serveur MCP gurddy
  • install - Installer ou mettre à niveau le paquet gurddy
  • run_example - Exécuter des programmes d'exemple (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, etc.)
  • solve_n_queens - Résoudre le problème des N-Reines pour toute taille de plateau
  • solve_sudoku - Résoudre des puzzles de Sudoku 9×9 en utilisant CSP
  • solve_graph_coloring - Résoudre la coloration de graphe avec des couleurs configurables
  • solve_map_coloring - Résoudre des problèmes de coloration de carte (par exemple, Australie, États-Unis)
  • solve_lp - Résoudre la programmation linéaire (LP) ou la programmation en nombres entiers mixtes (MIP)
  • solve_production_planning - Optimisation de la production avec analyse de sensibilité optionnelle
  • solve_minimax_game - Jeux à somme nulle à deux joueurs (trouver les équilibres de Nash)
  • solve_minimax_decision - Optimisation robuste (minimiser la perte maximale ou maximiser le gain minimal)
  • solve_24_point_game - Résoudre le jeu des 24 points avec quatre nombres en utilisant des opérations arithmétiques
  • solve_chicken_rabbit_problem - Résoudre le problème classique des poulets et des lapins avec contraintes de têtes et de pattes
  • solve_scipy_portfolio_optimization - Résoudre l'optimisation de portefeuille non linéaire en utilisant SciPy
  • solve_scipy_statistical_fitting - Résoudre l'estimation de paramètres statistiques en utilisant SciPy
  • solve_scipy_facility_location - Résoudre le problème de localisation d'installations en utilisant une approche hybride CSP-SciPy

Tester le serveur MCP :

# 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. Serveur MCP HTTP

Démarrer le serveur MCP HTTP (protocole MCP sur HTTP streamable) :

Développement local :

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

Accéder au serveur :

Tester le serveur MCP HTTP :

Transport HTTP (non-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":{}}}'

Transport HTTP (streaming avec en-tête Accept) :

# 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}}}'

Transport HTTP (streaming avec en-tête X-Stream) :

# 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":{}}}'

Exemple de client Python :

  • examples/streamable_http_client.py - Client de transport HTTP avec exemples de streaming

Outils MCP

Le serveur fournit les outils MCP suivants :

info

Obtenir des informations sur le paquet gurddy.

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

install

Installer ou mettre à niveau le paquet gurddy.

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

run_example

Exécuter un exemple gurddy.

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

Exemples disponibles : lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Résoudre le problème des N-Reines.

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

solve_sudoku

Résoudre un puzzle de Sudoku 9x9.

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

solve_graph_coloring

Résoudre le problème de coloration de graphe.

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

solve_map_coloring

Résoudre le problème de coloration de carte.

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

solve_lp

Résoudre un problème de programmation linéaire (LP) ou de programmation en nombres entiers mixtes (MIP) en utilisant PuLP.

{
  "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

Résoudre un problème d'optimisation de planification de production avec analyse de sensibilité optionnelle.

{
  "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

Résoudre un jeu à somme nulle à deux joueurs en utilisant minimax (théorie des jeux).

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

Renvoie la stratégie mixte optimale et la valeur du jeu pour le joueur spécifié.

solve_minimax_decision

Résoudre un problème de décision minimax sous incertitude (optimisation robuste).

{
  "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"
  }
}

Objectifs : minimize_max_loss (portefeuille robuste) ou maximize_min_gain (production conservatrice)

solve_24_point_game

Résoudre le jeu des 24 points avec quatre nombres en utilisant des opérations arithmétiques.

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

Trouve des expressions arithmétiques utilisant +, -, *, / et des parenthèses pour atteindre exactement 24.

solve_chicken_rabbit_problem

Résoudre le problème classique des poulets et des lapins avec contraintes de têtes et de pattes.

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

Détermine le nombre de poulets (2 pattes) et de lapins (4 pattes) étant donné le total de têtes et de pattes.

solve_scipy_portfolio_optimization

Résoudre l'optimisation de portefeuille non linéaire en utilisant SciPy avec des modèles de risque quadratiques.

{
  "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
  }
}

Optimise les poids du portefeuille pour maximiser le rendement moins la pénalité de risque en utilisant l'optimisation moyenne-variance.

solve_scipy_statistical_fitting

Résoudre l'estimation de paramètres statistiques en utilisant SciPy avec ajustement de distribution.

{
  "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"
  }
}

Ajuste des distributions statistiques ("normal", "exponential", "uniform") aux données et fournit des tests d'adéquation.

solve_scipy_facility_location

Résoudre le problème de localisation d'installations en utilisant une approche hybride CSP-SciPy.

{
  "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
  }
}

Combine la sélection d'installations discrètes (CSP) avec l'optimisation continue de la capacité (SciPy) pour minimiser le coût total.

Déploiement Docker

Construire et exécuter

# 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

Exemple de sortie

Problème des N-Reines

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

Structure du projet

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

Transports MCP

TransportCommandeProtocoleCas d'utilisation
Stdiogurddy-mcpMCP sur stdin/stdoutIntégration IDE (Kiro, Claude Desktop, etc.)
HTTP streamableuvicorn mcp_server.mcp_http_server:appMCP sur HTTP avec streaming optionnelClients web, accès à distance, déploiement Docker

Tous les transports implémentent le même protocole MCP et fournissent des outils identiques.

Fonctionnalités du transport HTTP

Transport HTTP (point de terminaison /mcp/http) :

  • Modèle requête-réponse unique
  • Streaming optionnel : Ajouter l'en-tête Accept: text/event-stream ou X-Stream: true
  • Plus simple pour les requêtes ponctuelles
  • Compatible avec les clients HTTP standard
  • Aucun état de connexion à gérer
  • Prend en charge à la fois les réponses JSON régulières et les réponses de streaming au format SSE

Exemple de sortie

Problème des N-Reines

$ 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)

Puzzles logiques

$ 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)

Exemples d'API HTTP

Résolution de problèmes classiques

Coloration de la carte de l'Australie

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
})

Problème des 8 reines

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

Exemples disponibles

Tous les exemples peuvent être exécutés en utilisant gurddy-mcp run-example <name> ou python -m mcp_server.server run-example <name> :

Exemples CSP ✅

  • n_queens - Problème des N-Reines (4, 6, 8 reines avec affichage visuel du plateau)
  • graph_coloring - Coloration de graphe (Triangle, Carré, graphe de Petersen, graphe en roue)
  • map_coloring - Coloration de carte (Australie, États de l'Ouest des États-Unis, Europe)
  • scheduling - Problèmes de planification (Planification de cours, de réunions, allocation de ressources)
  • logic_puzzles - Puzzles logiques (Puzzle logique simple, puzzle du zèbre d'Einstein)
  • optimized_csp - Techniques CSP avancées (Solveur de Sudoku)

Exemples LP ✅

  • lp / optimized_lp - Exemples de programmation linéaire :
    • Optimisation de portefeuille avec contraintes de risque
    • Problème de transport (optimisation de la chaîne d'approvisionnement)
    • Analyse de relaxation des contraintes
    • Comparaison des performances selon la taille des problèmes

Exemples Minimax ✅

  • minimax - Optimisation Minimax et théorie des jeux :
    • Pierre-Feuille-Ciseaux (jeu à somme nulle)
    • Matching Pennies (jeu de coordination)
    • Bataille des sexes (équilibre en stratégie mixte)
    • Optimisation de portefeuille robuste (minimiser la perte maximale)
    • Planification de production (maximiser le profit minimum)
    • Allocation de ressources de sécurité (jeu défenseur-attaquant)
    • Concurrence publicitaire (jeu de parts de marché)

Exemples d'intégration SciPy ✅

  • scipy_optimization - Optimisation avancée avec SciPy :
    • Optimisation non linéaire de portefeuille avec modèles de risque quadratiques
    • Estimation statistique de paramètres (ajustement de distribution avec contraintes)
    • Optimisation du traitement du signal (conception de filtre FIR)
    • Localisation d'installations hybride CSP-SciPy (optimisation discrète + continue)
    • Intégration numérique dans les objectifs d'optimisation

Problèmes mathématiques classiques ✅

  • classic_problems - Résolution de problèmes mathématiques éducatifs :
    • Jeu des 24 points (expressions arithmétiques pour atteindre 24)
    • Problème des poules et des lapins (satisfaction de contraintes classique)
    • Mini Sudoku 4×4 (démonstration simplifiée de CSP)
    • Problème des 4 reines (variante éducative des N-Reines)
    • Problème du sac à dos 0-1 (optimisation classique)

Types de problèmes pris en charge

🧩 Problèmes CSP

  • N-Reines : Problème classique des N-Reines pour toute taille de plateau (N=4 à N=100+)
  • Coloration de graphe : Coloration de sommets pour des graphes arbitraires (triangle, Petersen, roue, etc.)
  • Coloration de carte : Coloration de régions géographiques (cartes de l'Australie, des États-Unis, de l'Europe)
  • Sudoku : Puzzles de Sudoku 9×9 standard avec propagation de contraintes
  • Puzzles logiques : Le puzzle du zèbre d'Einstein et problèmes de raisonnement logique personnalisés
  • Planification : Planification de cours, salles de réunion, allocation de ressources avec contraintes temporelles

📈 Problèmes d'optimisation

  • Programmation linéaire : Optimisation de variables continues avec contraintes linéaires
  • Programmation en nombres entiers : Optimisation de variables discrètes (quantités de production, affectations)
  • Programmation mixte en nombres entiers : Combinaison de variables continues et discrètes
  • Planification de production : Optimisation multi-produits avec contraintes de ressources
  • Optimisation de portefeuille : Allocation d'investissement avec contraintes de risque et de rendement
  • Transport : Optimisation de la chaîne logistique (des entrepôts aux clients)

🎲 Théorie des jeux et optimisation robuste

  • Jeux à somme nulle : Pierre-Feuille-Ciseaux, Matching Pennies, Bataille des sexes
  • Équilibres de Nash en stratégies mixtes : Stratégies probabilistes optimales pour les deux joueurs
  • Décisions Minimax : Minimiser la perte dans le pire des cas parmi des scénarios d'incertitude
  • Décisions Maximin : Maximiser le gain dans le pire des cas (stratégies conservatrices)
  • Portefeuille robuste : Minimiser la perte maximale parmi des scénarios de marché
  • Jeux de sécurité : Problèmes d'allocation de ressources défenseur-attaquant

🔬 Optimisation avancée avec SciPy

  • Optimisation non linéaire de portefeuille : Modèles de risque quadratiques avec maximisation du ratio de Sharpe
  • Estimation statistique de paramètres : Ajustement de distribution par MLE et quantiles avec contraintes
  • Traitement du signal : Conception de filtre FIR avec optimisation de la réponse en fréquence
  • Optimisation hybride : Combiner Gurddy CSP avec l'optimisation continue de SciPy
  • Intégration numérique : Problèmes d'optimisation impliquant des fonctions mathématiques complexes

🧮 Problèmes éducatifs classiques

  • Jeu des 24 points : Trouver des expressions arithmétiques utilisant quatre nombres pour atteindre 24
  • Problème des poules et des lapins : Satisfaction de contraintes classique avec têtes et pattes
  • Mini Sudoku : Résolution de Sudoku 4×4 avec des techniques CSP
  • Variantes des N-Reines : Versions éducatives du problème classique
  • Problèmes du sac à dos : Optimisation du sac à dos 0-1 avec contraintes de poids et de valeur

Fonctionnalités de performance

  • Solution rapide : Réponse en millisecondes pour les problèmes petits à moyens (N-Reines N≤12, graphes <50 sommets)
  • Évolutif : Gère de grands problèmes (N-Reines N=100+, LP avec plus de 1000 variables)
  • Efficace en mémoire : La recherche avec retour arrière et la propagation de contraintes minimisent l'utilisation de la mémoire
  • Extensible : Contraintes, fonctions objectif et types de problèmes personnalisés
  • Sûr pour la concurrence : L'API HTTP prend en charge le traitement de requêtes simultanées
  • Prêt pour la production : Déploiement Docker, bilans de santé, gestion des erreurs

Benchmarks de performance

Temps d'exécution typiques sur du matériel standard :

  • Exemples CSP : 0,4-0,5s (N-Reines, Coloration de graphe, Puzzles logiques)
  • Exemples LP : 0,8-0,9s (Portefeuille, Transport, Planification de production)
  • Exemples Minimax : 0,3-0,5s (Résolution de jeux, Optimisation robuste)
  • Exemples SciPy : 0,5-1,2s (Optimisation non linéaire, Ajustement statistique)
  • Problèmes classiques : 0,1-0,3s (24 points, Poules et lapins, Mini sudoku)
  • Sudoku : <0,1s pour les puzzles 9×9 standard
  • Grandes N-Reines : ~2-3s pour N=100

Dépannage

Erreurs courantes

  • "gurddy package not available" : Installer avec python -m mcp_server.server install
  • "No solution found" : Aucune solution n'existe sous les contraintes données ; essayez de relâcher les contraintes
  • "Invalid input types" : Vérifiez les types de données des paramètres d'entrée
  • "Unknown example" : Utilisez python -m mcp_server.server run-example --help pour voir les exemples disponibles

Problèmes d'installation

# 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')"

Débogage des exemples

Exécutez les exemples directement pour le débogage :

# 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]]))"

Prérequis pour l'intégration SciPy

Les exemples d'intégration SciPy nécessitent des dépendances supplémentaires :

# 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')"

Les exemples SciPy incluent :

  • Optimisation non linéaire de portefeuille : Modèles de risque quadratiques avec maximisation du ratio de Sharpe
  • Estimation statistique de paramètres : Ajustement de distribution avec méthodes MLE et quantiles
  • Traitement du signal : Conception de filtre FIR avec optimisation de la réponse en fréquence
  • CSP-SciPy hybride : Localisation d'installations combinant optimisation discrète et continue
  • Intégration numérique : Problèmes d'optimisation complexes impliquant des intégrales

Développement

Architecture

Le projet utilise un registre d'outils centralisé avec des schémas auto-générés pour assurer la cohérence entre les serveurs stdio et HTTP :

  • Définitions d'outils : mcp_server/tool_definitions.py (métadonnées de base uniquement)
  • Registre auto-généré : mcp_server/tool_registry.py (schémas générés à partir des signatures de fonctions)
  • Serveur Stdio : mcp_server/mcp_stdio_server.py (pour l'intégration IDE)
  • Serveur HTTP : mcp_server/mcp_http_server.py (pour les clients web)
  • Gestionnaires : mcp_server/handlers/gurddy.py (implémentations des outils)
  • Générateur de schéma : scripts/generate_registry.py (génère automatiquement les schémas à partir des signatures de fonctions)

Ajouter un nouvel outil

  1. Implémenter le gestionnaire dans 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"}

  2. Ajouter les métadonnées de base dans 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"
}

  3. Générer les schémas et vérifier :

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

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

C'est tout ! Le schéma est automatiquement généré à partir des indications de type de votre fonction, et les serveurs stdio et HTTP prendront en compte le nouvel outil.

Contraintes personnalisées

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

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

Tests

# 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

Licence

Ce projet est sous licence open source. Veuillez consulter le fichier LICENSE pour plus de détails.