gurddy mcp Server

resmi

Repositori ini berisi server MCP (Model Context Protocol) yang berfungsi penuh, menyediakan solusi untuk Masalah Kepuasan Kendala (CSP) dan Pemrograman Linear (LP). Server ini didasarkan pada paket gurddy dan mendukung penyelesaian berbagai masalah klasik.

GitHub

Dokumentasi

Server MCP Gurddy

Server Model Context Protocol (MCP) komprehensif untuk menyelesaikan Masalah Kepuasan Kendala (CSP), Pemrograman Linear (LP), optimasi Minimax, dan masalah optimasi lanjutan berbasis SciPy. Dibangun di atas pustaka optimasi gurddy dengan integrasi SciPy, server ini mendukung penyelesaian berbagai masalah klasik melalui dua transport MCP: stdio (untuk integrasi IDE) dan HTTP streamable (untuk klien web).

🚀 Mulai Cepat (Stdio): pip install gurddy_mcp lalu konfigurasikan di IDE Anda

🌐 Mulai Cepat (HTTP): docker run -p 8080:8080 gurddy-mcp atau lihat panduan deployment

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

Fitur Utama

🎯 Penyelesaian Masalah CSP

Masalah N-Ratu: Tempatkan N ratu di papan catur N×N tanpa saling serang
Pewarnaan Graf: Tetapkan warna ke simpul sehingga simpul yang berdekatan berbeda
Pewarnaan Peta: Warnai wilayah geografis dengan wilayah yang berdekatan berbeda
Penyelesai Sudoku: Selesaikan teka-teki Sudoku standar 9×9
Teka-teki Logika: Teka-teki Zebra Einstein dan masalah logika kustom
Penjadwalan: Penjadwalan kursus, penjadwalan rapat, alokasi sumber daya
Penyelesai CSP Umum: Dukungan untuk masalah kepuasan kendala kustom

📊 Masalah LP/Optimasi

Pemrograman Linear: Optimasi variabel kontinu dengan kendala linear
Pemrograman Integer Campuran: Optimasi dengan variabel integer dan kontinu
Perencanaan Produksi: Optimasi produksi dengan kendala sumber daya dan analisis sensitivitas
Optimasi Portofolio: Alokasi investasi di bawah kendala risiko
Masalah Transportasi: Optimasi rantai pasok dan logistik

🎮 Minimax/Teori Permainan

Permainan Jumlah-Nol: Selesaikan permainan dua pemain (Batu-Gunting-Kertas, Koin Serasi, Pertempuran Jenis Kelamin)
Ekuilibrium Nash Strategi Campuran: Temukan strategi probabilistik optimal
Optimasi Robust: Minimalkan kerugian kasus terburuk di bawah ketidakpastian
Keputusan Maximin: Maksimalkan keuntungan kasus terburuk (strategi konservatif)
Permainan Keamanan: Alokasi sumber daya penyerang-bertahan
Portofolio Robust: Minimalkan kerugian maksimum di seluruh skenario pasar
Perencanaan Produksi: Keputusan produksi konservatif (maksimalkan laba minimum)
Persaingan Iklan: Permainan pangsa pasar dan strategi kompetitif

🔬 Integrasi SciPy

Optimasi Portofolio Nonlinear: Model risiko kuadratik dengan optimasi SciPy
Estimasi Parameter Statistik: Pencocokan distribusi dengan kendala (MLE, pencocokan kuantil)
Optimasi Pemrosesan Sinyal: Desain filter FIR dengan optimasi respons frekuensi
CSP-SciPy Hibrida: Pemilihan fasilitas diskrit + optimasi kapasitas kontinu
Integrasi Numerik: Masalah optimasi yang melibatkan integral dan fungsi kompleks

🧮 Masalah Matematika Klasik

Permainan 24-Angka: Temukan ekspresi aritmatika untuk mencapai 24 menggunakan empat angka
Masalah Ayam-Kelinci: Masalah kendala klasik dengan kepala dan kaki
Sudoku Mini: Penyelesai Sudoku 4×4 menggunakan teknik CSP
Masalah 4-Ratu: N-Ratu yang disederhanakan untuk tujuan edukasi
Knapsack 0-1: Masalah optimasi klasik dengan kendala berat dan nilai

🔌 Dukungan Protokol MCP

