Gurddy

Gurddy MCP 服务

这是一款功能全面的模型上下文协议（MCP）服务，可用于求解约束满足问题（CSP）、线性规划（LP）、极小极大优化以及由 SciPy 驱动的高级优化问题。它基于 gurddy 优化库并集成 SciPy，支持通过两种 MCP 传输方式求解各种经典问题：stdio（用于 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 协议支持

• Stdio 传输：本地 IDE 集成（Kiro、Claude Desktop、Cline 等）
• 可流式 HTTP 传输：Web 客户端和远程访问，支持可选的流式传输
• 统一接口：两种传输方式使用相同的工具
• 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 等）
Streamable 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 示例 ✅

• minimax - 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+）
• 图着色：任意图的顶点着色（三角形、彼得森图、轮图等）
• 地图着色：地理区域着色（澳大利亚、美国、欧洲地图）
• 数独：使用约束传播求解标准 9×9 数独谜题
• 逻辑谜题：爱因斯坦斑马谜题及自定义逻辑推理问题
• 调度：课程调度、会议室、带时间约束的资源分配

📈 优化问题

• 线性规划：带线性约束的连续变量优化
• 整数规划：离散变量优化（生产数量、任务分配）
• 混合整数规划：连续变量与离散变量的组合
• 生产计划：受资源约束的多产品优化
• 投资组合优化：带风险和收益约束的投资分配
• 运输：供应链优化（从仓库到客户）

🎲 博弈论与稳健优化

• 零和博弈：石头剪刀布、猜正反面、性别之战
• 混合策略纳什均衡：双方的最优概率策略
• Minimax 决策：在不确定性情景下最小化最坏情况损失
• Maximin 决策：最大化最坏情况收益（保守策略）
• 稳健投资组合：在各种市场情景下最小化最大损失
• 安全博弈：防御者-攻击者资源分配问题

🔬 由 SciPy 驱动的高级优化

• 非线性投资组合优化：使用二次风险模型最大化夏普比率
• 统计参数估计：带约束的 MLE 和基于分位数的分布拟合
• 信号处理：通过频率响应优化设计 FIR 滤波器
• 混合优化：结合 Gurddy CSP 与 SciPy 连续优化
• 数值积分：涉及复杂数学函数的优化问题

🧮 经典教育类问题

• 24 点游戏：使用四个数字构造算术表达式，得出 24
• 鸡兔同笼问题：经典的头脚约束满足问题
• 迷你数独：使用 CSP 技术求解 4×4 数独
• N 皇后变体：经典问题的教育版本
• 背包问题：带重量和价值约束的 0-1 背包优化

性能特性

• 快速求解：中小型问题可在毫秒级响应（N-Queens N≤12，图的顶点数 <50）
• 可扩展：可处理大型问题（N-Queens N=100+，包含 1000+ 个变量的 LP）
• 节省内存：回溯搜索和约束传播可最大限度地减少内存使用
• 可扩展：支持自定义约束、目标函数和问题类型
• 并发安全：HTTP API 支持并发处理请求
• 可用于生产环境：支持 Docker 部署、运行状况检查和错误处理

性能基准

标准硬件上的典型执行时间：

• CSP 示例：0.4-0.5s（N-Queens、图着色、逻辑谜题）
• LP 示例：0.8-0.9s（投资组合、运输、生产规划）
• Minimax 示例：0.3-0.5s（游戏求解、鲁棒优化）
• SciPy 示例：0.5-1.2s（非线性优化、统计拟合）
• 经典问题：0.1-0.3s（24 点、鸡兔同笼、迷你数独）
• 数独：标准 9×9 谜题耗时 <0.1s
• 大型 N-Queens：N=100 时约需 2-3s

故障排除

常见错误

• "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 示例包括：

• 非线性投资组合优化：使用夏普比率最大化的二次风险模型
• 统计参数估计：使用 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（用于 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]:
       """Tool implementation with proper type hints."""
       return {"result": "success"}
   

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

3. 生成架构并验证：

   # 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 文件。