はじめてのModel Context Protocol (MCP)

#

## はじめに

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) は、大規模言語モデル（LLM）とアプリケーション間の通信を標準化するためのプロトコルです。このガイドでは、MCPの基本概念から実装まで、実践的な例を交えて解説します。

## 目次
1. [MCPの基礎知識](#1-mcpの基礎知識)
2. [開発環境のセットアップ](#2-開発環境のセットアップ)
3. [MCPサーバーの実装](#3-mcpサーバーの実装)
4. [実践的な使用例](#4-実践的な使用例)
5. [トラブルシューティング](#5-トラブルシューティング)
6. [発展的なトピック](#6-発展的なトピック)

## 1. MCPの基礎知識

### 1.1 MCPとは
Model Context Protocol (MCP) は、LLMとアプリケーション間でコンテキストや機能を共有するための標準プロトコルです。以下の特徴があります：

- **標準化された通信**: LLMとツール間の一貫した通信方法を提供
- **コンテキスト共有**: LLMに追加の機能やデータを提供する仕組み
- **双方向通信**: LLMとアプリケーション間の双方向のデータ交換
- **拡張性**: 新しい機能やツールの追加が容易

### 1.2 主要な概念
- **MCPサーバー**: ツールやリソースを提供するサーバープログラム
- **ツール**: LLMが利用可能な機能（関数やコマンド）
- **リソース**: LLMがアクセス可能なデータや状態
- **トランスポート**: 通信方式（標準入出力、WebSocket等）

### 1.3 アーキテクチャ
```mermaid
graph LR
    A[LLM] <--> B[MCP Protocol]
    B <--> C[MCPサーバー]
    C --> D[ツール]
    C --> E[リソース]
```

## 2. 開発環境のセットアップ

### 2.1 必要なソフトウェア
- Node.js (v18以上推奨)
- TypeScript
- お好みのコードエディタ（VS Code推奨）

### 2.2 環境構築手順

1. Node.jsのインストール（macOSの場合）:
```bash
brew install node
```

2. プロジェクトの初期化:
```bash
mkdir mcp-project
cd mcp-project
npm init -y
```

3. 必要なパッケージのインストール:
```bash
npm install @modelcontextprotocol/sdk typescript @types/node
```

4. TypeScript設定:
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./build"
  }
}
```

## 3. MCPサーバーの実装

MCPサーバの実装例としてexample-mcp-serverの実装と使用方法について説明します。

### 3.1 基本情報
- サーバー名: `time`
- バージョン: `1.0.0`
- 主な機能: 現在時刻の取得（ISO 8601形式）
- 実装言語: TypeScript
- 実行環境: Node.js

### 3.2 提供機能
#### get_current_time
- 機能: 現在時刻をISO形式で返す
- 入力パラメータ: なし
- 戻り値: テキスト形式での現在時刻（UTC）


### 3.3 基本的なサーバー実装

```typescript
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// サーバーインスタンスの作成
const server = new McpServer({
  name: "example-server",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

// ツールの登録
server.tool(
  "hello_world",
  "Say hello to the world",
  {},
  async () => {
    return {
      content: [
        {
          type: "text",
          text: "Hello, World!",
        },
      ],
    };
  }
);

// サーバーの起動
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});
```

### 3.4 実装のポイント

1. **サーバー設定**
   - 名前とバージョンの指定
   - 機能（capabilities）の定義
   - エラーハンドリングの実装

2. **ツールの実装**
   - 機能名と説明の定義
   - パラメータスキーマの設定
   - 非同期処理の適切な実装

3. **トランスポートの選択**
   - 標準入出力（stdio）の使用
   - WebSocketなど他の通信方式も選択可能

## 4. 実践的な使用例

### 4.1 時刻取得サーバーの実装

```typescript
server.tool(
  "get_current_time",
  "Get the current time",
  {},
  async () => {
    const currentTime = new Date().toISOString();
    return {
      content: [
        {
          type: "text",
          text: currentTime,
        },
      ],
    };
  }
);
```

### 4.2 パラメータを受け取るツール

```typescript
server.tool(
  "format_time",
  "Format the time in a specific timezone",
  {
    type: "object",
    properties: {
      timezone: { type: "string" },
    },
    required: ["timezone"],
  },
  async (params) => {
    const time = new Date().toLocaleString("ja-JP", {
      timeZone: params.timezone,
    });
    return {
      content: [
        {
          type: "text",
          text: time,
        },
      ],
    };
  }
);
```

## 5. トラブルシューティング

### 5.1 よくある問題と解決方法

1. **サーバーが起動しない**
   - Node.jsのバージョン確認
   - 依存パッケージの整合性確認
   - TypeScriptのコンパイルエラーの確認

2. **ツールが認識されない**
   - ツール名の一意性確認
   - パラメータスキーマの正確性確認
   - 非同期関数の適切な実装確認

3. **通信エラー**
   - トランスポート設定の確認
   - 標準入出力の適切な使用
   - エラーハンドリングの実装確認

### 5.2 デバッグのベストプラクティス

1. ログ出力の活用
```typescript
console.error("Debug:", { 
  event: "tool_called",
  tool: "get_current_time",
  timestamp: new Date().toISOString()
});
```

2. エラーハンドリング
```typescript
try {
  // ツールの処理
} catch (error) {
  console.error("Error in tool:", error);
  throw new Error("Tool execution failed");
}
```

## 6. 発展的なトピック

### 6.1 高度な機能実装

1. **複数のツール連携**
```typescript
// ツール間でのデータ共有
const sharedState = new Map();

server.tool("set_data", "Set shared data", {/*...*/}, 
  async (params) => {
    sharedState.set(params.key, params.value);
    return {/*...*/};
  }
);

server.tool("get_data", "Get shared data", {/*...*/},
  async (params) => {
    return {
      content: [{ 
        type: "text", 
        text: sharedState.get(params.key)
      }]
    };
  }
);
```

2. **リソース管理**
```typescript
const server = new McpServer({
  name: "advanced-server",
  version: "1.0.0",
  capabilities: {
    resources: {
      config: {
        type: "object",
        properties: {
          settings: { type: "object" }
        }
      }
    },
    tools: {}
  }
});
```

### 6.2 セキュリティ考慮事項

1. **入力バリデーション**
   - パラメータの型チェック
   - 値の範囲チェック
   - 不正な入力の防御

2. **エラー処理**
   - 適切なエラーメッセージ
   - エラーの種類分け
   - リカバリー処理

3. **アクセス制御**
   - ツールの使用制限
   - リソースへのアクセス制限
   - ログの適切な管理

## 7. CursorでのMPC設定

### 7.1 Cursorの基本設定

Cursorは、MCPを活用したAIペアプログラミングを実現するIDEです。以下の手順でMCPの設定を行います：

1. **Cursorのインストール**
   - [Cursor公式サイト](https://cursor.sh)からダウンロード
   - インストール後、初回起動時にAI設定を完了

### 7.2 MCPサーバーのCursor統合
Cursorの画面右上のギアマークをクリックし、Setting画面を開きます。

![スクリーンショット 2025-06-08 16.04.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/192442/3b424fe9-b1b0-4874-ae02-6083b42d1256.png)

Cursor SettingsのMCP Toolsを選択。
新しくMCPサーバを追加するときは、NewMCPServerをクリック。
![スクリーンショット 2025-06-08 16.06.17.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/192442/94ca2ac4-a908-4fae-8768-c163cf414fde.png)

MCP.jsonに下記を追加します。
初めての場合は下記JSONを丸ごとコピー、すでにいくつか登録されている場合は、Server以下をJSON形式で追加してください。

1. **プロジェクトの設定**
```json
{
  "mcp": {
    "server": {
      "name": "your-server-name",
      "transport": "stdio",
      "command": ["node", "dist/server.js"]
    }
  }
}
```

2. **デバッグ設定**
```json
{
  "launch": {
    "configurations": [
      {
        "type": "node",
        "request": "launch",
        "name": "Debug MCP Server",
        "program": "${workspaceFolder}/dist/server.js",
        "preLaunchTask": "tsc: build"
      }
    ]
  }
}
```

## まとめ

MCPは、LLMとアプリケーションを効果的に連携させるための強力なプロトコルです。基本的な実装から高度な機能まで、段階的に理解を深めることで、より効果的なLLMアプリケーションの開発が可能になります。

## 参考リンク
- [MCP公式ドキュメント](https://modelcontextprotocol.io/quickstart/server)
- [TypeScript公式ドキュメント](https://www.typescriptlang.org/docs/)
- [Node.js公式ドキュメント](https://nodejs.org/docs/latest/api/) 
- [Qiita TypeScript版の公式SDK で自作MCPクライアントを試す](https://qiita.com/youtoy/items/8d6fc082e8c4b23dcd21)