Gurddy MCP

🚀 Gurddy MCP Server

Gurddy MCP Server 是一個全面的模型上下文協議（MCP）服務器，可用於解決約束滿足問題（CSP）、線性規劃（LP）、極小極大優化以及由 SciPy 驅動的高級優化問題。它基於 gurddy 優化庫構建，並集成了 SciPy，支持通過兩種 MCP 傳輸方式解決各種經典問題：標準輸入輸出（用於 IDE 集成）和可流式傳輸的 HTTP（用於 Web 客戶端）。

🚀 快速開始

• 🚀 標準輸入輸出方式（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 協議支持

• 標準輸入輸出傳輸：支持本地 IDE 集成（如 Kiro、Claude Desktop、Cline 等）。
• 可流式傳輸的 HTTP 傳輸：支持 Web 客戶端和遠程訪問，可選流式傳輸。
• 統一接口：兩種傳輸方式使用相同的工具。
• JSON - RPC 2.0：完全符合協議規範。
• 自動批准：配置受信任的工具以實現無縫執行。

📦 安裝指南

從 PyPI 安裝（推薦）

# 安裝最新穩定版本
pip install gurddy_mcp

# 或者安裝帶有開發依賴的版本
pip install gurddy_mcp[dev]

從源代碼安裝

# 克隆倉庫
git clone https://github.com/novvoo/gurddy-mcp.git
cd gurddy-mcp

# 以開發模式安裝
pip install -e .

驗證安裝

# 測試 MCP 標準輸入輸出服務器
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | gurddy-mcp

💻 使用示例

1. MCP 標準輸入輸出服務器（主要接口）

主命令 gurddy-mcp 是一個 MCP 標準輸入輸出服務器，可與 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

# 或者使用 pip 安裝
pip install uv

# 或者使用 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 服務器：

# 測試初始化
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | gurddy-mcp

# 測試列出工具
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | gurddy-mcp

# 測試信息工具
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"info","arguments":{"":""}}}' | gurddy-mcp |jq 

# 測試運行示例工具
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"run_example","arguments":{"example":"n_queens"}}}' | gurddy-mcp |jq

# 測試數獨工具
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：

# 構建鏡像
docker build -t gurddy-mcp .

# 運行容器
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 傳輸（非流式）：

# 列出可用工具
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":{}}'

# 調用工具
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 頭進行流式傳輸）：

# 流式響應列出工具
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":{}}'

# 流式響應調用工具
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 頭進行流式傳輸）：

# 啟用流式傳輸的另一種方式
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"
  }
}

將統計分佈（如“正態分佈”、“指數分佈”、“均勻分佈”）擬合到數據中，並提供擬合優度測試。

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 部署

構建和運行

# 構建鏡像
docker build -t gurddy-mcp .

# 運行容器
docker run -p 8080:8080 gurddy-mcp

# 或者設置環境變量運行
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           # 核心求解器實現（16 個 MCP 工具）
│                          # - solve_24_point_game, solve_chicken_rabbit_problem
│                          # - solve_scipy_portfolio_optimization, solve_scipy_statistical_fitting
│                          # - solve_scipy_facility_location, 以及其他 11 個求解器
├── tools/                  # MCP 工具包裝器
├── examples/               # 豐富的問題示例
│   ├── n_queens.py         # N 皇后問題
│   ├── graph_coloring.py   # 圖著色問題
│   ├── map_coloring.py     # 地圖著色問題
│   ├── logic_puzzles.py    # 邏輯謎題
│   ├── scheduling.py       # 調度問題
│   ├── scipy_optimization.py # SciPy 集成示例
│   │                      # - 投資組合優化、統計擬合、設施選址
│   ├── classic_problems.py # 經典數學問題
│   │                      # - 24 點遊戲、雞兔同籠問題、迷你數獨
│   ├── optimized_csp.py    # 高級 CSP 技術
│   ├── optimized_lp.py     # 線性規劃示例
│   └── minimax.py          # 博弈論和魯棒優化
├── mcp_stdio_server.py     # MCP 標準輸入輸出服務器（用於 IDE 集成）
└── mcp_http_server.py      # MCP HTTP 服務器（用於 Web 客戶端）

examples/
└── http_mcp_client.py      # 示例 HTTP MCP 客戶端

Dockerfile                  # HTTP 服務器的 Docker 配置

MCP 傳輸方式

傳輸方式	命令	協議	使用場景
標準輸入輸出	gurddy-mcp	通過標準輸入輸出運行 MCP	IDE 集成（如 Kiro、Claude Desktop 等）
可流式傳輸的 HTTP	uvicorn mcp_server.mcp_http_server:app	通過 HTTP 運行 MCP，可選流式傳輸	Web 客戶端、遠程訪問、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 進行高級優化：
  • 帶有二次風險模型的非線性投資組合優化
  • 統計參數估計（在約束條件下進行分佈擬合）
  • 信號處理優化（有限脈衝響應濾波器設計）
  • 混合 CSP - SciPy 設施選址（離散 + 連續優化）
  • 優化目標中的數值積分

經典數學問題 ✅

• classic_problems - 教育性數學問題求解：
  • 24 點遊戲（通過算術表達式得到 24）
  • 雞兔同籠問題（經典約束滿足問題）
  • 4×4 迷你數獨（簡化 CSP 演示）
  • 4 皇后問題（教育性 N 皇后變體）
  • 0 - 1 揹包問題（經典優化問題）

支持的問題類型

🧩 CSP 問題

• N 皇后問題：任意棋盤大小的經典 N 皇后問題（N = 4 到 N = 100+）
• 圖著色問題：任意圖的頂點著色（三角形、彼得森圖、輪圖等）
• 地圖著色問題：地理區域著色（澳大利亞、美國、歐洲地圖）
• 數獨問題：標準 9×9 數獨謎題，使用約束傳播方法。
• 邏輯謎題：愛因斯坦的斑馬謎題和自定義邏輯推理問題。
• 調度問題：課程調度、會議室安排、資源分配，帶有時間約束。

📈 優化問題

• 線性規劃：在線性約束條件下對連續變量進行優化。
• 整數規劃：對離散變量進行優化（生產數量、分配等）。
• 混合整數規劃：結合連續和離散變量的優化。
• 生產計劃：多產品資源約束下的生產優化。
• 投資組合優化：在風險和回報約束下進行投資分配。
• 運輸問題：供應鏈優化（倉庫到客戶）。

🎲 博弈論與魯棒優化

• 零和博弈：石頭剪刀布、猜硬幣、性別之戰。
• 混合策略納什均衡：為雙方玩家找到最優概率策略。
• 極小極大決策：在不確定性場景下最小化最壞情況損失。
• 極大極小決策：最大化最壞情況收益（保守策略）。
• 魯棒投資組合：在不同市場情景下最小化最大損失。
• 安全博弈：防禦者 - 攻擊者資源分配問題。

🔬 SciPy 驅動的高級優化

• 非線性投資組合優化：使用夏普比率最大化的二次風險模型。
• 統計參數估計：使用最大似然估計和分位數方法進行分佈擬合。
• 信號處理：優化有限脈衝響應濾波器設計。
• 混合優化：將 Gurddy CSP 與 SciPy 連續優化相結合。
• 數值積分：涉及複雜數學函數的優化問題。

🧮 經典教育問題

• 24 點遊戲：使用四個數字通過算術運算得到 24。
• 雞兔同籠問題：經典的約束滿足問題。
• 迷你數獨：使用 CSP 技術解決 4×4 數獨。
• N 皇后變體：教育性的 N 皇后問題變體。
• 揹包問題：經典的 0 - 1 揹包優化問題。

性能特性

• 快速求解：對於中小規模問題（N 皇后問題 N≤12、圖頂點數少於 50），響應時間在毫秒級。
• 可擴展性：能夠處理大規模問題（N 皇后問題 N = 100+、線性規劃問題變量數超過 1000）。
• 內存高效：回溯搜索和約束傳播算法最小化內存使用。
• 可擴展性：支持自定義約束、目標函數和問題類型。
• 併發安全：HTTP API 支持併發請求處理。
• 生產就緒：支持 Docker 部署、健康檢查和錯誤處理。

性能基準

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

• CSP 示例：0.4 - 0.5 秒（N 皇后問題、圖著色問題、邏輯謎題）
• LP 示例：0.8 - 0.9 秒（投資組合、運輸、生產計劃）
• 極小極大示例：0.3 - 0.5 秒（遊戲求解、魯棒優化）
• SciPy 示例：0.5 - 1.2 秒（非線性優化、統計擬合）
• 經典問題：0.1 - 0.3 秒（24 點遊戲、雞兔同籠問題、迷你數獨）
• 數獨：標準 9×9 謎題小於 0.1 秒
• 大 N 皇后問題：N = 100 時約 2 - 3 秒

🔧 技術細節

架構

項目使用集中式工具註冊表和自動生成的模式，以確保標準輸入輸出服務器和 HTTP 服務器之間的一致性：

• 工具定義：mcp_server/tool_definitions.py（僅包含基本元數據）
• 自動生成的註冊表：mcp_server/tool_registry.py（根據函數簽名生成模式）
• 標準輸入輸出服務器：mcp_server/mcp_stdio_server.py（用於 IDE 集成）
• HTTP 服務器：mcp_server/mcp_http_server.py（用於 Web 客戶端）
• 處理程序：mcp_server/handlers/gurddy.py（工具實現）
• 模式生成器：scripts/generate_registry.py（根據函數簽名自動生成模式）

添加新工具

1. 在 mcp_server/handlers/gurddy.py 中實現處理程序：

   def my_new_tool(param1: str, param2: int = 10) -> Dict[str, Any]:
       """工具實現，帶有正確的類型提示。"""
       return {"result": "success"}
   

2. 在 mcp_server/tool_definitions.py 中添加基本元數據：

   {
       "name": "my_new_tool",
       "function": "my_new_tool",
       "description": "工具功能描述",
       "category": "optimization",
       "module": "handlers.gurddy"
   }
   

3. 生成模式並驗證：

   # 根據函數簽名自動生成模式
   python scripts/generate_registry.py
   
   # 驗證一致性
   python scripts/verify_consistency.py
   pytest tests/test_consistency.py -v
   

這樣就完成了！模式會根據你的函數類型提示自動生成，標準輸入輸出服務器和 HTTP 服務器都會識別新工具。

自定義約束

# 在 gurddy 中定義自定義約束
def custom_constraint(var1, var2):
    return var1 + var2 <= 10

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

測試

# 運行所有測試
pytest

# 運行特定測試套件
pytest tests/test_consistency.py -v
pytest tests/test_tool_registry.py -v

# 驗證工具註冊表的一致性
python scripts/verify_consistency.py

📄 許可證

本項目採用開源許可證。詳情請參閱 LICENSE 文件。