gurddy-mcp

View on GitHub

gruddy mcp server

2 stars PythonOthers Updated Nov 14, 2025

Documentation

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

Installation

From PyPI (Recommended)

bash

# Install the latest stable version
pip install gurddy_mcp

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

From Source

bash

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

# Install in development mode
pip install -e .

Verify Installation

bash

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

Usage

1. MCP Stdio Server (Primary Interface)

The main `gurddy-mcp` command is an MCP stdio server that can be integrated with tools like Kiro.

Option A: Using uvx (Recommended - Always Latest Version)

Using `uvx` ensures you always run the latest published version without manual installation.

Configure in `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json`:

Recommended: Explicit latest version

json

{
  "mcpServers": {
    "gurddy": {
      "command": "uvx",
      "args": ["gurddy-mcp@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "run_example",
        "info",
        "install",
        "solve_n_queens",
        "solve_sudoku",
        "solve_graph_coloring",
        "solve_map_coloring",
        "solve_lp",
        "solve_production_planning",
        "solve_minimax_game",
        "solve_minimax_decision",
        "solve_24_point_game",
        "solve_chicken_rabbit_problem",
        "solve_scipy_portfolio_optimization",
        "solve_scipy_statistical_fitting",
        "solve_scipy_facility_location"
      ]
    }
  }
}

Alternative: Without version specifier (also uses latest)

json

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

Pin to specific version (if needed)

json

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

Why use uvx?

✅ Always runs the latest published version automatically
✅ No manual installation or upgrade needed
✅ Isolated environment per execution
✅ No dependency conflicts with your system Python

Prerequisites: Install `uv` first:

bash

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

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Option B: Using Direct Command (After Installation)

If you've already installed `gurddy-mcp` via pip:

json

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

Available MCP tools (16 total):

`info` - Get gurddy MCP server information and capabilities
`install` - Install or upgrade the gurddy package
`run_example` - Run example programs (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, etc.)
`solve_n_queens` - Solve N-Queens problem for any board size
`solve_sudoku` - Solve 9×9 Sudoku puzzles using CSP
`solve_graph_coloring` - Solve graph coloring with configurable colors
`solve_map_coloring` - Solve map coloring problems (e.g., Australia, USA)
`solve_lp` - Solve Linear Programming (LP) or Mixed Integer Programming (MIP)
`solve_production_planning` - Production optimization with optional sensitivity analysis
`solve_minimax_game` - Two-player zero-sum games (find Nash equilibria)
`solve_minimax_decision` - Robust optimization (minimize max loss or maximize min gain)
`solve_24_point_game` - Solve 24-point game with four numbers using arithmetic operations
`solve_chicken_rabbit_problem` - Solve classic chicken-rabbit problem with heads and legs constraints
`solve_scipy_portfolio_optimization` - Solve nonlinear portfolio optimization using SciPy
`solve_scipy_statistical_fitting` - Solve statistical parameter estimation using SciPy
`solve_scipy_facility_location` - Solve facility location problem using hybrid CSP-SciPy approach

Test the MCP server:

bash

# 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 ` or `python -m mcp_server.server run-example `:

### 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 =2.6.0 scipy>=1.9.0 numpy>=1.21.0

# Check installation
python -c "import gurddy, pulp, scipy, numpy; print('All dependencies installed')"

Example Debugging

Run examples directly for debugging:

bash

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

SciPy Integration Requirements

The SciPy integration examples require additional dependencies:

bash

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

SciPy Examples Include:

Nonlinear Portfolio Optimization: Quadratic risk models with Sharpe ratio maximization
Statistical Parameter Estimation: Distribution fitting with MLE and quantile methods
Signal Processing: FIR filter design with frequency response optimization
Hybrid CSP-SciPy: Facility location combining discrete and continuous optimization
Numerical Integration: Complex optimization problems involving integrals

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`:

python

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`:

python

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

bash

# 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

python

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

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

Testing

bash

# 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

License

This project is licensed under an open source license. Please see the LICENSE file for details.

Frequently asked questions

What is gurddy-mcp?

gurddy-mcp is gruddy mcp server

How do I install gurddy-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is gurddy-mcp open source?

Yes — it is hosted on GitHub at https://github.com/novvoo/gurddy-mcp and has 2 stars.

Related MCP tools

cognee

Cognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.

30,433 Python

agent-memoryagent-skillsai+16

skyvern

Automate browser based workflows with AI

22,930 Python

apiautomationbrowser+13

hindsight

Hindsight: Agent Memory That Learns

22,468 Python

agentic-aimemoryagents+1

watermarks-remover

A privacy-first app that strips AI watermarks from content you own.

20,504 Python

agent-skillaic2pa+12

Qwen-Agent

Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.

17,062 Python

pal-mcp-server

The power of Claude Code / GeminiCLI / CodexCLI + [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.

11,731 Python

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP