gurddy mcp Server

oficial

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

Documentación

Servidor MCP Gurddy

Un servidor integral del Protocolo de Contexto de Modelo (MCP) para resolver Problemas de Satisfacción de Restricciones (CSP), Programación Lineal (LP), optimización Minimax y problemas de optimización avanzada con tecnología SciPy. Construido sobre la biblioteca de optimización gurddy con integración de SciPy, soporta la resolución de varios problemas clásicos a través de dos transportes MCP: stdio (para integración en IDE) y HTTP transmitible (para clientes web).

🚀 Inicio Rápido (Stdio): pip install gurddy_mcp luego configure en su IDE

🌐 Inicio Rápido (HTTP): docker run -p 8080:8080 gurddy-mcp o consulte la guía de despliegue

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

Características Principales

🎯 Resolución de Problemas CSP

Problema de las N-Reinas: Colocar N reinas en un tablero N×N sin que se ataquen
Coloreado de Grafos: Asignar colores a los vértices para que los adyacentes difieran
Coloreado de Mapas: Colorear regiones geográficas con regiones adyacentes diferentes
Solucionador de Sudoku: Resolver puzles de Sudoku estándar de 9×9
Puzles Lógicos: El puzle de la cebra de Einstein y problemas lógicos personalizados
Planificación: Planificación de cursos, reuniones y asignación de recursos
Solucionador CSP General: Soporte para problemas de satisfacción de restricciones personalizados

📊 Problemas de LP/Optimización

Programación Lineal: Optimización de variables continuas con restricciones lineales
Programación Entera Mixta: Optimización con variables enteras y continuas
Planificación de Producción: Optimización de producción con recursos limitados y análisis de sensibilidad
Optimización de Carteras: Asignación de inversiones bajo restricciones de riesgo
Problemas de Transporte: Optimización de cadena de suministro y logística

🎮 Minimax/Teoría de Juegos

Juegos de Suma Cero: Resolver juegos de dos jugadores (Piedra-Papel-Tijeras, Pares o Nones, Batalla de los Sexos)
Equilibrios de Nash en Estrategias Mixtas: Encontrar estrategias probabilísticas óptimas
Optimización Robusta: Minimizar la pérdida en el peor caso bajo incertidumbre
Decisiones Maximin: Maximizar la ganancia en el peor caso (estrategias conservadoras)
Juegos de Seguridad: Asignación de recursos defensor-atacante
Cartera Robusta: Minimizar la pérdida máxima en escenarios de mercado
Planificación de Producción: Decisiones de producción conservadoras (maximizar el beneficio mínimo)
Competencia Publicitaria: Juegos de cuota de mercado y estrategias competitivas

🔬 Integración con SciPy

Optimización de Cartera No Lineal: Modelos de riesgo cuadrático con optimización SciPy
Estimación de Parámetros Estadísticos: Ajuste de distribuciones con restricciones (MLE, coincidencia de cuantiles)
Optimización de Procesamiento de Señales: Diseño de filtros FIR con optimización de respuesta en frecuencia
CSP-SciPy Híbrido: Selección discreta de instalaciones + optimización continua de capacidad
Integración Numérica: Problemas de optimización que involucran integrales y funciones complejas

🧮 Problemas Matemáticos Clásicos

Juego de los 24 Puntos: Encontrar expresiones aritméticas para alcanzar 24 usando cuatro números
Problema de Gallinas y Conejos: Problema clásico de restricciones con cabezas y patas
Mini Sudoku: Solucionador de Sudoku 4×4 usando técnicas CSP
Problema de las 4-Reinas: N-Reinas simplificado con fines educativos
Mochila 0-1: Problema clásico de optimización con restricciones de peso y valor

🔌 Soporte del Protocolo MCP

Transporte Stdio: Integración local en IDE (Kiro, Claude Desktop, Cline, etc.)
Transporte HTTP Transmitible: Clientes web y acceso remoto con transmisión opcional
Interfaz Unificada: Mismas herramientas en ambos transportes
JSON-RPC 2.0: Cumplimiento total del protocolo
Auto-aprobación: Configurar herramientas de confianza para ejecución sin interrupciones

