gurddy mcp Server

resmi

Bu depo, tam işlevsel bir MCP (Model Context Protocol) sunucusu içerir ve Kısıt Memnuniyeti Problemleri (CSP) ile Doğrusal Programlama (LP) için çözümler sağlar. gurddy paketine dayanır ve çeşitli klasik problemlerin çözümünü destekler.

GitHub
2

Dokümantasyon

Gurddy MCP Sunucusu

PyPI version Python Support License: MIT Live Demo

Kısıt Tatmin Problemleri (CSP), Doğrusal Programlama (LP), Minimax optimizasyonu ve SciPy destekli ileri düzey optimizasyon problemlerini çözmek için kapsamlı bir Model Bağlam Protokolü (MCP) sunucusu. SciPy entegrasyonlu gurddy optimizasyon kütüphanesi üzerine inşa edilmiştir ve iki MCP aktarımı aracılığıyla çeşitli klasik problemlerin çözümünü destekler: stdio (IDE entegrasyonu için) ve akışlı HTTP (web istemcileri için).

🚀 Hızlı Başlangıç (Stdio): pip install gurddy_mcp ardından IDE'nizde yapılandırın

🌐 Hızlı Başlangıç (HTTP): docker run -p 8080:8080 gurddy-mcp veya dağıtım kılavuzuna bakın

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

Ana Özellikler

🎯 CSP Problem Çözümü

  • N-Vezir Problemi: N veziri, birbirine saldırmayacak şekilde N×N satranç tahtasına yerleştirme
  • Graf Renklendirme: Bitişik köşeler farklı olacak şekilde köşelere renk atama
  • Harita Renklendirme: Bitişik bölgeler farklı olacak şekilde coğrafi bölgeleri renklendirme
  • Sudoku Çözücü: Standart 9×9 Sudoku bulmacalarını çözme
  • Mantık Bulmacaları: Einstein'ın Zebra bulmacası ve özel mantık problemleri
  • Zamanlama: Ders programı, toplantı zamanlaması, kaynak tahsisi
  • Genel CSP Çözücü: Özel kısıt tatmin problemleri için destek

📊 LP/Optimizasyon Problemleri

  • Doğrusal Programlama: Doğrusal kısıtlarla sürekli değişken optimizasyonu
  • Karma Tamsayılı Programlama: Tamsayı ve sürekli değişkenlerle optimizasyon
  • Üretim Planlaması: Duyarlılık analizi ile kaynak kısıtlı üretim optimizasyonu
  • Portföy Optimizasyonu: Risk kısıtları altında yatırım tahsisi
  • Taşıma Problemleri: Tedarik zinciri ve lojistik optimizasyonu

🎮 Minimax/Oyun Teorisi

  • Sıfır Toplamlı Oyunlar: İki oyunculu oyunları çözme (Taş-Kağıt-Makas, Yazı-Tura, Cinsiyetler Savaşı)
  • Karma Strateji Nash Dengeleri: Optimal olasılıksal stratejileri bulma
  • Gürbüz Optimizasyon: Belirsizlik altında en kötü durum kaybını minimize etme
  • Maximin Kararları: En kötü durum kazancını maksimize etme (muhafazakar stratejiler)
  • Güvenlik Oyunları: Savunmacı-saldırgan kaynak tahsisi
  • Gürbüz Portföy: Piyasa senaryoları arasında maksimum kaybı minimize etme
  • Üretim Planlaması: Muhafazakar üretim kararları (minimum karı maksimize etme)
  • Reklam Rekabeti: Pazar payı oyunları ve rekabetçi stratejiler

🔬 SciPy Entegrasyonu

  • Doğrusal Olmayan Portföy Optimizasyonu: SciPy optimizasyonu ile ikinci dereceden risk modelleri
  • İstatistiksel Parametre Tahmini: Kısıtlarla dağılım uydurma (MLE, kantil eşleştirme)
  • Sinyal İşleme Optimizasyonu: Frekans yanıtı optimizasyonu ile FIR filtre tasarımı
  • Hibrit CSP-SciPy: Ayrık tesis seçimi + sürekli kapasite optimizasyonu
  • Sayısal İntegrasyon: İntegraller ve karmaşık fonksiyonlar içeren optimizasyon problemleri

