MCP TypeScript Server Starter

MCP TypeScript Server Starter

TypeScript で Model Context Protocol（MCP）サーバーを構築するためのスタータープロジェクトです。このプロジェクトには、MCP の主要な機能を実演するシンプルなエコーサーバーの実装が含まれています。

クイックスタートチェックリスト

📥 インストール

• リポジトリをクローンします：

  git clone https://github.com/ralf-boltshauser/mcp-typescript-server-starter.git
  cd mcp-typescript-server-starter
  

• 依存関係をインストールします：

  pnpm install
  

🛠️ ローカル開発

• 開発サーバーを起動します：

  pnpm dev
  

• http://localhost:6274 でインスペクターにアクセスします
• MCP サーバーをテストします：
  1. インスペクターで「Connect」をクリックします
  2. 「Tools」セクションに移動します
  3. 「List Tools」をクリックします
  4. 「echo」ツールを選択します
  5. テストメッセージを入力します
  6. 「Submit」をクリックします
• src/index.ts を開いて、次の項目を追加します：
  • ツール（AI が呼び出せる関数）
  • リソース（AI がアクセスできるデータ）
  • プロンプト（AI とのやり取りのためのテンプレート）
• src/index.html を更新して、サーバーの説明とドキュメントを記載します

🚀 デプロイ（Coolify の例）

• Coolify でセットアップします：
  1. リポジトリを接続します
  2. 詳細設定で：
     • GZIP 圧縮を無効にします（SSE に必須）
  3. ドメインを設定します：
     • ドメインを https://subdomain.yourdomain.com:3001 の形式で追加します
       • :3001 は重要です。traefik に内部ポートへのバインドを指示します
• デプロイを確認します：
  1. subdomain.yourdomain.com にアクセスして index.html を確認します
  2. https://subdomain.yourdomain.com/sse で SSE 接続をテストします

🔌 デプロイ済みサーバーへの接続

次のコマンドを使用してサーバーに接続します：

npx -y mcp-remote https://subdomain.yourdomain.com/sse

Cursor/Claude Desktop の設定例：

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://subdomain.yourdomain.com/sse"]
    },
  }
}

機能

• シンプルなエコーサーバーの実装
• ツール、リソース、プロンプトに対応
• TypeScript に対応
• ホットリロード対応の開発サーバー
• テストとデバッグ用の組み込みインスペクター
• STDIO と SSE の両方の通信モードに対応

前提条件

• Node.js（v16 以降）
• pnpm（推奨）または npm

使用モード

このサーバーは、次の 2 つの主要な通信モードに対応しています：

1. STDIO モード

   • ローカル開発や基本的なテストに最適です
   • プロセス間で直接通信します
   • ほとんどの MCP クライアントでデフォルトとして使用されます
   • サーバーをローカルで実行するのに最適です
   • セットアップも使用も簡単です

2. SSE モード

   • 本番環境へのデプロイに適しています
   • HTTP/SSE 通信を使用します
   • npm パッケージを使って STDIO に変換できます（後述）
   • サーバーへのリモートアクセスを可能にします
   • よりスケーラブルで、本番環境に適しています

ローカル開発では STDIO を、リモートアクセス用にサーバーをデプロイする場合は SSE を選択してください。

STDIO モード（プロセス間の直接通信）

このモードは、Cursor や Claude Desktop などのツールとの直接統合に最適です。

1. サーバーを設定する

   • src/index.ts で：
     • Express/SSE コードを（末尾で）コメントアウトします
     • STDIO コードのコメントを解除します（その上にあります）

2. ビルドして実行する

   pnpm build
   node dist/index.cjs
   

または

pnpm dev # starts the server and the inspector

3. Claude Desktop と統合する

   pnpm add-claude
   

   ⚠️ 注：既存の Claude Desktop 設定は上書きされます。

   この Claude Desktop の設定方法は標準的なものです。生成された json は Cursor などでも使用できます！

4. 手動で統合する その他のツールでは、次のコマンドを使用します：

   node /path/to/your/project/dist/index.cjs
   

   または

   pnpm cmd # this gives you the node .../dist/index.cjs command directly with pwd
   

SSE モード（HTTP/SSE 通信）

Web ベースのツールやリモート環境へのデプロイに最適なモードです。

1. サーバーの設定

   • src/index.ts で：
     • Express/SSE のコード（末尾）を有効にしたままにします
     • STDIO のコード（その上）をコメントアウトします

