MCP Learning Project

🚀 MCP学習プロジェクト - 完全ガイド

このプロジェクトは、Model Context Protocol (MCP) の開発を初心者から上級者レベルまで教える包括的なチュートリアルです。サーバーサイド（バックエンド）とクライアントサイド（フロントエンド）の両方の開発を学ぶことができます。

🚀 クイックスタート

1. プロジェクトのセットアップ

# プロジェクトディレクトリの作成
mkdir mcp-learning-project
cd mcp-learning-project

# npmプロジェクトの初期化
npm init -y

# 依存関係のインストール
npm install @modelcontextprotocol/sdk

# 開発用依存関係のインストール
npm install --save-dev typescript @types/node tsx

2. package.jsonの作成

{
  "name": "mcp-learning-project",
  "version": "1.0.0",
  "description": "Learn MCP development from beginner to advanced",
  "main": "dist/server.js",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start:server": "node dist/server.js",
    "start:client": "node dist/client.js dist/server.js",
    "dev:server": "tsx src/server.ts",
    "dev:client": "tsx src/client.ts dist/server.js",
    "demo": "npm run build && npm run start:client"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.4.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}

3. TypeScript設定の作成

tsconfig.json を作成します。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

4. コードファイルの保存

• MCP学習サーバーのコードを src/server.ts として保存します。
• MCP学習クライアントのコードを src/client.ts として保存します。

5. ビルドと実行

# プロジェクトのビルド
npm run build

# インタラクティブクライアントの実行（これによりサーバーも起動します）
npm run demo

✨ 主な機能

初心者レベル

• ✅ MCPサーバーの基本構造と概念
• ✅ 簡単なツールの作成と登録
• ✅ パラメータの処理と検証
• ✅ 基本的なクライアント接続とツール呼び出し

中級者レベル

• ✅ ツール呼び出し間の状態管理
• ✅ リソース管理（AIへのデータ提供）
• ✅ データ処理と複雑な操作
• ✅ クライアント - サーバー間の通信パターン

上級者レベル

• ✅ 永続的な状態を持つCRUD操作
• ✅ 包括的なエラーハンドリング
• ✅ AIとの対話用のプロンプトテンプレート
• ✅ ベストプラクティスと本番環境での考慮事項

📦 インストール

上記の「クイックスタート」セクションに、インストール手順が記載されています。

💻 使用例

基本的な使用法

# インタラクティブクライアントの起動
npm run demo

# 基本コマンドの試行
mcp-learning> help
mcp-learning> tools
mcp-learning> call hello_world {"name": "Alice"}

# リソースについての学習
mcp-learning> resources
mcp-learning> read mcp-concepts

高度な使用法

# 上級者デモの実行
mcp-learning> demo advanced

# エラーハンドリングの学習
mcp-learning> call error_demo {"error_type": "none"}
mcp-learning> call error_demo {"error_type": "validation"}

# ベストプラクティスの学習
mcp-learning> read best-practices

📚 ドキュメント

プロジェクト構造

mcp-learning-project/
├── src/
│   ├── server.ts          # MCP Learning Server (backend)
│   └── client.ts          # MCP Learning Client (frontend)
├── dist/                  # Compiled JavaScript
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file

学習パス

フェーズ1: 基礎の理解

1. インタラクティブクライアントの起動

   npm run demo
   

2. 基本コマンドの試行

   mcp-learning> help
   mcp-learning> tools
   mcp-learning> call hello_world {"name": "Alice"}
   

3. リソースについての学習

   mcp-learning> resources
   mcp-learning> read mcp-concepts
   

フェーズ2: 実践練習

1. 初心者デモの実行

   mcp-learning> demo beginner
   

2. ツール呼び出しの練習

   mcp-learning> call calculator {"operation": "add", "a": 5, "b": 3}
   mcp-learning> call calculator {"operation": "divide", "a": 10, "b": 0}
   

3. 状態管理の理解

   mcp-learning> call counter {"action": "get"}
   mcp-learning> call counter {"action": "increment", "amount": 5}
   mcp-learning> call counter {"action": "get"}
   

フェーズ3: 高度な概念

1. 中級者デモの実行

   mcp-learning> demo intermediate
   

2. 複雑なデータの操作

   mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "sort"}
   mcp-learning> call data_processor {"data": [5, 2, 8, 1, 9], "operation": "average"}
   

3. CRUD操作

   mcp-learning> call task_manager {"action": "create", "task": {"title": "Learn MCP", "priority": "high"}}
   mcp-learning> call task_manager {"action": "list"}
   

フェーズ4: 本番環境対応

