Gurddy

Gurddy MCP Server

制約充足問題（CSP）、線形計画法（LP）、ミニマックス最適化、SciPy を活用した高度な最適化問題を解くための包括的な Model Context Protocol（MCP）サーバーです。SciPy と統合された最適化ライブラリ gurddy を基盤としており、2 種類の 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／最適化問題

• 線形計画法：線形制約下で連続変数を最適化します
• 混合整数計画法：整数変数と連続変数を組み合わせて最適化します
• 生産計画：感度分析を伴う、リソース制約下での生産最適化
• ポートフォリオ最適化：リスク制約下で投資を配分します
• 輸送問題：サプライチェーンと物流を最適化します

🎮 ミニマックス／ゲーム理論

• ゼロサムゲーム：2 人用ゲーム（じゃんけん、コイン合わせ、男女の争い）を解きます
• 混合戦略ナッシュ均衡：最適な確率的戦略を求めます
• ロバスト最適化：不確実性の下で最悪ケースの損失を最小化します
• マキシミン意思決定：最悪ケースの利得を最大化します（保守的な戦略）
• セキュリティゲーム：防御側と攻撃側のリソース配分
• ロバストポートフォリオ：市場シナリオ全体で最大損失を最小化します
• 生産計画：保守的な生産判断（最小利益を最大化）
• 広告競争：市場シェアゲームと競争戦略

🔬 SciPy 連携

• 非線形ポートフォリオ最適化：SciPy による最適化を用いた二次リスクモデル
• 統計的パラメーター推定：制約付き分布フィッティング（最尤推定、分位点マッチング）
• 信号処理の最適化：周波数応答の最適化を用いた FIR フィルター設計
• CSP と SciPy のハイブリッド：離散的な施設選択と連続的な容量最適化
• 数値積分：積分や複素関数を含む最適化問題

🧮 古典的な数学問題

• 24 ゲーム：4 つの数を使って 24 になる算術式を求めます
• 鶏とウサギの問題：頭数と脚数を扱う古典的な制約問題
• ミニ数独：CSP の手法を使った 4×4 数独ソルバー
• 4 クイーン問題：学習用に簡略化した N-クイーン問題
• 0-1 ナップサック問題：重量と価値の制約を扱う古典的な最適化問題

🔌 MCP プロトコルのサポート

• Stdio トランスポート：ローカル IDE との統合（Kiro、Claude Desktop、Cline など）
• Streamable 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 コマンドは、Kiro などのツールと統合できる MCP stdio サーバーです。

オプション 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：直接コマンドを使用する（インストール後）

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 - gurddy MCP サーバーの情報と機能を取得します
• install - gurddy パッケージをインストールまたはアップグレードします
• run_example - サンプルプログラムを実行します（n_queens、graph_coloring、minimax、scipy_optimization、classic_problems など）
• solve_n_queens - 任意の盤面サイズで N-Queens 問題を解きます
• solve_sudoku - CSP を使用して 9×9 の数独パズルを解きます
• solve_graph_coloring - 色数を設定してグラフ彩色問題を解きます
• solve_map_coloring - 地図彩色問題を解きます（例：オーストラリア、アメリカ）
• solve_lp - 線形計画法（LP）または混合整数計画法（MIP）を解きます
• solve_production_planning - 必要に応じて感度分析を行い、生産を最適化します
• solve_minimax_game - 2 人のプレイヤーによるゼロ和ゲームを解きます（ナッシュ均衡を求めます）
• solve_minimax_decision - ロバスト最適化を行います（最大損失の最小化、または最小利得の最大化）
• solve_24_point_game - 4 つの数と算術演算を使って 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-Queens 問題を解きます。

