MCP TypeScript Starter

MCP TypeScript Starterは、TypeScriptでModel Context Protocolサーバーを構築するための、本番運用を意識した土台です。型付きのサンプルツールが1つ、stdioおよびStreamable HTTPトランスポート、厳格な検証、テスト、堅牢化されたコンテナ、そしてGHCRへの自動公開が含まれています。

クローンして、サンプルのドメインを置き換えれば、実際のMCPサーバーに必要なインフラを維持できます。

目次

• このスターターを使う

• 概要

• 特徴

• MCPツール

• 技術スタック

• インストール

• 設定

• MCPクライアントのセットアップ

• スターターのカスタマイズ

• 検証

• 制限事項

• コントリビューション

• ライセンス

Related MCP server: mcp-server-http-streamable

このスターターを使う

GitHubでUse this templateをクリックすると、独立したGit履歴を持つ新しいMCPサーバーを作成できます。作成後、スターターのカスタマイズに従って、サンプルツールを置き換え、プロジェクトのアイデンティティを更新してください。

プルリクエストを通じて改善を還元したい場合は、このリポジトリをフォークしてください。変更を送信する前にコントリビューションを参照してください。

このスターターが役に立ったなら、リポジトリにスターを付けていただけると幸いです。他のTypeScript開発者がこのプロジェクトを見つけやすくなります。

概要

このスターターは、検証済みのMCPツール定義から、クライアントから見える構造化された結果に至るまでの完全な経路を示しています。カスタムサーバーフレームワークではなく、現在のモジュール式MCP TypeScript SDKとHonoのWeb標準HTTPモデルを使用しています。

デフォルトのstdioトランスポートは、サーバーを子プロセスとして起動するローカルクライアント向けです。Streamable HTTPはステートレスで、リクエストごとに新しいMCPサーバーを作成するため、共有セッションストレージなしでレプリケーションできます。

この例は、上限付きのインメモリ処理を行います。テレメトリ、アプリケーションデータベース、永続ストレージ、認証、外部サービスへの依存はありません。

特徴

• 厳格なZod入力・出力スキーマでツールを登録します。

• 人間が読めるコンテンツと型付きの構造化コンテンツの両方を返します。

• 正確なMCP安全性注釈を含みます。

• stdioとステートレスなStreamable HTTPをサポートします。

• DNSリバインディング対策のHost・Origin検証を備えたHonoを使用します。

• HTTPをデフォルトでループバックにバインドし、他のインターフェースには許可リストを要求します。

• ツール入力とHTTPリクエストボディを制限します。

• stdioモードでは、stdoutをMCPプロトコルメッセージ専用に保ちます。

• SIGINTとSIGTERMを冪等なグレースフルシャットダウンで処理します。

• 読み取り専用ルートファイルシステムをサポートした非rootコンテナとして実行します。

• 設定、stdio配線、MCP動作、Honoルート、実際のHTTPトラフィックをテストします。

• 品質チェックを通過した場合のみ、マルチアーキテクチャイメージを公開します。

MCPツール

echo

検証済みのメッセージと任意の文字列メタデータをエコーします。ビジネスドメインを考案せずにMCPのスキーマ、登録、注釈、結果を学べるよう、意図的にシンプルにしています。

入力例:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

構造化出力の例:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

メッセージは10,000文字に制限されています。メタデータは最大20エントリまで受け付けます。キーは64文字、値は1,024文字に制限されています。

技術スタック

• Node.js 24+

• 厳格なプロジェクトルールを適用したTypeScript

• Model Context Protocol TypeScript SDK 2

• Hono

• Zod

• Vitest

• pnpm

• Docker

インストール

前提条件

• ローカル開発にはNode.js 24+とpnpm 11。

• コンテナデプロイにはDockerとDocker Compose。

Docker Compose

推奨されるHTTPデプロイでは、公開済みのマルチアーキテクチャイメージを使用します:

ghcr.io/lukegskw/mcp-typescript-starter:latest

Composeの例をダウンロードし、クライアントが使用するホスト名を指定してください:

curl -O https://raw.githubusercontent.com/lukegskw/mcp-typescript-starter/main/compose.example.yaml
export MCP_ALLOWED_HOSTS='mcp.example.internal'
docker compose -f compose.example.yaml up -d

Streamable HTTPエンドポイントとヘルスチェックエンドポイントは、次の場所で利用できます:

http://<host>:3000/mcp
http://<host>:3000/healthz

