MCP Server Base v2.0 — スケールと運用性 (2026)

最新スタックを使用したモダンな Model Context Protocol サーバー:

• MCP SDK 1.12+ — McpServer 高レベル API + StreamableHTTPServerTransport (新規) & StdioServerTransport

• TypeScript 5.7 ESM + NodeNext モジュール

• Zod バリデーション → 自動 JSON Schema + 環境変数バリデーション (src/config.ts:1)

• Express 4 + helmet + CORS 許可リスト + レート制限 + health/ready + Admin UI

• デュアルトランスポート: STDIO (Claude Desktop) と Streamable HTTP (リモート、2025-03 仕様、ステートレス + RedisEventStore によるステートフル再開)

• 構造化されたツール/リソース/プロンプトモジュール + RAG (ローカルベクター)、Web (キャッシュ付き)、GitHub 統合

• OTEL トレーシング/メトリクス (src/utils/otel.ts:1)、Tasks (実験的 + create_task)、k6 ロードテスト

• tsx watch、vitest (130 テスト、91% カバレッジ)、グレースフルシャットダウン、docker-compose (redis、postgres、qdrant)

🚀 クイックスタート

npm install
npm run build

# STDIO (for Claude Desktop, Cursor, opencode, etc.)
npm start

# HTTP (Streamable HTTP - latest)
npm run start:http
# → http://localhost:3000/mcp
# → health http://localhost:3000/health

開発

npm run dev          # stdio watch
npm run dev:http     # http watch (Streamable HTTP at http://localhost:3000/mcp)
npm test             # unit + e2e (InMemory + HTTP)
npm run test:coverage # coverage 80% thresholds
npm run lint         # eslint 9 flat config
npm run format:check # prettier
npm run typecheck    # tsc --noEmit
npm run build

CI

.github/workflows/ci.yml は push/PR で main に対して、Node 20+22 のマトリックスで実行されます: lint、format:check、typecheck、test:coverage、build、docker build。

Related MCP server: MCP Server

🔌 トランスポート

Streamable HTTP は、SSE (2025年3月に廃止) に代わる新しい標準です。

🧰 ツール (31)

📦 リソース (6)

• config://server-info — サーバーメタデータ (JSON、features を含むようになりました)

• greeting://{name} — 動的挨拶テンプレート

• file:///{+path} — サンドボックス化されたファイル (ALLOWED\_ROOT)、一覧表示 + 補完、file:///notes.txt

• memory://{key} — メモリ KV、一覧表示 + 補完

• db://{table}/{id} — デモ用 DB レコード (users/notes)、一覧表示 + 補完

• docs://{id} — RAG チャンク (rag_ingest で取り込んだもの)、一覧表示 + 補完

💬 プロンプト (4)

• code-review — 引数: language、code

• explain-concept — 引数: concept、level

• summarize — 引数: text、length (short/medium/long)、style (bullets/paragraph/tldr)

• research — 引数: topic、depth (overview/deep)、audience (beginner/expert/executive)

⚙️ クライアント設定

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mcp-server-base": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}

HTTP クライアント

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp')));
const tools = await client.listTools();

Inspector

npm run inspect
# or
npx @modelcontextprotocol/inspector node dist/index.js
npx @modelcontextprotocol/inspector http://localhost:3000/mcp

🐳 Docker

# Single container
docker build -t mcp-server-base .
docker run -p 3000:3000 --env TRANSPORT=http mcp-server-base

# Full stack (app + redis + postgres + qdrant) — see docker-compose.yml
docker compose up -d
docker compose logs -f app
# → http://localhost:3000/health, http://localhost:3000/mcp
# → redis :6379, postgres :5432, qdrant :6333

