gurddy mcp Server

chính thức

Kho lưu trữ này chứa một máy chủ MCP (Model Context Protocol) hoàn chỉnh, cung cấp các giải pháp cho Bài toán Thỏa mãn Ràng buộc (CSP) và Quy hoạch Tuyến tính (LP). Nó dựa trên gói gurddy và hỗ trợ giải nhiều bài toán kinh điển khác nhau.

GitHub
2

Tài liệu

Máy chủ Gurddy MCP

PyPI version Python Support License: MIT Live Demo

Một máy chủ Giao thức Ngữ cảnh Mô hình (MCP) toàn diện để giải các Bài toán Thỏa mãn Ràng buộc (CSP), Quy hoạch Tuyến tính (LP), tối ưu Minimax và các bài toán tối ưu nâng cao sử dụng SciPy. Được xây dựng trên thư viện tối ưu gurddy với tích hợp SciPy, nó hỗ trợ giải nhiều bài toán kinh điển thông qua hai phương thức truyền tải MCP: stdio (cho tích hợp IDE) và HTTP có thể truyền phát (cho máy khách web).

🚀 Bắt đầu Nhanh (Stdio): pip install gurddy_mcp sau đó cấu hình trong IDE của bạn

🌐 Bắt đầu Nhanh (HTTP): docker run -p 8080:8080 gurddy-mcp hoặc xem hướng dẫn triển khai

📦 Gói PyPI: https://pypi.org/project/gurddy_mcp

Tính năng Chính

🎯 Giải Bài toán CSP

  • Bài toán N-Quân Hậu: Đặt N quân hậu lên bàn cờ N×N sao cho không quân nào tấn công nhau
  • Tô màu Đồ thị: Gán màu cho các đỉnh sao cho các đỉnh kề nhau có màu khác nhau
  • Tô màu Bản đồ: Tô màu các vùng địa lý sao cho các vùng liền kề khác màu
  • Giải Sudoku: Giải các câu đố Sudoku 9×9 tiêu chuẩn
  • Câu đố Logic: Câu đố Ngựa vằn của Einstein và các bài toán logic tùy chỉnh
  • Lập lịch: Lập lịch khóa học, lập lịch họp, phân bổ tài nguyên
  • Bộ giải CSP Tổng quát: Hỗ trợ các bài toán thỏa mãn ràng buộc tùy chỉnh

📊 Bài toán LP/Tối ưu

  • Quy hoạch Tuyến tính: Tối ưu biến liên tục với ràng buộc tuyến tính
  • Quy hoạch Nguyên Hỗn hợp: Tối ưu với biến nguyên và biến liên tục
  • Lập kế hoạch Sản xuất: Tối ưu sản xuất có ràng buộc tài nguyên với phân tích độ nhạy
  • Tối ưu Danh mục Đầu tư: Phân bổ đầu tư dưới ràng buộc rủi ro
  • Bài toán Vận tải: Tối ưu chuỗi cung ứng và hậu cần

🎮 Minimax/Lý thuyết Trò chơi

  • Trò chơi Tổng bằng Không: Giải trò chơi hai người (Oẳn tù tì, Đồng xu Ghép đôi, Cuộc chiến Giới tính)
  • Cân bằng Nash Chiến lược Hỗn hợp: Tìm chiến lược xác suất tối ưu
  • Tối ưu Bền vững: Tối thiểu hóa tổn thất trường hợp xấu nhất dưới sự không chắc chắn
  • Quyết định Maximin: Tối đa hóa lợi ích trường hợp xấu nhất (chiến lược bảo thủ)
  • Trò chơi An ninh: Phân bổ tài nguyên người phòng thủ - kẻ tấn công
  • Danh mục Bền vững: Tối thiểu hóa tổn thất tối đa qua các kịch bản thị trường
  • Lập kế hoạch Sản xuất: Quyết định sản xuất bảo thủ (tối đa hóa lợi nhuận tối thiểu)
  • Cạnh tranh Quảng cáo: Trò chơi thị phần và chiến lược cạnh tranh

