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:

// ✅ 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

# 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):

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