MCP Base Server

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

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

# リポジトリをクローン git clone <repository-url> cd mcp-base # Dockerイメージをビルド docker build -t mcp-base .

# 基本実行 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

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

{ "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" } } }

# 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() }; }

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

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

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; } }

# 環境変数の例 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と型チェックを実行
- プルリクエストを提出

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

MCP server that gives LLMs full control over local Kubernetes dev environments via k3d, kubectl, Tilt, Helm, and kustomize

Official Docker MCP Toolkit for discovering, configuring, and running containerized MCP servers through Docker Desktop and the Docker MCP gateway.

The Octopus MCP Server provides your AI assistant with powerful tools that allow it to inspect, query, and diagnose problems within your Octopus instance, transforming it into your ultimate DevOps wingmate.

The Railway MCP Server enables natural language interaction with your Railway projects and infrastructure. Ask your IDE or AI assistant to create projects, deploy templates, manage environments, pull variables, redeploy services, and more.

The Shipyard CLI provides an MCP server for agents to manage Shipyard environments directly: by pulling logs, comparing branches, running tests, and stopping/starting environments..

HashiCorp Terraform MCP server for Infrastructure as Code workflows, including provider and module discovery through the Terraform Registry.

MCP server for managing Unleash feature flags and automate best practices.

A secure, Docker-based server providing core execution capabilities for AI agents.