🧮 Klasik Matematik Problemleri

  • 24 Puan Oyunu: Dört sayı kullanarak 24'e ulaşmak için aritmetik ifadeler bulma
  • Tavşan-Tavuk Problemi: Baş ve bacaklarla klasik kısıt problemi
  • Mini Sudoku: CSP teknikleri kullanan 4×4 Sudoku çözücü
  • 4-Vezir Problemi: Eğitim amaçlı basitleştirilmiş N-Vezir
  • 0-1 Sırt Çantası: Ağırlık ve değer kısıtlarıyla klasik optimizasyon problemi

🔌 MCP Protokol Desteği

  • Stdio Aktarımı: Yerel IDE entegrasyonu (Kiro, Claude Desktop, Cline, vb.)
  • Akışlı HTTP Aktarımı: Web istemcileri ve isteğe bağlı akış ile uzaktan erişim
  • Birleşik Arayüz: Her iki aktarımda da aynı araçlar
  • JSON-RPC 2.0: Tam protokol uyumluluğu
  • Otomatik Onay: Sorunsuz yürütme için güvenilir araçları yapılandırma

Kurulum

PyPI'den (Önerilir)

# Install the latest stable version
pip install gurddy_mcp

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

Kaynaktan

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

# Install in development mode
pip install -e .

Kurulumu Doğrulama

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

Kullanım

1. MCP Stdio Sunucusu (Birincil Arayüz)

Ana gurddy-mcp komutu, Kiro gibi araçlarla entegre edilebilen bir MCP stdio sunucusudur.

Seçenek A: uvx Kullanımı (Önerilir - Her Zaman En Son Sürüm)

uvx kullanmak, manuel kurulum olmadan her zaman en son yayınlanan sürümü çalıştırmanızı sağlar.

~/.kiro/settings/mcp.json veya .kiro/settings/mcp.json içinde yapılandırın:

Önerilen: Açık en son sürüm

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

Alternatif: Sürüm belirteci olmadan (aynı zamanda en son sürümü kullanır)

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

Belirli bir sürüme sabitleme (gerekirse)

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

Neden uvx kullanmalı?

  • ✅ Her zaman en son yayınlanan sürümü otomatik olarak çalıştırır
  • ✅ Manuel kurulum veya yükseltme gerekmez
  • ✅ Her yürütme için yalıtılmış ortam
  • ✅ Sistem Python'unuzla bağımlılık çakışması olmaz

Önkoşullar: Önce uv yükleyin:

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

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Seçenek B: Doğrudan Komut Kullanımı (Kurulumdan Sonra)

gurddy-mcp paketini pip ile zaten yüklediyseniz:

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

Mevcut MCP araçları (toplam 16):

  • info - Gurddy MCP sunucusu bilgisi ve yeteneklerini alın
  • install - Gurddy paketini yükleyin veya yükseltin
  • run_example - Örnek programları çalıştırın (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, vb.)
  • solve_n_queens - Herhangi bir tahta boyutu için N-Vezir problemini çözün
  • solve_sudoku - CSP kullanarak 9×9 Sudoku bulmacalarını çözün
  • solve_graph_coloring - Yapılandırılabilir renklerle graf renklendirmeyi çözün
  • solve_map_coloring - Harita renklendirme problemlerini çözün (örn. Avustralya, ABD)
  • solve_lp - Doğrusal Programlama (LP) veya Karma Tamsayılı Programlama (MIP) çözün
  • solve_production_planning - İsteğe bağlı duyarlılık analizi ile üretim optimizasyonu
  • solve_minimax_game - İki oyunculu sıfır toplamlı oyunlar (Nash dengelerini bulun)
  • solve_minimax_decision - Gürbüz optimizasyon (maksimum kaybı minimize et veya minimum kazancı maksimize et)
  • solve_24_point_game - Dört sayı ile aritmetik işlemler kullanarak 24 puan oyununu çözün
  • solve_chicken_rabbit_problem - Baş ve bacak kısıtlarıyla klasik tavşan-tavuk problemini çözün
  • solve_scipy_portfolio_optimization - SciPy kullanarak doğrusal olmayan portföy optimizasyonunu çözün
  • solve_scipy_statistical_fitting - SciPy kullanarak istatistiksel parametre tahminini çözün
  • solve_scipy_facility_location - Hibrit CSP-SciPy yaklaşımıyla tesis konumu problemini çözün

