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

Documentação

Servidor MCP Gurddy

Um servidor abrangente do Model Context Protocol (MCP) para resolver Problemas de Satisfação de Restrições (CSP), Programação Linear (PL), otimização Minimax e problemas avançados de otimização com suporte do SciPy. Construído sobre a biblioteca de otimização gurddy com integração SciPy, ele suporta a resolução de vários problemas clássicos através de dois transportes MCP: stdio (para integração com IDE) e HTTP streamable (para clientes web).

🚀 Início Rápido (Stdio): pip install gurddy_mcp e configure em sua IDE

🌐 Início Rápido (HTTP): docker run -p 8080:8080 gurddy-mcp ou veja o guia de implantação

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

Principais Funcionalidades

🎯 Resolução de Problemas CSP

Problema das N-Rainhas: Posicione N rainhas em um tabuleiro N×N sem ataques
Coloração de Grafos: Atribua cores aos vértices de forma que vértices adjacentes tenham cores diferentes
Coloração de Mapas: Colora regiões geográficas com regiões adjacentes diferentes
Solucionador de Sudoku: Resolva quebra-cabeças de Sudoku 9×9 padrão
Quebra-cabeças Lógicos: O enigma da Zebra de Einstein e problemas lógicos personalizados
Agendamento: Agendamento de cursos, reuniões, alocação de recursos
Solucionador CSP Geral: Suporte para problemas de satisfação de restrições personalizados

📊 Problemas de PL/Otimização

Programação Linear: Otimização de variáveis contínuas com restrições lineares
Programação Inteira Mista: Otimização com variáveis inteiras e contínuas
Planejamento de Produção: Otimização da produção com restrição de recursos e análise de sensibilidade
Otimização de Portfólio: Alocação de investimentos sob restrições de risco
Problemas de Transporte: Otimização da cadeia de suprimentos e logística

🎮 Minimax/Teoria dos Jogos

Jogos de Soma Zero: Resolva jogos de dois jogadores (Pedra-Papel-Tesoura, Cara ou Coroa, Batalha dos Sexos)
Equilíbrios de Nash em Estratégias Mistas: Encontre estratégias probabilísticas ótimas
Otimização Robusta: Minimize a perda no pior caso sob incerteza
Decisões Maximin: Maximize o ganho no pior caso (estratégias conservadoras)
Jogos de Segurança: Alocação de recursos defensor-atacante
Portfólio Robusto: Minimize a perda máxima em cenários de mercado
Planejamento de Produção: Decisões de produção conservadoras (maximizar o lucro mínimo)
Competição Publicitária: Jogos de participação de mercado e estratégias competitivas

🔬 Integração com SciPy

Otimização Não Linear de Portfólio: Modelos de risco quadrático com otimização SciPy
Estimação Estatística de Parâmetros: Ajuste de distribuição com restrições (MLE, correspondência de quantis)
Otimização de Processamento de Sinais: Projeto de filtro FIR com otimização de resposta em frequência
CSP-SciPy Híbrido: Seleção discreta de instalações + otimização contínua de capacidade
Integração Numérica: Problemas de otimização envolvendo integrais e funções complexas

🧮 Problemas Matemáticos Clássicos

Jogo dos 24 Pontos: Encontre expressões aritméticas para chegar a 24 usando quatro números
Problema do Coelho e da Galinha: Problema clássico de restrição com cabeças e pernas
Mini Sudoku: Solucionador de Sudoku 4×4 usando técnicas CSP
Problema das 4 Rainhas: N-Rainhas simplificado para fins educacionais
Mochila 0-1: Problema clássico de otimização com restrições de peso e valor

🔌 Suporte ao Protocolo MCP

Transporte Stdio: Integração local com IDE (Kiro, Claude Desktop, Cline, etc.)
Transporte HTTP Streamable: Clientes web e acesso remoto com streaming opcional
Interface Unificada: As mesmas ferramentas em ambos os transportes
JSON-RPC 2.0: Conformidade total com o protocolo
Aprovação Automática: Configure ferramentas confiáveis para execução perfeita