🔬 Tích hợp SciPy

  • Tối ưu Danh mục Phi tuyến: Mô hình rủi ro bậc hai với tối ưu SciPy
  • Ước lượng Tham số Thống kê: Khớp phân phối với ràng buộc (MLE, khớp phân vị)
  • Tối ưu Xử lý Tín hiệu: Thiết kế bộ lọc FIR với tối ưu đáp ứng tần số
  • Kết hợp CSP-SciPy: Lựa chọn cơ sở rời rạc + tối ưu công suất liên tục
  • Tích phân Số: Các bài toán tối ưu liên quan đến tích phân và hàm phức tạp

🧮 Bài toán Toán Kinh điển

  • Trò chơi 24 Điểm: Tìm biểu thức số học để đạt 24 bằng bốn số
  • Bài toán Gà-Thỏ: Bài toán ràng buộc kinh điển với số đầu và số chân
  • Sudoku Nhỏ: Bộ giải Sudoku 4×4 sử dụng kỹ thuật CSP
  • Bài toán 4-Quân Hậu: N-Quân Hậu đơn giản hóa cho mục đích giáo dục
  • Ba lô 0-1: Bài toán tối ưu kinh điển với ràng buộc trọng lượng và giá trị

🔌 Hỗ trợ Giao thức MCP

  • Phương thức Stdio: Tích hợp IDE cục bộ (Kiro, Claude Desktop, Cline, v.v.)
  • Phương thức HTTP Có thể Truyền phát: Máy khách web và truy cập từ xa với truyền phát tùy chọn
  • Giao diện Thống nhất: Cùng các công cụ trên cả hai phương thức
  • JSON-RPC 2.0: Tuân thủ đầy đủ giao thức
  • Tự động Phê duyệt: Cấu hình các công cụ tin cậy để thực thi liền mạch

Cài đặt

Từ PyPI (Khuyến nghị)

# Install the latest stable version
pip install gurddy_mcp

# Or install with development dependencies
pip install gurddy_mcp[dev]

Từ Mã nguồn

# Clone the repository
git clone https://github.com/novvoo/gurddy-mcp.git
cd gurddy-mcp

# Install in development mode
pip install -e .

Xác minh Cài đặt

# Test MCP stdio server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | gurddy-mcp

Cách Sử dụng

1. Máy chủ MCP Stdio (Giao diện Chính)

Lệnh gurddy-mcp chính là một máy chủ MCP stdio có thể được tích hợp với các công cụ như Kiro.

Tùy chọn A: Sử dụng uvx (Khuyến nghị - Luôn là Phiên bản Mới nhất)

Sử dụng uvx đảm bảo bạn luôn chạy phiên bản mới nhất được xuất bản mà không cần cài đặt thủ công.

Cấu hình trong ~/.kiro/settings/mcp.json hoặc .kiro/settings/mcp.json:

Khuyến nghị: Phiên bản mới nhất rõ ràng

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

Thay thế: Không có chỉ định phiên bản (cũng sử dụng mới nhất)

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

Ghim vào phiên bản cụ thể (nếu cần)

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

Tại sao sử dụng uvx?

  • ✅ Luôn tự động chạy phiên bản mới nhất được xuất bản
  • ✅ Không cần cài đặt hoặc nâng cấp thủ công
  • ✅ Môi trường cô lập cho mỗi lần thực thi
  • ✅ Không xung đột phụ thuộc với Python hệ thống của bạn

Điều kiện tiên quyết: Cài đặt uv trước:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Or using Homebrew (macOS)
brew install uv

Tùy chọn B: Sử dụng Lệnh Trực tiếp (Sau khi Cài đặt)

Nếu bạn đã cài đặt gurddy-mcp qua 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"
      ]
    }
  }
}

