Gurddy MCP 服务器

](https://pypi.org/project/gurddy_mcp/) ![Python Support](https://pypi.org/project/gurddy_mcp/) ![License: MIT](https://opensource.org/licenses/MIT) ![Live Demo](https://gurddy-mcp.fly.dev)

一个全面的模型上下文协议（MCP）服务器，用于解决约束满足问题（CSP）、线性规划（LP）、极小化极大化优化问题，以及基于SciPy的高级优化问题。该服务器构建于……（此处根据上下文补充具体内容，如“构建于Python框架之上”或“构建于分布式计算环境中”等） gurddy 这是一个集成了SciPy的优化库，它通过两种MCP传输方式支持解决各种经典问题：stdio（用于集成开发环境）和流式HTTP（用于网页客户端）。

🚀 快速入门（标准控制台）： pip install gurddy_mcp 然后在你的集成开发环境（IDE）中进行配置

🌐 快速启动（HTTP）： docker run -p 8080:8080 gurddy-mcp 或者参阅部署指南

📦 PyPI 包： https://pypi.org/project/gurddy_mcp 翻译为中文是：“https://pypi.org 上的 gurddy_mcp 项目”

主要功能

🎯 解决约束满足问题（CSP）

N皇后问题在一个N×N的棋盘上放置N个皇后，使它们互不攻击
图着色为顶点分配颜色，使得相邻顶点颜色不同
地图着色为地理区域着色，相邻区域颜色不同
数独求解器解决标准的9×9数独谜题
逻辑谜题爱因斯坦的斑马谜题和自定义逻辑问题
调度安排课程安排、会议安排、资源分配
通用约束满足问题（CSP）求解器支持自定义约束满足问题

📊 线性规划/优化问题

线性规划带线性约束的连续变量优化
混合整数规划包含整数和连续变量的优化
生产计划资源受限下的生产优化与敏感性分析
投资组合优化风险约束下的投资配置
交通问题供应链与物流优化

🎮 极小化极大算法/博弈论

零和博弈解决两人博弈（石头剪刀布、匹配硬币、性别之战）
混合策略纳什均衡寻找最优的概率策略
鲁棒优化在不确定性下最小化最坏情况损失
最大化最小化决策最大化最坏情况收益（保守策略）
安全游戏防御者-攻击者资源分配
稳健的投资组合在各种市场情境下最小化最大损失
生产计划保守的生产决策（最大化最低利润）
广告竞争市场份额博弈与竞争策略

🔬 SciPy 集成

非线性投资组合优化使用SciPy优化的二次风险模型
统计参数估计带约束条件的分布拟合（最大似然估计，分位数匹配）
信号处理优化具有频率响应优化的FIR滤波器设计
混合CSP-SciPy离散设施选址 + 连续产能优化
数值积分涉及积分和复函数的优化问题

🧮 经典数学问题

24点游戏用四个数字找到算术表达式以达到24
鸡兔同笼问题经典的头和腿数量限制问题
迷你数独使用CSP技术的4×4数独求解器
四皇后问题简化版N皇后问题（用于教育目的）
0-1背包问题带有重量和价值约束的经典优化问题

🔌 MCP协议支持

Stdio 传输（或：标准I/O传输）本地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 Studio 服务器（主要接口）

主要的 gurddy-mcp \command\ 是一个 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=="],
      "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：使用直接命令（安装后）

如果你已经安装了 gurddy-mcp 通过 pip：

{
  "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 - 获取守护MCP服务器的信息和功能
install - 安装或升级 gurddy 包
run_example - 运行示例程序（n皇后问题、图着色、极小化极大算法、scipy优化、经典问题等）
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 ` 或者 `python -m mcp_server.server run-example `:

### CSP 示例 ✅

- **n皇后问题** - N皇后问题（4皇后、6皇后、8皇后问题，带可视化棋盘显示）
- **图着色** - 图着色（三角形图、四边形图、彼得森图、轮图）
- **地图着色** - 地图着色（澳大利亚、美国西部州、欧洲）
- **调度安排** - 调度问题（课程调度、会议调度、资源分配）
- **逻辑谜题** - 逻辑谜题（简单逻辑谜题，爱因斯坦的斑马谜题）
- **优化后的CSP（约束满足问题）** - 高级约束满足问题（CSP）技术（数独求解器）

### LP 示例 ✅

- **lp** / **优化后的线性规划（或：经过优化的线性规划模型）** - 线性规划示例：
  - 带风险约束的投资组合优化
  - 运输问题（供应链优化）
  - 约束松弛分析
  - 不同问题规模下的性能对比

### 最小最大值示例 ✅

- **“minimax”翻译成中文是“最小最大”（算法或策略）。这个术语通常用于博弈论、决策理论或优化问题中，表示在最坏的情况下寻求最优解的策略或方法** - 最小化最大损失优化与博弈论：
  - 石头剪刀布（零和游戏）
  - “Matching Pennies”（协调博弈）
  - 性别之战（混合策略均衡）
  - 稳健的投资组合优化（最小化最大损失）
  - 生产计划（最大化最小利润）
  - 安全资源分配（防御者-攻击者博弈）
  - 广告竞争（市场份额游戏）

### SciPy 积分示例 ✅

- **scipy优化（或：使用scipy进行优化）** - 使用SciPy进行高级优化：
  - 基于二次风险模型的非线性投资组合优化
  - 统计参数估计（带约束的分布拟合）
  - 信号处理优化（FIR滤波器设计）
  - 混合CSP-SciPy设施选址（离散+连续优化）
  - 优化目标中的数值积分

### 经典数学问题 ✅

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

### 支持的问题类型

#### 🧩 CSP（约束满足问题）问题

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

#### 📈 优化问题

- **线性规划**具有线性约束的连续变量优化
- **整数规划**离散变量优化（生产数量、分配任务）
- **混合整数规划**连续变量与离散变量的结合
- **生产计划**多产品资源受限优化
- **投资组合优化**在风险和回报约束下的投资分配
- **交通**供应链优化（从仓库到客户）

#### 🎲 博弈论与鲁棒优化

- **零和博弈**石头剪刀布，猜硬币游戏，性别之战（或译为“协调博弈”）
- **混合策略纳什均衡**双方玩家的最优概率策略
- **最小最大决策**在不确定性情景下最小化最坏情况损失
- **最大化最小化决策（或译为：最坏情况下的最优决策）**最大化最坏情况下的收益（保守策略）
- **稳健的投资组合**在各种市场情境下最小化最大损失
- **安全游戏**防御者-攻击者资源分配问题

#### 🔬 基于SciPy的强大优化功能

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

#### 🧮 经典教育问题

- **24点游戏**用四个数字找到算术表达式，使其结果为24
- **鸡兔同笼问题**经典的头和腿数量约束满足问题
- **迷你数独**使用约束满足问题（CSP）技术解决4×4数独
- **N皇后问题变体**经典问题的教育版
- **背包问题**带重量和价值约束的0-1背包优化问题

## 性能特性

- **快速解决方案**中小规模问题（N皇后问题N≤12，图中顶点数\=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 （适用于网页客户端）
处理程序： 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

就是这么简单！模式会根据您函数的类型提示自动生成，而且标准输入输出服务器和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文件。

Gurddy MCP Server

快速接入

详细介绍