Toy

概要

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

提供ツール

count_letters

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

リクエスト例 (MCPクライアントから送信される想定):

{
  "tool_name": "count_letters",
  "tool_args": {
    "word": "Programming",
    "letter": "m"
  }
}

レスポンス例 (MCPサーバーから返される想定):

{
  "result": 2
}

generate_uuid7s

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

リクエスト例 (MCPクライアントから送信される想定):

{
  "tool_name": "generate_uuid7s",
  "tool_args": {
    "count": 3
  }
}

レスポンス例 (MCPサーバーから返される想定):

{
  "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 が仮想環境を作成（存在しない場合）し、依存関係を同期します。

   uv sync
   

使用方法

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

サーバーを起動するには、プロジェクトのルートディレクトリで以下のコマンドを実行します。

uv run python server.py

または、仮想環境を有効化 (source .venv/bin/activate) している場合は、以下でも起動できます。

python server.py

起動後、MCPクライアントは上記「提供ツール」セクションに記載されたJSON形式でリクエストを標準入力に送信し、結果を標準出力から受け取ります。

Cursor / Windsurf での使用方法

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

{
  "mcpServers": {
    "letter-counter": {
      "command": "uv",
      "args": [
        "--directory",
        "<your_project_directory>",
        "run",
        "server.py"
      ]
    }
  }
}

注意: args 内の --directory のパスは、この README.md があるディレクトリ (プロジェクトのルートディレクトリ) を指すように、ご自身の環境に合わせて適宜修正してください。

開発コマンド (Makefile)

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

• フォーマットと静的解析、テストの実行:

  make test
  

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

• コードフォーマットとチェック:

  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