gurddy mcp

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

1. 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"}
   

2. 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"
   }
   

3. 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.