Các công cụ MCP có sẵn (tổng cộng 16):

  • info - Nhận thông tin và khả năng của máy chủ gurddy MCP
  • install - Cài đặt hoặc nâng cấp gói gurddy
  • run_example - Chạy các chương trình ví dụ (n_queens, graph_coloring, minimax, scipy_optimization, classic_problems, v.v.)
  • solve_n_queens - Giải bài toán N-Quân Hậu cho mọi kích thước bàn cờ
  • solve_sudoku - Giải câu đố Sudoku 9×9 sử dụng CSP
  • solve_graph_coloring - Giải tô màu đồ thị với số màu có thể cấu hình
  • solve_map_coloring - Giải bài toán tô màu bản đồ (ví dụ: Úc, Hoa Kỳ)
  • solve_lp - Giải Quy hoạch Tuyến tính (LP) hoặc Quy hoạch Nguyên Hỗn hợp (MIP)
  • solve_production_planning - Tối ưu sản xuất với phân tích độ nhạy tùy chọn
  • solve_minimax_game - Trò chơi tổng bằng không hai người (tìm cân bằng Nash)
  • solve_minimax_decision - Tối ưu bền vững (tối thiểu hóa tổn thất tối đa hoặc tối đa hóa lợi ích tối thiểu)
  • solve_24_point_game - Giải trò chơi 24 điểm với bốn số sử dụng phép toán số học
  • solve_chicken_rabbit_problem - Giải bài toán gà-thỏ kinh điển với ràng buộc số đầu và số chân
  • solve_scipy_portfolio_optimization - Giải tối ưu danh mục phi tuyến sử dụng SciPy
  • solve_scipy_statistical_fitting - Giải ước lượng tham số thống kê sử dụng SciPy
  • solve_scipy_facility_location - Giải bài toán vị trí cơ sở sử dụng phương pháp kết hợp CSP-SciPy

Kiểm tra máy chủ 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. Máy chủ MCP HTTP

Khởi động máy chủ MCP HTTP (giao thức MCP qua HTTP có thể truyền phát):

Phát triển Cục bộ:

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

Truy cập máy chủ:

Kiểm tra máy chủ MCP HTTP:

Phương thức HTTP (không truyền phát):

# 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":{}}}'

Phương thức HTTP (truyền phát với tiêu đề 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}}}'

