# Toy

## 概要
FastMCPを利用した、単語内の特定文字の出現回数をカウントするツールと、UUIDv7を生成するツールを提供するシンプルなMCPサーバーです。
`count_letters` ツールは、大文字・小文字を区別せずに文字をカウントします。

## 提供ツール

### `count_letters`
- **機能:** 指定された単語 (`word`) の中に、指定された文字 (`letter`) が何回出現するかを返します。
- **入力:**
  - `word` (文字列): カウント対象の単語。
  - `letter` (文字列): カウントする文字。
- **出力:**
  - `result` (数値): 文字の出現回数。

#### リクエスト例 (MCPクライアントから送信される想定):
```json
{
  "tool_name": "count_letters",
  "tool_args": {
    "word": "Programming",
    "letter": "m"
  }
}
```

#### レスポンス例 (MCPサーバーから返される想定):
```json
{
  "result": 2
}
```

### `generate_uuid7s`
- **機能:** 指定された数のUUIDv7を生成します。デフォルトは1つです。
- **入力:**
  - `count` (数値, オプション): 生成するUUIDの数。デフォルトは1。1以上の整数である必要があります。
- **出力:**
  - `result` (文字列のリスト): 生成されたUUIDv7のリスト。

#### リクエスト例 (MCPクライアントから送信される想定):
```json
{
  "tool_name": "generate_uuid7s",
  "tool_args": {
    "count": 3
  }
}
```

#### レスポンス例 (MCPサーバーから返される想定):
```json
{
  "result": [
    "018fa9e7-7d8a-7b9c-8000-000000000001",
    "018fa9e7-7d8a-7b9c-8000-000000000002",
    "018fa9e7-7d8a-7b9c-8000-000000000003"
  ]
}
```

## セットアップ

### 前提条件
- Python 3.13.1
- Make
- uv (Pythonパッケージ管理ツール)

### 手順
1. 仮想環境の作成と依存関係のインストール:
   `pyproject.toml` にプロジェクトの依存関係が定義されています。以下のコマンドを実行すると、`uv` が仮想環境を作成（存在しない場合）し、依存関係を同期します。
   ```bash
   uv sync
   ```

## 使用方法
このMCPサーバー (`server.py`) は、標準入出力（stdio）を介してMCPクライアントと通信します。

サーバーを起動するには、プロジェクトのルートディレクトリで以下のコマンドを実行します。
```bash
uv run python server.py
```
または、仮想環境を有効化 (`source .venv/bin/activate`) している場合は、以下でも起動できます。
```bash
python server.py
```
起動後、MCPクライアントは上記「提供ツール」セクションに記載されたJSON形式でリクエストを標準入力に送信し、結果を標準出力から受け取ります。

## Cursor / Windsurf での使用方法
Cursor / Windsurf の設定ファイル (`mcp_config.json` など) に以下のように追記することで、このMCPサーバーを利用できます。

```json
{
  "mcpServers": {
    "letter-counter": {
      "command": "uv",
      "args": [
        "--directory",
        "<your_project_directory>",
        "run",
        "server.py"
      ]
    }
  }
}
```
*注意: `args` 内の `--directory` のパスは、この `README.md` があるディレクトリ (プロジェクトのルートディレクトリ) を指すように、ご自身の環境に合わせて適宜修正してください。*

## 開発コマンド (Makefile)
プロジェクトのルートディレクトリで以下の `make` コマンドを実行できます。

- **フォーマットと静的解析、テストの実行:**
  ```bash
  make test
  ```
  このコマンドは、Ruffによるコードフォーマットとチェック、Mypyによる型チェック、Pytestによる単体テスト（カバレッジレポート生成を含む）を一括で実行します。

- **コードフォーマットとチェック:**
  ```bash
  make format
  ```
  このコマンドは、Ruffを使用してコードのフォーマットとチェック（自動修正含む）を実行します。

## ディレクトリ構成
```
.
├── .venv/                           # 仮想環境
├── htmlcov/                         # カバレッジレポート (pytest実行後に生成)
├── tests/
│   ├── __init__.py
│   ├── test_count_letters.py        # count_lettersツールのテスト
│   └── test_generate_uuid7s.py      # generate_uuid7sツールのテスト
├── tools/
│   ├── __init__.py
│   ├── count_letters_tool.py        # count_lettersツールの実装
│   └── generate_uuid_tool.py        # generate_uuid7sツールの実装
├── pyproject.toml                   # プロジェクト設定と依存関係
├── server.py                        # メインのサーバーアプリケーション
├── Makefile                         # 開発用コマンド定義
└── README.md
```