gurddy mcp Server

Gurddy MCP 서버

제약 충족 문제(CSP), 선형 계획법(LP), 미니맥스 최적화, 그리고 SciPy 기반 고급 최적화 문제를 해결하기 위한 포괄적인 모델 컨텍스트 프로토콜(MCP) 서버입니다. SciPy 통합을 포함한 gurddy 최적화 라이브러리를 기반으로 구축되었으며, stdio(IDE 통합용)와 스트리밍 가능 HTTP(웹 클라이언트용)라는 두 가지 MCP 전송 방식을 통해 다양한 고전 문제 해결을 지원합니다.

🚀 빠른 시작 (Stdio): pip install gurddy_mcp 그런 다음 IDE에서 구성하세요

🌐 빠른 시작 (HTTP): docker run -p 8080:8080 gurddy-mcp 또는 배포 가이드를 참조하세요

📦 PyPI 패키지: https://pypi.org/project/gurddy_mcp

주요 기능

🎯 CSP 문제 해결

• N-Queens 문제: N×N 체스판에 N개의 퀸을 서로 공격하지 않도록 배치
• 그래프 색칠: 인접한 정점이 서로 다른 색을 갖도록 정점에 색상 할당
• 지도 색칠: 인접한 지역이 서로 다른 색을 갖도록 지리적 영역 색칠
• 스도쿠 해결사: 표준 9×9 스도쿠 퍼즐 해결
• 논리 퍼즐: 아인슈타인의 얼룩말 퍼즐 및 사용자 정의 논리 문제
• 일정 계획: 강의 일정, 회의 일정, 자원 할당
• 일반 CSP 해결사: 사용자 정의 제약 충족 문제 지원

📊 LP/최적화 문제

• 선형 계획법: 선형 제약 조건 하의 연속 변수 최적화
• 혼합 정수 계획법: 정수 및 연속 변수를 사용한 최적화
• 생산 계획: 민감도 분석을 포함한 자원 제약 생산 최적화
• 포트폴리오 최적화: 위험 제약 조건 하의 투자 할당
• 수송 문제: 공급망 및 물류 최적화

🎮 미니맥스/게임 이론

• 제로섬 게임: 2인 게임 해결 (가위바위보, 동전 맞추기, 성 대결)
• 혼합 전략 내쉬 균형: 최적의 확률적 전략 찾기
• 강건 최적화: 불확실성 하에서 최악의 손실 최소화
• 맥시민 결정: 최악의 이득 최대화 (보수적 전략)
• 보안 게임: 방어자-공격자 자원 할당
• 강건 포트폴리오: 시장 시나리오 전반에서 최대 손실 최소화
• 생산 계획: 보수적 생산 결정 (최소 이익 최대화)
• 광고 경쟁: 시장 점유율 게임 및 경쟁 전략

🔬 SciPy 통합

• 비선형 포트폴리오 최적화: SciPy 최적화를 사용한 2차 위험 모델
• 통계적 모수 추정: 제약 조건이 있는 분포 피팅 (MLE, 분위수 매칭)
• 신호 처리 최적화: 주파수 응답 최적화를 통한 FIR 필터 설계
• 하이브리드 CSP-SciPy: 이산 시설 선택 + 연속 용량 최적화
• 수치 적분: 적분 및 복잡한 함수를 포함하는 최적화 문제

🧮 고전 수학 문제

• 24점 게임: 네 개의 숫자를 사용하여 24를 만드는 산술 표현식 찾기
• 닭-토끼 문제: 머리와 다리 수를 이용한 고전 제약 문제
• 미니 스도쿠: CSP 기법을 사용한 4×4 스도쿠 해결사
• 4-Queens 문제: 교육 목적으로 단순화된 N-Queens
• 0-1 배낭 문제: 무게와 가치 제약이 있는 고전 최적화 문제

🔌 MCP 프로토콜 지원

• Stdio 전송: 로컬 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 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: 직접 명령 사용 (설치 후)

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-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 - 산술 연산을 사용하여 네 개의 숫자로 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

산술 연산을 사용하여 네 개의 숫자로 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

2차 위험 모델과 함께 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-Queens 문제

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	웹 클라이언트, 원격 접근, Docker 배포

모든 전송은 동일한 MCP 프로토콜을 구현하며 동일한 도구를 제공합니다.

HTTP 전송 기능

HTTP 전송 (/mcp/http 엔드포인트):

• 단일 요청-응답 패턴
• 선택적 스트리밍: Accept: text/event-stream 또는 X-Stream: true 헤더 추가
• 일회성 요청에 더 간단함
• 표준 HTTP 클라이언트와 호환
• 관리할 연결 상태 없음
• 일반 JSON 응답과 SSE 형식의 스트리밍 응답 모두 지원

예제 출력

N-Queens 문제

$ 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-Queens 문제

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-Queens 문제 (시각적 보드 표시가 포함된 4, 6, 8 퀸)
• graph_coloring - 그래프 색칠 (삼각형, 사각형, 피터슨 그래프, 휠 그래프)
• map_coloring - 지도 색칠 (호주, 미국 서부 주, 유럽)
• scheduling - 일정 계획 문제 (강의 일정, 회의 일정, 자원 할당)
• logic_puzzles - 논리 퍼즐 (간단한 논리 퍼즐, 아인슈타인의 얼룩말 퍼즐)
• optimized_csp - 고급 CSP 기법 (스도쿠 해결사)

