t

tarot-mcp

moraxcheng/tarot-mcp
0 Stars 312 次浏览 更新于 2026-08-23

一个专业级别的塔罗牌解读模型上下文协议(MCP)服务器,使用Node.js和TypeScript构建。

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "tarot": {
      "url": "http://localhost:3000/sse"
    }
  }
}

服务介绍

🔮 塔罗牌 MCP 服务器

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

🚀 当前实现状态

✅ 完全实现并运行:

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

✨ 功能

🃏 专业塔罗系统

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

🧠 高级解释引擎

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

🚀 技术卓越

  • 多传输支持:stdio(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 张牌生命分析- Horseshoe: 7张牌的情况指导,包括障碍和建议

💕 关系与个人

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

🚀 职业与人生路径

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

🧘 精神与能量工作

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

每个牌阵包括:

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

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

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

🚀 快速开始

本地开发

  1. 克隆并安装
    git clone https://git.moraxcheng.me/Morax/tarot-mcp.git
    cd tarot-mcp
    npm install
    
  2. 构建项目
    npm run build
    
  3. 作为MCP服务器运行(标准输入输出)
    npm start
    # or
    node dist/index.js
    
  4. 作为HTTP服务器运行
    npm run start:http
    # or
    node dist/index.js --transport http --port 3000
    
  5. 开发模式
    npm run dev:http  # HTTP server with hot reload
    npm run dev       # stdio server with hot reload
    

Docker部署

  1. 使用脚本快速部署
    chmod +x deploy.sh
    ./deploy.sh
    
  2. 手动Docker构建
    npm run docker:build
    npm run docker:run
    
  3. Docker Compose
    npm run docker:compose
    # or
    docker-compose up -d
    
  4. 与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 (默认: upright)

专业解读

  • 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": "Your specific question here",
      "sessionId": "optional-session-id-for-tracking"
    }
    
  • POST /api/custom-spread - 创建并进行自定义塔罗牌阵
    {
      "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": "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张牌的关系动态、兼容性评估、统一/分裂分析

职业路径指导

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

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

脉轮能量对齐

PLACEHOLDER_CODE_29功能: 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传统
  • 专业标准: 实施认证塔罗读者使用的方法
  • 象征完整性: 正确解读传统符号和图像

🚢 部署

生产环境部署

  1. 构建生产版本
    npm run build
    
  2. 使用PM2运行(推荐)
    npm install -g pm2
    pm2 start dist/index.js --name tarot-mcp -- --transport http --port 3000
    
  3. 或者使用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!以下是您可以帮助的方式:

🎯 优先领域

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

📋 贡献流程

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

🔬 研究标准

  • 主要来源: 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 张卡片分析及位置关系
  • 三张卡片流:能量进展和时间分析
  • 元素平衡:缺失元素识别和建议
  • 原型模式:大阿卡纳进展和精神主题
  • 上下文意识:问题特定的意义选择和相关性

专业质量

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

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

相关 MCP 服务