mcp-base CLAUDE.md

MCP Base Server

プロジェクト概要

汎用的なMCP (Model Context Protocol) サーバーのベーステンプレートです。新しいMCPサーバーを簡単に作成できるように設計されています。

技術スタック

• 言語: TypeScript
• フレームワーク: MCP SDK (@modelcontextprotocol/sdk)
• バリデーション: Zod
• 実行環境: Node.js 22+
• テストフレームワーク: Vitest

アーキテクチャ

設計方針

MCPプロトコル準拠: Model Context Protocolの仕様に完全準拠し、標準的なMCPクライアントとの互換性を保つ モジュラー設計: ツール実装を独立したモジュールとして管理し、拡張性を重視 型安全性: TypeScriptとZodを活用した厳密な型チェック テンプレート性: 新しいMCPサーバー開発の出発点として使用可能

ディレクトリ構造

mcp-base/
├── src/
│   ├── core/              # MCPサーバーのコア機能
│   │   └── tool-handler.ts    # 共通ツールハンドラー
│   ├── tools/             # MCPツール実装（カテゴリ別整理）
│   │   ├── registry.ts         # ツールレジストリ
│   │   └── example/            # サンプルツール実装
│   ├── types/             # 型定義
│   └── index.ts           # エントリーポイント
├── package.json           # 依存関係とスクリプト
├── tsconfig.json          # TypeScript設定
├── vitest.config.ts       # テスト設定
├── README.md              # 使用方法
└── CLAUDE.md              # このファイル

ツール管理アーキテクチャ

ツールレジストリパターン: 各ツールファイルにMCP定義を含め、registry.tsで一元管理 動的ツール登録: index.tsはレジストリから動的にツール一覧を取得 共通ハンドラー: ToolHandlerクラスがバリデーションとエラーハンドリングを統一

開発ガイドライン

コーディング規約

• ファイル命名: kebab-case (例: example-tool.ts)
• クラス命名: PascalCase (例: BaseMCPServer)
• 関数・変数命名: camelCase (例: setupHandlers)
• 定数命名: UPPER_SNAKE_CASE (例: DEFAULT_TIMEOUT)
• 型命名: PascalCase with suffix (例: ExampleToolInput)

新規ツール追加フロー

1. カテゴリの決定: 追加するツールが属するカテゴリを決定
2. ツールファイルの作成: src/tools/{category}/{tool-name}.ts
3. ツール定義の実装: 以下の要素を含める
   • 入力スキーマ（Zod）
   • 出力スキーマ（Zod）
   • ツール定義（MCP形式）
   • 実装関数
4. レジストリへの登録: src/tools/registry.tsに追加
5. ハンドラーの更新: src/core/tool-handler.tsのswitchケースに追加
6. テストの作成: src/tools/{category}/{tool-name}.test.ts

開発コマンド

# Docker環境での開発
npm run docker:build    # Dockerイメージをビルド
npm run docker:run      # Dockerコンテナを実行
npm run docker:dev      # Docker Composeで開発環境を起動

# ローカル開発
npm run dev

# テスト実行
npm test
npm run test:watch      # 監視モード
npm run test:coverage   # カバレッジ付き

# ビルド
npm run build

# lint/typecheck
npm run lint
npm run typecheck