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
Claude Desktopの設定ファイルを編集します：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
以下の設定を追加します：
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型定義
新しいツールの追加
src/tools/[category]/[tool-name].tsに新しいツールファイルを作成
ツールスキーマ、入出力型、実装を定義
登録用にtoolDefinitionをエクスポート
src/tools/registry.tsにツールを追加
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 # このファイル
貢献
リポジトリをフォーク
フィーチャーブランチを作成
テスト付きで変更を追加
lintと型チェックを実行
プルリクエストを提出
ライセンス
MITライセンス - 詳細はLICENSEファイルを参照してください。
