Scryfall MCP 서버

AI 어시스턴트에게 매직: 더 개더링(MTG) 카드 데이터와 기능을 제공하기 위해 Scryfall API와 통합된 포괄적인 Model Context Protocol(MCP) 서버입니다.

이 저장소는 현재 다음을 지원합니다:

• 로컬 MCP 클라이언트를 위한 안정적인 기본 전송 방식인 stdio

• 로컬 우선 HTTP 워크플로우를 위한 추가 전송 방식인 실험적 Streamable HTTP

핵심 제품은 두 모드 모두 동일하며, MTG를 위한 Scryfall 기반 검색, 규칙 및 덱 빌딩 워크플로우를 제공합니다.

기능

🔧 MCP 도구

쿼리 빌딩

• build_scryfall_query: 자연어 요청을 최적화된 Scryfall 검색 쿼리로 변환

  • 입력: 자연어 설명, 형식 기본 설정, 최적화 전략

  • 출력: 설명 및 대안이 포함된 최적화된 Scryfall 쿼리

  • 예시: "red creatures under $5 for aggressive decks" → "c:r t:creature usd<=5 pow>=2 cmc<=3"

핵심 검색 도구

• search_cards: Scryfall의 강력한 검색 구문을 사용하여 카드 검색

• get_card: 특정 카드에 대한 상세 정보 가져오기

• get_card_prices: 카드에 대한 현재 가격 데이터 검색

• random_card: 선택적 필터를 사용하여 무작위 카드 가져오기

• search_sets: 매직 세트 검색 및 필터링

발견 및 분석 도구

• query_rules: 컨텍스트와 함께 MTG 종합 규칙 검색

• search_format_staples: 특정 형식의 필수 카드, 역할 수행 카드 및 메타 카드 찾기

• search_alternatives: 예산 친화적인 대체 카드, 업그레이드 또는 유사한 카드 찾기

• find_synergistic_cards: 카드, 테마 또는 아키타입에 대한 시너지 조각 발견

• batch_card_analysis: 여러 카드의 적법성, 가격, 시너지 또는 구성을 분석

덱 빌딩 도구

• validate_brawl_commander: 카드가 Brawl 또는 Standard Brawl 커맨더로 적법한지 확인

• analyze_deck_composition: 덱 리스트에서 마나 곡선, 카드 구성, 색상 및 권장 사항 평가

• suggest_mana_base: 색상 요구 사항에 따른 대지 수 및 마나 수정 패키지 권장

📚 MCP 리소스

• card-database://bulk: 일일 업데이트가 포함된 전체 Scryfall 대량 카드 데이터베이스

• set-database://all: 메타데이터와 아이콘이 포함된 모든 매직 세트

💡 MCP 프롬프트

• analyze_card: 경쟁력, 시너지 및 메타 포지셔닝을 포함한 포괄적인 카드 분석 생성

• build_deck: 특정 카드를 중심으로 한 덱 빌딩 가이드 생성

⚡ 성능 기능

• 속도 제한(Rate Limiting): 최소 100ms 간격으로 Scryfall의 API 제한 준수

• 지능형 캐싱: 구성 가능한 TTL로 API 호출을 70% 이상 감소

• 오류 처리: 모든 API 오류 조건에 대한 원활한 처리

• 서킷 브레이커: API 중단 시 연쇄 장애 방지

🔍 간단한 유효성 검사 시스템

• 경량 유효성 검사: 유용한 오류 메시지와 함께 기본적인 쿼리 구문 유효성 검사

• 필수 검사: 괄호, 따옴표 및 일반적인 구문 오류 균형 확인

• 연산자 인식: 오타에 대한 제안과 함께 알려진 Scryfall 연산자 유효성 검사

• 성능 최적화: 최소한의 오버헤드로 빠른 유효성 검사

Related MCP server: API Tester MCP Server

설치

사전 요구 사항

• Node.js 18+

• npm 또는 yarn

설정

1. 저장소 복제

   git clone https://github.com/bmurdock/scryfall-mcp.git
   cd scryfall-mcp

2. 의존성 설치

   npm install

3. 환경 구성 (선택 사항)

   cp .env.example .env
   # Edit .env with your preferences

4. 프로젝트 빌드

   npm run build

사용법

전송 모드

STDIO (안정적인 기본값)

Claude Desktop, Codex 및 MCP Inspector와 같은 로컬 MCP 클라이언트에는 stdio를 사용하십시오. 이는 여전히 기본적이고 가장 잘 지원되는 전송 방식입니다.