1. 上級者デモの実行

   mcp-learning> demo advanced
   

2. エラーハンドリングの学習

   mcp-learning> call error_demo {"error_type": "none"}
   mcp-learning> call error_demo {"error_type": "validation"}
   

3. ベストプラクティスの学習

   mcp-learning> read best-practices
   

キーコンセプトの説明

1. MCPサーバー（バックエンド）

サーバーは、AIモデルに機能を提供します。

// Server setup
const server = new Server({
  name: 'my-server',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {},      // Functions AI can call
    resources: {},  // Data AI can read  
    prompts: {}     // Templates AI can use
  }
});

// Tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'my_tool',
      description: 'What this tool does',
      inputSchema: { /* JSON Schema */ }
    }
  ]
}));

// Tool implementation
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Process the tool call and return results
  return {
    content: [{
      type: 'text',
      text: 'Tool response'
    }]
  };
});

2. MCPクライアント（フロントエンド）

クライアントは、サーバーに接続し、その機能を利用します。

// Client setup
const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: { /* client capabilities */ }
});

// Connect to server
const transport = new StdioClientTransport(/* server process */);
await client.connect(transport);

// Discover server capabilities
const tools = await client.listTools();
const resources = await client.listResources();

// Use server tools
const result = await client.callTool({
  name: 'tool_name',
  arguments: { /* tool parameters */ }
});

3. 通信フロー

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   AI Model  │ ───▶ │ MCP Client  │ ───▶ │ MCP Server  │
│             │      │ (Frontend)  │      │ (Backend)   │
│             │ ◀─── │             │ ◀─── │             │
└─────────────┘      └─────────────┘      └─────────────┘
     ▲                      │                      │
     │                      │                      │
     └──────────────────────┴──────────────────────┘
              Uses server capabilities

🔧 技術詳細

独自ツールの作成

天気ツール

{
  name: 'weather',
  description: 'Get weather information',
  inputSchema: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
      units: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
    },
    required: ['city']
  }
}

ファイルシステムツール

{
  name: 'file_operations',
  description: 'Basic file system operations',
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['list', 'read', 'write'] },
      path: { type: 'string', description: 'File or directory path' },
      content: { type: 'string', description: 'Content to write' }
    },
    required: ['action', 'path']
  }
}

データベースツール

{
  name: 'database',
  description: 'Simple in-memory database operations',
  inputSchema: {
    type: 'object',
    properties: {
      action: { type: 'string', enum: ['create', 'read', 'update', 'delete'] },
      table: { type: 'string', description: 'Table name' },
      data: { type: 'object', description: 'Data to store/update' },
      id: { type: 'string', description: 'Record ID' }
    },
    required: ['action', 'table']
  }
}

カスタムリソースの作成

設定リソース

{
  uri: 'config://app-settings',
  name: 'Application Settings',
  description: 'Current application configuration',
  mimeType: 'application/json'
}

ドキュメントリソース

{
  uri: 'docs://api-reference',
  name: 'API Reference',
  description: 'Complete API documentation',
  mimeType: 'text/markdown'
}

インタラクティブプロンプトの作成

コードレビュープロンプト

{
  name: 'code-review',
  description: 'Start a code review session',
  arguments: [
    {
      name: 'language',
      description: 'Programming language',
      required: true
    },
    {
      name: 'focus',
      description: 'Review focus (security, performance, style)',
      required: false
    }
  ]
}

🐛 デバッグとトラブルシューティング

一般的な問題

サーバーが起動しない場合

# TypeScriptが正しくコンパイルされたか確認
npm run build

# コンパイルエラーの確認
npx tsc --noEmit

# 欠落している依存関係の確認
npm install

クライアントが接続できない場合

# サーバーパスが正しいことを確認
node dist/client.js dist/server.js

# サーバープロセスが起動するか確認
node dist/server.js

ツール呼び出しが失敗する場合

// サーバーにデバッグ情報を追加
console.error(`[DEBUG] Tool called: ${name}`, JSON.stringify(args));

// 入力パラメータを慎重に検証
if (typeof args.requiredParam === 'undefined') {
  throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter');
}

デバッグモード

サーバーとクライアントの両方で詳細なログを有効にします。

// サーバーでのデバッグログ
console.error('[SERVER]', 'Detailed log message');

// クライアントでのデバッグログ
console.log('[CLIENT]', 'Connection status:', connected);

🚀 次のステップ: 本番用サーバーの構築

1. 実際の機能の追加

デモツールを実際に役立つ機能に置き換えます。

