Swift Tarot MCP Server

Swift Tarot MCP Server

一个提供塔罗牌占卜功能的 Model Context Protocol（MCP）服务。该服务允许 AI 助手抽取塔罗牌、进行多牌占卜，并访问完整的塔罗牌组。

功能

大模型在随机性方面一向表现不佳，人类也一样。这个 MCP 服务为塔罗牌占卜提供更可靠的随机数生成。

• 灵活抽牌：单次请求可抽取 1 到 78 张塔罗牌
• 完整牌组访问：查看传统塔罗牌组中的全部 78 张牌
• 卡牌图片：获取塔罗牌的 Base64 编码图片
• 确定性测试：使用带种子的随机数生成，确保测试结果一致
• 全面验证：验证输入并妥善处理错误

安装

前置条件

• Swift 5.9 或更高版本
• macOS 13.0 或更高版本
• Just 命令运行器（可选，但推荐安装）

安装 Just（可选）

brew install just

构建和安装

1. 克隆仓库：

git clone <repository-url>
cd swift-tarot-MCP

2. 构建并安装服务：

just install

此操作会构建发布版本，并将其安装到 /usr/local/bin/swift-tarot-MCP。

或者，也可以手动构建：

swift build -c release
sudo cp .build/release/swift-tarot-MCP /usr/local/bin/

Claude Desktop 配置

要在 Claude Desktop 中使用此 MCP 服务，请将以下内容添加到 Claude Desktop 配置文件中：

macOS 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tarot": {
      "command": "swift-tarot-MCP",
      "args": []
    }
  }
}

配置完成后

1. 重启 Claude Desktop
2. 塔罗牌工具现在应该会在对话中可用
3. 你可以让 Claude 抽取塔罗牌、进行占卜或展示完整牌组

可用工具

draw_cards

为占卜抽取一张或多张塔罗牌。

参数：

• count（可选）：抽取的卡牌数量（1-78，默认值：1）

在 Claude 中的使用示例：

“给我抽一张塔罗牌” “给我抽 5 张塔罗牌来占卜”

get_full_deck

返回塔罗牌组中的全部 78 张牌。

在 Claude 中的使用示例：

“给我看看完整的塔罗牌组”

fetch_images

获取塔罗牌 URI 对应的 Base64 编码图片。

参数：

• uris：要获取图片的塔罗牌 URI 数组

在 Claude 中的使用示例：

“给我看看愚者牌的图片”

开发

可用命令

如果已安装 Just，可以使用以下命令：

# Build the project (debug by default)
just build

# Build for release
just build release

# Run tests
just test

# Run tests with verbose output
just test --verbose

# Lint the code
just lint

# Auto-fix linting issues
just lint --fix

# Run the server locally
just run

# Clean build artifacts
just clean

# Install to system PATH
just install

# Remove from system PATH
just uninstall

手动命令

如果没有安装 Just，可以使用以下 Swift 命令：

# Build debug
swift build

# Build release
swift build -c release

# Run tests
swift test

# Run linting
swift package plugin --allow-writing-to-package-directory swiftlint

测试

项目包含全面的测试，涵盖：

• 塔罗牌数据结构和验证
• 牌组组成和抽牌
• 服务处理程序功能
• MCP 协议合规性
• 使用带种子的随机数生成器实现的确定性行为

运行测试：

just test
# or
swift test

架构

项目结构如下：

• TarotMCPCore：核心库，包含塔罗牌逻辑和 MCP 服务实现
• TarotMCP：使用 stdio 传输运行 MCP 服务的可执行程序

核心组件

• TarotCard：表示大阿卡纳和小阿卡纳牌的枚举
• TarotDeck：用于抽牌和管理牌组的静态方法
• TarotServer：MCP 服务实现
• TarotServerHandler：处理 MCP 工具调用和路由

卡牌格式

卡牌以包含卡牌详细信息的 JSON 对象形式返回：

[
  {
    "name": "The Fool",
    "imageURI": "tarot://card/major/0"
  },
  {
    "name": "Two of Cups",
    "imageURI": "tarot://card/minor/cups/2"
  },
  {
    "name": "King of Swords",
    "imageURI": "tarot://card/minor/swords/14"
  }
]

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。