麻雀点数計算 MCP サーバー

Claude ProjectsやClaude Desktopから麻雀の点数計算ができるMCPサーバーです。

特徴

• テキスト形式で牌姿を入力（例: 123m456p789s11z）
• 赤ドラ対応（0で表現、例: 50m = 赤5萬）
• 点数、役、翻数、符を自動計算
• Claude Desktopからツールとして直接呼び出し可能
• stdio/SSE両方のトランスポートに対応

MCPサーバーとは

MCP (Model Context Protocol) は、Claude DesktopとAIツール間の通信プロトコルです。MCPサーバーを作成することで、Claudeに新しい機能（ツール）を追加できます。

このプロジェクトでは、麻雀の点数計算をClaudeから呼び出せるようにしています。

トランスポート方式

MCPサーバーには2つの接続方式があります：

• stdio（標準入出力）: Claude Desktopがサーバープロセスを直接起動・管理（推奨）
• SSE（Server-Sent Events）: HTTPサーバーとして常駐し、Claude Desktopが接続

このプロジェクトでは、安定性と管理の容易さから stdio方式 を推奨しています。

セットアップ

1. 依存関係のインストール

uv sync

2. Claude Desktop での設定

設定ファイルの場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

#### Linux/macOS（ネイティブ環境）の場合

{
  "mcpServers": {
    "mahjong-calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mahjong_calculator",
        "run",
        "python",
        "-m",
        "src.server"
      ]
    }
  }
}

注意: /absolute/path/to/mahjong_calculator の部分は、このプロジェクトの絶対パスに置き換えてください。

#### Windows + WSL環境の場合（推奨設定）

Windows上のClaude DesktopからWSL内のMCPサーバーを起動する場合:

{
  "mcpServers": {
    "mahjong-calculator": {
      "command": "wsl",
      "args": [
        "-e",
        "bash",
        "-c",
        "export PATH=$HOME/.local/bin:$PATH && cd /home/your-username/projects/mahjong_calculator && exec uv run python -m src.server"
      ]
    }
  }
}

重要:

• /home/your-username/projects/mahjong_calculator をWSL内の実際のプロジェクトパスに置き換えてください
• your-username をWSLのユーザー名に置き換えてください
• この設定は、一行のコマンドとして実行されるため、確実に動作します

3. Claude Desktopを再起動

設定を反映させるため、Claude Desktopを完全に終了してから再起動してください。

使用方法

Claude DesktopやClaude Projectsで以下のように質問してください：

基本的な使い方

手牌: 234m345p456s6677z
和了牌: 7z
の点数を教えて

注意: 手牌（13枚）と和了牌（1枚）の合計14枚が正しい和了形（4面子1雀頭）である必要があります。

立直ツモの場合

手牌: 234m234p234s555z
和了牌: 5z
でツモ和了、立直ありの場合の点数を計算して

ドラありの場合

手牌: 234m456p678s3344s
和了牌: 5s
でロン和了、ドラ表示牌が1mの場合の点数は？

入力形式

牌の表記

• 萬子: 1-9m（例: 123m）
• 筒子: 1-9p（例: 456p）
• 索子: 1-9s（例: 789s）
• 字牌: 1-7z
• 1z = 東
• 2z = 南
• 3z = 西
• 4z = 北
• 5z = 白
• 6z = 發
• 7z = 中
• 赤ドラ: 0で表現（例: 50m = 赤5萬）

例

パラメータ

MCPツール calculate_mahjong_score は以下のパラメータを受け付けます：

トラブルシューティング

Claude Desktopで認識されない

1. 設定ファイルのパスと形式を確認

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• JSON構文エラーがないか確認（JSONLintで検証可能）
• ファイルをUTF-8で保存しているか確認

1. プロジェクトのパスが絶対パスになっているか確認

• 相対パスは使用できません
• WSL環境の場合: /home/username/... 形式

1. WSL環境での確認事項

• uv コマンドが正しくインストールされているか確認:

     which uv
     uv --version

• PATHが正しく設定されているか確認
• Windows側から手動でコマンドを実行してテスト:

     wsl -e bash -c "export PATH=$HOME/.local/bin:$PATH && cd /home/username/projects/mahjong_calculator && uv run python -m src.server"

1. Claude Desktopを完全に再起動

• Windowsの場合: タスクマネージャーでプロセスが完全に終了していることを確認
• 設定変更後は必ず再起動が必要

サーバーを再起動すると接続できなくなる（WSL環境）

問題: ローカルでSSE形式のサーバーを起動した場合、再起動後にClaude Desktopから接続できなくなる

解決策: stdio形式を使用する（上記の「Windows + WSL環境の場合」の設定）

stdio形式の利点:

