Swift Tarot MCP Server

Swift Tarot MCP Server

タロットカード占い機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーを使うと、AI アシスタントがタロットカードを引いたり、複数枚のカードを使った占いを行ったり、タロットデッキ全体にアクセスしたりできます。

特徴

LLM は人間と同じように、ランダム性の扱いが非常に苦手です。この MCP サーバーは、タロット占いにおいて、より信頼性の高い乱数生成を提供します。

• 柔軟なカードの抽出：1 回のリクエストで 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 の設定

この MCP サーバーを Claude Desktop で使用するには、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

占い用に 1 枚以上のタロットカードを引きます。

パラメーター：

• count（任意）：引くカードの枚数（1〜78、デフォルト：1）

Claude での使用例：

「タロットカードを 1 枚引いて」 「占い用にタロットカードを 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 プロトコルへの準拠
• シード付き RNG による再現可能な動作

以下のコマンドでテストを実行します：

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 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。