MCP sunucusunu test edin:

# 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. MCP HTTP Sunucusu

HTTP MCP sunucusunu başlatın (akışlı HTTP üzerinden MCP protokolü):

Yerel Geliştirme:

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

Sunucuya erişim:

HTTP MCP sunucusunu test edin:

HTTP Aktarımı (akışsız):

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

HTTP Aktarımı (Accept başlığı ile akış):

# 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}}}'

HTTP Aktarımı (X-Stream başlığı ile akış):

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

Python İstemci Örneği:

  • examples/streamable_http_client.py - Akış örnekleriyle HTTP aktarım istemcisi

MCP Araçları

Sunucu aşağıdaki MCP araçlarını sağlar:

info

Gurddy paketi hakkında bilgi alın.

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

install

Gurddy paketini yükleyin veya yükseltin.

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

run_example

Bir gurddy örneği çalıştırın.

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

Mevcut örnekler: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

N-Vezir problemini çözün.

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

solve_sudoku

Bir 9x9 Sudoku bulmacasını çözün.

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

solve_graph_coloring

Graf renklendirme problemini çözün.

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

solve_map_coloring

Harita renklendirme problemini çözün.

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

solve_lp

PuLP kullanarak bir Doğrusal Programlama (LP) veya Karma Tamsayılı Programlama (MIP) problemini çözün.

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

İsteğe bağlı duyarlılık analizi ile bir üretim planlaması optimizasyon problemini çözün.

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

Minimax (oyun teorisi) kullanarak iki oyunculu sıfır toplamlı bir oyunu çözün.

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

Belirtilen oyuncu için optimal karma stratejiyi ve oyun değerini döndürür.

solve_minimax_decision

Belirsizlik altında bir minimax karar problemini çözün (gürbüz optimizasyon).

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

Amaçlar: minimize_max_loss (gürbüz portföy) veya maximize_min_gain (muhafazakar üretim)

solve_24_point_game

Dört sayı ile aritmetik işlemler kullanarak 24 puan oyununu çözün.

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

Tam olarak 24'e ulaşmak için +, -, *, / ve parantezler kullanan aritmetik ifadeler bulur.

solve_chicken_rabbit_problem

Baş ve bacak kısıtlarıyla klasik tavşan-tavuk problemini çözün.

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

Toplam baş ve bacak sayısı verildiğinde tavuk (2 bacak) ve tavşan (4 bacak) sayısını belirler.

solve_scipy_portfolio_optimization

İkinci dereceden risk modelleriyle SciPy kullanarak doğrusal olmayan portföy optimizasyonunu çözün.

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

Ortalama-varyans optimizasyonu kullanarak getiriyi maksimize etmek ve risk cezasını minimize etmek için portföy ağırlıklarını optimize eder.

solve_scipy_statistical_fitting

Dağılım uydurma ile SciPy kullanarak istatistiksel parametre tahminini çözün.

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

İstatistiksel dağılımları ("normal", "exponential", "uniform") veriye uydurur ve uyum iyiliği testleri sağlar.

solve_scipy_facility_location

Hibrit CSP-SciPy yaklaşımıyla tesis konumu problemini çözün.

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

Toplam maliyeti minimize etmek için ayrık tesis seçimini (CSP) sürekli kapasite optimizasyonuyla (SciPy) birleştirir.

Docker Dağıtımı

İnşa ve Çalıştırma

# 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

