MCP Lab

MCP Lab

このリポジトリは、TypeScript を使って Model Context Protocol（@modelcontextprotocol/sdk）の SDK を試している個人用の実験場です。主な目的は、プロトコルの仕組みをしっかり理解し、手早くテストを行い、ツールに慣れるにつれて、より実用的なユースケースを構築することです。

プロジェクトの構成

.
├── 📂 mcp-server-dummies/   # Primeros pasos usando el SDK de MCP.
├── 📂 mcp-lab-text2sql/     # Caso de uso avanzado: Text-to-SQL sobre una base de datos SQLite.
├── 📂 mcp-client/           # Integración con OpenAI API para su integración con un Server MCP.

🧪 mcp-server-dummies

このプロジェクトには、MCP SDK に慣れるための基本的な実装が含まれています。プロトコルを初めて使うためのものとして考案され、簡単なテストや仕組みの理解に役立ちます（特別な機能はありません）。

インストール

メモ

このプロジェクトには Node.js >= v20 が必要です。

cd mcp-server-dummies
npm i

実行

npm run build     # Compila el proyecto con tsc
npm run dev       # Ejecuta el servidor con ts-node

デバッグツールとして、次のコマンドを使って MCP Inspector を起動できます。このユーティリティは、MCP サーバーをより簡単かつ対話的にテスト、デバッグするための視覚的なインターフェースを提供します。

npm run test

このコマンドを実行すると、MCP サーバーに紐付いた Inspector が http://localhost:6274 で利用できるようになります。

💬 mcp-lab-text2sql

この 2 つ目のプロジェクトでは、自然言語を使って SQLite データベースとチャットできる Text-to-SQL システムを実装しています。この MCP サーバーは、LLM がデータとチャットするために必要なツールとリソースを公開します。

インストール

メモ

このプロジェクトには Node.js >= v20 が必要です。

cd mcp-server-dummies
npm i

実行

npm run build     # Compila el proyecto con tsc
npm run dev       # Ejecuta el servidor con ts-node

デバッグツールとして、次のコマンドを使って MCP Inspector を起動できます。このユーティリティは、MCP サーバーをより簡単かつ対話的にテスト、デバッグするための視覚的なインターフェースを提供します。

npm run test

このコマンドを実行すると、MCP サーバーに紐付いた Inspector が http://localhost:6274 で利用できるようになります。

Claude Desktop

Claude Desktop から MCP サーバーを試すことができます。MCP サーバーを登録するには、claude_desktop_config.json ファイルを次のように変更します。

{
    "mcpServers": {
        "mcp-lab-dummies": {
            "command": "node",
            "args": [
                "C://PATH//mcp-lab//mcp-server-dummies//dist//index.js"
            ]
        },
        "mcp-lab-text2sql": {
            "command": "node",
            "args": [
                "C://PATH//mcp-lab//mcp-server-text2sql//dist//index.js"
            ]
        }
    }
}

重要

事前に各プロジェクト内で npm run build を実行してください。

Windows での claude_desktop_config.json の保存場所 ➡️ PATH//AppData//Roaming//Claude。

この設定ファイルの構文や場所について詳しくは、公式ドキュメントを参照してください。

OpenAI との互換性

OpenAI で MCP サーバーを使用する場合、ツールであれば問題なく動作します。しかし、リソースを利用しようとすると、すべてがより複雑になります。

メモ

注意：OpenAI Agents SDK では MCP サーバーをネイティブに使用できますが、現時点ではこの SDK は Python でのみ利用可能です。私の場合、Responses API を使用し、OpenAI の TypeScript SDK でテストしています。

さて……Claude Desktop から利用できる複数のツールを公開する MCP サーバーがあります。ここまでは問題ありません。しかし、この同じ MCP サーバーを OpenAI API で動作するエージェントで使えるのでしょうか？

まず、GPT モデルを使用して MCP サーバーに接続することには互換性がありません。@modelcontextprotocol と OpenAI のツール定義は異なります。これは利用できないということでしょうか？ そうとは限りません。この連携を可能にする MCP クライアントを構築しましょう。

重要

この仕様は、OpenAI TypeScript SDK のバージョン 4.95.0 および @modelcontextprotocol/sdk のバージョン 1.9.0 と互換性があります。

MCP クライアントの getTools() 関数が返す型：

import type { Tool } from "@modelcontextprotocol/sdk/types.js";

const mcpTool: Tool = {
  name: "getUser",
  description: "Get a user by ID",
  inputSchema: z.object({
    type: z.literal("object"),
    properties: z.object({
      id: z.string()
    })
  })
}

ツールを扱うために、OpenAI Responses API が期待する型：

OpenAI のドキュメント

import OpenAI from "openai";

// El campo "parameters" es un JSON Schema

const openaiTool: OpenAI.Responses.Tool {
  "type": "function",
  "name": "getUser",
  "description": "Get a user by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string" }
    },
    "required": ["id"],
    "additionalProperties": false
  },
  "strict": true
}

制限事項

MCP サーバーでツールを設定する際、Zod を使用して引数の型を定義する場合は、OpenAI と互換性のないオプションがあることに注意してください。

すべてのパラメーターを必須にする必要があります：

Invalid schema for function 'update-user-goal': In context=(), 'required' is required to be supplied and to be an array including every key in properties.

int() フィールドの定義時に max() または min() は使用できません：

Invalid schema for function 'update-user-goal': In context=('properties', 'age', 'anyOf', '0'), 'minimum|maximun' is not permitted.

デフォルト値の設定に default() は使用できません：

BadRequestError: 400 Invalid schema for function 'update-user-goal': In context=('properties', 'hasPaid', 'anyOf', '0'), 'default' is not permitted.

デモ test

メモ

このプロジェクトには Node.js >= v20 が必要です。

OpenAI を使用する LLM エージェントでデモを実行します。

1. mcp-server-dummies ディレクトリ内で npm run build を実行します。ここで使用する MCP サーバーがこのディレクトリにあるためです。

2. mcp-client ディレクトリ内で npm i を実行して、依存関係をインストールします。

3. mcp-client ディレクトリ内で、npm run dev コマンドを使用してデモを実行します。

• mcp-client 内に、有効な OpenAI API キーを設定した .env を作成するのを忘れないでください：

  OPENAI_API_KEY=<openai_key>
  

📄 ライセンス

MIT © rperezll