gurddy mcp Server

官方

该仓库包含一个功能完整的MCP（模型上下文协议）服务器，提供约束满足问题（CSP）和线性规划（LP）的解决方案。它基于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 优化的二次风险模型
统计参数估计：带约束的分布拟合（MLE、分位数匹配）
信号处理优化：具有频率响应优化的 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 等）
可流式传输的 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 进行高级优化：
- 带二次风险模型的非线性投资组合优化
- 统计参数估计（带约束的分布拟合）
- 信号处理优化（FIR 滤波器设计）
- 混合 CSP-SciPy 设施选址（离散 + 连续优化）
- 优化目标中的数值积分

经典数学问题 ✅

classic_problems - 教育性数学问题求解：
- 24 点游戏（通过算术表达式得到 24）
- 鸡兔同笼问题（经典约束满足）
- 4×4 迷你数独（简化的 CSP 演示）
- 4 皇后问题（教育性 N 皇后变体）
- 0-1 背包问题（经典优化）

支持的问题类型

🧩 CSP 问题

N 皇后：适用于任意棋盘大小的经典 N 皇后问题（N=4 到 N=100+）
图着色：任意图的顶点着色（三角形图、彼得森图、轮图等）
地图着色：地理区域着色（澳大利亚、美国、欧洲地图）
数独：带约束传播的标准 9×9 数独谜题
逻辑谜题：爱因斯坦斑马谜题和自定义逻辑推理问题
调度：课程调度、会议室、带时间约束的资源分配

📈 优化问题

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

🎲 博弈论与鲁棒优化

零和博弈：石头剪刀布、硬币配对、性别战
混合策略纳什均衡：双方的最优概率策略
极小化极大决策：在不确定性情景下最小化最坏情况损失
极大化极小决策：最大化最坏情况收益（保守策略）
鲁棒投资组合：在市场情景下最小化最大损失
安全博弈：防御者-攻击者资源分配问题

🔬 SciPy 驱动的高级优化

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

🧮 经典教育问题

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

性能特性

快速求解：中小规模问题的毫秒级响应（N 皇后 N≤12，顶点数 <50 的图）
可扩展：处理大规模问题（N 皇后 N=100+，1000+ 变量的线性规划）
内存高效：回溯搜索和约束传播最小化内存使用
可扩展：自定义约束、目标函数和问题类型
并发安全：HTTP API 支持并发请求处理
生产就绪：Docker 部署、健康检查、错误处理

性能基准

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

CSP 示例：0.4-0.5 秒（N 皇后、图着色、逻辑谜题）
线性规划示例：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 秒

故障排除

常见错误

"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（从函数签名自动生成模式）

添加新工具

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