tarot-mcp
一个专业级别的塔罗牌解读模型上下文协议(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 | ❌ 最小化类型 |
🚀 快速开始
本地开发
- 克隆并安装
git clone https://git.moraxcheng.me/Morax/tarot-mcp.git cd tarot-mcp npm install - 构建项目
npm run build - 作为MCP服务器运行(标准输入输出)
npm start # or node dist/index.js - 作为HTTP服务器运行
npm run start:http # or node dist/index.js --transport http --port 3000 - 开发模式
npm run dev:http # HTTP server with hot reload npm run dev # stdio server with hot reload
Docker部署
- 使用脚本快速部署
chmod +x deploy.sh ./deploy.sh - 手动Docker构建
npm run docker:build npm run docker:run - Docker Compose
npm run docker:compose # or 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(默认: 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传统
- 专业标准: 实施认证塔罗读者使用的方法
- 象征完整性: 正确解读传统符号和图像
🚢 部署
生产环境部署
- 构建生产版本
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 张卡片分析及位置关系
- 三张卡片流:能量进展和时间分析
- 元素平衡:缺失元素识别和建议
- 原型模式:大阿卡纳进展和精神主题
- 上下文意识:问题特定的意义选择和相关性
专业质量
解读在保持传统塔罗智慧的同时提供:
- 真实语言:专业塔罗术语和措辞
- 可操作的指导:结合实用建议和精神见解
- 深度和细微差别:多层次分析,超越表面意义
- 可访问性:清晰的解释,适合初学者和有经验的读者