Labsco
novvoo logo

gurddy mcp

ā˜… 2

from novvoo

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.

šŸ”„šŸ”„šŸ”„āœ“ VerifiedFreeAdvanced setup
#automation#calendar#devops#git#maps#security#project-mgmt

Gurddy MCP Server

A comprehensive Model Context Protocol (MCP) server for solving Constraint Satisfaction Problems (CSP), Linear Programming (LP), Minimax optimization, and SciPy-powered advanced optimization problems. Built on the gurddy optimization library with SciPy integration, it supports solving various classic problems through two MCP transports: stdio (for IDE integration) and streamable HTTP (for web clients).

šŸš€ Quick Start (Stdio): pip install gurddy_mcp then configure in your IDE

šŸŒ Quick Start (HTTP): docker run -p 8080:8080 gurddy-mcp or see deployment guide

šŸ“¦ PyPI Package: https://pypi.org/project/gurddy_mcp

Main Features

šŸŽÆ CSP Problem Solving

  • N-Queens Problem: Place N queens on an NƗN chessboard with no attacks
  • Graph Coloring: Assign colors to vertices so adjacent vertices differ
  • Map Coloring: Color geographic regions with adjacent regions differing
  • Sudoku Solver: Solve standard 9Ɨ9 Sudoku puzzles
  • Logic Puzzles: Einstein's Zebra puzzle and custom logic problems
  • Scheduling: Course scheduling, meeting scheduling, resource allocation
  • General CSP Solver: Support for custom constraint satisfaction problems

šŸ“Š LP/Optimization Problems

  • Linear Programming: Continuous variable optimization with linear constraints
  • Mixed Integer Programming: Optimization with integer and continuous variables
  • Production Planning: Resource-constrained production optimization with sensitivity analysis
  • Portfolio Optimization: Investment allocation under risk constraints
  • Transportation Problems: Supply chain and logistics optimization

šŸŽ® Minimax/Game Theory

  • Zero-Sum Games: Solve two-player games (Rock-Paper-Scissors, Matching Pennies, Battle of Sexes)
  • Mixed Strategy Nash Equilibria: Find optimal probabilistic strategies
  • Robust Optimization: Minimize worst-case loss under uncertainty
  • Maximin Decisions: Maximize worst-case gain (conservative strategies)
  • Security Games: Defender-attacker resource allocation
  • Robust Portfolio: Minimize maximum loss across market scenarios
  • Production Planning: Conservative production decisions (maximize minimum profit)
  • Advertising Competition: Market share games and competitive strategies

šŸ”¬ SciPy Integration

  • Nonlinear Portfolio Optimization: Quadratic risk models with SciPy optimization
  • Statistical Parameter Estimation: Distribution fitting with constraints (MLE, quantile matching)
  • Signal Processing Optimization: FIR filter design with frequency response optimization
  • Hybrid CSP-SciPy: Discrete facility selection + continuous capacity optimization
  • Numerical Integration: Optimization problems involving integrals and complex functions

šŸ§® Classic Math Problems

  • 24-Point Game: Find arithmetic expressions to reach 24 using four numbers
  • Chicken-Rabbit Problem: Classic constraint problem with heads and legs
  • Mini Sudoku: 4Ɨ4 Sudoku solver using CSP techniques
  • 4-Queens Problem: Simplified N-Queens for educational purposes
  • 0-1 Knapsack: Classic optimization problem with weight and value constraints

šŸ”Œ MCP Protocol Support

  • Stdio Transport: Local IDE integration (Kiro, Claude Desktop, Cline, etc.)
  • Streamable HTTP Transport: Web clients and remote access with optional streaming
  • Unified Interface: Same tools across both transports
  • JSON-RPC 2.0: Full protocol compliance
  • Auto-approval: Configure trusted tools for seamless execution

MCP Tools

The server provides the following MCP tools:

info

Get information about the gurddy package.

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

install

Install or upgrade the gurddy package.

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

run_example

Run a gurddy example.

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

Available examples: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Solve the N-Queens problem.

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

solve_sudoku

Solve a 9x9 Sudoku puzzle.

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

solve_graph_coloring

Solve graph coloring problem.

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

solve_map_coloring

Solve map coloring problem.

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

solve_lp

Solve a Linear Programming (LP) or Mixed Integer Programming (MIP) problem using 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

Solve a production planning optimization problem with optional sensitivity analysis.

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

Solve a two-player zero-sum game using minimax (game theory).

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

Returns the optimal mixed strategy and game value for the specified player.

solve_minimax_decision

Solve a minimax decision problem under uncertainty (robust optimization).

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