Phương thức HTTP (truyền phát với tiêu đề 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":{}}}'

Ví dụ Máy khách Python:

  • examples/streamable_http_client.py - Máy khách phương thức HTTP với ví dụ truyền phát

Công cụ MCP

Máy chủ cung cấp các công cụ MCP sau:

info

Nhận thông tin về gói gurddy.

{
  "name": "info",
  "arguments": {}
}

install

Cài đặt hoặc nâng cấp gói gurddy.

{
  "name": "install",
  "arguments": {
    "package": "gurddy",
    "upgrade": false
  }
}

run_example

Chạy một ví dụ gurddy.

{
  "name": "run_example",
  "arguments": {
    "example": "n_queens"
  }
}

Các ví dụ có sẵn: lp, csp, n_queens, graph_coloring, map_coloring, scheduling, logic_puzzles, optimized_csp, optimized_lp, minimax, scipy_optimization, classic_problems

solve_n_queens

Giải bài toán N-Quân Hậu.

{
  "name": "solve_n_queens",
  "arguments": {
    "n": 8
  }
}

solve_sudoku

Giải câu đố Sudoku 9x9.

{
  "name": "solve_sudoku",
  "arguments": {
    "puzzle": [[5,3,0,...], [6,0,0,...], ...]
  }
}

solve_graph_coloring

Giải bài toán tô màu đồ thị.

{
  "name": "solve_graph_coloring",
  "arguments": {
    "edges": [[0,1], [1,2], [2,0]],
    "num_vertices": 3,
    "max_colors": 3
  }
}

solve_map_coloring

Giải bài toán tô màu bản đồ.

{
  "name": "solve_map_coloring",
  "arguments": {
    "regions": ["A", "B", "C"],
    "adjacencies": [["A", "B"], ["B", "C"]],
    "max_colors": 2
  }
}

solve_lp

Giải bài toán Quy hoạch Tuyến tính (LP) hoặc Quy hoạch Nguyên Hỗn hợp (MIP) sử dụng PuLP.

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

Giải bài toán tối ưu lập kế hoạch sản xuất với phân tích độ nhạy tùy chọn.

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

Giải trò chơi tổng bằng không hai người sử dụng minimax (lý thuyết trò chơi).

{
  "name": "solve_minimax_game",
  "arguments": {
    "payoff_matrix": [
      [0, -1, 1],
      [1, 0, -1],
      [-1, 1, 0]
    ],
    "player": "row"
  }
}

Trả về chiến lược hỗn hợp tối ưu và giá trị trò chơi cho người chơi được chỉ định.

solve_minimax_decision

Giải bài toán quyết định minimax dưới sự không chắc chắn (tối ưu bền vững).

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

Mục tiêu: minimize_max_loss (danh mục bền vững) hoặc maximize_min_gain (sản xuất bảo thủ)

solve_24_point_game

Giải trò chơi 24 điểm với bốn số sử dụng phép toán số học.

{
  "name": "solve_24_point_game",
  "arguments": {
    "numbers": [1, 2, 3, 4]
  }
}

Tìm biểu thức số học sử dụng +, -, *, / và dấu ngoặc để đạt chính xác 24.

solve_chicken_rabbit_problem

Giải bài toán gà-thỏ kinh điển với ràng buộc số đầu và số chân.

{
  "name": "solve_chicken_rabbit_problem",
  "arguments": {
    "total_heads": 35,
    "total_legs": 94
  }
}

Xác định số gà (2 chân) và thỏ (4 chân) khi biết tổng số đầu và chân.

solve_scipy_portfolio_optimization

Giải tối ưu danh mục phi tuyến sử dụng SciPy với mô hình rủi ro bậc hai.

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

Tối ưu trọng số danh mục để tối đa hóa lợi nhuận trừ đi phạt rủi ro sử dụng tối ưu trung bình-phương sai.

solve_scipy_statistical_fitting

Giải ước lượng tham số thống kê sử dụng SciPy với khớp phân phối.

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

Khớp các phân phối thống kê ("normal", "exponential", "uniform") vào dữ liệu và cung cấp kiểm định độ phù hợp.

solve_scipy_facility_location

Giải bài toán vị trí cơ sở sử dụng phương pháp kết hợp 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
  }
}

Kết hợp lựa chọn cơ sở rời rạc (CSP) với tối ưu công suất liên tục (SciPy) để tối thiểu hóa tổng chi phí.

Triển khai Docker

Xây dựng và Chạy

# 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

Đầu ra Ví dụ

Bài toán N-Quân Hậu

POST /solve-n-queens
{
"n": 8
}

Cấu trúc Dự án

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

Phương thức MCP

Phương thứcLệnhGiao thứcTrường hợp Sử dụng
Stdiogurddy-mcpMCP qua stdin/stdoutTích hợp IDE (Kiro, Claude Desktop, v.v.)
HTTP Có thể Truyền phátuvicorn mcp_server.mcp_http_server:appMCP qua HTTP với truyền phát tùy chọnMáy khách web, truy cập từ xa, triển khai Docker

Tất cả các phương thức đều triển khai cùng giao thức MCP và cung cấp các công cụ giống hệt nhau.

Tính năng Phương thức HTTP

Phương thức HTTP (điểm cuối /mcp/http):

  • Mẫu yêu cầu-phản hồi đơn
  • Truyền phát tùy chọn: Thêm tiêu đề Accept: text/event-stream hoặc X-Stream: true
  • Đơn giản hơn cho các yêu cầu một lần
  • Tương thích với máy khách HTTP tiêu chuẩn
  • Không có trạng thái kết nối để quản lý
  • Hỗ trợ cả phản hồi JSON thông thường và phản hồi truyền phát định dạng SSE

Đầu ra Ví dụ

Bài toán N-Quân Hậu

$ 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)

Câu đố Logic

$ 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)

Ví dụ API HTTP

Giải Bài toán Kinh điển

