# Dice MCP Server

サイコロを振った結果を返す [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) サーバーです。Python で実装されており、MCP Streamable HTTP トランスポート（仕様バージョン: 2025-03-26）で動作します。

## 概要

MCP クライアントから接続すると、以下のツールが利用できます。

| ツール名 | 説明 |
|----------|------|
| `roll_dice` | 任意の面数のサイコロを任意の回数振り、各ダイスの出目と合計値を返します |

## 前提条件

### ローカル実行

- Python 3.12 以上
- pip

### Docker での実行

- Docker Engine 24.0 以上
- Docker Compose v2

## インストール

### ローカル実行

```bash
git clone https://github.com/your-org/dice-mcp.git
cd dice-mcp
pip install -r requirements.txt
```

### Docker での実行

```bash
docker compose build
```

## 実行方法

### ローカル実行

```bash
# デフォルト設定（0.0.0.0:8000）で起動
python server.py

# ポートを変更する場合
PORT=9000 python server.py
```

### Docker での実行

```bash
# イメージのビルドとコンテナの起動
docker compose up -d

# ログの確認
docker compose logs -f

# 停止
docker compose down
```

起動後、エンドポイント `http://localhost:8000/mcp` で MCP サーバーが利用可能になります。

## ツールの仕様

### `roll_dice`

サイコロを振り、結果を返します。

#### パラメータ

| パラメータ | 型 | デフォルト | 説明 |
|------------|------|-----------|------|
| `sides` | integer | `6` | サイコロの面数（2 以上の整数） |
| `count` | integer | `1` | 振る回数（1〜100 の整数） |

#### レスポンス

| フィールド | 型 | 説明 |
|------------|------|------|
| `results` | array[integer] | 各ダイスの出目リスト |
| `total` | integer | 出目の合計値 |
| `sides` | integer | 使用したサイコロの面数 |
| `count` | integer | 振った回数 |

#### 例

```json
// リクエスト（6面ダイスを 2 個振る）
{
  "name": "roll_dice",
  "arguments": {
    "sides": 6,
    "count": 2
  }
}

// レスポンス
{
  "results": [3, 5],
  "total": 8,
  "sides": 6,
  "count": 2
}
```

## MCP クライアントからの接続

### Claude Desktop

`claude_desktop_config.json` に以下を追記します。

```json
{
  "mcpServers": {
    "dice-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

### VS Code (GitHub Copilot)

ワークスペースの `.vscode/mcp.json` に以下を追記します。

```json
{
  "servers": {
    "dice-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

### その他の MCP クライアント

MCP Streamable HTTP トランスポートをサポートする任意のクライアントから、以下のエンドポイントに接続できます。

```
http://localhost:8000/mcp
```

## 環境変数

| 変数名 | デフォルト | 説明 |
|--------|-----------|------|
| `FASTMCP_HOST` | `0.0.0.0` | サーバーのバインドアドレス |
| `FASTMCP_PORT` | `8000` | サーバーのポート番号 |

`.env.example` をコピーして `.env` を作成することで設定を変更できます。

```bash
cp .env.example .env
```

## ファイル構成

```
dice-mcp/
├── server.py          # MCP サーバーの実装
├── requirements.txt   # Python 依存パッケージ
├── Dockerfile         # コンテナ定義
├── docker-compose.yml # Docker Compose 設定（ローカル開発用）
├── .dockerignore      # Docker ビルド除外設定
├── .env.example       # 環境変数のテンプレート
├── mcp.json           # MCP サーバーマニフェスト（API ディスカバリ・登録用）
├── openapi.yaml       # OpenAPI 仕様書（API 登録用）
└── README.md          # このファイル
```

## ライセンス

MIT