Objectives: minimize_max_loss (robust portfolio) or maximize_min_gain (conservative production)

solve_24_point_game

Solve the 24-point game with four numbers using arithmetic operations.

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

Finds arithmetic expressions using +, -, *, / and parentheses to reach exactly 24.

solve_chicken_rabbit_problem

Solve the classic chicken-rabbit problem with heads and legs constraints.

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

Determines the number of chickens (2 legs) and rabbits (4 legs) given total heads and legs.

solve_scipy_portfolio_optimization

Solve nonlinear portfolio optimization using SciPy with quadratic risk models.

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

Optimizes portfolio weights to maximize return minus risk penalty using mean-variance optimization.

solve_scipy_statistical_fitting

Solve statistical parameter estimation using SciPy with distribution fitting.

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

Fits statistical distributions ("normal", "exponential", "uniform") to data and provides goodness-of-fit tests.

solve_scipy_facility_location

Solve facility location problem using hybrid CSP-SciPy approach.

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

Combines discrete facility selection (CSP) with continuous capacity optimization (SciPy) to minimize total cost.

Example Output

N-Queens Problem

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

Project Structure

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

examples/
ā””ā”€ā”€ http_mcp_client.py      # Example HTTP MCP client

Dockerfile                  # Docker configuration for HTTP server

MCP Transports

TransportCommandProtocolUse Case
Stdiogurddy-mcpMCP over stdin/stdoutIDE integration (Kiro, Claude Desktop, etc.)
Streamable HTTPuvicorn mcp_server.mcp_http_server:appMCP over HTTP with optional streamingWeb clients, remote access, Docker deployment

All transports implement the same MCP protocol and provide identical tools.

HTTP Transport Features

HTTP Transport (/mcp/http endpoint):

  • Single request-response pattern
  • Optional streaming: Add Accept: text/event-stream or X-Stream: true header
  • Simpler for one-off requests
  • Compatible with standard HTTP clients
  • No connection state to manage
  • Supports both regular JSON responses and SSE-formatted streaming responses

Example Output

N-Queens Problem

$ gurddy-mcp-cli run-example n_queens

Solving 8-Queens problem...

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

Logic Puzzles

$ python -m mcp_server.server run-example logic_puzzles

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

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

HTTP API Examples

Classic Problem Solving

Australian Map Coloring

import requests

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

8-Queens Problem

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

Available Examples

All examples can be run using gurddy-mcp run-example <name> or python -m mcp_server.server run-example <name>:

CSP Examples āœ…

  • n_queens - N-Queens problem (4, 6, 8 queens with visual board display)
  • graph_coloring - Graph coloring (Triangle, Square, Petersen graph, Wheel graph)
  • map_coloring - Map coloring (Australia, USA Western states, Europe)
  • scheduling - Scheduling problems (Course scheduling, meeting scheduling, resource allocation)
  • logic_puzzles - Logic puzzles (Simple logic puzzle, Einstein's Zebra puzzle)
  • optimized_csp - Advanced CSP techniques (Sudoku solver)

LP Examples āœ…

  • lp / optimized_lp - Linear programming examples:
    • Portfolio optimization with risk constraints
    • Transportation problem (supply chain optimization)
    • Constraint relaxation analysis
    • Performance comparison across problem sizes

Minimax Examples āœ…

  • minimax - Minimax optimization and game theory:
    • Rock-Paper-Scissors (zero-sum game)
    • Matching Pennies (coordination game)
    • Battle of the Sexes (mixed strategy equilibrium)
    • Robust portfolio optimization (minimize maximum loss)
    • Production planning (maximize minimum profit)
    • Security resource allocation (defender-attacker game)
    • Advertising competition (market share game)

SciPy Integration Examples āœ…

  • scipy_optimization - Advanced optimization with SciPy:
    • Nonlinear portfolio optimization with quadratic risk models
    • Statistical parameter estimation (distribution fitting with constraints)
    • Signal processing optimization (FIR filter design)
    • Hybrid CSP-SciPy facility location (discrete + continuous optimization)
    • Numerical integration in optimization objectives

Classic Math Problems āœ…

  • classic_problems - Educational math problem solving:
    • 24-Point Game (arithmetic expressions to reach 24)
    • Chicken-Rabbit Problem (classic constraint satisfaction)
    • 4Ɨ4 Mini Sudoku (simplified CSP demonstration)
    • 4-Queens Problem (educational N-Queens variant)
    • 0-1 Knapsack Problem (classic optimization)

Supported Problem Types

šŸ§© CSP Problems

  • N-Queens: Classic N-Queens problem for any board size (N=4 to N=100+)
  • Graph Coloring: Vertex coloring for arbitrary graphs (triangle, Petersen, wheel, etc.)
  • Map Coloring: Geographic region coloring (Australia, USA, Europe maps)
  • Sudoku: Standard 9Ɨ9 Sudoku puzzles with constraint propagation
  • Logic Puzzles: Einstein's Zebra puzzle and custom logical reasoning problems
  • Scheduling: Course scheduling, meeting rooms, resource allocation with time constraints

šŸ“ˆ Optimization Problems

  • Linear Programming: Continuous variable optimization with linear constraints
  • Integer Programming: Discrete variable optimization (production quantities, assignments)
  • Mixed Integer Programming: Combined continuous and discrete variables
  • Production Planning: Multi-product resource-constrained optimization
  • Portfolio Optimization: Investment allocation with risk and return constraints
  • Transportation: Supply chain optimization (warehouses to customers)

šŸŽ² Game Theory & Robust Optimization

  • Zero-Sum Games: Rock-Paper-Scissors, Matching Pennies, Battle of Sexes
  • Mixed Strategy Nash Equilibria: Optimal probabilistic strategies for both players
  • Minimax Decisions: Minimize worst-case loss across uncertainty scenarios
  • Maximin Decisions: Maximize worst-case gain (conservative strategies)
  • Robust Portfolio: Minimize maximum loss across market scenarios
  • Security Games: Defender-attacker resource allocation problems

šŸ”¬ SciPy-Powered Advanced Optimization

  • Nonlinear Portfolio Optimization: Quadratic risk models with Sharpe ratio maximization
  • Statistical Parameter Estimation: MLE and quantile-based distribution fitting with constraints
  • Signal Processing: FIR filter design with frequency response optimization
  • Hybrid Optimization: Combine Gurddy CSP with SciPy continuous optimization
  • Numerical Integration: Optimization problems involving complex mathematical functions

šŸ§® Classic Educational Problems

  • 24-Point Game: Find arithmetic expressions using four numbers to reach 24
  • Chicken-Rabbit Problem: Classic constraint satisfaction with heads and legs
  • Mini Sudoku: 4Ɨ4 Sudoku solving using CSP techniques
  • N-Queens Variants: Educational versions of the classic problem
  • Knapsack Problems: 0-1 knapsack optimization with weight and value constraints

Performance Features

  • Fast Solution: Millisecond response for small-medium problems (N-Queens Nā‰¤12, graphs <50 vertices)
  • Scalable: Handles large problems (N-Queens N=100+, LP with 1000+ variables)
  • Memory Efficient: Backtracking search and constraint propagation minimize memory usage
  • Extensible: Custom constraints, objective functions, and problem types
  • Concurrency-Safe: HTTP API supports concurrent request processing
  • Production Ready: Docker deployment, health checks, error handling

Performance Benchmarks

Typical execution times on standard hardware:

  • CSP Examples: 0.4-0.5s (N-Queens, Graph Coloring, Logic Puzzles)
  • LP Examples: 0.8-0.9s (Portfolio, Transportation, Production Planning)
  • Minimax Examples: 0.3-0.5s (Game solving, Robust optimization)
  • SciPy Examples: 0.5-1.2s (Nonlinear optimization, Statistical fitting)
  • Classic Problems: 0.1-0.3s (24-point, Chicken-rabbit, Mini sudoku)
  • Sudoku: <0.1s for standard 9Ɨ9 puzzles
  • Large N-Queens: ~2-3s for N=100

Development

Architecture

The project uses a centralized tool registry with auto-generated schemas to ensure consistency between stdio and HTTP servers:

  • Tool Definitions: mcp_server/tool_definitions.py (basic metadata only)
  • Auto-Generated Registry: mcp_server/tool_registry.py (schemas generated from function signatures)
  • Stdio Server: mcp_server/mcp_stdio_server.py (for IDE integration)
  • HTTP Server: mcp_server/mcp_http_server.py (for web clients)
  • Handlers: mcp_server/handlers/gurddy.py (tool implementations)
  • Schema Generator: scripts/generate_registry.py (auto-generates schemas from function signatures)

Adding a New Tool

  1. Implement handler in mcp_server/handlers/gurddy.py:

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

  2. Add basic metadata in mcp_server/tool_definitions.py:

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

  3. Generate schemas and verify:

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

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

That's it! The schema is automatically generated from your function's type hints, and both stdio and HTTP servers will pick up the new tool.

Custom Constraints

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

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

Testing

# 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