別のホストポートを公開するには、MCP_PUBLISHED_PORTを設定します。アプリケーションはコンテナ内では引き続きポート3000を使用します。

latestタグは、デフォルトブランチの最新の成功ビルドに追従します。管理されたデプロイとロールバックには、バージョンまたは不変のsha-*タグを使用してください。

Docker run

docker run -d \
  --name mcp-typescript-starter \
  --restart unless-stopped \
  --read-only \
  --user 10001:10001 \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:size=16m,mode=1777 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_ALLOWED_HOSTS=127.0.0.1,localhost,mcp.example.internal \
  -p 3000:3000 \
  ghcr.io/lukegskw/mcp-typescript-starter:latest

ソースからコンテナをビルドする

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .

ローカルでのNode.jsインストール

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
pnpm install --frozen-lockfile
pnpm build
pnpm start -- --transport stdio

ローカルでのStreamable HTTP開発には:

MCP_TRANSPORT=streamable-http pnpm dev

設定

--transportコマンドラインオプションはMCP_TRANSPORTを上書きします。MCP_ALLOWED_HOSTSにはURLではなくホスト名を指定します。正当なクライアントとヘルスチェックが使用するすべてのホスト名を含めてください。

サーバーのサンプル設定にはシークレットは含まれていません。ドメインの認証情報は、デプロイプラットフォームまたは環境変数を通じて追加してください。MCPツールの引数やコミットされたファイルとして決して追加しないでください。

MCPクライアントのセットアップ

Streamable HTTPサーバー定義を受け付けるクライアントの場合:

mcp_servers:
  starter:
    url: http://127.0.0.1:3000/mcp

ローカルのstdioサーバーを起動するクライアントの場合:

{
  "mcpServers": {
    "starter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-typescript-starter/dist/main.js",
        "--transport",
        "stdio"
      ]
    }
  }
}

ローカルクライアントにstdio経由でコンテナを起動させるには、docker run -i --rmを使用し、イメージ名の後に--transport stdioを渡します。クライアントが標準入力と標準出力でMCPメッセージを交換できるよう、-iが必要です。

クライアントの設定形式は異なります。正確なスキーマについてはクライアントのドキュメントを参照し、サーバー定義を変更した後はクライアントを再起動または再読み込みしてください。

スターターのカスタマイズ

主な拡張ポイントは意図的に直接的です:

1. src/tools/echo.tsをコピーまたは置き換えます。

2. ハンドラーを書く前に、厳格な入力・出力スキーマを定義します。

3. src/server.tsでツールを登録します。

4. MCPの動作テストと、該当するドメインの統合テストを追加します。

5. パッケージ名、サーバーのアイデンティティ、イメージ参照、READMEの内容を置き換えます。

ツールモジュールは、自身のスキーマとハンドラーに責任を持たせてください。トランスポートモジュールはドメインツールから独立させてください。サービスや永続化は、実際の動作で必要になった場合にのみ導入してください。

検証

リポジトリの完全なテストスイートを実行します:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build

コンテナの変更の場合:

docker buildx build --load -t mcp-typescript-starter:test .

最後に、MCPクライアントを接続し、echoが一覧に表示され、テキストと構造化コンテンツの両方を返すことを確認します。HTTPモードでは、/healthzが{"status":"ok"}を返すことを確認します。

制限事項

• この例では1つのツールのみを公開し、リソースやプロンプトはありません。

• Streamable HTTPには認証がありません。ループバック、信頼できるLAN、VPN、プライベートコンテナネットワーク、または認証付きリバースプロキシに限定してください。

• HostおよびOriginの許可リストは、一部の種類のDNSリバインディング攻撃を防ぎますが、呼び出し元を認証するものではありません。

• HTTPサーバーはステートレスで、共有の永続化や分散調整は含まれていません。

• レート制限、トレーシング、メトリクス、ドメイン固有のロギングは含まれていません。

• このリポジトリはソーススターターであり、公開されたnpmライブラリではありません。

HTTPトランスポートを公開する前、またはセキュリティ問題を報告する前に、SECURITY.mdを確認してください。

コントリビューション

コントリビューションを歓迎します。プルリクエストを開く前に:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t mcp-typescript-starter:test .

変更は、厳格な型付け、上限付きの検証、構造化されたMCP結果、stdoutのプロトコル純粋性、安全なHTTPデフォルト、決定論的なテスト、ユーザーに見える動作のドキュメントを維持しなければなりません。具体的なユースケースのない抽象化は追加しないでください。

ライセンス

MIT。LICENSEを参照してください。