feat: Add comprehensive optimization report for Tarot MCP Server
- Implemented performance optimizations including improved singleton pattern and card lookup efficiency. - Enhanced error handling with a unified error type system and context-aware error messages. - Introduced a strong type validation framework for input validation, including sanitization functions. - Improved code quality through consistent formatting, ES module compatibility, and enhanced documentation. - Expanded test coverage with detailed tests for reading manager and error handling scenarios. - Created a simple test runner to validate optimizations and performance metrics.
This commit is contained in:
Morax
184
.github/copilot-instructions.md
vendored
Normal file
184
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user