npm run dev

npm start

Streamable HTTP (실험적)

로컬 우선 Streamable HTTP 사용을 위해 추가적인 HTTP 진입점을 사용할 수 있습니다.

npm run dev:http

npm run start:http

테스트

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

MCP Inspector

npm run inspector

HTTP 전송 상태

HTTP 지원은 현재 실험적입니다.

의미:

• stdio가 권장되는 기본값으로 유지됨

• HTTP는 대체가 아닌 추가 기능임

• 구현은 공식 MCP Streamable HTTP 전송 경로를 따름

• 첫 번째 구현은 의도적으로 로컬 우선이며 범위가 보수적임

현재 HTTP 동작:

• 기본적으로 127.0.0.1에 바인딩

• POST|GET|DELETE /mcp 노출

• GET /health 노출

• 기본적으로 루프백이 아닌 브라우저 스타일 Origin 헤더 거부

• 다른 오리진 정책이 의도적으로 필요한 경우 HTTP_ALLOWED_ORIGINS로 구성 가능

현재 목표가 아닌 것:

• 공용 인터넷 배포 지침

• 인증 미들웨어 또는 호스팅된 프로덕션 강화

• 저장소 전체에서 stdio 예제 대체

공용 배포 모델이 필요한 경우, 현재 HTTP 지원을 완성된 호스팅 솔루션이 아닌 기반으로 취급하십시오.

프로젝트 문서

• CONTRIBUTING.md

• SECURITY.md

• SCRYFALL_COMPLIANCE.md

Claude Desktop 통합

Claude Desktop 구성 파일에 다음을 추가하십시오:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/scryfall-mcp/dist/index.js"]
    }
  }
}

/absolute/path/to/scryfall-mcp를 실제 설치 경로로 바꾸십시오.

HTTP 구성

선택적 HTTP 환경 변수:

• HTTP_HOST 기본값 127.0.0.1

• HTTP_PORT 기본값 3000

• HTTP_MCP_PATH 기본값 /mcp

• HTTP_HEALTH_PATH 기본값 /health

• HTTP_ALLOWED_ORIGINS 선택적 쉼표로 구분된 오리진 허용 목록

로컬 HTTP 시작 예시:

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

이 모드는 로컬 또는 명시적으로 제어되는 환경을 위한 것입니다. 인증 및 배포 강화를 추가하지 않고 현재 HTTP 진입점을 프로덕션 준비가 완료된 공용 노출로 취급하지 마십시오.

도구 사용 예시

자연어 쿼리 빌딩

자연어를 Scryfall 구문으로 변환:

// Convert natural language to optimized Scryfall query
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "blue counterspells in modern under $20",
    "optimize_for": "precision"
  }
}

예산 친화적인 쿼리 생성:

// Budget-focused query generation
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "aggressive red creatures for standard",
    "optimize_for": "budget",
    "price_budget": {
      "max": 5,
      "currency": "usd"
    }
  }
}

흥미로운 카드 발견:

// Discovery-optimized search
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "legendary artifacts that produce mana",
    "format": "commander",
    "optimize_for": "discovery"
  }
}

쿼리 규칙

{
  "tool": "query_rules",
  "arguments": {
    "query": "state-based actions",
    "context_lines": 2
  }
}

형식 필수 카드 검색

{
  "tool": "search_format_staples",
  "arguments": {
    "format": "commander",
    "role": "ramp",
    "tier": "competitive",
    "limit": 10
  }
}

대안 검색

{
  "tool": "search_alternatives",
  "arguments": {
    "target_card": "Rhystic Study",
    "direction": "cheaper",
    "format": "commander",
    "max_price": 10
  }
}

시너지 카드 찾기

{
  "tool": "find_synergistic_cards",
  "arguments": {
    "focus_card": "Obeka, Splitter of Seconds",
    "synergy_type": "theme",
    "format": "commander",
    "limit": 12
  }
}

배치 카드 분석

{
  "tool": "batch_card_analysis",
  "arguments": {
    "card_list": ["Sol Ring", "Arcane Signet", "Command Tower"],
    "analysis_type": "prices",
    "currency": "usd",
    "include_suggestions": true
  }
}

Brawl 커맨더 유효성 검사

{
  "tool": "validate_brawl_commander",
  "arguments": {
    "card_identifier": "Ashiok, Nightmare Muse",
    "format": "brawl"
  }
}

덱 구성 분석