Instalación

Desde PyPI (Recomendado)

# Install the latest stable version
pip install gurddy_mcp

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

Desde el Código Fuente

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

# Install in development mode
pip install -e .

Verificar Instalación

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

Uso

1. Servidor MCP Stdio (Interfaz Principal)

El comando principal gurddy-mcp es un servidor MCP stdio que puede integrarse con herramientas como Kiro.

Opción A: Usando uvx (Recomendado - Siempre la Última Versión)

Usar uvx asegura que siempre ejecute la última versión publicada sin instalación manual.

Configurar en ~/.kiro/settings/mcp.json o .kiro/settings/mcp.json:

Recomendado: Última versión explícita

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

Alternativa: Sin especificador de versión (también usa la última)

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

Fijar a una versión específica (si es necesario)

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

¿Por qué usar uvx?

✅ Siempre ejecuta la última versión publicada automáticamente
✅ No necesita instalación ni actualización manual
✅ Entorno aislado por ejecución
✅ Sin conflictos de dependencias con su Python del sistema

Requisitos previos: Instalar uv primero:

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

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Opción B: Usando Comando Directo (Después de la Instalación)

Si ya ha instalado gurddy-mcp vía 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"
      ]
    }
  }
}

Herramientas MCP disponibles (16 en total):

info - Obtener información y capacidades del servidor MCP gurddy
install - Instalar o actualizar el paquete gurddy
run_example - Ejecutar programas de ejemplo (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, etc.)
solve_n_queens - Resolver el problema de N-Reinas para cualquier tamaño de tablero
solve_sudoku - Resolver puzles de Sudoku 9×9 usando CSP
solve_graph_coloring - Resolver coloreado de grafos con colores configurables
solve_map_coloring - Resolver problemas de coloreado de mapas (ej., Australia, EE. UU.)
solve_lp - Resolver Programación Lineal (LP) o Programación Entera Mixta (MIP)
solve_production_planning - Optimización de producción con análisis de sensibilidad opcional
solve_minimax_game - Juegos de suma cero de dos jugadores (encontrar equilibrios de Nash)
solve_minimax_decision - Optimización robusta (minimizar pérdida máxima o maximizar ganancia mínima)
solve_24_point_game - Resolver el juego de los 24 puntos con cuatro números usando operaciones aritméticas
solve_chicken_rabbit_problem - Resolver el problema clásico de gallinas y conejos con restricciones de cabezas y patas
solve_scipy_portfolio_optimization - Resolver optimización de cartera no lineal usando SciPy
solve_scipy_statistical_fitting - Resolver estimación de parámetros estadísticos usando SciPy
solve_scipy_facility_location - Resolver problema de ubicación de instalaciones usando enfoque híbrido CSP-SciPy

Probar el servidor 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. Servidor MCP HTTP

Iniciar el servidor MCP HTTP (protocolo MCP sobre HTTP transmitible):

Desarrollo 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

Acceder al servidor:

Raíz: http://127.0.0.1:8080/
Verificación de estado: http://127.0.0.1:8080/health
Transporte HTTP: http://127.0.0.1:8080/mcp/http (POST - soporta tanto regular como transmisión)

Probar el servidor MCP HTTP:

Transporte HTTP (sin transmisión):

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

Transporte HTTP (transmisión con cabecera 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}}}'

