tarot-mcp/.github/copilot-instructions.md

# AI Coding Agent Instructions for Tarot MCP Server

## Project Overview
This is a **professional-grade Model Context Protocol (MCP) server** for Rider-Waite tarot readings, built with TypeScript/Node.js. The server provides both MCP protocol and HTTP API endpoints with comprehensive tarot functionality.

## Architecture & Key Components

### Multi-Transport Entry Point
- **`src/index.ts`**: Main entry with command-line parsing (`--transport stdio|http|sse --port 3000`)
- **Transports**: stdio (MCP default), HTTP REST API, SSE (Server-Sent Events)
- **Production**: Docker containerized with health checks and non-root user

### Core Server Structure
```
src/
├── index.ts              # Multi-transport entry point
├── tarot-server.ts       # Core MCP tool handler (12 tools available)
├── http-server.ts        # Express server with CORS, SSE, and health endpoints
└── tarot/                # Tarot engine modules
    ├── types.ts          # TypeScript definitions for all domain objects
    ├── card-data.ts      # Complete 78-card Rider-Waite database
    ├── card-manager.ts   # Card data management and search
    ├── spreads.ts        # 25 professional spread definitions
    ├── reading-manager.ts # Advanced interpretation engine
    ├── session-manager.ts # Session tracking and history
    ├── card-search.ts    # Multi-criteria search and similarity
    ├── card-analytics.ts # Database analytics and reporting
    ├── lunar-utils.ts    # Moon phase calculations and recommendations
    └── utils.ts          # Cryptographic randomness utilities
```

### Critical Initialization Pattern
The **`TarotServer.create()`** static factory method is **required** - never use `new TarotServer()`. This ensures proper async initialization of the card database:

```typescript
// ✅ Correct
const tarotServer = await TarotServer.create();

// ❌ Wrong - will fail
const tarotServer = new TarotServer();
```

## Core Domain Logic

### Card Drawing & Randomness
- **Cryptographically secure**: Uses `crypto.getRandomValues()` via `getSecureRandom()` in `utils.ts`
- **50/50 distribution**: Equal probability for upright/reversed orientations
- **Fisher-Yates shuffle**: Proper card randomization in `card-manager.ts`

### Interpretation Engine Features
- **Context-aware meanings**: Question analysis determines love/career/health/spiritual focus
- **Multi-dimensional analysis**: Elemental balance, suit patterns, numerical progressions
- **Spread-specific logic**: Celtic Cross position dynamics, Three Card flow analysis
- **Advanced patterns**: Court card analysis, Major Arcana progressions, elemental balance

### Spread System (25 Spreads)
Key spreads with specialized analysis:
- **`celtic_cross`**: 10-card comprehensive with position relationship analysis
- **`three_card`**: Past/Present/Future with energy flow assessment
- **`relationship_cross`**: 7-card relationship dynamics
- **`career_path`**: 6-card professional guidance
- **`chakra_alignment`**: 7-card energy center analysis
- **Custom spreads**: 1-15 positions via `create_custom_spread` tool

## Development Workflow

### Build & Test Commands
```bash
# Development
npm run dev          # stdio transport with hot reload
npm run dev:http     # HTTP server with hot reload

# Production
npm run build        # TypeScript compilation to dist/
npm start           # Run built stdio server
npm run start:http  # Run built HTTP server

# Testing
npm test            # Jest with ESM support
npm run test:watch  # Watch mode
npm run test:coverage # Coverage reports

# Docker
npm run docker:build && npm run docker:run
./deploy.sh         # Complete deployment script
```

### TypeScript Configuration
- **ES2022/ESNext modules**: Uses `.js` extensions in imports despite `.ts` source
- **Strict mode enabled**: Full type safety required
- **ESM-first**: Jest configured for ESM with `ts-jest/presets/default-esm`

### Import Patterns
Always use `.js` extensions in imports (required for ESM):
```typescript
import { TarotCardManager } from "./tarot/card-manager.js";  // ✅ Correct
import { TarotCardManager } from "./tarot/card-manager";     // ❌ Wrong
```

## API Integration Points

### MCP Tools (12 Available)
Key tools for AI integration:
- **`perform_reading`**: Main reading function with 25+ spread types
- **`create_custom_spread`**: Dynamic spread creation (1-15 positions)
- **`get_card_info`**: Detailed card information with context
- **`search_cards`**: Multi-criteria search (keyword, suit, element, etc.)
- **`recommend_spread`**: AI-driven spread recommendations
- **`get_moon_phase_reading`**: Lunar-based readings with automatic phase detection

### HTTP Endpoints
When running with `--transport http`:
- **`POST /api/reading`**: Direct reading endpoint
- **`POST /api/custom-spread`**: Custom spread creation
- **`GET /health`**: Health check with endpoint discovery
- **`GET /sse`**: MCP over Server-Sent Events

## Testing Strategy

### File Locations
- **Tests**: `src/tarot/__tests__/*.test.ts`
- **Jest config**: ESM-configured in `jest.config.js`
- **Coverage**: Excludes test files, includes all `src/**/*.ts`

### Test Patterns
Focus on core business logic:
- Card manager functionality and search
- Reading interpretation accuracy
- Spread configuration validation
- Cryptographic randomness verification

## Data & Configuration

### Card Database
- **Location**: `src/tarot/card-data.json` (78 complete cards)
- **Structure**: Research-verified Rider-Waite with multiple contexts (general, love, career, health, spiritual)
- **Quality**: Professional interpretations from Biddy Tarot, Labyrinthos sources

### Spread Definitions
- **Location**: `src/tarot/spreads.ts`
- **Pattern**: Each spread has `name`, `description`, `cardCount`, `positions[]`
- **Validation**: `isValidSpreadType()` and `getSpread()` helpers

## Project-Specific Conventions

### Error Handling
- **MCP tools**: Return descriptive strings, never throw
- **HTTP endpoints**: Use try/catch with proper status codes
- **Async patterns**: Always await `TarotServer.create()`

### Moon Phase Integration
- **Automatic detection**: `calculateMoonPhase()` in `lunar-utils.ts`
- **Themed spreads**: New moon intentions, full moon release
- **Recommendations**: Context-aware lunar guidance

### Session Management
- **Optional**: Sessions track reading history when `sessionId` provided
- **Stateless**: Server works without sessions for simple use cases
- **History**: Full reading preservation with timestamps

## Production Deployment

### Docker Strategy
- **Multi-stage**: Build in container, optimized production image
- **Security**: Non-root user (`tarot:nodejs`)
- **Health checks**: HTTP endpoint monitoring
- **Default**: SSE transport on port 3000

### Environment Variables
- **`NODE_ENV`**: development/production
- **`PORT`**: Override default 3000

## Key Dependencies
- **`@modelcontextprotocol/sdk`**: Core MCP protocol implementation
- **`express`**: HTTP server with CORS support
- **`zod`**: Runtime type validation (limited use)
- **TypeScript/Jest**: Development and testing infrastructure

## Common Pitfalls to Avoid
1. **Never instantiate TarotServer directly** - always use `TarotServer.create()`
2. **Don't forget `.js` extensions** in imports
3. **Session IDs are optional** - don't require them
4. **Card orientations are 50/50** - respect the cryptographic randomness
5. **Context matters** - question analysis drives interpretation selection