Örnek Çıktı

N-Vezir Problemi

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

Proje Yapısı

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 Aktarımları

AktarımKomutProtokolKullanım Durumu
Stdiogurddy-mcpstdin/stdout üzerinden MCPIDE entegrasyonu (Kiro, Claude Desktop, vb.)
Akışlı HTTPuvicorn mcp_server.mcp_http_server:appİsteğe bağlı akış ile HTTP üzerinden MCPWeb istemcileri, uzaktan erişim, Docker dağıtımı

Tüm aktarımlar aynı MCP protokolünü uygular ve aynı araçları sağlar.

HTTP Aktarım Özellikleri

HTTP Aktarımı (/mcp/http uç noktası):

  • Tek istek-yanıt deseni
  • İsteğe bağlı akış: Accept: text/event-stream veya X-Stream: true başlığını ekleyin
  • Tek seferlik istekler için daha basit
  • Standart HTTP istemcileriyle uyumlu
  • Yönetilecek bağlantı durumu yok
  • Hem normal JSON yanıtlarını hem de SSE formatlı akış yanıtlarını destekler

Örnek Çıktı

N-Vezir Problemi

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

Mantık Bulmacaları

$ 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 Örnekleri

Klasik Problem Çözümü

Avustralya Harita Renklendirme

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-Vezir Problemi

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

Mevcut Örnekler

Tüm örnekler gurddy-mcp run-example <name> veya python -m mcp_server.server run-example <name> kullanılarak çalıştırılabilir:

