Custom MCP Server with Enhanced Tools

強化ツールを備えたカスタム MCP サーバー

このプロジェクトでは、Cursor 内で AI アシスタントの機能を直接拡張する5 つのカスタムツールを備えた、強力な MCP（Model Context Protocol）サーバーを紹介します。AI Makerspace MCP フレームワークを基盤とするこのサーバーには、ウェブ検索、ユーティリティツール、コンテンツ生成機能が含まれています。

🚀 特長

利用可能なツール：

🔍 ウェブ検索 - Tavily API 連携によるウェブ検索
🎲 サイコロローラー - カスタム記法（例：2d20k1）でサイコロを振ります
📱 QR コード生成 - 任意のテキストや URL の QR コードを生成します
🔄 単位変換 - さまざまな単位（長さ、重量、温度、体積）を変換します
🔗 URL 短縮 - TinyURL または is.gd サービスを使用して URL を短縮します

プロジェクト概要

この MCP サーバーは Model Context Protocol を通じて Cursor とシームレスに連携し、AI アシスタント内から強力なツールにすぐにアクセスできるようにします。サーバーは標準入力／出力（stdio）トランスポートモードで動作するよう設計されており、次の機能を備えています。

• TavilyClient：Tavily API を使用したウェブ検索機能
• QR コード生成：qrcode ライブラリを使用した Base64 エンコード済み QR コード
• 単位変換：温度を手動で処理する包括的な単位変換
• URL 短縮：複数のサービスに対応（TinyURL、is.gd）
• サイコロを振る機能：最大値を残す機能を備えた高度なサイコロ記法

前提条件

• Python 3.13 以降
• 有効な Tavily API キー
• UV パッケージマネージャー（依存関係の管理用）

⚠️NOTE FOR WINDOWS:⚠️

OS の Windows 側にインストールする必要があります。

そのためには、次の手順で Powershell 用の CLI ツールを 2 つインストールします。

• winget install astral-sh.uv
• winget install --id Git.Git -e --source winget

これらの CLI ツールをインストールしたら、Cursor を Windows 内で開いてください。

インストール

1. リポジトリをクローンします：

   git clone https://github.com/suh4s/my-mcp-server.git
   cd my-mcp-server
   

2. 依存関係をインストールします：

   uv sync
   

3. 環境変数を設定します： .env ファイルを作成し、Tavily API キーを追加します。

   TAVILY_API_KEY=your_api_key_here
   

MCP サーバーの実行

MCP サーバーを起動するには、Cursor の MCP プロファイルに以下を追加する必要があります。

注：MCP の設定を開くには、コマンドパレット（CMD/CTRL+SHIFT+P）を使用して「View: Open MCP Settings」を選択し、内容を以下の JSON 設定に置き換えてください。

{
    "mcpServers": {
        "mcp-server": {
            "command": "uv",
            "args": ["--directory", "/FULL/PATH/TO/YOUR/REPOSITORY", "run", "server.py"]
        }
    }
}

サーバーが起動し、標準入力／出力を介してコマンドを受け付けます。

🛠️ ツールの使用例

QR コード生成

"Generate a QR code for 'Hello World'"
"Create a QR code for https://github.com/suh4s/my-mcp-server"

単位変換

"Convert 100 fahrenheit to celsius"
"Convert 5 miles to kilometers"
"Convert 2 pounds to grams"

URL 短縮

"Shorten this URL: https://github.com/suh4s/my-mcp-server"
"Shorten https://example.com using is.gd"

サイコロローラー

"Roll 2d20k1" (roll 2 20-sided dice, keep highest)
"Roll 3d6" (roll 3 6-sided dice)

ウェブ検索

"Search for 'MCP protocol documentation'"
"Find recent AI news"

🔧 技術的な実装

依存関係：

• mcp[cli] - Model Context Protocol フレームワーク
• tavily-python - ウェブ検索 API 連携
• qrcode + pillow - QR コード生成
• pint - 単位変換ライブラリ
• requests - URL 短縮用の HTTP リクエスト
• python-dotenv - 環境変数の管理

アーキテクチャ：

• FastMCP Server：ツールの登録とプロトコル通信を処理します
• ツール関数：自動検出のために @mcp.tool() で装飾されています
• エラー処理：わかりやすいメッセージを含む包括的なエラー処理
• 型安全性：すべてのツールパラメーターに完全な型ヒントを付与

🎯 高度な機能

• 温度変換：華氏／摂氏変換に対応するカスタム数式
• QR コードのカスタマイズ：サイズと枠線のパラメーターを調整可能
• 複数の URL サービス：TinyURL および is.gd に対応し、フォールバック処理も実装
• サイコロ記法：最大値を残すロジックを備えた複雑なサイコロ式に対応

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

コントリビューション

コントリビューションを歓迎します！変更を提案する場合は、イシューを作成するか、プルリクエストを送信してください。

謝辞

AI Makerspace MCP Session の一環として構築されました。オリジナルのフレームワークは AI-Maker-Space によるものです。