🔮 塔罗牌 MCP 服务器

一个基于 Node.js 和 TypeScript 构建的专业级模型上下文协议（MCP）服务器，用于 Rider-Waite 塔罗牌解读。该服务器通过 MCP 协议和 HTTP API 端点提供全面的塔罗功能，包括基于研究的解释和高级解读分析。

服务器配置


{

  "command": "npx",

  "args": ["tarot-mcp-server@latest"],

  "env": {

    "NODE_ENV": "production"

  }

}

🚀 当前实现状态

✅ 完全实现并运行：

包含详细解释的完整 78 张 Rider-Waite 牌组
11 种专业塔罗牌布局（单张牌、三张牌、凯尔特十字、马蹄铁、关系十字、职业路径、决策制定、灵性指导、年度展望、脉轮对齐、阴影工作）
自定义布局创建：当现有布局不适合时，AI 可以创建自定义塔罗牌布局
多传输 MCP 服务器（标准输入输出、HTTP、SSE）
具有元素分析的高级解释引擎
密码学安全的洗牌和抽牌
上下文感知的意义选择
支持 CORS 的专业级 HTTP API
带健康检查的 Docker 容器化
全面的搜索和分析工具
会话管理和解读历史记录
完全使用 TypeScript 实现，并采用严格类型
Jest 测试框架设置

✨ 功能

🃏 专业塔罗系统

基于研究的准确性：解释经过专业塔罗来源（Biddy Tarot, Labyrinthos, 经典文献）验证
完整的 Rider-Waite 牌组：包含详细意义、象征、占星术和数字命理的全面卡片数据库
11 种专业布局：凯尔特十字、关系十字、职业路径、灵性指导、脉轮对齐、年度展望等
自定义布局创建：当现有布局不适合特定问题或上下文时，AI 可以创建无限数量的自定义布局（1-15 个位置）
专门的解读分析：针对关系、职业、灵性成长和能量平衡的定制解释
智能卡牌组合：多维度分析，包括元素平衡、花色模式和数字进展

🧠 高级解释引擎

上下文感知解读：根据问题内容（爱情、职业、健康、灵性）自动选择相关意义
元素分析：火、水、风、土元素平衡评估和缺失元素识别
原型模式：大阿卡纳进展分析和愚人之旅见解
位置动态：凯尔特十字关系分析（意识与潜意识、目标与结果）
能量流评估：三张牌布局进展和整体解读能量分析

🚀 技术卓越

多传输支持：标准输入输出（MCP）、HTTP 和 SSE 协议
密码学随机性：使用密码学安全的随机数生成的 Fisher-Yates 洗牌算法
50/50 公平分布：正位和逆位卡牌方向的相等概率
生产就绪：Docker 容器化、健康检查和全面的错误处理
会话管理：高级上下文跟踪和解读历史记录
RESTful API：直接 HTTP 端点，无缝集成
类型安全：完全使用 TypeScript 实现，并采用严格类型

🎯 实时解读示例

以下是一个专业的凯尔特十字解读示例：


{

  "question": "What should I know about my career path this year?",

  "cards": [

    {"position": "Present Situation", "card": "The Emperor (upright)", "meaning": "Leadership opportunities and career advancement"},

    {"position": "Challenge", "card": "The Lovers (reversed)", "meaning": "Misaligned career choices or workplace conflicts"},

    {"position": "Foundation", "card": "Ace of Wands (upright)", "meaning": "Creative spark and new opportunities"},

    // ... 7 more cards

  ],

  "analysis": {

    "elementalBalance": "Strong Fire energy suggests action and creativity needed",

    "positionDynamics": "Conscious goals align with subconscious drives",

    "energyFlow": "Progression from challenge to resolution",

    "guidance": "Trust your leadership abilities while addressing relationship conflicts"

  }

}

展示的关键功能：

✅ 上下文感知解释（职业导向的意义）
✅ 位置关系分析（意识与潜意识）
✅ 元素平衡评估（火元素主导）
✅ 专业指导和可操作的见解

🔮 专业塔罗牌布局

我们的服务器提供了11 种专为不同生活领域和精神实践设计的塔罗牌布局：

🔮 一般指导

单张牌：日常指导和快速见解
三张牌：过去/现在/未来分析及能量流动- 凯尔特十字：全面的10张牌生命分析
马蹄形：7张牌的情况指导，包括障碍和建议