Tô màu Bản đồ Úc

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
})

Bài toán 8-Quân Hậu

response = requests.post("http://127.0.0.1:8080/solve-n-queens",
json={"n": 8})

Ví dụ Có sẵn

Tất cả các ví dụ có thể được chạy bằng gurddy-mcp run-example <name> hoặc python -m mcp_server.server run-example <name>:

Ví dụ CSP ✅

  • n_queens - Bài toán N-Quân Hậu (4, 6, 8 quân hậu với hiển thị bàn cờ trực quan)
  • graph_coloring - Tô màu đồ thị (Tam giác, Hình vuông, đồ thị Petersen, đồ thị Bánh xe)
  • map_coloring - Tô màu bản đồ (Úc, các bang miền Tây Hoa Kỳ, Châu Âu)
  • scheduling - Bài toán lập lịch (Lập lịch khóa học, lập lịch họp, phân bổ tài nguyên)
  • logic_puzzles - Câu đố logic (Câu đố logic đơn giản, câu đố Ngựa vằn của Einstein)
  • optimized_csp - Kỹ thuật CSP nâng cao (Bộ giải Sudoku)

Ví dụ LP ✅

  • lp / optimized_lp - Ví dụ quy hoạch tuyến tính:
    • Tối ưu danh mục với ràng buộc rủi ro
    • Bài toán vận tải (tối ưu chuỗi cung ứng)
    • Phân tích nới lỏng ràng buộc
    • So sánh hiệu suất qua các kích thước bài toán

Ví dụ Minimax ✅

  • minimax - Tối ưu minimax và lý thuyết trò chơi:
    • Oẳn tù tì (trò chơi tổng bằng không)
    • Đồng xu Ghép đôi (trò chơi phối hợp)
    • Cuộc chiến Giới tính (cân bằng chiến lược hỗn hợp)
    • Tối ưu danh mục bền vững (tối thiểu hóa tổn thất tối đa)
    • Lập kế hoạch sản xuất (tối đa hóa lợi nhuận tối thiểu)
    • Phân bổ tài nguyên an ninh (trò chơi phòng thủ-tấn công)
    • Cạnh tranh quảng cáo (trò chơi thị phần)

Ví dụ Tích hợp SciPy ✅

  • scipy_optimization - Tối ưu hóa nâng cao với SciPy:
    • Tối ưu hóa danh mục đầu tư phi tuyến với mô hình rủi ro bậc hai
    • Ước lượng tham số thống kê (khớp phân phối có ràng buộc)
    • Tối ưu hóa xử lý tín hiệu (thiết kế bộ lọc FIR)
    • Vị trí cơ sở lai CSP-SciPy (tối ưu hóa rời rạc + liên tục)
    • Tích phân số trong các mục tiêu tối ưu hóa

Bài toán Toán Kinh điển ✅

  • classic_problems - Giải bài toán toán học giáo dục:
    • Trò chơi 24 điểm (biểu thức số học để đạt 24)
    • Bài toán Gà-Thỏ (thỏa mãn ràng buộc kinh điển)
    • Sudoku Mini 4×4 (trình diễn CSP đơn giản hóa)
    • Bài toán 4-Hậu (biến thể N-Hậu giáo dục)
    • Bài toán Xếp ba lô 0-1 (tối ưu hóa kinh điển)

Các Loại Bài toán Được Hỗ trợ

🧩 Bài toán CSP

  • N-Hậu: Bài toán N-Hậu kinh điển cho mọi kích thước bàn cờ (N=4 đến N=100+)
  • Tô màu Đồ thị: Tô màu đỉnh cho đồ thị tùy ý (tam giác, Petersen, bánh xe, v.v.)
  • Tô màu Bản đồ: Tô màu vùng địa lý (bản đồ Úc, Mỹ, Châu Âu)
  • Sudoku: Câu đố Sudoku 9×9 tiêu chuẩn với lan truyền ràng buộc
  • Câu đố Logic: Bài toán Ngựa vằn của Einstein và các bài toán suy luận logic tùy chỉnh
  • Lập lịch: Lập lịch khóa học, phòng họp, phân bổ tài nguyên với ràng buộc thời gian

