MCP Template

MCP Template

macOS アプリケーションやコマンドラインツール向けの Model Control Protocol（MCP）サーバーを構築するための、基本的な土台を提供するテンプレートリポジトリです。

概要

MCP Template は、プロジェクトに MCP サーバーを実装したい開発者向けの出発点となります。このテンプレートでは、mcp-swift-sdk の基本的な使い方を最小限の形で示しているため、MCP 統合の基本を理解しやすくなっています。他のプロジェクトに統合するためのライブラリテンプレートと、基本的な使い方を説明するシンプルなコマンドラインの例が含まれています。

目的

このリポジトリは、次の用途を想定しています。

• mcp-swift-sdk の使い方を示すリファレンス実装
• 独自の MCP サーバー実装の土台としてフォークまたはクローンできるテンプレート
• MCP の主要な概念を最小限のコードで示す基本的なサンプル

機能

現在および今後予定されている機能は次のとおりです。

• 基本的な Swift パッケージ構成
• コマンドラインの「hello world」サンプルツール
• run コマンドを使用した、MCP との直接通信のためのコマンドライン stdio
• App Store に準拠したコマンドライン stdio → スタンドアロン Mac アプリ間の通信
• Package 内の SSE サーバー → SSE ベースの MCP 用コマンドラインアプリのサンプル

インストール

Swift Package Manager

Package.swift ファイルに以下を追加します。

dependencies: [
    .package(url: "https://github.com/your-username/mcp-template.git", branch: "main"),
]

次に、ターゲットに依存関係を追加します。

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "EasyMCP", package: "mcp-template")
    ]
),

使い方

基本的な例

import EasyMCP

// Create an instance of EasyMCP
let mcp = EasyMCP()

// Register a tool
try await mcp.register(tool: Tool(
    name: "helloPerson",
    description: "Returns a friendly greeting message",
    inputSchema: [
        "type": "object",
        "properties": [
            "name": [
                "type": "string",
                "description": "Name of the person to say hello to",
            ]
        ],
        "required": ["name"]
    ]
)) { input in
    // It's an async closure, so you can await whatever you need to for long running tasks
    await someOtherAsyncStuffIfYouWant()
    // Return your result and flag if it is/not an error
    return Result(content: [.text(hello(input["name"]?.stringValue ?? "world"))], isError: false)
}

// Start the MCP server for full MCP interaction
try await mcp.start()
try await mcp.waitUntilComplete()

コマンドラインの例

このパッケージには、基本的な使い方を示す mcpexample というコマンドライン実行ファイルが含まれています。

# Run the basic hello example
mcpexample hello

# Start the MCP server to handle MCP protocol communications
mcpexample run

プロジェクト構成

ターゲット

1. EasyMCP（ライブラリ）

   • MCP サーバーの最小限のテンプレート実装
   • MCP プロトコルとの基本的な統合方法を示します
   • 公式の mcp-swift-sdk の活用方法を示します
   • シンプルなツールの例（helloworld）が含まれています

2. mcpexample（実行ファイル）

   • EasyMCP ライブラリを使用したシンプルなコマンドラインの例
   • hello コマンドと run コマンドの両方が含まれています
   • run コマンドは stdio トランスポートを使用して、完全な MCP サーバーを起動します
   • CLI 引数の処理に ArgumentParser を使用します

3. EasyMCPTests（テストターゲット）

   • EasyMCP ライブラリの機能をテストするテンプレート
   • hello 関数の基本的なテストが含まれています

依存関係

• swift-argument-parser（1.3.0 以降）- CLI 引数の処理に使用します
• mcp-swift-sdk（ブランチ："feature/wait-for-complete"）- MCP サーバーの終了を待機する機能を追加した、MCP 実装のカスタムフォークです

開発

このテンプレートを独自の MCP サーバーに使用するには、次の手順に従います。

1. リポジトリをクローンまたはフォークします
2. パッケージをビルドして、すべてが正常に動作することを確認します。

   swift build
   

3. テストを実行します。

   swift test
   

4. EasyMCP の実装を変更して、独自の機能を追加します
5. コマンドラインの例を拡張するか、独自の Mac アプリケーションを作成します

カスタム MCP サーバーの診断やデバッグには、MCP Inspector の使用も役立ちます。

$ npx @modelcontextprotocol/inspector

MCP コマンドライン実行ファイルのテスト

MCP Inspector を使用して MCP サーバーをテストおよびデバッグするには、次の手順に従います。

1. Xcode でコマンドライン実行ファイルをビルドします
2. Xcode → Product → Show Build Folder in Finder を選択して、実行ファイルの場所を確認します
3. そのディレクトリから実行ファイルの絶対パスをコピーします
4. MCP Inspector を使用してサーバーをテストします
5. ターミナルを開いて、次のコマンドを実行します。

   npx @modelcontextprotocol/inspector <absolute_path_to_your_executable> run
   

6. 出力に表示されたポートにブラウザーでアクセスします。

   🔍 MCP Inspector is up and running at http://localhost:5173 🚀
   

7. MCP Inspector のインターフェースで「Connect」ボタンを押します
8. アクティビティモニタを開き、実行ファイル名を検索します
9. Inspector とツールのインスタンスが 1 つだけ実行されていることを確認します
10. Xcode → Debug → Attach to Process → 上部で実行ファイル名を探してアタッチします
11. ターミナルで tail -n 20 -f ~/Library/Logs/Claude/mcp*.log を実行します
12. これで、Xcode でブレークポイントを設定しながら、Inspector を通じてサーバーとやり取りできます。

このセットアップにより、強力なデバッグ環境を利用できます。

• Inspector の UI を通じて MCP サーバーの機能をテストする
• コードにブレークポイントを設定して、実行を追跡する
• 動作中に変数や状態を調べる
• リソース、プロンプト、ツールの実装をリアルタイムでデバッグする

デバッグのヒントについては、Anthropic の modelcontextprotocol.io サイトにある MCP Debugging をご覧ください。

ライセンス

MIT ライセンスです。

謝辞

• MCP Swift SDK を提供してくださった loopwork-ai に感謝します