gurddy mcp Server

官方

此儲存庫包含一個功能完整的 MCP（模型上下文協定）伺服器，提供約束滿足問題（CSP）與線性規劃（LP）的解決方案。它基於 gurddy 套件，支援解決多種經典問題。

文件

Gurddy MCP 伺服器

一個全面的模型上下文協定 (MCP) 伺服器，用於解決約束滿足問題 (CSP)、線性規劃 (LP)、極小化極大 (Minimax) 最佳化，以及由 SciPy 驅動的進階最佳化問題。基於 gurddy 最佳化函式庫並整合 SciPy，它支援透過兩種 MCP 傳輸方式解決各種經典問題：stdio（用於 IDE 整合）和可串流的 HTTP（用於網頁客戶端）。

🚀 快速入門 (Stdio)： pip install gurddy_mcp 然後在您的 IDE 中設定

🌐 快速入門 (HTTP)： docker run -p 8080:8080 gurddy-mcp 或查看部署指南

📦 PyPI 套件： https://pypi.org/project/gurddy_mcp

主要功能

🎯 CSP 問題解決

N 皇后問題：在 N×N 的棋盤上放置 N 個皇后，使其互不攻擊
圖形著色：為頂點分配顏色，使相鄰頂點顏色不同
地圖著色：為地理區域著色，使相鄰區域顏色不同
數獨求解器：解決標準的 9×9 數獨謎題
邏輯謎題：愛因斯坦斑馬謎題和自訂邏輯問題
排程：課程排程、會議排程、資源分配
通用 CSP 求解器：支援自訂的約束滿足問題

📊 LP/最佳化問題

線性規劃：具有線性約束的連續變數最佳化
混合整數規劃：具有整數和連續變數的最佳化
生產規劃：資源受限的生產最佳化，附帶敏感性分析
投資組合最佳化：風險約束下的投資配置
運輸問題：供應鏈和物流最佳化

🎮 極小化極大/賽局理論

零和賽局：解決雙人賽局（剪刀石頭布、配對硬幣、性別之戰）
混合策略納許均衡：找出最佳機率策略
穩健最佳化：在不確定性下最小化最壞情況損失
極大化極小決策：最大化最壞情況收益（保守策略）
安全賽局：防守者-攻擊者資源分配
穩健投資組合：最小化跨市場情境的最大損失
生產規劃：保守的生產決策（最大化最小利潤）
廣告競爭：市場份額賽局和競爭策略

🔬 SciPy 整合

非線性投資組合最佳化：使用 SciPy 最佳化的二次風險模型
統計參數估計：帶約束的分配擬合（最大概似估計、分位數匹配）
訊號處理最佳化：具有頻率響應最佳化的 FIR 濾波器設計
混合 CSP-SciPy：離散設施選擇 + 連續容量最佳化
數值積分：涉及積分和複雜函數的最佳化問題

🧮 經典數學問題

24 點遊戲：使用四個數字找出算術表達式以達到 24
雞兔同籠問題：具有頭和腳約束的經典約束問題
迷你數獨：使用 CSP 技術的 4×4 數獨求解器
4 皇后問題：用於教育目的的簡化 N 皇后問題
0-1 背包問題：具有重量和價值約束的經典最佳化問題

🔌 MCP 協定支援

Stdio 傳輸：本地 IDE 整合（Kiro、Claude Desktop、Cline 等）
可串流 HTTP 傳輸：網頁客戶端和遠端存取，可選串流
統一介面：兩種傳輸方式使用相同的工具
JSON-RPC 2.0：完整的協定遵循
自動核准：設定受信任的工具以實現無縫執行

安裝

從 PyPI 安裝（建議）

# Install the latest stable version
pip install gurddy_mcp

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

從原始碼安裝

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

# Install in development mode
pip install -e .

驗證安裝

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

使用方式

1. MCP Stdio 伺服器（主要介面）

主要的 gurddy-mcp 指令是一個 MCP stdio 伺服器，可以與 Kiro 等工具整合。

選項 A：使用 uvx（建議 - 永遠使用最新版本）

使用 uvx 可確保您始終執行最新發布的版本，無需手動安裝。

在 ~/.kiro/settings/mcp.json 或 .kiro/settings/mcp.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"
      ]
    }
  }
}

替代方案：不指定版本（同樣使用最新版）

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