Instalação

Do PyPI (Recomendado)

# Install the latest stable version
pip install gurddy_mcp

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

Do Código Fonte

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

# Install in development mode
pip install -e .

Verificar Instalação

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

Uso

1. Servidor MCP Stdio (Interface Principal)

O comando principal gurddy-mcp é um servidor MCP stdio que pode ser integrado com ferramentas como Kiro.

Opção A: Usando uvx (Recomendado - Sempre a Versão Mais Recente)

Usar uvx garante que você sempre execute a versão publicada mais recente sem instalação manual.

Configure em ~/.kiro/settings/mcp.json ou .kiro/settings/mcp.json:

Recomendado: Versão mais recente 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: Sem especificador de versão (também usa a mais recente)

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

Fixar uma versão específica (se necessário)

{
  "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 que usar uvx?

✅ Sempre executa a versão publicada mais recente automaticamente
✅ Sem necessidade de instalação ou atualização manual
✅ Ambiente isolado por execução
✅ Sem conflitos de dependência com o Python do seu sistema

Pré-requisitos: Instale uv primeiro:

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

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Opção B: Usando Comando Direto (Após Instalação)

Se você já instalou 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"
      ]
    }
  }
}

Ferramentas MCP disponíveis (16 no total):

info - Obter informações e capacidades do servidor MCP gurddy
install - Instalar ou atualizar o pacote gurddy
run_example - Executar programas de exemplo (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, etc.)
solve_n_queens - Resolver o problema das N-Rainhas para qualquer tamanho de tabuleiro
solve_sudoku - Resolver quebra-cabeças de Sudoku 9×9 usando CSP
solve_graph_coloring - Resolver coloração de grafos com cores configuráveis
solve_map_coloring - Resolver problemas de coloração de mapas (ex.: Austrália, EUA)
solve_lp - Resolver Programação Linear (PL) ou Programação Inteira Mista (PIM)
solve_production_planning - Otimização de produção com análise de sensibilidade opcional
solve_minimax_game - Jogos de soma zero para dois jogadores (encontrar equilíbrios de Nash)
solve_minimax_decision - Otimização robusta (minimizar perda máxima ou maximizar ganho mínimo)
solve_24_point_game - Resolver o jogo dos 24 pontos com quatro números usando operações aritméticas
solve_chicken_rabbit_problem - Resolver o problema clássico do coelho e da galinha com restrições de cabeças e pernas
solve_scipy_portfolio_optimization - Resolver otimização não linear de portfólio usando SciPy
solve_scipy_statistical_fitting - Resolver estimação estatística de parâmetros usando SciPy
solve_scipy_facility_location - Resolver problema de localização de instalações usando abordagem híbrida CSP-SciPy

Teste o 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

Inicie o servidor MCP HTTP (protocolo MCP sobre HTTP streamable):

Desenvolvimento 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

Acesse o servidor:

Raiz: http://127.0.0.1:8080/
Verificação de saúde: http://127.0.0.1:8080/health
Transporte HTTP: http://127.0.0.1:8080/mcp/http (POST - suporta tanto regular quanto streaming)

Teste o servidor MCP HTTP:

Transporte HTTP (sem 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":{}}}'

Transporte HTTP (streaming com cabeçalho 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 (streaming com cabeçalho 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":{}}}'

Exemplo de Cliente Python:

examples/streamable_http_client.py - Cliente de transporte HTTP com exemplos de streaming

Ferramentas MCP

O servidor fornece as seguintes ferramentas MCP:

info

Obter informações sobre o pacote gurddy.

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

install

Instalar ou atualizar o pacote gurddy.

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

run_example

Executar um exemplo do gurddy.

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

Exemplos disponíveis: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Resolver o problema das N-Rainhas.

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

solve_sudoku

Resolver um quebra-cabeça de Sudoku 9x9.

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

solve_graph_coloring

Resolver problema de coloração 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 coloração de mapas.

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

solve_lp

Resolver um problema de Programação Linear (PL) ou Programação Inteira Mista (PIM) 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 um problema de otimização de planejamento de produção com análise de sensibilidade 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 um jogo de soma zero para dois jogadores usando minimax (teoria dos jogos).

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

Retorna a estratégia mista ótima e o valor do jogo para o jogador especificado.

solve_minimax_decision

Resolver um problema de decisão minimax sob incerteza (otimização 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 (portfólio robusto) ou maximize_min_gain (produção conservadora)

solve_24_point_game

Resolver o jogo dos 24 pontos com quatro números usando operações aritméticas.

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

Encontra expressões aritméticas usando +, -, *, / e parênteses para chegar exatamente a 24.

solve_chicken_rabbit_problem

Resolver o problema clássico do coelho e da galinha com restrições de cabeças e pernas.

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

Determina o número de galinhas (2 pernas) e coelhos (4 pernas) dados o total de cabeças e pernas.

solve_scipy_portfolio_optimization

Resolver otimização não linear de portfólio usando SciPy com modelos de risco quadrá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
  }
}

Otimiza os pesos do portfólio para maximizar o retorno menos a penalidade de risco usando otimização de média-variância.

solve_scipy_statistical_fitting

Resolver estimação estatística de parâmetros usando SciPy com ajuste de distribuição.

{
  "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 distribuições estatísticas ("normal", "exponencial", "uniforme") aos dados e fornece testes de qualidade de ajuste.

solve_scipy_facility_location

Resolver problema de localização de instalações usando abordagem híbrida 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 seleção discreta de instalações (CSP) com otimização contínua de capacidade (SciPy) para minimizar o custo total.

Implantação com Docker

Construir e Executar

# 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

Exemplo de Saída

Problema das N-Rainhas

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

Estrutura do Projeto

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	Integração com IDE (Kiro, Claude Desktop, etc.)
HTTP Streamable	`uvicorn mcp_server.mcp_http_server:app`	MCP sobre HTTP com streaming opcional	Clientes web, acesso remoto, implantação Docker

Todos os transportes implementam o mesmo protocolo MCP e fornecem ferramentas idênticas.

Recursos do Transporte HTTP

Transporte HTTP (endpoint /mcp/http):

Padrão de requisição-resposta única
Streaming opcional: Adicione o cabeçalho Accept: text/event-stream ou X-Stream: true
Mais simples para requisições pontuais
Compatível com clientes HTTP padrão
Sem estado de conexão para gerenciar
Suporta tanto respostas JSON regulares quanto respostas de streaming formatadas em SSE

Exemplo de Saída

Problema das N-Rainhas

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

Quebra-cabeças 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)

Exemplos de API HTTP

Resolução de Problemas Clássicos

Coloração do Mapa da Austrália

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 das 8 Rainhas

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

Exemplos Disponíveis

Todos os exemplos podem ser executados usando gurddy-mcp run-example <name> ou python -m mcp_server.server run-example <name>:

Exemplos CSP ✅

n_queens - Problema das N-Rainhas (4, 6, 8 rainhas com exibição visual do tabuleiro)
graph_coloring - Coloração de grafos (Triângulo, Quadrado, grafo de Petersen, grafo Roda)
map_coloring - Coloração de mapas (Austrália, estados do oeste dos EUA, Europa)
scheduling - Problemas de agendamento (Agendamento de cursos, reuniões, alocação de recursos)
logic_puzzles - Quebra-cabeças lógicos (Quebra-cabeça lógico simples, enigma da Zebra de Einstein)
optimized_csp - Técnicas avançadas de CSP (Solucionador de Sudoku)

Exemplos de PL ✅

lp / optimized_lp - Exemplos de programação linear:
- Otimização de portfólio com restrições de risco
- Problema de transporte (otimização da cadeia de suprimentos)
- Análise de relaxação de restrições
- Comparação de desempenho entre tamanhos de problema

Exemplos Minimax ✅

minimax - Otimização minimax e teoria dos jogos:
- Pedra-Papel-Tesoura (jogo de soma zero)
- Cara ou Coroa (jogo de coordenação)
- Batalha dos Sexos (equilíbrio de estratégia mista)
- Otimização robusta de portfólio (minimizar a perda máxima)
- Planejamento de produção (maximizar o lucro mínimo)
- Alocação de recursos de segurança (jogo defensor-atacante)
- Competição publicitária (jogo de participação de mercado)

Exemplos de Integração com SciPy ✅

scipy_optimization - Otimização avançada com SciPy:
- Otimização não linear de portfólio com modelos de risco quadráticos
- Estimação estatística de parâmetros (ajuste de distribuição com restrições)
- Otimização de processamento de sinais (projeto de filtro FIR)
- Localização de instalações híbrida CSP-SciPy (otimização discreta + contínua)
- Integração numérica em objetivos de otimização

Problemas Matemáticos Clássicos ✅

classic_problems - Resolução de problemas matemáticos educacionais:
- Jogo dos 24 Pontos (expressões aritméticas para chegar a 24)
- Problema das Galinhas e Coelhos (satisfação de restrições clássica)
- Mini Sudoku 4×4 (demonstração simplificada de CSP)
- Problema das 4 Rainhas (variante educacional das N-Rainhas)
- Problema da Mochila 0-1 (otimização clássica)

Tipos de Problemas Suportados

🧩 Problemas de CSP

N-Rainhas: Problema clássico das N-Rainhas para qualquer tamanho de tabuleiro (N=4 a N=100+)
Coloração de Grafos: Coloração de vértices para grafos arbitrários (triângulo, Petersen, roda, etc.)
Coloração de Mapas: Coloração de regiões geográficas (mapas da Austrália, EUA, Europa)
Sudoku: Quebra-cabeças de Sudoku 9×9 padrão com propagação de restrições
Quebra-cabeças Lógicos: Problema da Zebra de Einstein e problemas de raciocínio lógico personalizados
Agendamento: Agendamento de cursos, salas de reunião, alocação de recursos com restrições de tempo

📈 Problemas de Otimização

Programação Linear: Otimização de variáveis contínuas com restrições lineares
Programação Inteira: Otimização de variáveis discretas (quantidades de produção, atribuições)
Programação Inteira Mista: Combinação de variáveis contínuas e discretas
Planejamento de Produção: Otimização multi-produto com restrição de recursos
Otimização de Portfólio: Alocação de investimentos com restrições de risco e retorno
Transporte: Otimização da cadeia de suprimentos (armazéns para clientes)

🎲 Teoria dos Jogos e Otimização Robusta

Jogos de Soma Zero: Pedra-Papel-Tesoura, Cara ou Coroa, Batalha dos Sexos
Equilíbrios de Nash em Estratégias Mistas: Estratégias probabilísticas ótimas para ambos os jogadores
Decisões Minimax: Minimizar a perda no pior caso em cenários de incerteza
Decisões Maximin: Maximizar o ganho no pior caso (estratégias conservadoras)
Portfólio Robusto: Minimizar a perda máxima em cenários de mercado
Jogos de Segurança: Problemas de alocação de recursos defensor-atacante

🔬 Otimização Avançada com SciPy

Otimização Não Linear de Portfólio: Modelos de risco quadráticos com maximização do índice de Sharpe
Estimação Estatística de Parâmetros: Ajuste de distribuição baseado em MLE e quantis com restrições
Processamento de Sinais: Projeto de filtro FIR com otimização de resposta em frequência
Otimização Híbrida: Combinar CSP do Gurddy com otimização contínua do SciPy
Integração Numérica: Problemas de otimização envolvendo funções matemáticas complexas

🧮 Problemas Educacionais Clássicos

Jogo dos 24 Pontos: Encontrar expressões aritméticas usando quatro números para chegar a 24
Problema das Galinhas e Coelhos: Satisfação de restrições clássica com cabeças e pernas
Mini Sudoku: Resolução de Sudoku 4×4 usando técnicas de CSP
Variantes das N-Rainhas: Versões educacionais do problema clássico
Problemas da Mochila: Otimização da mochila 0-1 com restrições de peso e valor

Recursos de Desempenho

Solução Rápida: Resposta em milissegundos para problemas pequenos-médios (N-Rainhas N≤12, grafos <50 vértices)
Escalável: Lida com problemas grandes (N-Rainhas N=100+, PL com mais de 1000 variáveis)
Eficiência de Memória: Busca com retrocesso e propagação de restrições minimizam o uso de memória
Extensível: Restrições personalizadas, funções objetivo e tipos de problemas
Seguro para Concorrência: API HTTP suporta processamento de requisições concorrentes
Pronto para Produção: Implantação com Docker, verificações de saúde, tratamento de erros

Benchmarks de Desempenho

Tempos de execução típicos em hardware padrão:

Exemplos de CSP: 0.4-0.5s (N-Rainhas, Coloração de Grafos, Quebra-cabeças Lógicos)
Exemplos de PL: 0.8-0.9s (Portfólio, Transporte, Planejamento de Produção)
Exemplos Minimax: 0.3-0.5s (Resolução de jogos, Otimização robusta)
Exemplos com SciPy: 0.5-1.2s (Otimização não linear, Ajuste estatístico)
Problemas Clássicos: 0.1-0.3s (24 pontos, Galinhas e coelhos, Mini sudoku)
Sudoku: <0.1s para quebra-cabeças 9×9 padrão
N-Rainhas Grande: ~2-3s para N=100

Solução de Problemas

Erros Comuns

"gurddy package not available": Instale com python -m mcp_server.server install
"No solution found": Nenhuma solução existe sob as restrições fornecidas; tente relaxar as restrições
"Invalid input types": Verifique os tipos de dados dos parâmetros de entrada
"Unknown example": Use python -m mcp_server.server run-example --help para ver os exemplos disponíveis

Problemas de Instalação

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

Depuração de Exemplos

Execute os exemplos diretamente para depuração:

# 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 Integração com SciPy

Os exemplos de integração com SciPy requerem dependências adicionais:

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

Exemplos com SciPy Incluem:

Otimização Não Linear de Portfólio: Modelos de risco quadráticos com maximização do índice de Sharpe
Estimação Estatística de Parâmetros: Ajuste de distribuição com métodos MLE e quantis
Processamento de Sinais: Projeto de filtro FIR com otimização de resposta em frequência
CSP-SciPy Híbrido: Localização de instalações combinando otimização discreta e contínua
Integração Numérica: Problemas de otimização complexos envolvendo integrais

Desenvolvimento

Arquitetura

O projeto usa um registro centralizado de ferramentas com esquemas gerados automaticamente para garantir consistência entre os servidores stdio e HTTP:

Definições de Ferramentas: mcp_server/tool_definitions.py (apenas metadados básicos)
Registro Gerado Automaticamente: mcp_server/tool_registry.py (esquemas gerados a partir das assinaturas das funções)
Servidor Stdio: mcp_server/mcp_stdio_server.py (para integração com IDE)
Servidor HTTP: mcp_server/mcp_http_server.py (para clientes web)
Manipuladores: mcp_server/handlers/gurddy.py (implementações das ferramentas)
Gerador de Esquemas: scripts/generate_registry.py (gera esquemas automaticamente a partir das assinaturas das funções)

Adicionando uma Nova Ferramenta

Implementar o manipulador em 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"}

Adicionar metadados básicos em 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"
}

Gerar esquemas e 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

É isso! O esquema é gerado automaticamente a partir das dicas de tipo da sua função, e ambos os servidores stdio e HTTP irão captar a nova ferramenta.

Restrições Personalizadas

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

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

Testes

# 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

Licença

Este projeto está licenciado sob uma licença de código aberto. Consulte o arquivo LICENSE para obter detalhes.