Transporte HTTP (transmisión con cabecera 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":{}}}'

Ejemplo de Cliente Python:

examples/streamable_http_client.py - Cliente de transporte HTTP con ejemplos de transmisión

Herramientas MCP

El servidor proporciona las siguientes herramientas MCP:

info

Obtener información sobre el paquete gurddy.

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

install

Instalar o actualizar el paquete gurddy.

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

run_example

Ejecutar un ejemplo de gurddy.

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

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

solve_n_queens

Resolver el problema de las N-Reinas.

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

solve_sudoku

Resolver un puzle de Sudoku 9x9.

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

solve_graph_coloring

Resolver problema de coloreado de grafos.

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

solve_map_coloring

Resolver problema de coloreado de mapas.

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

solve_lp

Resolver un problema de Programación Lineal (LP) o Programación Entera Mixta (MIP) usando 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

Resolver un problema de optimización de planificación de producción con análisis de sensibilidad opcional.

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

Resolver un juego de suma cero de dos jugadores usando minimax (teoría de juegos).

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

Devuelve la estrategia mixta óptima y el valor del juego para el jugador especificado.

solve_minimax_decision

Resolver un problema de decisión minimax bajo incertidumbre (optimización robusta).

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

Objetivos: minimize_max_loss (cartera robusta) o maximize_min_gain (producción conservadora)

solve_24_point_game

Resolver el juego de los 24 puntos con cuatro números usando operaciones aritméticas.

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

Encuentra expresiones aritméticas usando +, -, *, / y paréntesis para alcanzar exactamente 24.

solve_chicken_rabbit_problem

Resolver el problema clásico de gallinas y conejos con restricciones de cabezas y patas.

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

Determina el número de gallinas (2 patas) y conejos (4 patas) dadas las cabezas y patas totales.

solve_scipy_portfolio_optimization

Resolver optimización de cartera no lineal usando SciPy con modelos de riesgo cuadrático.

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

Optimiza los pesos de la cartera para maximizar el retorno menos la penalización por riesgo usando optimización de media-varianza.

solve_scipy_statistical_fitting

Resolver estimación de parámetros estadísticos usando SciPy con ajuste de distribuciones.

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

Ajusta distribuciones estadísticas ("normal", "exponencial", "uniforme") a los datos y proporciona pruebas de bondad de ajuste.

solve_scipy_facility_location

Resolver problema de ubicación de instalaciones usando enfoque híbrido 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
  }
}

Combina la selección discreta de instalaciones (CSP) con la optimización continua de capacidad (SciPy) para minimizar el coste total.

Despliegue con Docker

Construir y Ejecutar

# 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

Salida de Ejemplo

Problema de las N-Reinas

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

Estructura del Proyecto

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

Transportes MCP

Transporte	Comando	Protocolo	Caso de Uso
Stdio	`gurddy-mcp`	MCP sobre stdin/stdout	Integración en IDE (Kiro, Claude Desktop, etc.)
HTTP Transmitible	`uvicorn mcp_server.mcp_http_server:app`	MCP sobre HTTP con transmisión opcional	Clientes web, acceso remoto, despliegue Docker

Todos los transportes implementan el mismo protocolo MCP y proporcionan herramientas idénticas.

Características del Transporte HTTP

Transporte HTTP (endpoint /mcp/http):

Patrón único de solicitud-respuesta
Transmisión opcional: Añadir cabecera Accept: text/event-stream o X-Stream: true
Más simple para solicitudes puntuales
Compatible con clientes HTTP estándar
Sin estado de conexión que gestionar
Soporta tanto respuestas JSON regulares como respuestas de transmisión formateadas SSE

Salida de Ejemplo

Problema de las N-Reinas

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

Puzles Lógicos

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

Ejemplos de API HTTP

Resolución de Problemas Clásicos

Coloreado del Mapa de Australia

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

Problema de las 8-Reinas

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

Ejemplos Disponibles

Todos los ejemplos se pueden ejecutar usando gurddy-mcp run-example <name> o python -m mcp_server.server run-example <name>:

Ejemplos CSP ✅

n_queens - Problema de las N-Reinas (4, 6, 8 reinas con visualización del tablero)
graph_coloring - Coloreado de grafos (Triángulo, Cuadrado, grafo de Petersen, grafo Rueda)
map_coloring - Coloreado de mapas (Australia, estados del oeste de EE. UU., Europa)
scheduling - Problemas de planificación (Planificación de cursos, reuniones, asignación de recursos)
logic_puzzles - Puzles lógicos (Puzle lógico simple, puzle de la cebra de Einstein)
optimized_csp - Técnicas CSP avanzadas (Solucionador de Sudoku)

Ejemplos LP ✅

lp / optimized_lp - Ejemplos de programación lineal:
- Optimización de cartera con restricciones de riesgo
- Problema de transporte (optimización de cadena de suministro)
- Análisis de relajación de restricciones
- Comparación de rendimiento entre tamaños de problema