鎖定特定版本（如有需要）

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

為什麼使用 uvx？

✅ 始終自動執行最新發布的版本
✅ 無需手動安裝或升級
✅ 每次執行都有隔離的環境
✅ 不會與您系統的 Python 產生依賴衝突

先決條件： 先安裝 uv：

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

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

選項 B：使用直接指令（安裝後）

如果您已經透過 pip 安裝了 gurddy-mcp：

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

可用的 MCP 工具（共 16 個）：

info - 取得 gurddy MCP 伺服器資訊和功能
install - 安裝或升級 gurddy 套件
run_example - 執行範例程式（n_queens、graph_coloring、minimax、scipy_optimization、classic_problems 等）
solve_n_queens - 解決任意棋盤大小的 N 皇后問題
solve_sudoku - 使用 CSP 解決 9×9 數獨謎題
solve_graph_coloring - 使用可設定的顏色解決圖形著色問題
solve_map_coloring - 解決地圖著色問題（例如：澳洲、美國）
solve_lp - 解決線性規劃 (LP) 或混合整數規劃 (MIP)
solve_production_planning - 生產最佳化，附帶可選的敏感性分析
solve_minimax_game - 雙人零和賽局（找出納許均衡）
solve_minimax_decision - 穩健最佳化（最小化最大損失或最大化最小收益）
solve_24_point_game - 使用算術運算解決四個數字的 24 點遊戲
solve_chicken_rabbit_problem - 解決具有頭和腳約束的經典雞兔同籠問題
solve_scipy_portfolio_optimization - 使用 SciPy 解決非線性投資組合最佳化
solve_scipy_statistical_fitting - 使用 SciPy 解決統計參數估計
solve_scipy_facility_location - 使用混合 CSP-SciPy 方法解決設施選址問題

測試 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. MCP HTTP 伺服器

啟動 HTTP MCP 伺服器（透過可串流 HTTP 的 MCP 協定）：

本地開發：

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

存取伺服器：

根路徑：http://127.0.0.1:8080/
健康檢查：http://127.0.0.1:8080/health
HTTP 傳輸：http://127.0.0.1:8080/mcp/http（POST - 支援一般請求和串流）

測試 HTTP MCP 伺服器：

HTTP 傳輸（非串流）：

# 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 傳輸（使用 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}}}'

HTTP 傳輸（使用 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":{}}}'

Python 客戶端範例：

examples/streamable_http_client.py - 帶有串流範例的 HTTP 傳輸客戶端

MCP 工具

伺服器提供以下 MCP 工具：

info

取得 gurddy 套件的相關資訊。

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

install

安裝或升級 gurddy 套件。

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

run_example

執行 gurddy 範例。

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

可用的範例：lp、csp、n_queens、graph_coloring、map_coloring、scheduling、logic_puzzles、optimized_csp、optimized_lp、minimax、scipy_optimization、classic_problems

solve_n_queens

解決 N 皇后問題。

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

solve_sudoku

解決一個 9x9 的數獨謎題。

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

solve_graph_coloring

解決圖形著色問題。

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

solve_map_coloring

解決地圖著色問題。

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

solve_lp

使用 PuLP 解決線性規劃 (LP) 或混合整數規劃 (MIP) 問題。

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

解決生產規劃最佳化問題，附帶可選的敏感性分析。

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

使用極小化極大（賽局理論）解決雙人零和賽局。

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

回傳指定玩家的最佳混合策略和賽局價值。

solve_minimax_decision

解決不確定性下的極小化極大決策問題（穩健最佳化）。

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

目標：minimize_max_loss（穩健投資組合）或 maximize_min_gain（保守生產）

solve_24_point_game

使用算術運算解決四個數字的 24 點遊戲。

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

找出使用 +、-、*、/ 和括號以達到精確值 24 的算術表達式。

solve_chicken_rabbit_problem

解決具有頭和腳約束的經典雞兔同籠問題。

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

根據給定的總頭數和總腳數，確定雞（2 隻腳）和兔子（4 隻腳）的數量。

solve_scipy_portfolio_optimization

使用 SciPy 和二次風險模型解決非線性投資組合最佳化。

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

使用均值-變異數最佳化來最佳化投資組合權重，以最大化收益減去風險懲罰。

solve_scipy_statistical_fitting

使用 SciPy 和分配擬合解決統計參數估計。

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