💕 关系与个人

关系十字：7张牌的关系动态分析

🚀 职业与人生路径

职业路径：6张牌的职业发展指导
决策制定：5张牌的选择评估和指导
年度展望：13张牌的年度预测，包含每月见解

🧘 精神与能量工作

精神指导：6张牌的精神发展和高我连接
脉轮对齐：7张牌的能量中心分析与疗愈
阴影工作：5张牌的心理整合与成长

每个牌阵包括：

专业分析：针对每种牌阵类型的定制解读方法
位置动态：理解牌位之间的关系
能量评估：元素平衡与流动分析
专业指导：可操作的见解和精神智慧

🏆 为什么选择这个塔罗服务器？

特性	本服务器	基础塔罗API	通用读卡器
基于研究的准确性	✅ 经过专业来源验证	❌ 通用含义	❌ 简化解释
高级分析	✅ 元素、数字、原型	❌ 基础牌意	❌ 单层解释
上下文感知	✅ 针对问题的具体含义	❌ 一刀切	❌ 通用响应
专业牌阵	✅ 凯尔特十字动态	❌ 简单布局	❌ 基础定位
MCP集成	✅ 原生MCP + HTTP/SSE	❌ 仅HTTP	❌ 有限协议
生产就绪	✅ Docker、健康检查、监控	❌ 基础部署	❌ 开发聚焦
类型安全	✅ 完整TypeScript	❌ 仅JavaScript	❌ 最小类型

🚀 快速开始

本地开发

克隆并安装 bash

git clone https://git.moraxcheng.me/Morax/tarot-mcp.git
cd tarot-mcp
npm install

构建项目 bash
```
npm run build
```
作为MCP服务器运行（标准输入输出） bash
```
npm start
# or
node dist/index.js
```

作为HTTP服务器运行 bash

npm run start:http
# or
node dist/index.js --transport http --port 3000

开发模式 bash

npm run dev:http  # HTTP server with hot reload
npm run dev       # stdio server with hot reload

Docker部署

使用脚本快速部署 bash
```
chmod +x deploy.sh
./deploy.sh
```
手动Docker构建 bash
```
npm run docker:build
npm run docker:run
```

Docker Compose bash

npm run docker:compose
# or
docker-compose up -d

与Traefik一起使用（可选） bash
```
docker-compose --profile traefik up -d
```

📡 API端点

在HTTP模式下运行时，以下端点可用：

健康与信息

GET /health - 服务状态健康检查
GET /api/info - 服务器信息、功能和可用工具

塔罗牌

GET /api/cards - 列出所有卡片，并提供过滤选项
- ?category=all|major_arcana|minor_arcana|wands|cups|swords|pentacles
GET /api/cards/:cardName - 获取详细的卡片信息
- ?orientation=upright|reversed (默认: upright)

专业解读

POST /api/reading - 执行一次全面的塔罗解读 json

{
  "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",
  "sessionId": "optional-session-id-for-tracking"
}

POST /api/custom-spread - 创建并执行自定义塔罗牌阵 json

{
  "spreadName": "Your Custom Spread Name",
  "description": "What this spread explores",
  "positions": [
    {
      "name": "Position Name",
      "meaning": "What this position represents"
    }
  ],
  "question": "Your specific question",
  "sessionId": "optional-session-id"
}

GET /api/spreads - 列出所有可用的牌阵类型及其描述

高级功能

凯尔特十字分析：10张牌的全面解读，包含位置动态
三张牌流：过去/现在/未来，带能量进展分析
元素平衡：自动分析火、水、风、土元素
上下文感知解释：根据问题内容选择含义
高级卡片搜索：多条件搜索，支持关键词、花色、元素和大阿卡纳过滤
相似性分析：查找具有相关含义和主题的卡片
数据库分析：全面统计和质量指标
安全随机化：加密安全的抽牌和洗牌

MCP协议

GET /sse - 用于MCP客户端的Server-Sent Events端点- POST /mcp - 用于直接协议通信的基于HTTP的MCP端点

🛠️ MCP工具

服务器提供了8种全面的MCP工具，用于专业的塔罗牌解读和分析：

`get_card_info`

获取特定塔罗牌的综合信息，包括象征意义、占星学和数字命理。

