README.md•5.01 kB
# 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
```