塔罗-MCP

Name: 塔罗-MCP
Author: fzlzjerry

作者：fzlzjerry4 星标更新：2025-07-29

安装使用来源：spider==github.com

项目介绍

技术文档摘要

🔮 Tarot MCP Server

这是一个使用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服务器（标准I/O、HTTP、SSE）
先进的解释引擎，具有元素分析
加密安全的洗牌和抽牌
上下文感知的意义选择
支持CORS的专业级HTTP API
带健康检查的Docker容器化
综合搜索和分析工具
会话管理和阅读历史
完整的TypeScript实现，严格的类型检查
Jest测试框架设置

✨ 功能

🃏 专业塔罗系统

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

🧠 高级解释引擎

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

🚀 技术卓越

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

🎯 实时阅读示例

这里是一个专业的凯尔特十字阅读示例：

{
  "question": "今年我对职业道路应该知道什么？",
  "cards": [
    {"position": "当前情况", "card": "皇帝（正位）", "meaning": "领导机会和职业晋升"},
    {"position": "挑战", "card": "恋人（逆位）", "meaning": "职业生涯选择不当或职场冲突"},
    {"position": "基础", "card": "权杖ACE（正位）", "meaning": "创意火花和新机会"},
    // ... 再有7张牌
  ],
  "analysis": {
    "elementalBalance": "强烈的火元素表明需要行动和创造力",
    "positionDynamics": "意识目标与潜意识驱动一致",
    "energyFlow": "从挑战到解决的进展",
    "guidance": "相信你的领导能力，同时解决人际关系冲突"
  }
}

展示的关键特性：

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

🔮 专业塔罗布局

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

🔮 通用指导

单张牌：每日指导和快速洞察
三张牌：过去/现在/未来的能量流分析
凯尔特十字：全面的10张牌生活分析
马蹄铁：7张牌的情况指导，包括障碍和建议

💕 关系和个人

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

🚀 职业和人生路径

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

🧘 精神和能量工作

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

每个布局都包括：

专门分析：每种布局类型的定制解释方法
位置动力学：理解卡片位置之间的关系
能量评估：元素平衡和流动分析
专业指导：可操作见解和精神智慧

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

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

🚀 快速开始

本地开发

克隆并安装

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

构建项目
```
npm run build
```
作为MCP服务器运行（标准I/O）
```
npm start
# 或
node dist/index.js
```

作为HTTP服务器运行

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

开发模式

npm run dev:http  # 带热重载的HTTP服务器
npm run dev       # 带热重载的标准I/O服务器

Docker部署

快速部署脚本
```
chmod +x deploy.sh
./deploy.sh
```

手动Docker构建

npm run docker:build
npm run docker:run

Docker Compose

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

使用Traefik（可选）
```
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（默认：正位）

专业阅读

POST /api/reading - 执行全面的塔罗阅读

{
  "spreadType": "single_card|three_card|celtic_cross|horseshoe|relationship_cross|career_path|decision_making|spiritual_guidance|year_ahead|chakra_alignment|shadow_work",
  "question": "您的具体问题在这里",
  "sessionId": "用于跟踪的可选会话ID"
}

POST /api/custom-spread - 创建并执行自定义塔罗布局

{
  "spreadName": "您的自定义布局名称",
  "description": "此布局探讨的内容",
  "positions": [
    {
      "name": "位置名称",
      "meaning": "此位置代表的内容"
    }
  ],
  "question": "您的具体问题",
  "sessionId": "可选会话ID"
}

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

高级功能

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

MCP协议

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

🛠️ MCP工具

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

`get_card_info`

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

{
  "cardName": "愚者",
  "orientation": "正位"
}

返回：适用于一般、爱情、职业、健康和精神背景的详细卡片意义。

`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": "今年我对职业道路应该知道什么？",
  "sessionId": "可选会话ID"
}

特性：

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

`search_cards`

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

{
  "keyword": "爱情",
  "suit": "杯子",
  "arcana": "小阿卡纳",
  "element": "水",
  "orientation": "正位",
  "limit": 10
}

特性：

在意义、关键词和象征中进行关键词搜索
按花色、大阿卡纳、元素、数字和方向过滤
可灵活调整的搜索标准和结果限制

`find_similar_cards`

查找给定卡片的相似意义的卡片。

{
  "cardName": "愚者",
  "limit": 5
}

特性：

语义相似性分析
基于意义的卡片关系
可灵活调整的结果限制

`get_database_analytics`

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

{
  "includeRecommendations": true
}

特性：

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

`get_random_cards`

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

{
  "count": 3,
  "suit": "权杖",
  "arcana": "大阿卡纳",
  "element": "火"
}

特性：

加密安全的随机化
可按花色、大阿卡纳或元素过滤
自定义卡片数量

`create_custom_spread`

创建自定义塔罗布局并为其抽牌。当没有现有的布局适合特定需求时，非常适合AI。

{
  "spreadName": "AI决策制定布局",
  "description": "一种自定义布局，旨在帮助AI在没有现有布局适合的情况下做出决策",
  "positions": [
    {
      "name": "当前状况",
      "meaning": "需要解决的现状"
    },
    {
      "name": "隐藏影响",
      "meaning": "影响情况的未见因素"
    },
    {
      "name": "指导",
      "meaning": "最佳决策的智慧和建议"
    }
  ],
  "question": "在这种独特情况下，最好的方法是什么？",
  "sessionId": "可选会话ID"
}

特性：

创建具有1-15个位置的自定义布局
定义自定义位置名称和意义
自动加密安全的卡片抽取
具有位置特定分析的完整解释
会话管理支持
当现有布局不适合特定问题或上下文时，非常适合AI

🔧 配置

命令行选项

node dist/index.js [选项]

选项：
  --transport <类型>    传输类型：标准I/O、HTTP、SSE（默认：标准I/O）
  --port <数字>         HTTP/SSE传输端口（默认：3000）
  --help, -h            显示帮助信息

环境变量

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客户端

对于支持Server-Sent Events的客户端：

{
  "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": "今天我应该拥抱什么样的能量？"
  }'

特性：元素分析、每日指导、精神洞察

三张牌关系阅读

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type: application/json" \
  -d '{
    "spreadType": "three_card",
    "question": "如何改善我的关系？"
  }'

特性：过去/现在/未来的流动，能量进展分析

凯尔特十字职业阅读

curl -X POST http://localhost:3000/api/reading \
  -H "Content-Type:  application/json" \
  -d '{
    "spreadType": "celtic_cross",
    "question": "今年我对职业道路应该知道什么？"
  }'

特性：10张牌的全面分析，位置动力学，意识与潜意识