{
  "cardName": "The Fool",
  "orientation": "upright"
}

返回: 一般、爱情、事业、健康和精神层面的详细牌意。

`list_all_cards`

列出所有可用的塔罗牌，并提供过滤和分类功能。

{
  "category": "major_arcana|minor_arcana|wands|cups|swords|pentacles|all"
}

返回: 带有关键词和简要描述的组织化卡片列表。

`perform_reading`

进行带有高级解释分析的专业塔罗牌解读。

{
  "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?",
  "sessionId": "optional-session-id"
}

功能:

根据问题内容选择上下文感知的意义
元素平衡分析（火、水、风、土）
花色模式识别与解释
位置动态分析（凯尔特十字）
能量流动评估（三张牌）
关系兼容性分析（关系十字）
职业准备度评估（职业路径）
脉轮能量平衡评估（脉轮对齐）
精神发展指导（精神指导）
年度预测（年度展望）

`search_cards`

使用各种标准（如关键词、花色、元素等）搜索塔罗牌。

{
  "keyword": "love",
  "suit": "cups",
  "arcana": "minor",
  "element": "water",
  "orientation": "upright",
  "limit": 10
}

功能:

意义、关键词和象征意义中的关键词搜索
按花色、大/小阿卡纳、元素、数字和方向筛选
可定制的结果限制

`find_similar_cards`

找到与给定牌具有相似意义的牌。

{
  "cardName": "The Fool",
  "limit": 5
}

功能:

语义相似性分析
基于意义的牌关系
可定制的结果限制

`get_database_analytics`

获取关于塔罗牌数据库的综合分析和统计数据。

{
  "includeRecommendations": true
}

功能:

完整的数据库统计
卡片分布分析
质量指标和建议
数据库完整性评估

`get_random_cards`

获取随机卡片，可选过滤器用于练习和探索。

{
  "count": 3,
  "suit": "wands",
  "arcana": "major",
  "element": "fire"
}

功能:

加密安全的随机化
可选按花色、大/小阿卡纳或元素筛选
可定制的卡片数量

`create_custom_spread`

创建自定义塔罗牌布局并抽取卡片。非常适合在没有现有布局适合特定需求时使用。

{
  "spreadName": "AI Decision Making Spread",
  "description": "A custom spread designed to help AI make decisions when no existing spread fits the situation",
  "positions": [
    {
      "name": "Current Situation",
      "meaning": "The present state of affairs that needs to be addressed"
    },
    {
      "name": "Hidden Influences",
      "meaning": "Unseen factors affecting the situation"
    },
    {
      "name": "Guidance",
      "meaning": "Wisdom and advice for making the best decision"
    }
  ],
  "question": "What is the best approach for this unique situation?",
  "sessionId": "optional-session-id"
}

功能:

创建具有1-15个位置的自定义布局
定义自定义位置名称和意义
自动抽牌，加密安全的随机化
完整的解释，包括位置特定的分析
会话管理支持
非常适合在现有布局不适合特定问题或上下文时使用

🔧 配置

命令行选项


node dist/index.js [options]



Options:

  --transport <type>    Transport type: stdio, http, sse (default: stdio)

  --port <number>       Port for HTTP/SSE transport (default: 3000)

  --help, -h           Show help message

环境变量

NODE_ENV - 环境（开发/生产）
PORT - 服务器端口（默认：3000）

🎯 MCP客户端集成

Cursor IDE

将以下内容添加到您的Cursor mcp.json中：


{

  "mcpServers": {

    "tarot": {

      "command": "npx",

      "args": ["tarot-mcp-server@latest"]

    }

  }

}

或者对于本地开发：


{

  "mcpServers": {

    "tarot": {

      "command": "node",

      "args": ["/path/to/tarot-mcp/dist/index.js"]

    }

  }

}

基于HTTP的MCP客户端

对于支持HTTP MCP的客户端：


{

  "mcpServers": {

    "tarot": {

      "url": "http://localhost:3000/mcp"

    }

  }

}

基于SSE的MCP客户端

对于支持服务器发送事件的客户端：


{

  "mcpServers": {

    "tarot": {

      "url": "http://localhost:3000/sse"

    }

  }

}

📚 使用示例

专业解读示例

单张牌每日指导

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "single_card",
    "question": "What energy should I embrace today?"
  }'

