Morax/tarot-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: Update author name in package.json to Morax

Browse Source
This commit is contained in:
Morax
2025-07-28 22:21:50 +08:00
parent 0cb4777284
commit 479809bd8e
2 changed files with 160 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
README.md
View File

@@ -2,6 +2,22 @@
A professional-grade Model Context Protocol (MCP) server for Rider-Waite tarot card readings, built with Node.js and TypeScript. This server provides comprehensive tarot functionality through both MCP protocol and HTTP API endpoints, featuring research-based interpretations and advanced reading analysis. A professional-grade Model Context Protocol (MCP) server for Rider-Waite tarot card readings, built with Node.js and TypeScript. This server provides comprehensive tarot functionality through both MCP protocol and HTTP API endpoints, featuring research-based interpretations and advanced reading analysis.
## 🚀 Current Implementation Status
**✅ FULLY IMPLEMENTED AND WORKING:**
- Complete 78-card Rider-Waite deck with detailed interpretations
- 11 professional tarot spreads (Single Card, Three Card, Celtic Cross, Horseshoe, Relationship Cross, Career Path, Decision Making, Spiritual Guidance, Year Ahead, Chakra Alignment, Shadow Work)
- Multi-transport MCP server (stdio, HTTP, SSE)
- Advanced interpretation engine with elemental analysis
- Cryptographically secure card shuffling and drawing
- Context-aware meaning selection
- Professional-grade HTTP API with CORS support
- Docker containerization with health checks
- Comprehensive search and analytics tools
- Session management and reading history
- Full TypeScript implementation with strict typing
- Jest testing framework setup
## ✨ Features ## ✨ Features
### 🃏 Professional Tarot System ### 🃏 Professional Tarot System
@@ -55,7 +71,7 @@ Here's what a professional Celtic Cross reading looks like:
- ✅ Elemental balance assessment (Fire energy dominance) - ✅ Elemental balance assessment (Fire energy dominance)
- ✅ Professional guidance and actionable insights - ✅ Professional guidance and actionable insights
## <EFBFBD> Professional Tarot Spreads ## 🔮 Professional Tarot Spreads
Our server features **11 specialized tarot spreads** designed for different life areas and spiritual practices: Our server features **11 specialized tarot spreads** designed for different life areas and spiritual practices:
@@ -67,16 +83,16 @@ Our server features **11 specialized tarot spreads** designed for different life
### 💕 Relationships & Personal ### 💕 Relationships & Personal
- **Relationship Cross**: 7-card relationship dynamics analysis - **Relationship Cross**: 7-card relationship dynamics analysis
- **Decision Making**: 5-card choice evaluation and guidance
- **Shadow Work**: 5-card psychological integration and growth
### 🚀 Career & Life Path ### 🚀 Career & Life Path
- **Career Path**: 6-card professional development guidance - **Career Path**: 6-card professional development guidance
- **Decision Making**: 5-card choice evaluation and guidance
- **Year Ahead**: 13-card annual forecast with monthly insights - **Year Ahead**: 13-card annual forecast with monthly insights
### 🧘 Spiritual & Energy Work ### 🧘 Spiritual & Energy Work
- **Spiritual Guidance**: 6-card spiritual development and higher self connection - **Spiritual Guidance**: 6-card spiritual development and higher self connection
- **Chakra Alignment**: 7-card energy center analysis and healing - **Chakra Alignment**: 7-card energy center analysis and healing
- **Shadow Work**: 5-card psychological integration and growth
Each spread includes: Each spread includes:
- **Specialized Analysis**: Tailored interpretation methods for each spread type - **Specialized Analysis**: Tailored interpretation methods for each spread type
@@ -84,7 +100,7 @@ Each spread includes:
- **Energy Assessment**: Elemental balance and flow analysis - **Energy Assessment**: Elemental balance and flow analysis
- **Professional Guidance**: Actionable insights and spiritual wisdom - **Professional Guidance**: Actionable insights and spiritual wisdom
## <EFBFBD>🏆 Why Choose This Tarot Server? ## 🏆 Why Choose This Tarot Server?
| Feature | This Server | Basic Tarot APIs | Generic Card Readers | | Feature | This Server | Basic Tarot APIs | Generic Card Readers |
|---------|-------------|------------------|---------------------| |---------|-------------|------------------|---------------------|
@@ -102,7 +118,7 @@ Each spread includes:
1. **Clone and Install** 1. **Clone and Install**
```bash ```bash
git clone <repository-url> git clone https://git.moraxcheng.me/Morax/tarot-mcp.git
cd tarot-mcp cd tarot-mcp
npm install npm install
``` ```
@@ -176,7 +192,7 @@ When running in HTTP mode, the following endpoints are available:
- `POST /api/reading` - Perform a comprehensive tarot reading - `POST /api/reading` - Perform a comprehensive tarot reading
```json ```json
{ {
"spreadType": "single_card|three_card|celtic_cross", "spreadType": "single_card|three_card|celtic_cross|horseshoe|relationship_cross|career_path|decision_making|spiritual_guidance|year_ahead|chakra_alignment|shadow_work",
"question": "Your specific question here", "question": "Your specific question here",
"sessionId": "optional-session-id-for-tracking" "sessionId": "optional-session-id-for-tracking"
} }
@@ -188,6 +204,10 @@ When running in HTTP mode, the following endpoints are available:
- **Three Card Flow**: Past/Present/Future with energy progression analysis - **Three Card Flow**: Past/Present/Future with energy progression analysis
- **Elemental Balance**: Automatic analysis of Fire, Water, Air, Earth energies - **Elemental Balance**: Automatic analysis of Fire, Water, Air, Earth energies
- **Context-Aware Interpretations**: Meanings selected based on question content - **Context-Aware Interpretations**: Meanings selected based on question content
- **Advanced Card Search**: Multi-criteria search with keyword, suit, element, and arcana filtering
- **Similarity Analysis**: Find cards with related meanings and themes
- **Database Analytics**: Comprehensive statistics and quality metrics
- **Secure Randomization**: Cryptographically secure card drawing and shuffling
### MCP Protocol ### MCP Protocol
- `GET /sse` - Server-Sent Events endpoint for MCP clients - `GET /sse` - Server-Sent Events endpoint for MCP clients
@@ -195,7 +215,7 @@ When running in HTTP mode, the following endpoints are available:
## 🛠️ MCP Tools ## 🛠️ MCP Tools
The server provides the following professional MCP tools: The server provides **7 comprehensive MCP tools** for professional tarot reading and analysis:
### `get_card_info` ### `get_card_info`
Get comprehensive information about a specific tarot card including symbolism, astrology, and numerology. Get comprehensive information about a specific tarot card including symbolism, astrology, and numerology.
@@ -220,7 +240,7 @@ List all available tarot cards with filtering and categorization.
Perform a professional tarot reading with advanced interpretation analysis. Perform a professional tarot reading with advanced interpretation analysis.
```json ```json
{ {
"spreadType": "celtic_cross|three_card|single_card", "spreadType": "single_card|three_card|celtic_cross|horseshoe|relationship_cross|career_path|decision_making|spiritual_guidance|year_ahead|chakra_alignment|shadow_work",
"question": "What should I know about my career path this year?", "question": "What should I know about my career path this year?",
"sessionId": "optional-session-id" "sessionId": "optional-session-id"
} }
@@ -237,25 +257,63 @@ Perform a professional tarot reading with advanced interpretation analysis.
- Spiritual development guidance (Spiritual Guidance) - Spiritual development guidance (Spiritual Guidance)
- Annual forecasting (Year Ahead) - Annual forecasting (Year Ahead)
### `list_available_spreads` ### `search_cards`
List all available tarot spread types with detailed descriptions and position meanings. Search for tarot cards using various criteria like keywords, suit, element, etc.
### `interpret_card_combination`
Get advanced interpretation for specific card combinations with archetypal analysis.
```json ```json
{ {
"cards": [ "keyword": "love",
{"name": "The Fool", "orientation": "upright"}, "suit": "cups",
{"name": "The Magician", "orientation": "reversed"} "arcana": "minor",
], "element": "water",
"context": "Career guidance and decision making" "orientation": "upright",
"limit": 10
} }
``` ```
**Features**: **Features**:
- Multi-dimensional combination analysis - Keyword search across meanings, keywords, and symbolism
- Archetypal pattern recognition - Filter by suit, arcana, element, number, and orientation
- Elemental and numerical significance - Flexible search criteria with customizable result limits
- Professional interpretation language
### `find_similar_cards`
Find cards with similar meanings to a given card.
```json
{
"cardName": "The Fool",
"limit": 5
}
```
**Features**:
- Semantic similarity analysis
- Meaning-based card relationships
- Customizable result limits
### `get_database_analytics`
Get comprehensive analytics and statistics about the tarot card database.
```json
{
"includeRecommendations": true
}
```
**Features**:
- Complete database statistics
- Card distribution analysis
- Quality metrics and recommendations
- Database completeness assessment
### `get_random_cards`
Get random cards with optional filtering for practice and exploration.
```json
{
"count": 3,
"suit": "wands",
"arcana": "major",
"element": "fire"
}
```
**Features**:
- Cryptographically secure randomization
- Optional filtering by suit, arcana, or element
- Customizable card count
## 🔧 Configuration ## 🔧 Configuration
@@ -408,6 +466,72 @@ curl "http://localhost:3000/api/cards?category=wands"
curl "http://localhost:3000/api/spreads" curl "http://localhost:3000/api/spreads"
``` ```
### Advanced Search and Analytics
#### Search Cards by Keyword
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "search_cards",
"arguments": {
"keyword": "love",
"suit": "cups",
"limit": 5
}
}
}'
```
#### Find Similar Cards
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "find_similar_cards",
"arguments": {
"cardName": "The Lovers",
"limit": 3
}
}
}'
```
#### Get Database Analytics
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "get_database_analytics",
"arguments": {
"includeRecommendations": true
}
}
}'
```
#### Get Random Cards for Practice
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "get_random_cards",
"arguments": {
"count": 3,
"arcana": "major"
}
}
}'
```
## 🏗️ Architecture ## 🏗️ Architecture
### Professional Tarot Engine ### Professional Tarot Engine
@@ -526,11 +650,11 @@ MIT License - see LICENSE file for details.
We welcome contributions to improve the Tarot MCP Server! Here's how you can help: We welcome contributions to improve the Tarot MCP Server! Here's how you can help:
### 🎯 Priority Areas ### 🎯 Priority Areas
1. **Complete Card Database**: Add remaining 56 Minor Arcana cards with full interpretations 1. **Enhanced Interpretations**: Deeper psychological analysis and Jungian insights
2. **Additional Spreads**: Implement Relationship, Career, and Spiritual-focused spreads 2. **Timing Predictions**: Advanced timing predictions and seasonal influences
3. **Enhanced Analysis**: Advanced timing predictions and seasonal influences 3. **Internationalization**: Support for multiple languages and cultural variations
4. **Internationalization**: Support for multiple languages and cultural variations 4. **Visual Integration**: Card imagery and visual representation support
5. **Visual Integration**: Card imagery and visual representation support 5. **Mobile Integration**: React Native or Flutter SDK development
### 📋 Contribution Process ### 📋 Contribution Process
1. **Fork the repository** and create a feature branch 1. **Fork the repository** and create a feature branch
@@ -551,27 +675,27 @@ We welcome contributions to improve the Tarot MCP Server! Here's how you can hel
- **Type Safety**: Maintain 100% TypeScript coverage with strict mode - **Type Safety**: Maintain 100% TypeScript coverage with strict mode
- **Documentation**: Include usage examples and API documentation - **Documentation**: Include usage examples and API documentation
## <EFBFBD>️ Roadmap ## 🗺️ Roadmap
### 📅 Version 2.0 (Planned) ### 📅 Version 2.0 (Planned)
- **Complete 78-Card Deck**: All remaining Minor Arcana cards with full interpretations - **Enhanced Interpretations**: Deeper psychological analysis and Jungian insights
- **Advanced Spreads**: Relationship Cross, Career Path, Spiritual Journey spreads
- **Timing Predictions**: Seasonal influences and time-based guidance - **Timing Predictions**: Seasonal influences and time-based guidance
- **Enhanced AI**: Machine learning for pattern recognition in readings - **Enhanced AI**: Machine learning for pattern recognition in readings
- **Visual Integration**: Card imagery and interactive visual representations
### 📅 Version 2.5 (Future) ### 📅 Version 2.5 (Future)
- **Visual Integration**: Card imagery and interactive visual representations
- **Multi-Language Support**: Internationalization for global accessibility - **Multi-Language Support**: Internationalization for global accessibility
- **Cultural Variations**: Support for different tarot traditions and interpretations - **Cultural Variations**: Support for different tarot traditions and interpretations
- **Advanced Analytics**: Reading history analysis and personal growth tracking - **Advanced Analytics**: Reading history analysis and personal growth tracking
- **Mobile SDK**: Native mobile application support
### 📅 Version 3.0 (Vision) ### 📅 Version 3.0 (Vision)
- **Psychological Integration**: Jungian analysis and psychological tarot methods - **Psychological Integration**: Advanced Jungian analysis and psychological tarot methods
- **Real-Time Collaboration**: Shared readings and collaborative interpretation - **Real-Time Collaboration**: Shared readings and collaborative interpretation
- **Mobile SDK**: Native mobile application support
- **AI-Enhanced Insights**: Advanced pattern recognition and personalized guidance - **AI-Enhanced Insights**: Advanced pattern recognition and personalized guidance
- **Blockchain Integration**: Decentralized reading verification and authenticity
## <EFBFBD>🔮 About This Professional Tarot Implementation ## 🔮 About This Professional Tarot Implementation
### Research-Based Accuracy ### Research-Based Accuracy
This server implements the traditional Rider-Waite tarot deck with interpretations verified against multiple professional sources: This server implements the traditional Rider-Waite tarot deck with interpretations verified against multiple professional sources:
@@ -582,7 +706,7 @@ This server implements the traditional Rider-Waite tarot deck with interpretatio
- **Professional Reader Methods**: Advanced combination interpretation techniques - **Professional Reader Methods**: Advanced combination interpretation techniques
### Comprehensive Card Database ### Comprehensive Card Database
Each card includes extensive information: **✅ COMPLETE**: All 78 cards of the Rider-Waite deck are fully implemented with extensive information for each card:
- **Multi-Context Meanings**: General, love, career, health, and spiritual interpretations - **Multi-Context Meanings**: General, love, career, health, and spiritual interpretations
- **Orientation Specific**: Detailed upright and reversed meanings beyond simple opposites - **Orientation Specific**: Detailed upright and reversed meanings beyond simple opposites

2
package.json
View File

@@ -27,7 +27,7 @@
"divination", "divination",
"ai" "ai"
], ],
"author": "Your Name", "author": "Morax",
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0", "@modelcontextprotocol/sdk": "^1.0.0",