// Example: Real file system access
private async handleFileOperations(args: any) {
  const { action, path, content } = args;
  
  switch (action) {
    case 'read':
      return {
        content: [{
          type: 'text',
          text: await fs.readFile(path, 'utf-8')
        }]
      };
    case 'write':
      await fs.writeFile(path, content);
      return {
        content: [{
          type: 'text', 
          text: `File written: ${path}`
        }]
      };
  }
}

2. 外部統合の追加

// Example: HTTP API integration
private async handleApiCall(args: any) {
  const { url, method, data } = args;
  
  const response = await fetch(url, {
    method,
    headers: { 'Content-Type': 'application/json' },
    body: data ? JSON.stringify(data) : undefined
  });
  
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        status: response.status,
        data: await response.json()
      }, null, 2)
    }]
  };
}

3. 永続性の追加

import * as fs from 'fs/promises';

class PersistentMCPServer {
  private dataFile = './mcp-data.json';
  
  async loadState(): Promise<Map<string, any>> {
    try {
      const data = await fs.readFile(this.dataFile, 'utf-8');
      return new Map(Object.entries(JSON.parse(data)));
    } catch {
      return new Map();
    }
  }
  
  async saveState(state: Map<string, any>): Promise<void> {
    const data = Object.fromEntries(state);
    await fs.writeFile(this.dataFile, JSON.stringify(data, null, 2));
  }
}

4. 認証の追加

private validateAuth(headers: any): boolean {
  const token = headers['authorization'];
  return token === 'Bearer your-secret-token';
}

private async handleSecureTool(args: any, headers: any) {
  if (!this.validateAuth(headers)) {
    throw new McpError(ErrorCode.InvalidParams, 'Authentication required');
  }
  
  // Continue with tool logic...
}

📚 追加リソース

公式ドキュメント

• MCP Specification
• MCP SDK Documentation

コミュニティの例

• MCP Servers Repository
• Community Tools and Integrations

高度なトピック

• Webサービス用のHTTPトランスポート
• リアルタイム通信用のWebSocketトランスポート
• カスタムトランスポートの実装
• パフォーマンス最適化テクニック
• セキュリティのベストプラクティス

🎯 学習演習

演習1: 電卓の拡張

power、sqrt、factorial、sin、cos などの操作を追加します。

演習2: メモシステムの構築

タグ付きのメモの作成、編集、検索、整理用のツールを作成します。

演習3: 外部APIの統合

実際のAPI（天気、ニュース、株価）と統合し、対応するツールを作成します。

演習4: プロジェクトマネージャーの構築

タスク、期限、優先度、進捗トラッキングを持つ包括的なプロジェクト管理システムを作成します。

演習5: リアルタイム機能の追加

クライアントに通知や更新を送信できるツールを実装します。

🏆 習得チェックリスト

初心者レベル ✅

• [ ] MCPアーキテクチャ（クライアント、サーバー、トランスポート）を理解する
• [ ] 入力検証付きの基本的なツールを作成する
• [ ] 簡単なツール呼び出しと応答を処理する
• [ ] エラーメッセージを読み理解する

中級者レベル ✅

• [ ] 永続性を持つステートフルツールを実装する
• [ ] AIにリソースを作成し提供する
• [ ] 複雑なデータ処理を扱う
• [ ] 適切なエラーハンドリングパターンを実装する

上級者レベル ✅

• [ ] 複雑な状態を持つCRUD操作を構築する
• [ ] インタラクティブなプロンプトテンプレートを作成する
• [ ] 本番環境で使用できるエラーハンドリングを実装する
• [ ] セキュリティと認証の概念を理解する
• [ ] 本番環境でのパフォーマンスを最適化する

エキスパートレベル 🚀

• [ ] カスタムトランスポートレイヤーを構築する
• [ ] MCPサーバーフレームワークを作成する
• [ ] 高度なセキュリティ対策を実装する
• [ ] 分散型MCPアーキテクチャを構築する
• [ ] MCPエコシステムに貢献する

🎉 おめでとうございます！

これで、フロントエンドとバックエンドの両方の観点からMCP開発を完全に理解しました。以下ができるようになります。

• ツール、リソース、プロンプトを提供するMCPサーバーを構築する
• サーバーと効果的に対話するMCPクライアントを作成する
• エラーを適切にハンドリングし、適切な検証を実装する
• ツール呼び出し間およびセッション間で状態を管理する
• 本番環境で使用できる実装のためのベストプラクティスに従う

このプロジェクトのインタラクティブな学習環境を通じて、すべてのMCP概念に関する実践的な経験を積むことができます。これを基盤として、任意のドメインやユースケースに対応した独自のMCPサーバーを構築しましょう！

楽しいコーディングを！ 🚀