功能: 元素分析、每日指导、精神洞察

三张牌关系解读

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "three_card",
    "question": "How can I improve my relationships?"
  }'

功能: 过去/现在/未来流程、能量进展分析

凯尔特十字职业解读

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "celtic_cross",
    "question": "What should I know about my career path this year?"
  }'

功能: 10张牌的综合分析、位置动态、意识与潜意识洞察

关系十字分析

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "relationship_cross",
    "question": "How can I improve my relationship with my partner?"
  }'

功能: 7张牌的关系动态、兼容性评估、统一/分裂分析

职业路径指导

PLACEHOLDER_CODE_30功能: 6张牌的专业分析、技能评估、机会识别

脉轮能量对齐

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "chakra_alignment",
    "question": "How can I balance my energy centers?"
  }'

功能: 7张牌的脉轮分析、能量平衡评估、灵性疗愈指导

自定义展开创建

curl -X POST http://localhost:3000/api/custom-spread \
  -H "Content-Type: application/json" \
  -d '{
    "spreadName": "AI Decision Making Spread",
    "description": "A custom spread designed to help AI make decisions when no existing spread fits the situation",
    "positions": [
      {
        "name": "Current Situation",
        "meaning": "The present state of affairs that needs to be addressed"
      },
      {
        "name": "Hidden Influences",
        "meaning": "Unseen factors affecting the situation"
      },
      {
        "name": "Option A",
        "meaning": "One potential direction or choice"
      },
      {
        "name": "Option B",
        "meaning": "An alternative direction or choice"
      },
      {
        "name": "Guidance",
        "meaning": "Wisdom and advice for making the best decision"
      }
    ],
    "question": "What is the best approach for creating a new tarot spread when existing ones don'\''t fit?"
  }'

功能: 无限自定义展开创建（1-15个位置）、AI驱动的抽牌、特定位置的解读

卡牌信息查询

详细的卡牌信息

curl "http://localhost:3000/api/cards/The%20Fool?orientation=upright"

按类别浏览卡牌

curl "http://localhost:3000/api/cards?category=major_arcana"
curl "http://localhost:3000/api/cards?category=wands"

列出可用的展开

curl "http://localhost:3000/api/spreads"

高级搜索和分析

按关键词搜索卡牌

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
      }
    }
  }'

查找相似卡牌

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
      }
    }
  }'

获取数据库分析

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_database_analytics",
      "arguments": {
        "includeRecommendations": true
      }
    }
  }'

获取随机卡牌进行练习

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"
      }
    }
  }'

🏗️ 架构

专业塔罗引擎

src/
├── index.ts              # Multi-transport entry point (stdio/HTTP/SSE)
├── http-server.ts        # Production HTTP server with CORS and error handling
├── tarot-server.ts       # Core tarot server with MCP tool integration
└── tarot/
    ├── types.ts          # Comprehensive TypeScript definitions
    ├── card-data.ts      # Research-verified Rider-Waite card database
    ├── card-manager.ts   # Advanced card data management and search
    ├── spreads.ts        # Professional spread definitions and layouts
    ├── reading-manager.ts # Advanced interpretation engine with:
    │                     #   - Elemental balance analysis
    │                     #   - Suit pattern recognition
    │                     #   - Numerical progression interpretation
    │                     #   - Archetypal pattern analysis
    │                     #   - Context-aware meaning selection
    └── session-manager.ts # Session tracking and reading history

关键组件

高级解释引擎

多维度分析: 单张卡牌 + 组合 + 整体主题
专业方法: 基于Biddy Tarot、Labyrinthos和经典来源的研究
上下文感知: 根据问题选择特定含义（爱情、职业、健康、灵性）
元素分析: 火、水、风、土的平衡及缺失元素识别

生产就绪基础设施

多传输支持: stdio (MCP)、HTTP REST API、服务器发送事件
Docker容器化: 完整部署，包括健康检查和监控
错误处理: 全面的错误响应和日志记录
类型安全: 完全使用TypeScript实现，并启用严格模式

🧪 测试与质量保证

测试套件

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

# Code quality checks
npm run lint
npm run format

质量指标

单元测试: 卡牌管理器、解读逻辑和解释引擎
集成测试: API端点和MCP工具功能
类型安全: 100% TypeScript并启用严格模式
代码覆盖率: 核心功能的全面测试覆盖
专业验证: 解读内容经过已建立的塔罗来源验证

