MCP Base Server

English README

MCP (Model Context Protocol) サーバー作成用のベーステンプレートです。

特徴

• TypeScriptベースのMCPサーバー実装
• モジュラーなツールアーキテクチャ
• Zodスキーマによる組み込みバリデーション
• サンプルツール実装
• Vitestテスト環境
• 包括的なエラーハンドリング
• 高速なMCPサーバー開発テンプレート

要件

• Docker
• Docker Compose（オプション）

インストール

# リポジトリをクローン
git clone <repository-url>
cd mcp-base

# Dockerイメージをビルド
docker build -t mcp-base .

使用方法

Docker（推奨）

# 基本実行
docker run --rm -i mcp-base

# 環境変数を指定して実行
docker run --rm -i -e API_KEY=your_api_key_here mcp-base

# Docker Composeを使用
docker-compose up --build

開発環境（ローカル開発用）

# 依存関係をインストール
npm install

# 開発モードで開始
npm run dev

# テスト実行
npm test

# ビルド
npm run build

MCPクライアント設定

Claude Desktop

1. Claude Desktopの設定ファイルを編集します：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 以下の設定を追加します：

Dockerを使用する場合（推奨）

{
  "mcpServers": {
    "mcp-base": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i",
        "mcp-base"
      ]
    }
  }
}

ローカルビルドを使用する場合

{
  "mcpServers": {
    "mcp-base": {
      "command": "node",
      "args": ["/path/to/mcp-base/dist/index.js"]
    }
  }
}

開発環境での設定

{
  "mcpServers": {
    "mcp-base-dev": {
      "command": "npx",
      "args": ["ts-node", "/path/to/mcp-base/src/index.ts"],
      "cwd": "/path/to/mcp-base"
    }
  }
}

その他のMCPクライアント

stdio転送をサポートする任意のMCPクライアントから利用できます：

# Dockerで直接実行
docker run --rm -i mcp-base

アーキテクチャ

プロジェクトはモジュラーアーキテクチャに従います：

• src/index.ts - メインサーバーエントリーポイント
• src/core/tool-handler.ts - コアツール実行ロジック
• src/tools/ - カテゴリ別に整理されたツール実装
• src/tools/registry.ts - ツール登録と発見
• src/types/ - TypeScript型定義

新しいツールの追加

1. src/tools/[category]/[tool-name].tsに新しいツールファイルを作成
2. ツールスキーマ、入出力型、実装を定義
3. 登録用にtoolDefinitionをエクスポート
4. src/tools/registry.tsにツールを追加
5. src/core/tool-handler.tsのツールハンドラーを更新

ツール実装テンプレート

import { z } from 'zod';
import { ToolDefinition } from '../../types/mcp.js';

// 入力スキーマ定義
export const MyToolInputSchema = z.object({
  parameter: z.string().describe('パラメータの説明'),
  optionalParam: z.boolean().optional().default(false)
}).strict();

export type MyToolInput = z.infer<typeof MyToolInputSchema>;

// MCPツール定義
export const toolDefinition: ToolDefinition = {
  name: 'my_tool',
  description: 'ツールの機能説明',
  inputSchema: {
    type: 'object' as const,
    properties: {
      parameter: {
        type: 'string',
        description: 'パラメータの説明'
      },
      optionalParam: {
        type: 'boolean',
        description: 'オプションパラメータの説明',
        default: false
      }
    },
    required: ['parameter'],
    additionalProperties: false
  }
};

// 出力スキーマ定義
export const MyToolOutputSchema = z.object({
  result: z.string(),
  timestamp: z.string().optional()
});

export type MyToolOutput = z.infer<typeof MyToolOutputSchema>;

// ツール実装
export async function myTool(input: MyToolInput): Promise<MyToolOutput> {
  return {
    result: `処理結果: ${input.parameter}`,
    timestamp: new Date().toISOString()
  };
}

カスタマイズガイド

1. プロジェクト名の変更

package.jsonとsrc/index.tsをプロジェクト名で更新：

// src/index.ts
this.server = new Server({
  name: 'your-mcp-server',
  version: '1.0.0',
});

2. カスタムクライアントの追加

src/core/tool-handler.tsにカスタムクライアントを追加：

export class ToolHandler {
  private customClient: CustomClient | null = null;

  private async ensureCustomClient(): Promise<CustomClient> {
    if (!this.customClient) {
      const apiKey = process.env.API_KEY;
      if (!apiKey) {
        throw new McpError(
          ErrorCode.InvalidRequest,
          'API_KEY環境変数が設定されていません'
        );
      }
      this.customClient = new CustomClient(apiKey);
    }
    return this.customClient;
  }
}

3. 環境変数

必要に応じて環境変数の処理を追加：

# 環境変数の例
export API_KEY="your_api_key_here"
export LOG_LEVEL="info"

利用可能なスクリプト

• npm run build - TypeScriptをJavaScriptにコンパイル
• npm run start - 本番サーバーを開始
• npm run dev - ts-nodeで開発サーバーを開始
• npm run lint - ESLintを実行
• npm run typecheck - TypeScript型チェックを実行
• npm test - テストを実行
• npm run test:watch - 監視モードでテストを実行
• npm run test:coverage - カバレッジレポート付きでテストを実行
• npm run docker:build - Dockerイメージをビルド
• npm run docker:run - Dockerコンテナを実行
• npm run docker:dev - Docker Composeで開発環境を起動

プロジェクト構造

mcp-base/
├── src/
│   ├── core/
│   │   └── tool-handler.ts    # コアツール実行ロジック
│   ├── tools/
│   │   ├── registry.ts        # ツール登録
│   │   └── example/
│   │       └── example-tool.ts # サンプルツール実装
│   ├── types/
│   │   └── mcp.ts            # 型定義
│   └── index.ts              # メインサーバーエントリーポイント
├── dist/                     # コンパイル済みJavaScript出力
├── package.json              # プロジェクト依存関係とスクリプト
├── tsconfig.json             # TypeScript設定
├── vitest.config.ts          # テスト設定
├── CLAUDE.md                 # 開発ドキュメント
└── README.md                 # このファイル

貢献

1. リポジトリをフォーク
2. フィーチャーブランチを作成
3. テスト付きで変更を追加
4. lintと型チェックを実行
5. プルリクエストを提出

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。