CSP Örnekleri ✅

  • n_queens - N-Vezir problemi (görsel tahta gösterimi ile 4, 6, 8 vezir)
  • graph_coloring - Graf renklendirme (Üçgen, Kare, Petersen grafı, Tekerlek grafı)
  • map_coloring - Harita renklendirme (Avustralya, ABD Batı eyaletleri, Avrupa)
  • scheduling - Zamanlama problemleri (Ders programı, toplantı zamanlaması, kaynak tahsisi)
  • logic_puzzles - Mantık bulmacaları (Basit mantık bulmacası, Einstein'ın Zebra bulmacası)
  • optimized_csp - Gelişmiş CSP teknikleri (Sudoku çözücü)

LP Örnekleri ✅

  • lp / optimized_lp - Doğrusal programlama örnekleri:
    • Risk kısıtlarıyla portföy optimizasyonu
    • Taşıma problemi (tedarik zinciri optimizasyonu)
    • Kısıt gevşetme analizi
    • Problem boyutları arasında performans karşılaştırması

Minimax Örnekleri ✅

  • minimax - Minimax optimizasyonu ve oyun teorisi:
    • Taş-Kağıt-Makas (sıfır toplamlı oyun)
    • Yazı-Tura (koordinasyon oyunu)
    • Cinsiyetler Savaşı (karma strateji dengesi)
    • Gürbüz portföy optimizasyonu (maksimum kaybı minimize etme)
    • Üretim planlaması (minimum karı maksimize etme)
    • Güvenlik kaynak tahsisi (savunmacı-saldırgan oyunu)
    • Reklam rekabeti (pazar payı oyunu)

SciPy Entegrasyon Örnekleri ✅

  • scipy_optimization - SciPy ile gelişmiş optimizasyon:
    • Kuadratik risk modelleri ile doğrusal olmayan portföy optimizasyonu
    • İstatistiksel parametre tahmini (kısıtlı dağılım uydurma)
    • Sinyal işleme optimizasyonu (FIR filtre tasarımı)
    • Hibrit CSP-SciPy tesis yerleşimi (ayrık + sürekli optimizasyon)
    • Optimizasyon hedeflerinde sayısal entegrasyon

Klasik Matematik Problemleri ✅

  • classic_problems - Eğitsel matematik problem çözümü:
    • 24-Puan Oyunu (24'e ulaşmak için aritmetik ifadeler)
    • Tavşan-Tavuk Problemi (klasik kısıt sağlama)
    • 4×4 Mini Sudoku (basitleştirilmiş CSP gösterimi)
    • 4-Vezir Problemi (eğitsel N-Vezir varyantı)
    • 0-1 Sırt Çantası Problemi (klasik optimizasyon)

Desteklenen Problem Türleri

🧩 CSP Problemleri

  • N-Vezir: Herhangi bir tahta boyutu için klasik N-Vezir problemi (N=4 ila N=100+)
  • Graf Boyama: Rastgele graflar için köşe boyama (üçgen, Petersen, çark, vb.)
  • Harita Boyama: Coğrafi bölge boyama (Avustralya, ABD, Avrupa haritaları)
  • Sudoku: Kısıt yayılımı ile standart 9×9 Sudoku bulmacaları
  • Mantık Bulmacaları: Einstein'ın Zebra bulmacası ve özel mantıksal akıl yürütme problemleri
  • Zamanlama: Ders programı, toplantı odaları, zaman kısıtlı kaynak tahsisi

📈 Optimizasyon Problemleri

  • Doğrusal Programlama: Doğrusal kısıtlarla sürekli değişken optimizasyonu
  • Tamsayı Programlama: Ayrık değişken optimizasyonu (üretim miktarları, atamalar)
  • Karma Tamsayı Programlama: Birleşik sürekli ve ayrık değişkenler
  • Üretim Planlama: Çok ürünlü kaynak kısıtlı optimizasyon
  • Portföy Optimizasyonu: Risk ve getiri kısıtlı yatırım tahsisi
  • Ulaştırma: Tedarik zinciri optimizasyonu (depolardan müşterilere)

🎲 Oyun Teorisi ve Gürbüz Optimizasyon

  • Sıfır Toplamlı Oyunlar: Taş-Kağıt-Makas, Yazı-Tura Eşleştirme, Cinsiyetler Savaşı
  • Karma Strateji Nash Dengeleri: Her iki oyuncu için optimal olasılıksal stratejiler
  • Minimaks Kararları: Belirsizlik senaryolarında en kötü durum kaybını en aza indir
  • Maksimin Kararları: En kötü durum kazancını en üst düzeye çıkar (muhafazakar stratejiler)
  • Gürbüz Portföy: Piyasa senaryolarında maksimum kaybı en aza indir
  • Güvenlik Oyunları: Savunmacı-saldırgan kaynak tahsisi problemleri

🔬 SciPy Destekli Gelişmiş Optimizasyon

  • Doğrusal Olmayan Portföy Optimizasyonu: Sharpe oranı maksimizasyonu ile kuadratik risk modelleri
  • İstatistiksel Parametre Tahmini: Kısıtlarla MLE ve kantil tabanlı dağılım uydurma
  • Sinyal İşleme: Frekans yanıtı optimizasyonu ile FIR filtre tasarımı
  • Hibrit Optimizasyon: Gurddy CSP'yi SciPy sürekli optimizasyonu ile birleştir
  • Sayısal Entegrasyon: Karmaşık matematiksel fonksiyonlar içeren optimizasyon problemleri

🧮 Klasik Eğitim Problemleri

  • 24-Puan Oyunu: 24'e ulaşmak için dört sayı kullanarak aritmetik ifadeler bul
  • Tavşan-Tavuk Problemi: Baş ve bacaklarla klasik kısıt sağlama
  • Mini Sudoku: CSP teknikleri kullanarak 4×4 Sudoku çözme
  • N-Vezir Varyantları: Klasik problemin eğitsel sürümleri
  • Sırt Çantası Problemleri: Ağırlık ve değer kısıtlı 0-1 sırt çantası optimizasyonu

Performans Özellikleri

  • Hızlı Çözüm: Küçük-orta problemler için milisaniye yanıt (N-Vezir N≤12, <50 köşeli graflar)
  • Ölçeklenebilir: Büyük problemleri işler (N-Vezir N=100+, 1000+ değişkenli DP)
  • Bellek Verimli: Geri izleme araması ve kısıt yayılımı bellek kullanımını en aza indirir
  • Genişletilebilir: Özel kısıtlar, amaç fonksiyonları ve problem türleri
  • Eşzamanlılık Güvenli: HTTP API eşzamanlı istek işlemeyi destekler
  • Üretime Hazır: Docker dağıtımı, sağlık kontrolleri, hata yönetimi

Performans Karşılaştırmaları

Standart donanımda tipik yürütme süreleri:

  • CSP Örnekleri: 0.4-0.5s (N-Vezir, Graf Boyama, Mantık Bulmacaları)
  • DP Örnekleri: 0.8-0.9s (Portföy, Ulaştırma, Üretim Planlama)
  • Minimaks Örnekleri: 0.3-0.5s (Oyun çözme, Gürbüz optimizasyon)
  • SciPy Örnekleri: 0.5-1.2s (Doğrusal olmayan optimizasyon, İstatistiksel uydurma)
  • Klasik Problemler: 0.1-0.3s (24-puan, Tavşan-tavuk, Mini sudoku)
  • Sudoku: Standart 9×9 bulmacalar için <0.1s
  • Büyük N-Vezir: N=100 için ~2-3s

Sorun Giderme

Yaygın Hatalar

  • "gurddy package not available": python -m mcp_server.server install ile yükleyin
  • "No solution found": Verilen kısıtlar altında çözüm yok; kısıtları gevşetmeyi deneyin
  • "Invalid input types": Girdi parametrelerinin veri türlerini kontrol edin
  • "Unknown example": Mevcut örnekleri görmek için python -m mcp_server.server run-example --help kullanın

Kurulum Sorunları

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

Örnek Hata Ayıklama

Hata ayıklama için örnekleri doğrudan çalıştırın:

# 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 Entegrasyon Gereksinimleri

SciPy entegrasyon örnekleri ek bağımlılıklar gerektirir:

# 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 Örnekleri Şunları İçerir:

  • Doğrusal Olmayan Portföy Optimizasyonu: Sharpe oranı maksimizasyonu ile kuadratik risk modelleri
  • İstatistiksel Parametre Tahmini: MLE ve kantil yöntemleri ile dağılım uydurma
  • Sinyal İşleme: Frekans yanıtı optimizasyonu ile FIR filtre tasarımı
  • Hibrit CSP-SciPy: Ayrık ve sürekli optimizasyonu birleştiren tesis yerleşimi
  • Sayısal Entegrasyon: İntegraller içeren karmaşık optimizasyon problemleri

Geliştirme

Mimari

Proje, stdio ve HTTP sunucuları arasında tutarlılığı sağlamak için otomatik oluşturulan şemalar ile merkezi bir araç kaydı kullanır:

  • Araç Tanımları: mcp_server/tool_definitions.py (yalnızca temel meta veriler)
  • Otomatik Oluşturulan Kayıt: mcp_server/tool_registry.py (fonksiyon imzalarından oluşturulan şemalar)
  • Stdio Sunucusu: mcp_server/mcp_stdio_server.py (IDE entegrasyonu için)
  • HTTP Sunucusu: mcp_server/mcp_http_server.py (web istemcileri için)
  • İşleyiciler: mcp_server/handlers/gurddy.py (araç uygulamaları)
  • Şema Oluşturucu: scripts/generate_registry.py (fonksiyon imzalarından otomatik şema oluşturur)

Yeni Bir Araç Ekleme

  1. İşleyiciyi uygulayın mcp_server/handlers/gurddy.py içinde:

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

  2. Temel meta verileri ekleyin mcp_server/tool_definitions.py içinde:

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

  3. Şemaları oluşturun ve doğrulayın:

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

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

Hepsi bu kadar! Şema, fonksiyonunuzun tür ipuçlarından otomatik olarak oluşturulur ve hem stdio hem de HTTP sunucuları yeni aracı alır.

Özel Kısıtlar

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

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

Test Etme

# 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

Lisans

Bu proje açık kaynaklı bir lisans altında lisanslanmıştır. Ayrıntılar için lütfen LICENSE dosyasına bakın.