Transport Stdio: Integrasi IDE lokal (Kiro, Claude Desktop, Cline, dll.)
Transport HTTP Streamable: Klien web dan akses jarak jauh dengan streaming opsional
Antarmuka Terpadu: Alat yang sama di kedua transport
JSON-RPC 2.0: Kepatuhan protokol penuh
Persetujuan Otomatis: Konfigurasikan alat tepercaya untuk eksekusi mulus

Instalasi

Dari PyPI (Direkomendasikan)

# Install the latest stable version
pip install gurddy_mcp

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

Dari Sumber

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

# Install in development mode
pip install -e .

Verifikasi Instalasi

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

Penggunaan

1. Server MCP Stdio (Antarmuka Utama)

Perintah gurddy-mcp utama adalah server MCP stdio yang dapat diintegrasikan dengan alat seperti Kiro.

Opsi A: Menggunakan uvx (Direkomendasikan - Selalu Versi Terbaru)

Menggunakan uvx memastikan Anda selalu menjalankan versi terbaru yang dipublikasikan tanpa instalasi manual.

Konfigurasikan di ~/.kiro/settings/mcp.json atau .kiro/settings/mcp.json:

Direkomendasikan: Versi terbaru eksplisit

{
  "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: Tanpa penentu versi (juga menggunakan terbaru)

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

Sematkan ke versi spesifik (jika diperlukan)

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

Mengapa menggunakan uvx?

✅ Selalu menjalankan versi terbaru yang dipublikasikan secara otomatis
✅ Tidak perlu instalasi atau peningkatan manual
✅ Lingkungan terisolasi per eksekusi
✅ Tidak ada konflik dependensi dengan Python sistem Anda

Prasyarat: Instal uv terlebih dahulu:

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

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Opsi B: Menggunakan Perintah Langsung (Setelah Instalasi)

Jika Anda sudah menginstal gurddy-mcp melalui 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"
      ]
    }
  }
}

Alat MCP yang tersedia (total 16):

info - Dapatkan informasi dan kemampuan server MCP gurddy
install - Instal atau tingkatkan paket gurddy
run_example - Jalankan program contoh (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, dll.)
solve_n_queens - Selesaikan masalah N-Ratu untuk ukuran papan apa pun
solve_sudoku - Selesaikan teka-teki Sudoku 9×9 menggunakan CSP
solve_graph_coloring - Selesaikan pewarnaan graf dengan warna yang dapat dikonfigurasi
solve_map_coloring - Selesaikan masalah pewarnaan peta (mis., Australia, AS)
solve_lp - Selesaikan Pemrograman Linear (LP) atau Pemrograman Integer Campuran (MIP)
solve_production_planning - Optimasi produksi dengan analisis sensitivitas opsional
solve_minimax_game - Permainan jumlah-nol dua pemain (temukan ekuilibrium Nash)
solve_minimax_decision - Optimasi robust (minimalkan kerugian maks atau maksimalkan keuntungan min)
solve_24_point_game - Selesaikan permainan 24-angka dengan empat angka menggunakan operasi aritmatika
solve_chicken_rabbit_problem - Selesaikan masalah ayam-kelinci klasik dengan kendala kepala dan kaki
solve_scipy_portfolio_optimization - Selesaikan optimasi portofolio nonlinear menggunakan SciPy
solve_scipy_statistical_fitting - Selesaikan estimasi parameter statistik menggunakan SciPy
solve_scipy_facility_location - Selesaikan masalah lokasi fasilitas menggunakan pendekatan CSP-SciPy hibrida

Uji server 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. Server MCP HTTP

Mulai server MCP HTTP (protokol MCP melalui HTTP streamable):

Pengembangan Lokal:

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

Akses server:

Root: http://127.0.0.1:8080/
Pemeriksaan kesehatan: http://127.0.0.1:8080/health
Transport HTTP: http://127.0.0.1:8080/mcp/http (POST - mendukung reguler dan streaming)

Uji server MCP HTTP:

Transport HTTP (non-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":{}}}'

Transport HTTP (streaming dengan header 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}}}'

