npm package: @iflow-mcp/scryfall-mcp
Description: MCP Server for Scryfall
Latest version: 1.0.6

# Scryfall MCP Server

A comprehensive Model Context Protocol (MCP) server that integrates with the Scryfall API to provide Magic: The Gathering card data and functionality to AI assistants like Claude.

## Features

### 🔧 MCP Tools

#### Enhanced Search Tools
- **build_scryfall_query**: Convert natural language requests into optimized Scryfall search queries
  - Input: Natural language description, format preferences, optimization strategy
  - Output: Optimized Scryfall query with explanation and alternatives
  - Example: "red creatures under $5 for aggressive decks" → "c:r t:creature usd<=5 pow>=2 cmc<=3"

#### Core Search Tools
- **search_cards**: Search for cards using Scryfall's powerful search syntax
- **get_card**: Get detailed information about specific cards
- **get_card_prices**: Retrieve current price data for cards
- **random_card**: Get random cards with optional filters
- **search_sets**: Search and filter Magic sets

### 📚 MCP Resources
- **card-database://bulk**: Complete Scryfall bulk card database with daily updates
- **set-database://all**: All Magic sets with metadata and icons

### 💡 MCP Prompts
- **analyze_card**: Generate comprehensive card analysis including competitive viability, synergies, and meta positioning
- **build_deck**: Create deck building guides centered around specific cards

### ⚡ Performance Features
- **Rate Limiting**: Respects Scryfall's API limits with 100ms minimum intervals
- **Intelligent Caching**: Reduces API calls by >70% with configurable TTL
- **Error Handling**: Graceful handling of all API error conditions
- **Circuit Breaker**: Prevents cascading failures during API outages

### 🔍 Simple Validation System
- **Lightweight Validation**: Basic query syntax validation with helpful error messages
- **Essential Checks**: Balanced parentheses, quotes, and common syntax errors
- **Operator Recognition**: Validates known Scryfall operators with suggestions for typos
- **Performance Optimized**: Fast validation with minimal overhead

## Installation

### Prerequisites
- Node.js 18+
- npm or yarn

### Setup

1. **Clone the repository**
   ```bash
   git clone https://github.com/bmurdock/scryfall-mcp.git
   cd scryfall-mcp
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure environment** (optional)
   ```bash
   cp .env.example .env
   # Edit .env with your preferences
   ```

4. **Build the project**
   ```bash
   npm run build
   ```

## Usage

### Development Mode
```bash
npm run dev
```

### Production Mode
```bash
npm start
```

### Testing
```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui
```

### MCP Inspector
```bash
npm run inspector
```

## Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

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

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

Replace `/absolute/path/to/scryfall-mcp` with the actual path to your installation.

## Tool Usage Examples

### Natural Language Query Building

Convert natural language to Scryfall syntax:

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

Generate budget-friendly queries:

```javascript
// 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"
    }
  }
}
```

Discover interesting cards:

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

### Search Cards
```javascript
// 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"
}
```

### Get Card Details
```javascript
// 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"
}
```

### Get Card Prices
```javascript
{
  "card_id": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a",
  "currency": "usd"
}
```

### Random Card
```javascript
// Completely random
{}

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

### Search Sets
```javascript
// All sets
{}

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

## Scryfall Search Syntax

The server supports Scryfall's full search syntax:

### Basic Operators
- `c:red` - Color
- `type:creature` - Type line
- `set:dom` - Set code
- `cmc:3` - Converted mana cost
- `power>=4` - Power/toughness comparisons
- `legal:modern` - Format legality

### Advanced Operators
- `is:commander` - Card properties
- `year:2023` - Release year
- `rarity:mythic` - Rarity
- `artist:"john avon"` - Artist name
- `flavor:"text"` - Flavor text search

### Boolean Logic
- `red OR blue` - Either condition
- `creature AND red` - Both conditions
- `NOT black` - Exclude condition
- `(red OR blue) type:instant` - Grouping

## Error Handling

The server provides detailed error messages for common issues:

- **404**: Card/resource not found
- **422**: Invalid search syntax
- **429**: Rate limit exceeded (automatic retry)
- **Validation errors**: Parameter validation failures

## Performance Monitoring

### Cache Statistics
```javascript
// Get cache performance
server.getCacheStats()
```

### Rate Limiter Status
```javascript
// Check rate limiting status
server.getRateLimiterStatus()
```

### Health Check
```javascript
// Overall system health
server.healthCheck()
```

## Configuration

### Environment Variables
```bash
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
```

### Cache Durations
- **Card Search**: 30 minutes
- **Card Details**: 24 hours
- **Card Prices**: 6 hours
- **Set Data**: 1 week
- **Bulk Data**: 24 hours

### Logging Configuration

The server uses **Pino** for high-performance structured logging with comprehensive error tracking and monitoring.

#### Log Levels
```bash
# 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
```

#### Development vs Production Logging

**Development Mode** (`NODE_ENV=development`):
- Pretty-printed, colorized output
- Human-readable timestamps
- Request ID and tool name highlighting
- Automatic log formatting for readability

**Production Mode** (`NODE_ENV=production`):
- JSON-structured logs for machine processing
- Optimized for log aggregation systems
- Minimal overhead for high-performance scenarios
- Compatible with ELK Stack, Grafana, and monitoring tools

#### Structured Log Format

All logs include structured context for debugging and monitoring:

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

#### Request Correlation

Every request gets a unique correlation ID for tracking across operations:
- Format: `req_{timestamp}_{random}`
- Tracks tool executions, API calls, and errors
- Enables end-to-end request tracing
- Automatic cleanup of old correlation data

### Error Handling & Monitoring

#### Error Classification

The server implements comprehensive error handling with structured error classes:

**Base Error Types:**
- `MCPError` - Base class with structured logging support
- `ToolExecutionError` - Tool-specific execution failures
- `ResourceError` - Resource access failures
- `PromptError` - Prompt generation failures

**Domain-Specific Errors:**
- `ScryfallAPIError` - Scryfall API-related errors
- `RateLimitError` - Rate limiting and throttling
- `ValidationError` - Input validation failures

#### Error Monitoring Features

**Automatic Error Tracking:**
- Error frequency monitoring by type
- Performance metrics collection
- Request correlation tracking
- Circuit breaker pattern for API failures

**Monitoring Data Access:**
```javascript
// 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 Monitoring