RAG デモ (取り込み → 検索 → docs://)

# via MCP tools (Inspector or Client)
# 1. ingest
rag_ingest { "text": "MCP is Model Context Protocol...", "id": "mcp-intro" }
# 2. search
rag_search { "query": "what is MCP?", "topK": 3 }
# 3. read resource
# docs://mcp-intro  → returns ingested text

📁 構造

src/
├── index.ts              # entry: stdio + http (helmet/cors/rateLimit/auth/resumability)
├── server.ts             # createMcpServer() factory
├── config.ts             # zod env (AUTH, CORS, rateLimit, RAG, cache, integrations)
├── types.ts              # Zod schemas
├── middleware/auth.ts    # AUTH_MODE none|apiKey|bearer
├── middleware/rateLimit.ts
├── middleware/requestId.ts
├── utils/logger.ts       # stderr, JSON/text, redaction, child(requestId)
├── utils/eventStore.ts   # InMemoryEventStore for Last-Event-ID
├── utils/cache.ts        # MemoryCache (TTL) + defaultCache
├── utils/queue.ts        # SimpleQueue
├── tools/                # 31 tools: echo, fs, memory, db, shell, rag, web, github, elicitation, sampling, tasks
│   ├── filesystem.tool.ts, memory.tool.ts, database.tool.ts, shell.tool.ts
│   ├── rag.tool.ts, web.tool.ts, github.tool.ts, elicitation.tool.ts, sampling.tool.ts, tasks.tool.ts
├── resources/            # 6 resources: config, greeting, file, memory, db, docs
├── routes/admin.ts       # Admin UI + metrics + spans
└── prompts/              # 4 prompts: code-review, explain-concept, summarize, research

新しいツールを追加するには: src/tools/my.tool.ts を作成 → registerMyTool(server) をエクスポート → src/tools/index.ts に追加。

🔐 セキュリティ (Phase 2)

• helmet ヘッダー (x-dns-prefetch-control、x-frame-options、x-content-type-options など) を helmet@7 で設定 (src/index.ts:1)

• CORS 許可リスト (CORS\_ORIGIN=* またはカンマ区切りリスト) と cors 認証情報処理 (src/config.ts:60)

• 認証 AUTH\_MODE=none|apiKey|bearer を src/middleware/auth.ts:1 で設定 — 有効な X-API-Key または Authorization: Bearer がない場合 401 (health/ready と OPTIONS は除外)

• レート制限 express-rate-limit (デフォルト 100回/15分) を /mcp に適用 — 429 Too Many Requests (src/middleware/rateLimit.ts:1)

• RequestId (X-Request-Id に randomUUID、ヘッダーでエコー、子ロガーで相関付け) (src/middleware/requestId.ts:1)

• Zod 環境変数バリデーション (src/config.ts:1) — parseEnv() が PORT、AUTH\_MODE、API\_KEY をフィールド横断で検証し、無効な環境変数があれば即座に失敗

• 構造化ロガー JSON/テキスト対応、authorization、apiKey、token は [REDACTED] に秘匿 (src/utils/logger.ts:24)

• 再開可能性 InMemoryEventStore (src/utils/eventStore.ts:1) + RESUMABILITY\_ENABLED=true のときのステートフルセッションマップ (Last-Event-ID によるリプレイ、GET /mcp ストリーム、DELETE でクローズ)

• Docker の堅牢化 非 root の appuser + HEALTHCHECK (Dockerfile:1)

• テスト: tests/unit/auth.test.ts、tests/unit/logger.test.ts、tests/unit/eventStore.test.ts、tests/e2e/security.test.ts (helmet/auth/rateLimit/resumability) — 67 tests → 130 total with Phase 5, 90.89%

🔗 インテグレーション (Phase 4)

• キャッシュ MemoryCache TTL (src/utils/cache.ts:1) — web/github 用の defaultCache、SimpleQueue (src/utils/queue.ts:1)

• RAG ローカルベクタ (ハッシュ埋め込み 128次元、コサイン類似度、チャンク 500/50) (src/tools/rag.tool.ts:1) — rag_ingest (チャンク化 + sendResourceListChanged)、rag_search (topK、threshold)、rag_list、rag_clear + docs://{id} リソース

• Web (src/tools/web.tool.ts:1) — brave_search (BRAVE\_API\_KEY がない場合はモック)、tavily_search (モック)、web_fetch (defaultCache、CACHE\_MAX\_MS によるキャッシュ付き)

• GitHub (src/tools/github.tool.ts:1) — github_search_repos、github_get_repo、github_get_issue (キャッシュ付き、summaryToken で API レート制限対策)

• スタック (docker-compose.yml:1) — app + redis:7 + postgres:16 + qdrant:v1.0.0 にヘルスチェック付き

• デモ rag_ingest → rag → docs:// E2E を tests/integrations.test.ts:1 (21 件) で検証

📈 スケールと運用性 (Phase 5 — v2.0)

• バージョン化された MCP v2.0.0 (package.json:1、config.MCP\_SERVER\_VERSION) 各マイナー向けの説明付き (src/server.ts:1)

• OTEL トレーシング/メトリクス (src/utils/otel.ts:1) — createSpan/withSpan、incrementCounter/recordHistogram、getMetrics/getSpans、OTEL\_EXPORTER\_OTLP\_ENDPOINT 用の JSON エクスポートスタブ、OTEL\_ フラグ

• RedisEventStore (src/utils/redisEventStore.ts:1) — storeEvent/replayEventsAfter を持つ EventStore 実装、インメモリフォールバック、水平スケール用 eventStoreFactory.create() (EVENT\_STORE\_TYPE=memory|redis、REDIS\_URL)

• Admin UI (src/routes/admin.ts:1) — GET /admin (HTML ダッシュボード)、/admin/tools|resources|prompts|metrics|spans|stores|health (JSON)、ADMIN\_TOKEN (X-Admin-Token) で保護、ADMIN\_ENABLED フラグ

• タスク (src/tools/tasks.tool.ts:1) — 実験的な delay_task (SDK タスクが利用可能な場合) + フォールバック create_task/get_task/get_task_result (インメモリ、ポーリング)、SimpleQueue/MemoryCache 基盤

• ベンチマーク (k6/load.js:1) — http_req_duration_ratio p(95) <100ms、stages 10→50 VUs、checks >99%、npm run bench / bench:local

• Compose (docker-compose.yml:1) — スケール用に redis/postgres/qdrant を既に内包

• テスト: tests/scale.test.ts:1 (OTEL spans/metrics、RedisEventStore リプレイ、キャッシュ TTL、キュー、admin HTML/metrics/token/ready、タスクの create/poll、バージョン、k6 スクリプト) — 合計 130 件

• デプロイ — Fly.io/Cloud Run 対応 (ステートレス + RedisEventStore)、release.yml 経由で GHCR、npm 2.0.0

• ロガーは stderr で安全に動作し、シークレットを一切ログに記録しない (秘匿化)

• Zod → JSON Schema を SDK 経由で生成 (src/types.ts:1、src/tools/*.tool.ts)

• fetch のタイムアウト (10 秒) + 構造化エラー

• グレースフルシャットダウン (SIGINT/SIGTERM)

• ヘルスチェック (GET /health) と readiness (GET /ready) を MCP と分離

• デフォルトはステートレス (sessionIdGenerator: undefined)、RESUMABILITY\_ENABLED=true のときはステートフル (src/index.ts:22)

• 型安全な厳格 TS + ESLint flat + Prettier + husky + lint-staged

• カバレッジ 行 85% / ブランチ 70% を強制 (vitest.config.ts:1)、130 件のテスト: 単体 + e2e HTTP/セキュリティ/機能/インテグレーション/スケール

🤝 コントリビューション

CONTRIBUTING.md を参照してください — nvm use、npm test、ツール/リソース/プロンプトの追加、lint/typecheck/test が通ることを確認してください。CODE_OF_CONDUCT.md も参照してください。

📚 MCP ドキュメント

• 仕様: https://spec.modelcontextprotocol.io

• SDK: https://github.com/modelcontextprotocol/typescript-sdk

• Inspector: https://github.com/modelcontextprotocol/inspector