Ejemplos Minimax ✅

minimax - Optimización minimax y teoría de juegos:
- Piedra-Papel-Tijeras (juego de suma cero)
- Pares o Nones (juego de coordinación)
- Batalla de los Sexos (equilibrio de estrategia mixta)
- Optimización de cartera robusta (minimizar la pérdida máxima)
- Planificación de producción (maximizar el beneficio mínimo)
- Asignación de recursos de seguridad (juego defensor-atacante)
- Competencia publicitaria (juego de cuota de mercado)

Ejemplos de Integración con SciPy ✅

scipy_optimization - Optimización avanzada con SciPy:
- Optimización de cartera no lineal con modelos de riesgo cuadráticos
- Estimación de parámetros estadísticos (ajuste de distribuciones con restricciones)
- Optimización de procesamiento de señales (diseño de filtros FIR)
- Ubicación de instalaciones híbrida CSP-SciPy (optimización discreta + continua)
- Integración numérica en objetivos de optimización

Problemas Matemáticos Clásicos ✅

classic_problems - Resolución de problemas matemáticos educativos:
- Juego de los 24 puntos (expresiones aritméticas para alcanzar 24)
- Problema de gallinas y conejos (satisfacción de restricciones clásica)
- Mini Sudoku 4×4 (demostración simplificada de CSP)
- Problema de las 4 reinas (variante educativa de N-Reinas)
- Problema de la mochila 0-1 (optimización clásica)

Tipos de Problemas Soportados

🧩 Problemas CSP

N-Reinas: Problema clásico de N-Reinas para cualquier tamaño de tablero (N=4 a N=100+)
Coloreado de Grafos: Coloreado de vértices para grafos arbitrarios (triángulo, Petersen, rueda, etc.)
Coloreado de Mapas: Coloreado de regiones geográficas (mapas de Australia, EE. UU., Europa)
Sudoku: Puzzles de Sudoku estándar 9×9 con propagación de restricciones
Puzzles Lógicos: El acertijo de la cebra de Einstein y problemas de razonamiento lógico personalizados
Planificación: Planificación de cursos, salas de reuniones, asignación de recursos con restricciones temporales

📈 Problemas de Optimización

Programación Lineal: Optimización de variables continuas con restricciones lineales
Programación Entera: Optimización de variables discretas (cantidades de producción, asignaciones)
Programación Entera Mixta: Combinación de variables continuas y discretas
Planificación de Producción: Optimización multi-producto con recursos restringidos
Optimización de Cartera: Asignación de inversiones con restricciones de riesgo y retorno
Transporte: Optimización de la cadena de suministro (de almacenes a clientes)

🎲 Teoría de Juegos y Optimización Robusta

Juegos de Suma Cero: Piedra, papel o tijera, Pares o nones, Batalla de los sexos
Equilibrios de Nash en Estrategias Mixtas: Estrategias probabilísticas óptimas para ambos jugadores
Decisiones Minimax: Minimizar la peor pérdida en escenarios de incertidumbre
Decisiones Maximin: Maximizar la peor ganancia (estrategias conservadoras)
Cartera Robusta: Minimizar la pérdida máxima en diferentes escenarios de mercado
Juegos de Seguridad: Problemas de asignación de recursos defensor-atacante

🔬 Optimización Avanzada con SciPy

Optimización de Cartera No Lineal: Modelos de riesgo cuadráticos con maximización del ratio de Sharpe
Estimación de Parámetros Estadísticos: Ajuste de distribuciones con MLE y métodos basados en cuantiles con restricciones
Procesamiento de Señales: Diseño de filtros FIR con optimización de respuesta en frecuencia
Optimización Híbrida: Combinar CSP de Gurddy con optimización continua de SciPy
Integración Numérica: Problemas de optimización que involucran funciones matemáticas complejas

🧮 Problemas Educativos Clásicos