將統計分配（"normal"、"exponential"、"uniform"）擬合到資料，並提供擬合優度檢定。

solve_scipy_facility_location

使用混合 CSP-SciPy 方法解決設施選址問題。

{
  "name": "solve_scipy_facility_location",
  "arguments": {
    "customer_locations": [[0, 0], [10, 10], [5, 15]],
    "customer_demands": [100, 150, 80],
    "facility_locations": [[2, 3], [8, 12], [6, 8]],
    "max_facilities": 2,
    "fixed_cost": 100.0
  }
}

結合離散設施選擇 (CSP) 和連續容量最佳化 (SciPy)，以最小化總成本。

Docker 部署

建置與執行

# 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

範例輸出

N 皇后問題

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

專案結構

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 傳輸方式

傳輸方式	指令	協定	使用案例
Stdio	`gurddy-mcp`	透過 stdin/stdout 的 MCP	IDE 整合（Kiro、Claude Desktop 等）
可串流 HTTP	`uvicorn mcp_server.mcp_http_server:app`	透過 HTTP 的 MCP，可選串流	網頁客戶端、遠端存取、Docker 部署

所有傳輸方式都實作相同的 MCP 協定，並提供相同的工具。

HTTP 傳輸功能

HTTP 傳輸（/mcp/http 端點）：

單一請求-回應模式
可選串流：新增 Accept: text/event-stream 或 X-Stream: true 標頭
對於一次性請求較為簡單
與標準 HTTP 客戶端相容
無需管理連線狀態
支援一般 JSON 回應和 SSE 格式的串流回應

範例輸出

N 皇后問題

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

邏輯謎題

$ 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 範例

經典問題解決

澳洲地圖著色

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 皇后問題

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

可用的範例

所有範例都可以使用 gurddy-mcp run-example <name> 或 python -m mcp_server.server run-example <name> 執行：

CSP 範例 ✅

n_queens - N 皇后問題（4、6、8 皇后，附帶視覺化棋盤顯示）
graph_coloring - 圖形著色（三角形、正方形、彼得森圖、輪圖）
map_coloring - 地圖著色（澳洲、美國西部各州、歐洲）
scheduling - 排程問題（課程排程、會議排程、資源分配）
logic_puzzles - 邏輯謎題（簡單邏輯謎題、愛因斯坦斑馬謎題）
optimized_csp - 進階 CSP 技術（數獨求解器）

LP 範例 ✅

lp / optimized_lp - 線性規劃範例：
- 帶有風險約束的投資組合最佳化
- 運輸問題（供應鏈最佳化）
- 約束放寬分析
- 跨問題規模的效能比較

極小化極大範例 ✅

minimax - 極小化極大最佳化和賽局理論：
- 剪刀石頭布（零和賽局）
- 配對硬幣（協調賽局）
- 性別之戰（混合策略均衡）
- 穩健投資組合最佳化（最小化最大損失）
- 生產規劃（最大化最小利潤）
- 安全資源分配（防守者-攻擊者賽局）
- 廣告競爭（市場份額賽局）

SciPy 整合範例 ✅

scipy_optimization - 使用 SciPy 進行進階最佳化：
- 具備二次風險模型的非線性投資組合最佳化
- 統計參數估計（含限制條件的分佈擬合）
- 訊號處理最佳化（FIR 濾波器設計）
- 混合 CSP-SciPy 設施選址（離散 + 連續最佳化）
- 最佳化目標中的數值積分

經典數學問題 ✅

classic_problems - 教育性數學問題求解：
- 24 點遊戲（算術表達式以達到 24）
- 雞兔同籠問題（經典限制滿足問題）
- 4×4 迷你數獨（簡化 CSP 示範）
- 4 皇后問題（教育性 N 皇后變體）
- 0-1 背包問題（經典最佳化）

支援的問題類型

🧩 CSP 問題

N 皇后：適用於任何棋盤大小的經典 N 皇后問題（N=4 至 N=100+）
圖形著色：任意圖形的頂點著色（三角形、Petersen、輪圖等）
地圖著色：地理區域著色（澳洲、美國、歐洲地圖）
數獨：具備限制傳播的標準 9×9 數獨謎題
邏輯謎題：愛因斯坦斑馬謎題及自訂邏輯推理問題
排程：課程排程、會議室、具時間限制的資源分配

📈 最佳化問題