2. ローカル開発

   pnpm dev
   

   サーバーは次のアドレスで利用できます：

   • メインエンドポイント： http://127.0.0.1:3001
   • SSE エンドポイント： http://127.0.0.1:3001/sse
   • テストエンドポイント： http://127.0.0.1:3001/test
   • インスペクター： http://127.0.0.1:6274

3. ローカルでの Docker テスト ポートを実際に公開するには、docker compose のオーバーライドが必要です。coolify のような環境にデプロイする場合は不要です。traefik が処理するためです。

   docker compose -f docker-compose.yaml -f docker-compose.local.yaml up
   

4. 本番環境へのデプロイ（例：Coolify）

   • IDE に依頼して、src/index.html をサーバーの説明に合わせて更新します。
   • お好みのプラットフォームにサーバーをデプロイします
   • 重要：Coolify の詳細設定で：
     • GZIP 圧縮を無効にします（SSE ストリームが機能しなくなります）
     • ポート 3001 が適切に公開されていることを確認します。ドメインを設定するときは、https://your-domain.com:3001 のように設定します。これにより、traefik にポート 3001 をバインドするよう指示できます。
     • サーバーがすべてのインターフェース（0.0.0.0）でリッスンするよう設定します（設定済み）

5. リモートサーバーの使用 デプロイ後、次の方法でサーバーに接続できます：

   npx -y mcp-remote https://your-domain.com/sse
   

   これをコマンドとして貼り付け、「node .../dist/index.cjs」を置き換えてください。

プロジェクト構成

• src/index.ts - メインのサーバー実装
• src/low-level-index.ts - 低レベル API を使用した代替実装
• dist/ - コンパイル済み出力ディレクトリ

サーバーの機能

Echo ツール

入力メッセージをそのまま返すシンプルなツールです：

server.tool("echo", { message: z.string() }, async ({ message }) => ({
  content: [{ type: "text", text: `Tool echo: ${message}` }],
}));

Echo リソース

URI 経由でアクセスできるリソースです：

server.resource(
  "echo",
  new ResourceTemplate("echo://{message}", { list: undefined }),
  async (uri, { message }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Resource echo: ${message}`,
      },
    ],
  })
);

Echo プロンプト

メッセージを処理するためのプロンプトテンプレートです：

server.prompt("echo", { message: z.string() }, ({ message }) => ({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: `Please process this message: ${message}`,
      },
    },
  ],
}));

実装に関する推奨事項

デバッグメッセージ

デバッグメッセージは、server.server.sendLoggingMessage メソッドを使って送信できます。これにより、サーバーの操作状況を確認できます。

基本的な使い方

server.server.sendLoggingMessage({
  level: "info",
  data: "Starting server...",
});

これにより、次のことができます：

• サーバーの操作をリアルタイムで追跡する
• 開発中の問題をデバッグする
• 本番環境でサーバーの状態を監視する

インスペクターの右下で確認できます！

環境変数

サーバー側の環境変数（開発者が設定するもので、ユーザー固有ではありません）について：

1. Docker Compose の使用

   # docker-compose.yaml
   services:
     mmcp-server:
       environment:
         - API_KEY=${API_KEY}
         - DATABASE_URL=${DATABASE_URL}
   

   これにより、次のことができます：

   • シェルで変数を設定する：export API_KEY=your-key
   • Docker Compose が自動的に読み込む .env ファイルを使用する

2. コードでのアクセス

   const apiKey = process.env.API_KEY;
   const dbUrl = process.env.DATABASE_URL;
   

3. ローカル開発

   • プロジェクトのルートに .env ファイルを作成します：

     API_KEY=sk-123
     

   • シークレットを安全に保つため、.env を .gitignore に追加します
   • 環境変数を設定して開発サーバーを実行します：

     pnpm dev
     

4. 本番環境へのデプロイ

   • デプロイ先のプラットフォーム（例：Coolify）で環境変数を設定します
   • 機密情報をバージョン管理にコミットしないでください

ベストプラクティス

1. エラー処理

   • 環境変数に対する適切なエラー処理を必ず実装します
   • 必須の変数がない場合は、わかりやすいエラーメッセージを表示します

2. 型安全性

   • TypeScript で環境変数の型を定義します
   • 実行時チェックには、zod のような検証ライブラリの使用を検討します

3. セキュリティ

   • 機密性の高い環境変数をクライアントに公開しないでください
   • 開発環境と本番環境では、異なる変数セットを使用します

ライセンス

MIT