mcp-server-template

エンタープライズ MCP サーバーテンプレート 🚀

TypeScript と Node.js で Model Context Protocol（MCP） サーバーを構築するための、本番環境対応のエンタープライズグレードのテンプレートです。スケーラビリティ、型安全性、Claude Desktop や Cursor などの AI エージェントとのシームレスな統合を考慮して設計されています。

📖 概要

Model Context Protocol（MCP） は、AI モデルがローカルおよびリモートのリソースとやり取りする方法を標準化します。このテンプレートは、定型コードをなくし、ベストプラクティスを徹底しながら、独自の MCP サーバーを構築するための堅牢な基盤を提供します。

主な機能

• 厳格な TypeScript 設定：厳密な型安全性を備えた最新の ECMAScript ターゲットを使用します。
• Zod による検証：ツールの入力と環境変数を実行時にスキーマ検証し、不正な AI ペイロードによってサーバーがクラッシュするのを防ぎます。
• 高速なバンドル（esbuild）：サーバー全体を最適化された単一の実行可能ファイル（dist/index.js）にコンパイルし、node_modules のデプロイを不要にします。
• 安全な構造化ログ：設定済みの pino ロガーが stderr に安全に書き込み、MCP が必要とする stdout の JSON-RPC トランスポートの整合性を保ちます。
• モジュール型アーキテクチャ：ツール、リソース、プロンプト、サービスを明確に分離します。
• Vitest の統合：すぐに使える非常に高速な単体テスト環境です。

🚀 はじめに

1. インストール

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/qmmughal/mcp-server-template.git
cd mcp-server-template
npm install

2. 設定

サンプルの環境ファイルをコピーし、変数を設定します。

cp .env.example .env

3. 開発ワークフロー

ローカル開発用に、ウォッチモードでサーバーを起動します。

npm run dev

テストスイートを実行します。

npm test

型を検証します。

npm run typecheck

4. 本番ビルド

サーバーを最適化された単一の実行可能ファイルにバンドルします。

npm run build

出力先は dist/index.js です。

🔌 MCP クライアントへの接続

Claude Desktop

このサーバーを Claude Desktop アプリに接続するには、Claude の設定ファイルを編集します（通常、Windows では %APPDATA%\Claude\claude_desktop_config.json、Mac では ~/Library/Application Support/Claude/claude_desktop_config.json にあります）。

{
  "mcpServers": {
    "enterprise-template-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-template/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "EXAMPLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Cursor で 設定 -> 機能 -> MCP に移動し、新しい MCP サーバーを追加します。

• タイプ：command
• コマンド：node /absolute/path/to/mcp-server-template/dist/index.js

🏗️ アーキテクチャの概要

• src/index.ts：アプリケーションのエントリーポイント、機能の登録、stdio 接続の設定です。
• src/tools/：MCP ツール（AI が実行できるアクション）の定義と JSON スキーマです。
• src/resources/：URI テンプレートを使用した動的リソース（AI が読み取れるデータ）です。
• src/prompts/：再利用可能なエージェント用プロンプトテンプレートです。
• src/services/：プロトコルハンドラーを薄く保ち、テストしやすくするための中核的なビジネスロジックです。
• src/utils/errors.ts：MCP のエラーコードに準拠した標準化されたエラー処理です。

📦 公開とレジストリ

package.json は公開できる状態になっており（スコープ付きの名前 @qmmughal/mcp-server-template、ライセンス、リポジトリ、キーワードを設定済み）、server.json と .github/workflows/publish-mcp.yml は、v* タグがプッシュされるたびに npm と MCP Registry の両方へ自動公開するよう設定されています。

git tag v1.0.0
git push origin v1.0.0

ワークフローの実行には、事前にリポジトリのシークレットが 1 つ必要です。NPM_TOKEN（@qmmughal スコープへの公開権限を持つ npm の自動化トークン）を設定してください。MCP Registry の認証には GitHub OIDC を使用するため、追加のシークレットは不要です。

🤝 コントリビューション

コントリビューション、問題の報告、機能リクエストを歓迎します。お気軽にイシューをご確認ください。

📝 ライセンス

このプロジェクトは MIT ライセンスの下で提供されています。