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