{
  "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

ミニマックス法（ゲーム理論）を使用して、2 人プレイヤーのゼロサムゲームを解きます。

{
  "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

4 つの数字を使い、算術演算で 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	標準入力／標準出力経由の 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 - ミニマックス最適化とゲーム理論：
  • じゃんけん（ゼロサムゲーム）
  • マッチングペニー（協調ゲーム）
  • 性別の戦い（混合戦略均衡）
  • ロバストなポートフォリオ最適化（最大損失を最小化）
  • 生産計画（最小利益を最大化）
  • セキュリティ資源の配分（防御側と攻撃側のゲーム）
  • 広告競争（市場シェアゲーム）

SciPy 統合の例 ✅

• scipy_optimization - SciPy による高度な最適化：
  • 二次リスクモデルを用いた非線形ポートフォリオ最適化
  • 統計的パラメーター推定（制約付き分布フィッティング）
  • 信号処理の最適化（FIR フィルター設計）
  • CSP と SciPy を組み合わせた施設配置（離散最適化と連続最適化）
  • 最適化目的関数における数値積分

古典的な数学問題 ✅

• classic_problems - 教育用の数学問題解決：
  • 24 ゲーム（算術式を使って 24 を作る）
  • 鶏とウサギの問題（古典的な制約充足問題）
  • 4×4 ミニ数独（簡略化された CSP のデモ）
  • 4 クイーン問題（N クイーン問題の教育用バリエーション）
  • 0-1 ナップサック問題（古典的な最適化問題）

対応する問題の種類

🧩 CSP 問題

• N-Queens：任意の盤面サイズ（N=4～N=100 以上）に対応する古典的な N クイーン問題
• Graph Coloring：任意のグラフ（三角形、ピーターセングラフ、ホイールグラフなど）の頂点彩色
• Map Coloring：地理的領域の彩色（オーストラリア、米国、ヨーロッパの地図）
• Sudoku：制約伝播に対応した標準的な 9×9 数独パズル
• Logic Puzzles：アインシュタインのシマウマパズルと、カスタムの論理推論問題
• Scheduling：時間制約のある授業スケジュール、会議室、リソースの割り当て

📈 最適化問題

• Linear Programming：線形制約による連続変数の最適化
• Integer Programming：離散変数の最適化（生産量、割り当て）
• Mixed Integer Programming：連続変数と離散変数の組み合わせ
• Production Planning：複数製品を対象とする、リソース制約付き最適化
• Portfolio Optimization：リスクとリターンの制約を考慮した投資配分
• Transportation：サプライチェーンの最適化（倉庫から顧客まで）

🎲 ゲーム理論とロバスト最適化

• Zero-Sum Games：じゃんけん、マッチングペニー、性別の戦い
• Mixed Strategy Nash Equilibria：両プレイヤーにとって最適な確率的戦略
• Minimax Decisions：不確実性のあるシナリオ全体で最悪の場合の損失を最小化
• Maximin Decisions：最悪の場合の利益を最大化（保守的な戦略）
• Robust Portfolio：市場シナリオ全体で最大損失を最小化
• Security Games：防御側と攻撃側の資源配分問題

🔬 SciPy を活用した高度な最適化

• Nonlinear Portfolio Optimization：シャープレシオの最大化を伴う二次リスクモデル
• Statistical Parameter Estimation：制約付きの MLE および分位点ベースの分布フィッティング
• Signal Processing：周波数応答の最適化を伴う FIR フィルター設計
• Hybrid Optimization：Gurddy CSP と SciPy による連続最適化の組み合わせ
• Numerical Integration：複雑な数学関数を含む最適化問題

🧮 古典的な教育用問題

• 24-Point Game：4 つの数を使った算術式で 24 を作る
• Chicken-Rabbit Problem：頭数と脚数を扱う古典的な制約充足問題
• Mini Sudoku：CSP 技法を用いた 4×4 数独の解法
• N-Queens Variants：古典的な問題の教育用バリエーション
• Knapsack Problems：重さと価値の制約を伴う 0-1 ナップサック最適化

パフォーマンス機能

• 高速な解決：小〜中規模の問題（N-Queens N≤12、頂点数50未満のグラフ）ではミリ秒単位で応答します
• スケーラブル：大規模な問題（N-Queens N=100以上、変数数1000以上のLP）に対応します
• メモリ効率：バックトラッキング検索と制約伝播により、メモリ使用量を最小限に抑えます
• 拡張可能：カスタム制約、目的関数、問題タイプに対応します
• 並行処理に安全：HTTP API は同時リクエストの処理に対応します
• 本番環境対応：Docker デプロイ、ヘルスチェック、エラー処理に対応します

パフォーマンスベンチマーク

標準的なハードウェアでの一般的な実行時間：

• CSP の例：0.4〜0.5 秒（N-Queens、グラフ彩色、論理パズル）
• LP の例：0.8〜0.9 秒（ポートフォリオ、輸送、生産計画）
• ミニマックスの例：0.3〜0.5 秒（ゲームの解決、ロバスト最適化）
• SciPy の例：0.5〜1.2 秒（非線形最適化、統計的フィッティング）
• 古典的な問題：0.1〜0.3 秒（24 点、鶏とうさぎ、ミニ数独）
• 数独：標準的な 9×9 パズルなら 0.1 秒未満
• 大規模な N-Queens：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（ウェブクライアント用）
• ハンドラー：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 ファイルを参照してください。