📈 Bài toán Tối ưu hóa

  • Quy hoạch Tuyến tính: Tối ưu hóa biến liên tục với ràng buộc tuyến tính
  • Quy hoạch Nguyên: Tối ưu hóa biến rời rạc (số lượng sản xuất, phân công)
  • Quy hoạch Nguyên Hỗn hợp: Kết hợp biến liên tục và rời rạc
  • Lập kế hoạch Sản xuất: Tối ưu hóa đa sản phẩm có ràng buộc tài nguyên
  • Tối ưu hóa Danh mục: Phân bổ đầu tư với ràng buộc rủi ro và lợi nhuận
  • Vận tải: Tối ưu hóa chuỗi cung ứng (kho hàng đến khách hàng)

🎲 Lý thuyết Trò chơi & Tối ưu hóa Bền vững

  • Trò chơi Tổng bằng Không: Oẳn tù tì, Đồng xu khớp, Cuộc chiến giới tính
  • Cân bằng Nash Chiến lược Hỗn hợp: Chiến lược xác suất tối ưu cho cả hai người chơi
  • Quyết định Minimax: Tối thiểu hóa tổn thất trường hợp xấu nhất qua các kịch bản bất định
  • Quyết định Maximin: Tối đa hóa lợi ích trường hợp xấu nhất (chiến lược bảo thủ)
  • Danh mục Bền vững: Tối thiểu hóa tổn thất tối đa qua các kịch bản thị trường
  • Trò chơi An ninh: Bài toán phân bổ tài nguyên kẻ tấn công-người phòng thủ

🔬 Tối ưu hóa Nâng cao Sử dụng SciPy

  • Tối ưu hóa Danh mục Phi tuyến: Mô hình rủi ro bậc hai với tối đa hóa tỷ lệ Sharpe
  • Ước lượng Tham số Thống kê: Khớp phân phối dựa trên MLE và lượng tử có ràng buộc
  • Xử lý Tín hiệu: Thiết kế bộ lọc FIR với tối ưu hóa đáp ứng tần số
  • Tối ưu hóa Lai: Kết hợp Gurddy CSP với tối ưu hóa liên tục SciPy
  • Tích phân Số: Các bài toán tối ưu hóa liên quan đến hàm toán học phức tạp

🧮 Bài toán Giáo dục Kinh điển

  • Trò chơi 24 điểm: Tìm biểu thức số học sử dụng bốn số để đạt 24
  • Bài toán Gà-Thỏ: Thỏa mãn ràng buộc kinh điển với đầu và chân
  • Sudoku Mini: Giải Sudoku 4×4 sử dụng kỹ thuật CSP
  • Biến thể N-Hậu: Phiên bản giáo dục của bài toán kinh điển
  • Bài toán Xếp ba lô: Tối ưu hóa xếp ba lô 0-1 với ràng buộc trọng lượng và giá trị

Tính năng Hiệu suất

  • Giải Nhanh: Phản hồi mili giây cho bài toán nhỏ-vừa (N-Hậu N≤12, đồ thị <50 đỉnh)
  • Có thể Mở rộng: Xử lý bài toán lớn (N-Hậu N=100+, LP với 1000+ biến)
  • Hiệu quả Bộ nhớ: Tìm kiếm quay lui và lan truyền ràng buộc giảm thiểu sử dụng bộ nhớ
  • Có thể Mở rộng: Ràng buộc tùy chỉnh, hàm mục tiêu và loại bài toán
  • An toàn Đồng thời: API HTTP hỗ trợ xử lý yêu cầu đồng thời
  • Sẵn sàng Sản xuất: Triển khai Docker, kiểm tra sức khỏe, xử lý lỗi

Điểm chuẩn Hiệu suất

