aintmcp-test-tool

TypeScriptで実装したModel Context Protocol (MCP)サーバーのnpmパッケージです。このMCPサーバーは、Windsurf（Claude AIアシスタント）に新しい機能を追加するために使用できます。

機能

このMCPサーバーは以下の機能を提供します：

1. double_number - 数値を2倍にする
2. reverse_text - テキストを反転させる
3. count_characters - テキストの文字数と単語数をカウント
4. fetch_weather - 天気情報を取得する（デモ用）
5. generate_uuid - ランダムなUUIDを生成する

実行方法 (npx)

このMCPサーバーはnpmに公開されており、npxコマンドを使って直接実行できます。個別のインストールは不要です。

1npx aintmcp-test-tool

通常は、Windsurf/Claudeがバックグラウンドでこのコマンドを実行します。

Windsurfとの連携

1. Windsurfの設定ファイルを編集

Windsurfの設定ファイル（mcp_config.json）を以下の場所で編集します：

• Windows: C:\Users\<ユーザー名>\.codeium\windsurf\mcp_config.json
• macOS: ~/Library/Application Support/Codeium/windsurf/mcp_config.json
• Linux: ~/.config/Codeium/windsurf/mcp_config.json

2. MCPサーバーの設定を追加

以下の内容をmcp_config.jsonに追加します（既存の設定がある場合は、mcpServersオブジェクト内に追加）：

1{
2  "mcpServers": {
3    "my-npm-mcp": { // ← 任意のサーバー名
4      "command": "npx",
5      "args": [
6        "aintmcp-test-tool" // ← 公開したパッケージ名
7      ]
8    }
9  }
10}

3. Windsurfの再起動

設定を反映させるために、Windsurfを再起動します。

使用方法

Windsurfのチャットインターフェースで、以下のようにツールを呼び出すことができます：

1. 数値を2倍にする:

   5を2倍にして
   

   または明示的に:

   mcp0_double_numberを使って5を2倍にして
   

2. テキストを反転させる:

   「こんにちは」を反転させて
   

   または明示的に:

   mcp0_reverse_textを使って「こんにちは」を反転させて
   

3. 文字数をカウント:

   「こんにちは世界」の文字数を数えて
   

   または明示的に:

   mcp0_count_charactersを使って「こんにちは世界」の文字数を数えて
   

4. 天気情報を取得:

   東京の天気を教えて
   

   または明示的に:

   mcp0_fetch_weatherを使って東京の天気を教えて
   

   注意: 現在の実装では、引数なしで呼び出す際に技術的な問題が発生することがあります。もし自動選択でエラーになる場合は、以下のようにダミー引数を付けて明示的に呼び出す必要があるかもしれません。

   mcp0_fetch_weatherを使って _dummy="" で天気情報を取得して
   

5. UUIDを生成する:

   UUIDを生成して
   

   または明示的に:

   mcp0_generate_uuidを使ってUUIDを生成して
   

   注意: 天気情報と同様に、もし自動選択でエラーになる場合は、以下のようにダミー引数を付けて明示的に呼び出す必要があるかもしれません。

   mcp0_generate_uuidを使って _dummy="" でUUIDを生成して
   

各ツールの呼び出し結果には、使用されたツール名が含まれるため、どのツールが選択されたかを確認できます。

ツールの自動選択

このMCPサーバーは、ツール名を明示的に指定しなくても、ユーザーの意図に基づいて適切なツールを選択できるように設計されています。これは、各ツールに詳細な説明とパラメータ定義を提供することで実現しています。

ツールが期待通りに選択されているかを確認するには、レスポンスに含まれるツール名（例：[double_number tool]）を確認してください。また、サーバーのログにも呼び出されたツールとその引数が記録されます。

開発者向け情報

必要条件 (開発用)

• Node.js (v16以上)
• npm

ローカルでの開発手順

1. リポジトリのクローン

   1git clone https://github.com/tamanyo/mcp-ts-example.git # またはあなたのリポジトリ
   2cd AINTMCPTest1 # プロジェクトディレクトリ名