Enhanced health checks with detailed service status:

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

#### Production Monitoring Setup

**Recommended Monitoring Stack:**

1. **Log Aggregation**: ELK Stack (Elasticsearch, Logstash, Kibana)
2. **Metrics**: Grafana with Prometheus
3. **Error Tracking**: Sentry with structured error context
4. **Alerting**: Based on error rates and response times

**Key Metrics to Monitor:**
- Tool execution success/failure rates
- API response time distributions
- Error type frequencies
- Cache hit/miss ratios
- Rate limiter status

#### Error Recovery Strategies

**Automatic Recovery:**
- Exponential backoff for API failures
- Circuit breaker prevents cascading failures
- Intelligent retry logic with jitter
- Graceful degradation during outages

**Manual Recovery:**
```javascript
// Reset error monitoring
server.resetRateLimiter();
server.clearCaches();

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

## Troubleshooting

### Common Issues

**"Rate limit exceeded"**
- The server automatically handles rate limiting
- Wait a moment and try again
- Check if you're making too many concurrent requests

**"Network error: Unexpected token" or gzip-related errors**
- This was fixed in v1.0.2 by disabling gzip compression
- Make sure you're using the latest build: `npm run build`
- Restart Claude Desktop after rebuilding
- The server now requests uncompressed responses to avoid parsing issues

**"Card not found"**
- Verify card name spelling
- Try using set code + collector number format
- Check if the card exists in Scryfall

**"Invalid search syntax"**
- Review Scryfall search syntax documentation
- Check for unmatched parentheses
- Avoid starting queries with boolean operators

**Claude Desktop integration not working**
- Verify the absolute path in configuration
- Ensure the server builds successfully
- Check Claude Desktop logs for errors

### Debug Mode
```bash
LOG_LEVEL=debug npm run dev
```

### Clear Cache
```bash
# Programmatically
server.clearCaches()

# Or restart the server
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

### Development Guidelines
- Follow TypeScript best practices
- Maintain >80% test coverage
- Use conventional commit messages
- Update documentation for new features

## API Rate Limiting & Compliance

This server fully complies with Scryfall's API guidelines:
- **Rate Limiting**: 100ms minimum between requests (10 requests/second max)
- **Required Headers**: Proper User-Agent and Accept headers
- **Caching**: 24+ hour caching for card data, 6 hours for prices
- **Bulk Data**: Uses daily bulk downloads that don't count against limits
- **Error Handling**: Respects 429 responses with exponential backoff
- **Circuit Breaker**: Prevents overloading during API issues

See [SCRYFALL_COMPLIANCE.md](./SCRYFALL_COMPLIANCE.md) for complete compliance details.

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- [Scryfall](https://scryfall.com/) for providing the excellent Magic: The Gathering API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- The Magic: The Gathering community for inspiration and feedback
### HTTP Behavior & Headers

- The server sends a descriptive `User-Agent` and `Accept: application/json` on all Scryfall API calls, per Scryfall guidelines.
- All `fetch` calls have a configurable timeout via `SCRYFALL_TIMEOUT_MS` (default 15000 ms). Aborted requests surface with error code `timeout` in logs.
- Bulk data and icon downloads also include `User-Agent`; icons set `Accept: image/svg+xml`.

### Search Pagination Notes

- Scryfall’s `/cards/search` endpoint does not support a custom page size. The `limit` parameter in tools controls how many results are displayed from each Scryfall page, client-side.
- Pagination metadata (like total pages) is computed using Scryfall’s `total_cards` and your requested `limit` for accurate display.