Thời gian thực thi điển hình trên phần cứng tiêu chuẩn:

  • Ví dụ CSP: 0.4-0.5s (N-Hậu, Tô màu Đồ thị, Câu đố Logic)
  • Ví dụ LP: 0.8-0.9s (Danh mục, Vận tải, Lập kế hoạch Sản xuất)
  • Ví dụ Minimax: 0.3-0.5s (Giải trò chơi, Tối ưu hóa bền vững)
  • Ví dụ SciPy: 0.5-1.2s (Tối ưu hóa phi tuyến, Khớp thống kê)
  • Bài toán Kinh điển: 0.1-0.3s (24 điểm, Gà-thỏ, Sudoku mini)
  • Sudoku: <0.1s cho câu đố 9×9 tiêu chuẩn
  • N-Hậu Lớn: ~2-3s cho N=100

Xử lý Sự cố

Lỗi Thường gặp

  • "gurddy package not available": Cài đặt với python -m mcp_server.server install
  • "No solution found": Không có giải pháp tồn tại dưới các ràng buộc đã cho; thử nới lỏng ràng buộc
  • "Invalid input types": Kiểm tra kiểu dữ liệu của tham số đầu vào
  • "Unknown example": Sử dụng python -m mcp_server.server run-example --help để xem các ví dụ có sẵn

Vấn đề Cài đặt

# 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')"

Gỡ lỗi Ví dụ

Chạy trực tiếp ví dụ để gỡ lỗi:

# 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]]))"

Yêu cầu Tích hợp SciPy

Các ví dụ tích hợp SciPy yêu cầu phụ thuộc bổ sung:

# 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')"

Ví dụ SciPy Bao gồm:

  • Tối ưu hóa Danh mục Phi tuyến: Mô hình rủi ro bậc hai với tối đa hóa tỷ lệ Sharpe
  • Ước lượng Tham số Thống kê: Khớp phân phối với phương pháp MLE và lượng tử
  • Xử lý Tín hiệu: Thiết kế bộ lọc FIR với tối ưu hóa đáp ứng tần số
  • CSP-SciPy Lai: Vị trí cơ sở kết hợp tối ưu hóa rời rạc và liên tục
  • Tích phân Số: Bài toán tối ưu hóa phức tạp liên quan đến tích phân

Phát triển

Kiến trúc

Dự án sử dụng sổ đăng ký công cụ tập trung với lược đồ tự động sinh để đảm bảo tính nhất quán giữa máy chủ stdio và HTTP:

  • Định nghĩa Công cụ: mcp_server/tool_definitions.py (chỉ siêu dữ liệu cơ bản)
  • Sổ đăng ký Tự động Sinh: mcp_server/tool_registry.py (lược đồ được sinh từ chữ ký hàm)
  • Máy chủ Stdio: mcp_server/mcp_stdio_server.py (cho tích hợp IDE)
  • Máy chủ HTTP: mcp_server/mcp_http_server.py (cho máy khách web)
  • Trình xử lý: mcp_server/handlers/gurddy.py (triển khai công cụ)
  • Trình sinh Lược đồ: scripts/generate_registry.py (tự động sinh lược đồ từ chữ ký hàm)

Thêm Công cụ Mới

  1. Triển khai trình xử lý trong 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. Thêm siêu dữ liệu cơ bản trong 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. Sinh lược đồ và xác minh:

    # Auto-generate schemas from function signatures
python scripts/generate_registry.py

# Verify consistency
python scripts/verify_consistency.py
pytest tests/test_consistency.py -v

Vậy thôi! Lược đồ được tự động sinh từ gợi ý kiểu của hàm bạn, và cả máy chủ stdio và HTTP sẽ nhận công cụ mới.

Ràng buộc Tùy chỉnh

# Define a custom constraint in gurddy
def custom_constraint(var1, var2):
    return var1 + var2 <= 10

model.addConstraint(gurddy.FunctionConstraint(custom_constraint, (var1, var2)))

Kiểm thử

# 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

Giấy phép

Dự án này được cấp phép theo giấy phép nguồn mở. Vui lòng xem tệp LICENSE để biết chi tiết.