研究验证

准确性验证: 交叉引用Biddy Tarot、Labyrinthos和经典文献
传统合规性: 遵循已建立的Rider-Waite传统
专业标准: 实施认证塔罗读者使用的方法
象征完整性: 正确解读传统符号和图像

🚢 部署

生产部署

构建生产版本
```
npm run build
```

使用PM2运行（推荐）

npm install -g pm2
pm2 start dist/index.js --name tarot-mcp -- --transport http --port 3000

或使用Docker

docker run -d -p 3000:3000 --name tarot-mcp tarot-mcp

反向代理设置

示例Nginx配置：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

📄 许可证

MIT许可证 - 详情请参阅LICENSE文件。

🤝 贡献

我们欢迎贡献以改进Tarot MCP Server！以下是您可以帮助的方式：

🎯 优先领域

增强解读: 更深入的心理分析和荣格见解
时间预测: 高级时间预测和季节影响
国际化: 支持多种语言和文化变体
视觉集成: 卡牌图像和视觉表示支持
移动集成: React Native或Flutter SDK开发

📋 贡献流程

分叉仓库并创建一个特性分支
彻底研究 - 所有卡牌含义必须经过专业来源验证
保持质量 - 遵循TypeScript最佳实践并包含全面的测试
文档更新 - 更新README并为新功能添加示例
提交拉取请求 - 附带详细描述和测试覆盖率

🔬 研究标准

主要来源: Biddy Tarot、Labyrinthos、经典塔罗文献
验证: 与多个专业来源交叉引用含义- 传统准确性：保持对既定Rider-Waite传统的遵循
专业语言：使用正宗的塔罗术语和措辞

🧪 测试要求

单元测试：所有新功能必须包含全面的测试
集成测试：API端点和MCP工具验证
类型安全：保持100% TypeScript覆盖率并启用严格模式
文档：包括使用示例和API文档

🗺️ 路线图

📅 版本2.0（计划中）

增强解读：更深入的心理分析和荣格见解
时间预测：季节性影响和基于时间的指导
增强AI：用于读牌模式识别的机器学习
视觉整合：卡牌图像和交互式视觉表示

📅 版本2.5（未来）

多语言支持：国际化以实现全球可访问性
文化差异：支持不同的塔罗传统和解读
高级分析：读牌历史分析和个人成长跟踪
移动SDK：原生移动应用程序支持

📅 版本3.0（愿景）

心理整合：高级荣格分析和心理塔罗方法
实时协作：共享读牌和协作解读
AI增强的见解：高级模式识别和个性化指导
区块链整合：去中心化的读牌验证和真实性

🔮 关于这个专业的塔罗实现

基于研究的准确性

此服务器实现了传统的Rider-Waite塔罗牌，并通过多个专业来源验证了解读：

Biddy Tarot：专业的凯尔特十字方法和高级读牌技巧
Labyrinthos：传统象征和古典解读
经典塔罗文学：历史意义和既定对应关系
专业读者方法：高级组合解读技巧

全面的卡牌数据库

✅ 完整：Rider-Waite牌组中的78张牌已全部实现，每张牌都有详尽的信息：

多上下文含义：一般、爱情、职业、健康和精神解读
方向特定：详细的正位和逆位含义，超越简单的对立
象征分析：对传统Rider-Waite图像的全面解读
占星对应：行星和星座关联
数秘意义：精神和实际的数字含义
元素关联：火、水、风、土能量及其相互作用

高级读牌方法

凯尔特十字动态：专业的10张牌分析及位置关系
三张牌流动：能量进展和时间分析
元素平衡：缺失元素识别和建议
原型模式：大阿卡纳进展和精神主题
上下文意识：问题特定的意义选择和相关性

专业质量

这些解读在保持传统塔罗智慧的同时提供：

真实语言：专业塔罗术语和措辞
可操作的指导：结合实用建议和精神洞见
深度和细微差别：多层次分析超越表面含义
可访问性：清晰的解释适合初学者和有经验的读者

服务配置

[{'args': ['tarot-mcp-server@latest'], 'command': 'npx', 'env': {'NODE_ENV': 'production'}}]

来源

来源：ModelScope
链接：https://github.com/fzlzjerry/tarot-mcp