Juego de los 24 Puntos: Encontrar expresiones aritméticas usando cuatro números para alcanzar 24
Problema de Gallinas y Conejos: Satisfacción de restricciones clásica con cabezas y patas
Mini Sudoku: Resolución de Sudoku 4×4 usando técnicas CSP
Variantes de N-Reinas: Versiones educativas del problema clásico
Problemas de la Mochila: Optimización de la mochila 0-1 con restricciones de peso y valor

Características de Rendimiento

Solución Rápida: Respuesta en milisegundos para problemas pequeños-medianos (N-Reinas N≤12, grafos <50 vértices)
Escalable: Maneja problemas grandes (N-Reinas N=100+, PL con más de 1000 variables)
Eficiencia de Memoria: Búsqueda con retroceso y propagación de restricciones minimizan el uso de memoria
Extensible: Restricciones, funciones objetivo y tipos de problemas personalizados
Seguro para Concurrencia: La API HTTP soporta procesamiento de solicitudes concurrentes
Listo para Producción: Despliegue con Docker, verificaciones de estado, manejo de errores

Referencias de Rendimiento

Tiempos de ejecución típicos en hardware estándar:

Ejemplos CSP: 0.4-0.5s (N-Reinas, Coloreado de Grafos, Puzzles Lógicos)
Ejemplos PL: 0.8-0.9s (Cartera, Transporte, Planificación de Producción)
Ejemplos Minimax: 0.3-0.5s (Resolución de juegos, Optimización robusta)
Ejemplos SciPy: 0.5-1.2s (Optimización no lineal, Ajuste estadístico)
Problemas Clásicos: 0.1-0.3s (24 puntos, Gallinas y conejos, Mini sudoku)
Sudoku: <0.1s para puzzles estándar 9×9
N-Reinas Grande: ~2-3s para N=100

Solución de Problemas

Errores Comunes

"gurddy package not available": Instalar con python -m mcp_server.server install
"No solution found": No existe solución bajo las restricciones dadas; intente relajar las restricciones
"Invalid input types": Verifique los tipos de datos de los parámetros de entrada
"Unknown example": Use python -m mcp_server.server run-example --help para ver los ejemplos disponibles

Problemas de Instalación

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

Depuración de Ejemplos

Ejecute los ejemplos directamente para depurar:

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

Requisitos de Integración con SciPy

Los ejemplos de integración con SciPy requieren dependencias adicionales:

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

Los Ejemplos de SciPy Incluyen:

Optimización de Cartera No Lineal: Modelos de riesgo cuadráticos con maximización del ratio de Sharpe
Estimación de Parámetros Estadísticos: Ajuste de distribuciones con métodos MLE y cuantiles
Procesamiento de Señales: Diseño de filtros FIR con optimización de respuesta en frecuencia
CSP-SciPy Híbrido: Ubicación de instalaciones combinando optimización discreta y continua
Integración Numérica: Problemas de optimización complejos que involucran integrales

Desarrollo

Arquitectura

El proyecto utiliza un registro centralizado de herramientas con esquemas autogenerados para asegurar la consistencia entre los servidores stdio y HTTP:

Definiciones de Herramientas: mcp_server/tool_definitions.py (solo metadatos básicos)
Registro Autogenerado: mcp_server/tool_registry.py (esquemas generados a partir de las firmas de las funciones)
Servidor Stdio: mcp_server/mcp_stdio_server.py (para integración con IDE)
Servidor HTTP: mcp_server/mcp_http_server.py (para clientes web)
Manejadores: mcp_server/handlers/gurddy.py (implementaciones de herramientas)
Generador de Esquemas: scripts/generate_registry.py (autogenera esquemas a partir de las firmas de las funciones)

Añadir una Nueva Herramienta

Implementar el manejador en 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"}

Añadir metadatos básicos en 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"
}

Generar esquemas y verificar:

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

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

¡Eso es todo! El esquema se genera automáticamente a partir de las sugerencias de tipo de su función, y tanto los servidores stdio como HTTP recogerán la nueva herramienta.

Restricciones Personalizadas

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

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

Pruebas

# 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

Licencia

Este proyecto está licenciado bajo una licencia de código abierto. Consulte el archivo LICENSE para más detalles.