• Claude Desktopがサーバープロセスのライフサイクルを管理
• ポートの競合や接続問題が発生しない
• 設定が簡単で安定している

SSE形式を使いたい場合

どうしてもSSE形式を使いたい場合は、以下の手順で起動:

bash /home/miz/projects/mahjong_calculator/start_http_server.sh

設定ファイル:

{
  "mcpServers": {
    "mahjong-calculator": {
      "url": "http://localhost:8000/sse"
    }
  }
}

注意: SSE形式は手動でサーバーを起動・停止する必要があり、管理が煩雑です。

計算結果がおかしい

1. 入力形式が正しいか確認

• 萬子: m, 筒子: p, 索子: s, 字牌: z
• 数字は0-9のみ（0は赤ドラ）
• 例: 123m456p789s1122z

1. 手牌が14枚になっているか確認

• 手牌13枚 + 和了牌1枚 = 合計14枚
• 正しい和了形（4面子1雀頭）である必要があります

1. 和了っているか確認

• 向聴数が-1（テンパイを超えている状態）

Claude Desktopのログを確認

MCPサーバーのログは標準エラー出力に出力されます。Claude Desktopのログで詳細を確認できます：

• macOS: ~/Library/Logs/Claude/
• Windows: %APPDATA%\Claude\logs\

ログで以下を確認:

• サーバーが正常に起動しているか
• コマンドのパスが正しいか
• 実行時エラーが発生していないか

開発

ローカルでのテスト

MCPサーバーとして起動せずに、直接Pythonスクリプトとして動作確認できます：

# JSON出力のテスト
uv run python test_json_output.py

# エラーケースのテスト
uv run python test_error_cases.py

MCPサーバーのテスト

stdio形式で手動テスト:

bash start_stdio_server.sh

SSE形式で手動テスト（別ターミナルで実行）:

# サーバー起動
bash start_http_server.sh

# 別ターミナルでアクセスを確認
curl http://localhost:8000/sse

テストの実行

uv run pytest

型チェック

uv run mypy src/

コードフォーマット

uv run ruff check src/

依存関係の更新

# 依存関係を追加
uv add package-name

# 依存関係を更新
uv sync --upgrade

プロジェクト構成

mahjong_calculator/
├── pyproject.toml              # プロジェクト設定・依存関係
├── uv.lock                     # 依存関係のロックファイル
├── README.md                   # このファイル
├── main.py                     # スタンドアロン実行用（MCP不使用）
├── start_http_server.sh        # SSE形式でのサーバー起動スクリプト
├── start_stdio_server.sh       # stdio形式でのサーバー起動スクリプト
├── test_json_output.py         # JSON出力のテスト
├── test_error_cases.py         # エラーケースのテスト
└── src/
    ├── __init__.py             # パッケージ初期化
    ├── constants.py            # 定数定義
    ├── tile_parser.py          # 入力解析（テキスト→内部形式）
    ├── calculator.py           # 点数計算ロジック
    └── server.py               # MCPサーバー（エントリーポイント）

ファイルの役割

#### コアモジュール

• server.py: MCPサーバーのエントリーポイント。Claude Desktopとの通信を担当
• calculate_mahjong_score(): MCPツールとして公開される関数
• stdio/SSE両方のトランスポートに対応

• calculator.py: 麻雀の点数計算ロジック
• calculate_hand(): 手牌と和了牌から点数を計算
• GameContext: 対局状況（自風、場風、リーチなど）を管理
• 役、符、点数の詳細を返す

• tile_parser.py: テキスト形式の牌姿を解析
• 123m456p789s11z のような入力をmahjongライブラリの形式に変換
• 赤ドラ（0）の処理に対応

• constants.py: 役名や符の理由の日本語翻訳など、定数を定義

#### 起動スクリプト

• start_stdio_server.sh: stdio形式でサーバーを起動（Claude Desktop推奨）
• start_http_server.sh: SSE形式（HTTP）でサーバーを起動

#### テスト

• test_json_output.py: 計算結果のJSON形式をテスト
• test_error_cases.py: エラーハンドリングをテスト

アーキテクチャ

Claude Desktop
    ↓ (MCP stdio/SSE)
server.py (FastMCP)
    ↓
calculator.py (計算ロジック)
    ↓
tile_parser.py (入力解析)
    ↓
mahjong-python (外部ライブラリ)

1. Claude Desktop が MCP プロトコルでリクエストを送信
2. server.py が calculate_mahjong_score ツールとしてリクエストを受信
3. tile_parser.py が牌姿テキストを解析
4. calculator.py が mahjong-python ライブラリを使って計算
5. 結果を JSON 形式で Claude Desktop に返却

ライセンス

このプロジェクトは個人用です。