{
  "tool": "analyze_deck_composition",
  "arguments": {
    "deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
    "format": "modern",
    "strategy": "aggro"
  }
}

마나 베이스 제안

{
  "tool": "suggest_mana_base",
  "arguments": {
    "color_requirements": "WUG",
    "format": "commander",
    "strategy": "midrange",
    "budget": "moderate"
  }
}

카드 검색

// Basic search
{
  "query": "lightning bolt"
}

// Advanced search with Scryfall syntax
{
  "query": "c:red type:instant cmc:1",
  "limit": 10,
  "format": "json"
}

// Format-specific search
{
  "query": "legal:modern type:creature power>=4",
  "order": "cmc"
}

카드 상세 정보 가져오기

// By name
{
  "identifier": "Lightning Bolt"
}

// By set and collector number
{
  "identifier": "dom/123"
}

// By Scryfall ID
{
  "identifier": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a"
}

// With specific set
{
  "identifier": "Lightning Bolt",
  "set": "m21"
}

카드 가격 가져오기

{
  "card_identifier": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a",
  "currency": "usd"
}

무작위 카드

// Completely random
{}

// Filtered random card
{
  "query": "type:creature",
  "format": "modern"
}

세트 검색

// All sets
{}

// Filter by type and date
{
  "type": "expansion",
  "released_after": "2020-01-01"
}

Scryfall 검색 구문

서버는 Scryfall의 전체 검색 구문을 지원합니다:

기본 연산자

• c:red - 색상

• type:creature - 카드 유형

• set:dom - 세트 코드

• cmc:3 - 변환 마나 비용

• power>=4 - 공격력/방어력 비교

• legal:modern - 형식 적법성

고급 연산자

• is:commander - 카드 속성

• year:2023 - 출시 연도

• rarity:mythic - 희귀도

• artist:"john avon" - 아티스트 이름

• flavor:"text" - 플레이버 텍스트 검색

불리언 논리

• red OR blue - 두 조건 중 하나

• creature AND red - 두 조건 모두

• NOT black - 조건 제외

• (red OR blue) type:instant - 그룹화

오류 처리

서버는 일반적인 문제에 대해 자세한 오류 메시지를 제공합니다:

• 404: 카드/리소스 찾을 수 없음

• 422: 잘못된 검색 구문

• 429: 속도 제한 초과 (자동 재시도)

• 유효성 검사 오류: 매개변수 유효성 검사 실패

성능 모니터링

캐시 통계

// Get cache performance
server.getCacheStats()

속도 제한 상태

// Check rate limiting status
server.getRateLimiterStatus()

상태 확인

// Overall system health
server.healthCheck()

구성

환경 변수

SCRYFALL_USER_AGENT=ScryfallMCPServer/1.0
RATE_LIMIT_MS=100
LOG_LEVEL=info
NODE_ENV=development
# Optional timeouts and health/deep checks
SCRYFALL_TIMEOUT_MS=15000
HEALTHCHECK_DEEP=false
# Bound the internal rate limiter queue
RATE_LIMIT_QUEUE_MAX=500

캐시 지속 시간

• 카드 검색: 30분

• 카드 상세 정보: 24시간

• 카드 가격: 6시간

• 세트 데이터: 1주

• 대량 데이터: 24시간

로깅 구성

서버는 포괄적인 오류 추적 및 모니터링을 갖춘 고성능 구조화 로깅을 위해 Pino를 사용합니다.

로그 수준

# Available log levels (default: info)
LOG_LEVEL=trace    # Most verbose - all operations
LOG_LEVEL=debug    # Debug information and performance metrics
LOG_LEVEL=info     # General information (default)
LOG_LEVEL=warn     # Warnings and degraded performance
LOG_LEVEL=error    # Errors only
LOG_LEVEL=fatal    # Critical errors only

개발 vs 프로덕션 로깅

개발 모드 (NODE_ENV=development):

• 예쁘게 출력되고 색상이 지정된 출력

• 사람이 읽을 수 있는 타임스탬프

• 요청 ID 및 도구 이름 강조

• 가독성을 위한 자동 로그 형식 지정

프로덕션 모드 (NODE_ENV=production):

• 기계 처리를 위한 JSON 구조 로그

• 로그 집계 시스템에 최적화

• 고성능 시나리오를 위한 최소 오버헤드

• ELK Stack, Grafana 및 모니터링 도구와 호환

구조화된 로그 형식

모든 로그에는 디버깅 및 모니터링을 위한 구조화된 컨텍스트가 포함됩니다:

{
  "level": "info",
  "time": "2025-01-17T19:32:53.123Z",
  "pid": 12345,
  "hostname": "server-01",
  "service": "scryfall-mcp",
  "version": "1.0.0",
  "requestId": "req_1737145973123_abc123def",
  "toolName": "search_cards",
  "operation": "tool_execution",
  "duration": 245,
  "msg": "Tool execution completed"
}

요청 상관관계

모든 요청은 작업 전반을 추적하기 위한 고유한 상관관계 ID를 가집니다:

• 형식: req_{timestamp}_{random}

• 도구 실행, API 호출 및 오류 추적

• 종단 간 요청 추적 가능

• 오래된 상관관계 데이터 자동 정리

오류 처리 및 모니터링

오류 분류

서버는 구조화된 오류 클래스를 사용하여 포괄적인 오류 처리를 구현합니다:

기본 오류 유형:

• MCPError - 구조화된 로깅 지원을 포함하는 기본 클래스

• ToolExecutionError - 도구별 실행 실패

• ResourceError - 리소스 액세스 실패

• PromptError - 프롬프트 생성 실패

도메인별 오류:

• ScryfallAPIError - Scryfall API 관련 오류

• RateLimitError - 속도 제한 및 스로틀링

• ValidationError - 입력 유효성 검사 실패

오류 모니터링 기능

자동 오류 추적:

• 유형별 오류 빈도 모니터링

• 성능 지표 수집

• 요청 상관관계 추적

• API 실패에 대한 서킷 브레이커 패턴

모니터링 데이터 액세스:

// Get comprehensive monitoring report
const status = server.getStatus();
console.log(status.monitoring);

// Output includes:
// - Error counts by type
// - Performance metrics (avg response times)
// - Request correlation data
// - Health check status

상태 확인 모니터링

상세한 서비스 상태를 포함한 향상된 상태 확인:

# Health check includes:
# - Cache service status
# - Rate limiter status
# - Scryfall API connectivity
# - Error monitoring metrics
# - Performance statistics

프로덕션 모니터링 설정

권장 모니터링 스택:

1. 로그 집계: ELK Stack (Elasticsearch, Logstash, Kibana)

2. 지표: Prometheus를 사용하는 Grafana

3. 오류 추적: 구조화된 오류 컨텍스트를 사용하는 Sentry

4. 알림: 오류율 및 응답 시간을 기반으로 함

모니터링할 주요 지표:

• 도구 실행 성공/실패율

• API 응답 시간 분포

• 오류 유형 빈도

• 캐시 적중/미스 비율

• 속도 제한 상태

오류 복구 전략

자동 복구:

• API 실패에 대한 지수 백오프

• 서킷 브레이커가 연쇄 장애 방지

• 지터를 포함한 지능형 재시도 로직

• 중단 시 원활한 성능 저하

수동 복구:

// Reset error monitoring
server.resetRateLimiter();
server.clearCaches();

// Check system health
const health = await server.healthCheck();

문제 해결

일반적인 문제

"Rate limit exceeded"

• 서버가 자동으로 속도 제한을 처리합니다

• 잠시 기다렸다가 다시 시도하십시오

• 너무 많은 동시 요청을 보내고 있는지 확인하십시오

"Network error: Unexpected token" 또는 gzip 관련 오류

• v1.0.2에서 gzip 압축을 비활성화하여 수정되었습니다

• 최신 빌드를 사용 중인지 확인하십시오: npm run build

• 재빌드 후 Claude Desktop을 다시 시작하십시오

• 서버는 이제 구문 분석 문제를 피하기 위해 압축되지 않은 응답을 요청합니다

"Card not found"

• 카드 이름 철자를 확인하십시오

• 세트 코드 + 수집가 번호 형식을 사용해 보십시오

• Scryfall에 카드가 존재하는지 확인하십시오

"Invalid search syntax"

• Scryfall 검색 구문 문서를 검토하십시오

• 짝이 맞지 않는 괄호가 있는지 확인하십시오

• 불리언 연산자로 쿼리를 시작하지 마십시오

Claude Desktop 통합이 작동하지 않음

• 구성의 절대 경로를 확인하십시오

• 서버가 성공적으로 빌드되는지 확인하십시오

• Claude Desktop 로그에서 오류를 확인하십시오

디버그 모드

LOG_LEVEL=debug npm run dev

캐시 지우기

# Programmatically
server.clearCaches()

# Or restart the server

기여

1. 저장소 포크

2. 기능 브랜치 생성

3. 변경 사항