LP 예제 ✅

• lp / optimized_lp - 선형 계획법 예제:
  • 위험 제약 조건이 있는 포트폴리오 최적화
  • 수송 문제 (공급망 최적화)
  • 제약 완화 분석
  • 문제 크기별 성능 비교

미니맥스 예제 ✅

• minimax - 미니맥스 최적화 및 게임 이론:
  • 가위바위보 (제로섬 게임)
  • 동전 맞추기 (조정 게임)
  • 성 대결 (혼합 전략 균형)
  • 강건 포트폴리오 최적화 (최대 손실 최소화)
  • 생산 계획 (최소 이익 최대화)
  • 보안 자원 할당 (방어자-공격자 게임)
  • 광고 경쟁 (시장 점유율 게임)

SciPy 통합 예제 ✅

• scipy_optimization - SciPy를 활용한 고급 최적화:
  • 2차 위험 모델을 사용한 비선형 포트폴리오 최적화
  • 통계적 모수 추정 (제약 조건이 있는 분포 피팅)
  • 신호 처리 최적화 (FIR 필터 설계)
  • 하이브리드 CSP-SciPy 시설 위치 선정 (이산 + 연속 최적화)
  • 최적화 목적 함수에서의 수치 적분

고전 수학 문제 ✅

• classic_problems - 교육용 수학 문제 풀이:
  • 24점 게임 (24를 만들기 위한 산술 표현식)
  • 닭-토끼 문제 (고전적인 제약 충족 문제)
  • 4×4 미니 스도쿠 (단순화된 CSP 시연)
  • 4-퀸 문제 (교육용 N-퀸 변형)
  • 0-1 배낭 문제 (고전적 최적화)

지원되는 문제 유형

🧩 CSP 문제

• N-퀸: 모든 보드 크기에 대한 고전적인 N-퀸 문제 (N=4에서 N=100+)
• 그래프 색칠: 임의 그래프에 대한 정점 색칠 (삼각형, 페테르센, 휠 등)
• 지도 색칠: 지리적 영역 색칠 (호주, 미국, 유럽 지도)
• 스도쿠: 제약 전파를 사용한 표준 9×9 스도쿠 퍼즐
• 논리 퍼즐: 아인슈타인의 얼룩말 퍼즐 및 사용자 정의 논리 추론 문제
• 스케줄링: 시간 제약이 있는 강의 스케줄링, 회의실, 자원 할당

📈 최적화 문제

• 선형 계획법: 선형 제약 조건이 있는 연속 변수 최적화
• 정수 계획법: 이산 변수 최적화 (생산 수량, 할당)
• 혼합 정수 계획법: 연속 변수와 이산 변수 결합
• 생산 계획: 다중 제품 자원 제약 최적화
• 포트폴리오 최적화: 위험 및 수익 제약 조건이 있는 투자 할당
• 수송: 공급망 최적화 (창고에서 고객까지)

🎲 게임 이론 및 강건 최적화

• 제로섬 게임: 가위바위보, 동전 맞추기, 성 대결
• 혼합 전략 내쉬 균형: 두 플레이어를 위한 최적의 확률적 전략
• 미니맥스 결정: 불확실성 시나리오 전반에서 최악의 손실 최소화
• 맥시민 결정: 최악의 이득 최대화 (보수적 전략)
• 강건 포트폴리오: 시장 시나리오 전반에서 최대 손실 최소화
• 보안 게임: 방어자-공격자 자원 할당 문제

🔬 SciPy 기반 고급 최적화

• 비선형 포트폴리오 최적화: 샤프 비율 최대화를 포함한 2차 위험 모델
• 통계적 모수 추정: 제약 조건이 있는 MLE 및 분위수 기반 분포 피팅
• 신호 처리: 주파수 응답 최적화를 통한 FIR 필터 설계
• 하이브리드 최적화: Gurddy CSP와 SciPy 연속 최적화 결합
• 수치 적분: 복잡한 수학 함수를 포함하는 최적화 문제

🧮 고전 교육 문제

• 24점 게임: 네 개의 숫자를 사용하여 24를 만드는 산술 표현식 찾기
• 닭-토끼 문제: 머리와 다리를 사용한 고전적인 제약 충족 문제
• 미니 스도쿠: CSP 기법을 사용한 4×4 스도쿠 풀이
• N-퀸 변형: 고전 문제의 교육용 버전
• 배낭 문제: 무게와 가치 제약 조건이 있는 0-1 배낭 최적화

성능 특징

• 빠른 해법: 중소 규모 문제에 대해 밀리초 단위 응답 (N-퀸 N≤12, 그래프 <50 정점)
• 확장성: 대규모 문제 처리 (N-퀸 N=100+, 변수 1000개 이상의 LP)
• 메모리 효율성: 백트래킹 탐색 및 제약 전파로 메모리 사용 최소화
• 확장 가능: 사용자 정의 제약 조건, 목적 함수 및 문제 유형
• 동시성 안전: 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초

문제 해결

일반적인 오류

• "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 예제 포함 사항:

• 비선형 포트폴리오 최적화: 샤프 비율 최대화를 포함한 2차 위험 모델
• 통계적 모수 추정: 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 파일을 참조하세요.