2. 依存パッケージのインストール

   1npm install

3. ビルド

   1npm run build

   これにより、buildディレクトリにコンパイルされたJavaScriptファイルが生成されます。

4. ローカル実行

   1node build/index.js

   Windsurfと連携してテストする場合は、mcp_config.json で上記のコマンドとパスを指定します。

npm への公開 (開発者向け)

このプロジェクトをフォークし、独自のバージョンを npm に公開する手順は以下の通りです。

1. package.json の編集:

   • name: npm で ユニークなパッケージ名 に変更します。必要であれば @your-npm-username/package-name のようなスコープ付き名を使用します。
   • version: 公開するバージョン番号を設定します (例: 1.0.0)。
   • description, author, repository.url などのフィールドを適切に更新します。
   • bin フィールドのコマンド名も、新しいパッケージ名に合わせて更新します。

2. ビルド:

   1npm run build

3. npm へのログイン:

   1npm login

   プロンプトに従い、npm のユーザー名、パスワード、メールアドレスを入力します。

4. 公開:

   1npm publish

   • スコープ付きパッケージ (@username/packagename) を公開する場合は、npm publish --access public のように --access public フラグが必要になることがあります。

5. バージョンの更新: パッケージを更新して再公開する場合は、package.json の version を上げる必要があります（例: 1.0.0 -> 1.0.1）。バージョンを上げた後、再度ビルド (npm run build) と公開 (npm publish) を行います。

カスタマイズ

ツールの追加

新しいツールを追加するには、src/index.tsファイルを編集し、以下のパターンに従ってツールを定義します：

1import { z } from "zod";
2
3// ... 他のコード
4
5server.tool(
6  "ツール名",
7  "ツールの詳細な説明（AIが適切に選択できるように）",
8  { // スキーマ定義 (プレーンオブジェクト形式)
9    param1: z.string().describe("パラメータの詳細な説明")
10    // 必要に応じて他のパラメータを追加
11  },
12  ({param1}) => {
13    console.error(`ツール名 tool called with argument: ${param1}`);
14    // ツールの処理
15    const resultText = `処理結果: ${param1}`;
16    return {
17      content: [{type: "text", text: `[ツール名 tool] ${resultText}`}]
18    };
19  },
20);

重要: 引数がないツールや、全ての引数がオプショナルなツールを定義する場合、現状の @modelcontextprotocol/sdk では -32602 エラーが発生する可能性があります。回避策として、以下のようにオプショナルなダミー引数 _dummy をスキーマに追加してください。

1server.tool(
2  "引数なしツール",
3  "引数がないツールの説明",
4  { // ダミー引数を追加
5    _dummy: z.string().optional().describe("内部処理用のダミーパラメータ（無視されます）")
6  },
7  ({_dummy}) => {
8    console.error(`引数なしツール tool called`);
9    const resultText = "ダミー引数付きで実行されました";
10    return {
11      content: [{type: "text", text: `[引数なしツール tool] ${resultText}`}]
12    };
13  },
14);

ツール名の変更

ツール名を変更するには、server.toolの第1引数を変更します。変更後は、npm run buildを実行して変更を反映させてください。

技術的な詳細

このプロジェクトは以下の技術を使用しています：

• TypeScript: 型安全なJavaScriptスーパーセット
• @modelcontextprotocol/sdk: MCPサーバー実装用SDK
• zod: スキーマ定義・検証ライブラリ
• uuid: UUID生成ライブラリ

トラブルシューティング (NPM/NPX)

• npx aintmcp-test-tool がエラーになる:
  • ネットワーク接続を確認してください。
  • npx が最新のパッケージを取得できていない場合、npx clear-npx-cache (または npm cache clean --force 後に再度 npx) を試してみてください。
  • npm レジストリ (registry.npmjs.org) が利用可能か確認してください。
• Windsurfでツールが認識されない:
  • mcp_config.json の設定 (command と args) が正しいか確認してください。
  • Windsurfを再起動して設定を読み込ませてください。
  • npx aintmcp-test-tool が単体で実行できるか確認してください。