線性規劃：具線性限制的連續變數最佳化
整數規劃：離散變數最佳化（生產數量、指派）
混合整數規劃：結合連續與離散變數
生產規劃：多產品資源限制最佳化
投資組合最佳化：具風險與回報限制的投資分配
運輸：供應鏈最佳化（倉庫到客戶）

🎲 賽局理論與穩健最佳化

零和賽局：剪刀石頭布、配對硬幣、性別之戰
混合策略納許均衡：雙方玩家的最佳機率策略
最小化最大損失決策：在不確定情境中最小化最壞情況損失
最大化最小收益決策：最大化最壞情況收益（保守策略）
穩健投資組合：在市場情境中最小化最大損失
安全賽局：防守者-攻擊者資源分配問題

🔬 SciPy 驅動的進階最佳化

非線性投資組合最佳化：具 Sharpe 比率最大化的二次風險模型
統計參數估計：具限制條件的 MLE 與基於分位數的分佈擬合
訊號處理：具頻率響應最佳化的 FIR 濾波器設計
混合最佳化：結合 Gurddy CSP 與 SciPy 連續最佳化
數值積分：涉及複雜數學函數的最佳化問題

🧮 經典教育問題

24 點遊戲：使用四個數字找出算術表達式以達到 24
雞兔同籠問題：經典的頭腳限制滿足問題
迷你數獨：使用 CSP 技術求解 4×4 數獨
N 皇后變體：經典問題的教育版本
背包問題：具重量與價值限制的 0-1 背包最佳化

效能特色

快速求解：中小型問題毫秒級回應（N 皇后 N≤12、少於 50 個頂點的圖形）
可擴展：處理大型問題（N 皇后 N=100+、具 1000+ 變數的 LP）
記憶體高效：回溯搜尋與限制傳播最小化記憶體使用
可擴充：自訂限制、目標函數與問題類型
並行安全：HTTP API 支援並行請求處理
生產就緒：Docker 部署、健康檢查、錯誤處理

效能基準

標準硬體上的典型執行時間：

CSP 範例：0.4-0.5 秒（N 皇后、圖形著色、邏輯謎題）
LP 範例：0.8-0.9 秒（投資組合、運輸、生產規劃）
Minimax 範例：0.3-0.5 秒（賽局求解、穩健最佳化）
SciPy 範例：0.5-1.2 秒（非線性最佳化、統計擬合）
經典問題：0.1-0.3 秒（24 點、雞兔同籠、迷你數獨）
數獨：標準 9×9 謎題 <0.1 秒
大型 N 皇后：N=100 時約 2-3 秒

疑難排解

常見錯誤

"gurddy package not available"：使用 python -m mcp_server.server install 安裝
"No solution found"：在給定限制下無解；嘗試放寬限制
"Invalid input types"：檢查輸入參數的資料型別
"Unknown example"：使用 python -m mcp_server.server run-example --help 查看可用範例

安裝問題

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

範例除錯

直接執行範例以進行除錯：

# 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 整合需求

SciPy 整合範例需要額外的相依套件：

# 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 範例包含：

非線性投資組合最佳化：具 Sharpe 比率最大化的二次風險模型
統計參數估計：使用 MLE 與分位數方法進行分佈擬合
訊號處理：具頻率響應最佳化的 FIR 濾波器設計
混合 CSP-SciPy：結合離散與連續最佳化的設施選址
數值積分：涉及積分的複雜最佳化問題

開發

架構

本專案使用集中式工具註冊表搭配自動生成的結構描述，以確保 stdio 與 HTTP 伺服器之間的一致性：

工具定義：mcp_server/tool_definitions.py（僅基本中繼資料）
自動生成註冊表：mcp_server/tool_registry.py（從函式簽章生成結構描述）
Stdio 伺服器：mcp_server/mcp_stdio_server.py（用於 IDE 整合）
HTTP 伺服器：mcp_server/mcp_http_server.py（用於網頁客戶端）
處理常式：mcp_server/handlers/gurddy.py（工具實作）
結構描述生成器：scripts/generate_registry.py（從函式簽章自動生成結構描述）

新增工具

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

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

生成結構描述並驗證：

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

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

就是這樣！結構描述會從函式的型別提示自動生成，且 stdio 與 HTTP 伺服器都會納入新工具。

自訂限制

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

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

測試

# 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 檔案。