Transport HTTP (streaming dengan header 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":{}}}'

Contoh Klien Python:

examples/streamable_http_client.py - Klien transport HTTP dengan contoh streaming

Alat MCP

Server menyediakan alat MCP berikut:

info

Dapatkan informasi tentang paket gurddy.

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

install

Instal atau tingkatkan paket gurddy.

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

run_example

Jalankan contoh gurddy.

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

Contoh yang tersedia: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Selesaikan masalah N-Ratu.

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

solve_sudoku

Selesaikan teka-teki Sudoku 9x9.

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

solve_graph_coloring

Selesaikan masalah pewarnaan graf.

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

solve_map_coloring

Selesaikan masalah pewarnaan peta.

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

solve_lp

Selesaikan masalah Pemrograman Linear (LP) atau Pemrograman Integer Campuran (MIP) menggunakan 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

Selesaikan masalah optimasi perencanaan produksi dengan analisis sensitivitas opsional.

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

Selesaikan permainan jumlah-nol dua pemain menggunakan minimax (teori permainan).

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

Mengembalikan strategi campuran optimal dan nilai permainan untuk pemain yang ditentukan.

solve_minimax_decision

Selesaikan masalah keputusan minimax di bawah ketidakpastian (optimasi robust).

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

Tujuan: minimize_max_loss (portofolio robust) atau maximize_min_gain (produksi konservatif)

solve_24_point_game

Selesaikan permainan 24-angka dengan empat angka menggunakan operasi aritmatika.

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

Menemukan ekspresi aritmatika menggunakan +, -, *, / dan tanda kurung untuk mencapai tepat 24.

solve_chicken_rabbit_problem

Selesaikan masalah ayam-kelinci klasik dengan kendala kepala dan kaki.

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

Menentukan jumlah ayam (2 kaki) dan kelinci (4 kaki) berdasarkan total kepala dan kaki.

solve_scipy_portfolio_optimization

Selesaikan optimasi portofolio nonlinear menggunakan SciPy dengan model risiko kuadratik.

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

Mengoptimalkan bobot portofolio untuk memaksimalkan imbal hasil dikurangi penalti risiko menggunakan optimasi mean-variance.

solve_scipy_statistical_fitting

Selesaikan estimasi parameter statistik menggunakan SciPy dengan pencocokan distribusi.

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

Mencocokkan distribusi statistik ("normal", "exponential", "uniform") ke data dan menyediakan uji goodness-of-fit.

solve_scipy_facility_location

Selesaikan masalah lokasi fasilitas menggunakan pendekatan CSP-SciPy hibrida.

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

Menggabungkan pemilihan fasilitas diskrit (CSP) dengan optimasi kapasitas kontinu (SciPy) untuk meminimalkan biaya total.

Deployment Docker

Build dan Jalankan

# 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

Contoh Output

Masalah N-Ratu

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

Struktur Proyek

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

Transport MCP

Transport	Perintah	Protokol	Kasus Penggunaan
Stdio	`gurddy-mcp`	MCP melalui stdin/stdout	Integrasi IDE (Kiro, Claude Desktop, dll.)
HTTP Streamable	`uvicorn mcp_server.mcp_http_server:app`	MCP melalui HTTP dengan streaming opsional	Klien web, akses jarak jauh, deployment Docker

Semua transport mengimplementasikan protokol MCP yang sama dan menyediakan alat yang identik.

Fitur Transport HTTP

Transport HTTP (endpoint /mcp/http):

Pola permintaan-respons tunggal
Streaming opsional: Tambahkan header Accept: text/event-stream atau X-Stream: true
Lebih sederhana untuk permintaan satu kali
Kompatibel dengan klien HTTP standar
Tidak ada status koneksi yang perlu dikelola
Mendukung respons JSON reguler dan respons streaming berformat SSE

Contoh Output

Masalah N-Ratu

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

Teka-teki Logika

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

Contoh API HTTP

Penyelesaian Masalah Klasik

Pewarnaan Peta Australia

import requests

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

Masalah 8-Ratu

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

Contoh yang Tersedia

Semua contoh dapat dijalankan menggunakan gurddy-mcp run-example <name> atau python -m mcp_server.server run-example <name>:

Contoh CSP ✅

n_queens - Masalah N-Ratu (4, 6, 8 ratu dengan tampilan papan visual)
graph_coloring - Pewarnaan graf (Segitiga, Persegi, graf Petersen, graf Roda)
map_coloring - Pewarnaan peta (Australia, negara bagian Barat AS, Eropa)
scheduling - Masalah penjadwalan (Penjadwalan kursus, penjadwalan rapat, alokasi sumber daya)
logic_puzzles - Teka-teki logika (Teka-teki logika sederhana, teka-teki Zebra Einstein)
optimized_csp - Teknik CSP lanjutan (Penyelesai Sudoku)

Contoh LP ✅

lp / optimized_lp - Contoh pemrograman linear:
- Optimasi portofolio dengan kendala risiko
- Masalah transportasi (optimasi rantai pasok)
- Analisis relaksasi kendala
- Perbandingan kinerja di berbagai ukuran masalah

Contoh Minimax ✅

minimax - Optimasi minimax dan teori permainan:
- Batu-Gunting-Kertas (permainan jumlah-nol)
- Koin Serasi (permainan koordinasi)
- Pertempuran Jenis Kelamin (ekuilibrium strategi campuran)
- Optimasi portofolio robust (minimalkan kerugian maksimum)
- Perencanaan produksi (maksimalkan laba minimum)
- Alokasi sumber daya keamanan (permainan penyerang-bertahan)
- Persaingan iklan (permainan pangsa pasar)

Contoh Integrasi SciPy ✅

scipy_optimization - Optimasi lanjutan dengan SciPy:
- Optimasi portofolio nonlinear dengan model risiko kuadratik
- Estimasi parameter statistik (pencocokan distribusi dengan kendala)
- Optimasi pemrosesan sinyal (desain filter FIR)
- Lokasi fasilitas CSP-SciPy hibrida (optimasi diskrit + kontinu)
- Integrasi numerik dalam tujuan optimasi

Masalah Matematika Klasik ✅

classic_problems - Penyelesaian masalah matematika edukatif:
- Permainan 24-Angka (ekspresi aritmatika untuk mencapai 24)
- Masalah Ayam-Kelinci (kepuasan kendala klasik)
- Sudoku Mini 4×4 (demonstrasi CSP yang disederhanakan)
- Masalah 4-Ratu (varian N-Ratu edukatif)
- Masalah Knapsack 0-1 (optimasi klasik)

Jenis Masalah yang Didukung

🧩 Masalah CSP

N-Ratu: Masalah N-Ratu klasik untuk ukuran papan apa pun (N=4 hingga N=100+)
Pewarnaan Graf: Pewarnaan simpul untuk graf arbitrer (segitiga, Petersen, roda, dll.)
Pewarnaan Peta: Pewarnaan wilayah geografis (peta Australia, AS, Eropa)
Sudoku: Teka-teki Sudoku standar 9×9 dengan propagasi kendala
Teka-teki Logika: Teka-teki Zebra Einstein dan masalah penalaran logika kustom
Penjadwalan: Penjadwalan kursus, ruang rapat, alokasi sumber daya dengan kendala waktu

📈 Masalah Optimasi

Pemrograman Linear: Optimasi variabel kontinu dengan kendala linear
Pemrograman Integer: Optimasi variabel diskrit (kuantitas produksi, penugasan)
Pemrograman Integer Campuran: Variabel kontinu dan diskrit gabungan
Perencanaan Produksi: Optimasi produksi multi-produk dengan kendala sumber daya
Optimasi Portofolio: Alokasi investasi dengan kendala risiko dan imbal hasil
Transportasi: Optimasi rantai pasok (gudang ke pelanggan)

🎲 Teori Permainan & Optimasi Robust

Permainan Jumlah-Nol: Batu-Gunting-Kertas, Koin Serasi, Pertempuran Jenis Kelamin
Ekuilibrium Nash Strategi Campuran: Strategi probabilistik optimal untuk kedua pemain
Keputusan Minimax: Minimalkan kerugian kasus terburuk di seluruh skenario ketidakpastian
Keputusan Maximin: Maksimalkan keuntungan kasus terburuk (strategi konservatif)
Portofolio Robust: Minimalkan kerugian maksimum di seluruh skenario pasar
Permainan Keamanan: Masalah alokasi sumber daya penyerang-bertahan

🔬 Optimasi Lanjutan Bertenaga SciPy

Optimasi Portofolio Nonlinear: Model risiko kuadratik dengan maksimisasi rasio Sharpe
Estimasi Parameter Statistik: Pencocokan distribusi berbasis MLE dan kuantil dengan kendala
Pemrosesan Sinyal: Desain filter FIR dengan optimasi respons frekuensi
Optimasi Hibrida: Gabungkan CSP Gurddy dengan optimasi kontinu SciPy
Integrasi Numerik: Masalah optimasi yang melibatkan fungsi matematika kompleks

🧮 Masalah Edukasi Klasik

Permainan 24-Angka: Temukan ekspresi aritmatika menggunakan empat angka untuk mencapai 24
Masalah Ayam-Kelinci: Kepuasan kendala klasik dengan kepala dan kaki
Sudoku Mini: Penyelesaian Sudoku 4×4 menggunakan teknik CSP
Varian N-Ratu: Versi edukatif dari masalah klasik
Masalah Knapsack: Optimasi knapsack 0-1 dengan kendala berat dan nilai

Fitur Kinerja

Solusi Cepat: Respons milidetik untuk masalah kecil-menengah (N-Ratu N≤12, graf <50 simpul)
Skalabel: Menangani masalah besar (N-Ratu N=100+, LP dengan 1000+ variabel)
Efisien Memori: Pencarian backtracking dan propagasi kendala meminimalkan penggunaan memori
Dapat Diperluas: Kendala kustom, fungsi tujuan, dan jenis masalah
Aman Konkurensi: API HTTP mendukung pemrosesan permintaan konkuren
Siap Produksi: Deployment Docker, pemeriksaan kesehatan, penanganan kesalahan

Tolok Ukur Kinerja

Waktu eksekusi tipikal pada perangkat keras standar:

Contoh CSP: 0,4-0,5 detik (N-Ratu, Pewarnaan Graf, Teka-teki Logika)
Contoh LP: 0,8-0,9 detik (Portofolio, Transportasi, Perencanaan Produksi)
Contoh Minimax: 0,3-0,5 detik (Penyelesaian permainan, Optimasi robust)
Contoh SciPy: 0,5-1,2 detik (Optimasi nonlinear, Pencocokan statistik)
Masalah Klasik: 0,1-0,3 detik (24-angka, Ayam-kelinci, Sudoku mini)
Sudoku: <0,1 detik untuk teka-teki standar 9×9
N-Ratu Besar: ~2-3 detik untuk N=100

Pemecahan Masalah

Kesalahan Umum

"gurddy package not available": Instal dengan python -m mcp_server.server install
"No solution found": Tidak ada solusi di bawah kendala yang diberikan; coba relaksasi kendala
"Invalid input types": Periksa tipe data parameter input
"Unknown example": Gunakan python -m mcp_server.server run-example --help untuk melihat contoh yang tersedia

Masalah Instalasi

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

Debugging Contoh

Jalankan contoh secara langsung untuk debugging:

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

Persyaratan Integrasi SciPy

Contoh integrasi SciPy memerlukan dependensi tambahan:

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

Contoh SciPy Meliputi:

Optimasi Portofolio Nonlinear: Model risiko kuadratik dengan maksimisasi rasio Sharpe
Estimasi Parameter Statistik: Pencocokan distribusi dengan metode MLE dan kuantil
Pemrosesan Sinyal: Desain filter FIR dengan optimasi respons frekuensi
CSP-SciPy Hibrida: Lokasi fasilitas yang menggabungkan optimasi diskrit dan kontinu
Integrasi Numerik: Masalah optimasi kompleks yang melibatkan integral

Pengembangan

Arsitektur

Proyek ini menggunakan registri alat terpusat dengan skema yang dihasilkan otomatis untuk memastikan konsistensi antara server stdio dan HTTP:

Definisi Alat: mcp_server/tool_definitions.py (hanya metadata dasar)
Registri yang Dihasilkan Otomatis: mcp_server/tool_registry.py (skema dihasilkan dari tanda tangan fungsi)
Server Stdio: mcp_server/mcp_stdio_server.py (untuk integrasi IDE)
Server HTTP: mcp_server/mcp_http_server.py (untuk klien web)
Handler: mcp_server/handlers/gurddy.py (implementasi alat)
Generator Skema: scripts/generate_registry.py (menghasilkan skema otomatis dari tanda tangan fungsi)

Menambahkan Alat Baru

Implementasikan handler di 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"}

Tambahkan metadata dasar di 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"
}

Hasilkan skema dan verifikasi:

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

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

Itu saja! Skema secara otomatis dihasilkan dari petunjuk tipe fungsi Anda, dan server stdio dan HTTP akan mengambil alat baru tersebut.

Kendala Kustom

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

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

Pengujian

# 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

Lisensi

Proyek ini dilisensikan di bawah lisensi sumber terbuka. Silakan lihat file LICENSE untuk detailnya.