MCP TypeScript Starter

MCP TypeScript スターター

TypeScript で実装された、機能が充実した Model Context Protocol（MCP）サーバーのテンプレートです。このスターターでは、主要な MCP 機能をすべて、すっきりとした本番環境対応のコードで紹介します。

📚 ドキュメント

• Model Context Protocol
• TypeScript SDK
• MCP サーバーの構築

✨ 機能

カテゴリ	機能	説明
ツール	hello	アノテーション付きの基本的なツール
	get_weather	構造化出力スキーマを備えたツール
	ask_llm	LLM サンプリングを呼び出すツール
	long_task	5 秒ごとに進捗を更新するツール
	load_bonus_tool	新しいツールを動的に読み込む
リソース	info://about	静的な情報リソース
	file://example.md	ファイルベースの Markdown リソース
テンプレート	greeting://{name}	パーソナライズされた挨拶
	data://items/{id}	ID によるデータ検索
プロンプト	greet	さまざまなスタイルの挨拶
	code_review	注目点を絞ったコードレビュー

🚀 クイックスタート

前提条件

• Node.js 20+
• npm または pnpm

インストール

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-typescript-starter.git
cd mcp-typescript-starter

# Install dependencies
npm install

# Build
npm run build

サーバーの実行

stdio トランスポート（ローカル開発用）：

npm run start:stdio

HTTP トランスポート（リモート／Web デプロイ用）：

npm run start:http
# Server runs on http://localhost:3000

🔧 VS Code との統合

このプロジェクトには、スムーズに開発できるよう VS Code の設定が含まれています。

1. VS Code でプロジェクトを開きます
2. MCP の設定は .vscode/mcp.json にあります
3. Ctrl+Shift+B（Mac では Cmd+Shift+B）でビルドします
4. VS Code の MCP ツールを使ってサーバーをテストします

DevContainers の使用

1. Dev Containers 拡張機能をインストールします
2. コマンドパレットを開き、「Dev Containers: Reopen in Container」を選択します
3. すべて設定済みで、すぐに使用できます！

📁 プロジェクト構成

.
├── src/
│   ├── tools.ts       # Tool definitions (hello, get_weather, ask_llm, etc.)
│   ├── resources.ts   # Resource and template definitions
│   ├── prompts.ts     # Prompt definitions
│   ├── server.ts      # Server orchestration (combines all modules)
│   ├── stdio.ts       # stdio transport entrypoint
│   └── http.ts        # HTTP transport entrypoint
├── .vscode/
│   ├── mcp.json       # MCP server configuration
│   ├── tasks.json     # Build/run tasks
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── package.json
├── tsconfig.json
├── .prettierrc        # Prettier configuration
└── eslint.config.js

🛠️ 開発

# Development mode with live reload
npm run dev

# Build for production
npm run build

# Format code
npm run format

# Lint
npm run lint

# Clean build
npm run clean && npm run build

ライブリロード

npm run dev コマンドでは tsx watch を使用しており、開発中にすぐリロードできます。 任意の .ts ファイルを変更すると、サーバーが自動的に再起動します。

🔍 MCP Inspector

MCP Inspector は、MCP サーバーのテストやデバッグに欠かせない開発ツールです。

Inspector の実行

npx @modelcontextprotocol/inspector -- npx tsx src/stdio.ts

Inspector でできること

• Tools タブ：登録済みのすべてのツールをパラメーター付きで一覧表示し、実行できます
• Resources タブ：リソースとテンプレートを参照して読み取れます
• Prompts タブ：プロンプトテンプレートを表示してテストできます
• Logs タブ：クライアントとサーバー間の JSON-RPC メッセージを確認できます
• スキーマ検証：ツールの入出力スキーマを検証できます

デバッグのヒント

1. IDE／クライアントに接続する前に Inspector を起動します
2. 「Logs」タブで、正確なリクエスト／レスポンスのペイロードを確認します
3. ツールのアノテーションが正しく公開されていることをテストします
4. long_task の進捗通知が表示されることを確認します

📖 機能の例

アノテーション付きツール

server.tool(
  "hello",
  {
    title: "Say Hello",
    description: "A friendly greeting tool",
    annotations: { readOnlyHint: true },
  },
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  })
);

リソーステンプレート

server.resourceTemplate(
  "greeting://{name}",
  { name: "Personalized Greeting", mimeType: "text/plain" },
  async ({ name }) => ({
    contents: [{
      uri: `greeting://${name}`,
      text: `Hello, ${name}!`,
    }],
  })
);

進捗更新付きツール

server.tool(
  "long_task",
  { title: "Long Task" },
  { taskName: z.string() },
  async ({ taskName }, { sendProgress }) => {
    for (let i = 0; i < 5; i++) {
      await sendProgress({ progress: i / 5, total: 1.0 });
      await sleep(1000);
    }
    return { content: [{ type: "text", text: "Done!" }] };
  }
);

🔐 環境変数

.env.example を .env にコピーして設定します。

cp .env.example .env

変数	説明	デフォルト
PORT	HTTP サーバーのポート	3000

🤝 貢献

貢献を歓迎します！変更を加える際は、ほかの言語のスターターと機能が同等に保たれるようにしてください。

📄 ライセンス

MIT License - 詳細はLICENSEをご覧ください。