MCP Server Base v3.0 — スケール & エンタープライズ (2026)

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

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

• TypeScript 5.7 ESM + NodeNext モジュール

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

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

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

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

• プラグイン SDK (src/plugin/index.ts:1) + 統合 (slack/notion/linear)、レジストリ (smithery.yaml、mcpName)、プロンプトプレイグラウンド at /admin

• v3.0 エンタープライズ: マルチテナント (X-Tenant-Id、名前空間付きストア)、SSO OIDC、コントロールプレーン CRUD、クラスターモード、Prometheus/Grafana スタック

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

• tsx ウォッチ、vitest (178 テスト、88% カバレッジ)、グレースフルシャットダウン、docker-compose (redis、postgres、qdrant、otel-collector、prometheus、grafana)

🚀 クイックスタート

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 は main への push/PR で実行され、Node 20+22 マトリックスで lint、format:check、typecheck、test:coverage、build、docker build を行います。

Related MCP server: TokenHub MCP

🔌 トランスポート

Streamable HTTP は SSE (2025年3月に非推奨) に代わる新しい標準です。

🧰 ツール (40)

📦 リソース (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();

インスペクタ

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/RBAC/OTEL/metrics)
├── server.ts             # createMcpServer() factory (v2.1.0, instructions)
├── config.ts             # zod env (AUTH, CORS, rateLimit, RAG, cache, integrations, OTEL, admin, tasks)
├── types.ts              # Zod schemas
├── middleware/auth.ts    # AUTH_MODE none|apiKey|bearer
├── middleware/rateLimit.ts
├── middleware/requestId.ts
├── middleware/rbac.ts    # RBAC reader/writer/admin + mcpRbacMiddleware (v2.1)
├── observability/otel-real.ts # OTEL NodeSDK init (v2.1)
├── observability/slo.ts  # checkSlo() for /health/ready (v2.1)
├── utils/logger.ts       # stderr, JSON/text, redaction, child(requestId)
├── utils/eventStore.ts   # InMemoryEventStore
├── utils/redisEventStore.ts # RedisEventStore (scale)
├── utils/cache.ts        # MemoryCache (TTL) + defaultCache
├── utils/queue.ts        # SimpleQueue
├── utils/metrics.ts      # prom-client Registry (v2.1)
├── utils/persistence.ts  # save/load backup (v2.1)
├── utils/otel.ts         # stub OTEL spans/metrics
├── tools/                # 40 tools: echo, fs, memory, db, shell, rag (hybrid), 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
├── plugin/index.ts       # Plugin SDK: definePlugin/registerPlugin (v2.2)
├── integrations/         # slack/notion/linear plugins (v2.2)
├── middleware/tenant.ts  # Multi-tenant X-Tenant-Id + scoped stores (v3.0)
├── routes/controlplane.ts# Tenants CRUD + key rotation (v3.0)
├── utils/cluster.ts      # Cluster mode horizontal scale (v3.0)
├── resources/            # 6 resources: config, greeting, file, memory, db, docs
├── routes/admin.ts       # Admin UI + metrics/spans/stores (v2.0) + /metrics Prometheus (v2.1)
└── prompts/              # 4 prompts: code-review, explain-concept, summarize, research

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

🔐 セキュリティ (フェーズ 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 at 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 env バリデーション (src/config.ts:1) — parseEnv() が PORT, AUTH_MODE, API_KEY をクロスフィールド検証し、無効な env で即座に失敗

• 構造化ロガー 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 テスト → フェーズ 5 で合計 130、90.89% カバレッジ

🔗 統合 (フェーズ 4)

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

• RAG ローカルベクトル (ハッシュ埋め込み 128 次元、コサイン、チャンク 500/50) at 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_TTL_MS)

• GitHub src/tools/github.tool.ts:1 — github_search_repos, github_get_repo, github_get_issue (キャッシュ、GITHUB_TOKEN でレート制限)

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

• デモ rag_ingest → rag_search → docs:// E2E を tests/integrations.test.ts:1 で検証 (21 テスト)

🏢 スケール & エンタープライズ (フェーズ 5 — v3.0) — 新機能

• マルチテナント src/middleware/tenant.ts:1 — X-Tenant-Id ヘッダー（または ?tenant=）、tenantMiddleware は TENANT_REQUIRED=true で欠落している場合 400 を拒否、テナントスコープのメモリ getTenantMemory(tid)（分離されたストア）、名前空間付きキャッシュキー tenant:{id}:key、レジストリ createTenant/deleteTenant

• SSO OIDC src/middleware/auth.ts:1 — AUTH_MODE=oidc: Bearer JWT の構造的検証（3パート、exp、iss と OIDC_ISSUER の比較、aud と OIDC_AUDIENCE の比較）、クレームは req.oidcClaims に添付。本番環境では JWKS 署名検証に置き換え

• コントロールプレーン src/routes/controlplane.ts:1 — CRUD /admin/tenants（POST/GET/PATCH/DELETE + 409 重複/400 無効ID）、POST /admin/tenants/:id/rotate-key、GET /admin/tenants/:id/store 分離検査。admin トークンで保護

• ランタイムスケール src/utils/cluster.ts:1 — initCluster() は CLUSTER_WORKERS（デフォルト CPU-1）をフォーク、ワーカー終了時に自動再起動、CLUSTER_MODE=true。ステートレス + RedisEventStore による真の水平スケーリング

• モニタリングスタック docker-compose.override.yml:1 — Prometheus（prometheus.yml は app:3000/metrics をスクレイプ）:9090 + Grafana :3001

• テスト tests/v3_0.test.ts:1（15テスト: テナント抽出/分離/必須-400、OIDC トークン検証 + issuer/audience + HTTP 401/200、コントロールプレーンライフサイクル 201/409/400/404/rotate-key/store-inspection/disabled-404、クラスターノーオペレーション、compose サービス）— 合計 178

🔌 エコシステム & DX（フェーズ 5 — v2.2）

• プラグインSDK src/plugin/index.ts:1 — definePlugin({name, version, register})、registerPlugin(server, plugin)（重複許容）、getRegisteredPlugins()、自動 sendToolListChanged 通知

• 統合 src/integrations/ — slackPlugin（list/post/search）、notionPlugin（search/get/create）、linearPlugin（list/create/get）— すべてトークンなしでモック化（SLACK_TOKEN、NOTION_TOKEN）。src/server.ts:1 で自動登録

• レジストリ smithery.yaml:1 — Smithery 設定 + MCP レジストリ名 io.github.ahmedalbanna/mcp-server-base、package.json:1 の mcpName/files フィールド

• ハイブリッドRAG src/tools/rag.tool.ts:1 — rag_search モード vector|bm25|hybrid（デフォルト hybrid、alpha 0.5）、BM25（k1=1.5、b=0.75）正規化 + コサイン再ランク。評価セット tests/eval/rag-eval.json（20 Q/A）で p@5 ≥0.8 を tests/v2_2.test.ts:1 で検証

• プロンプトプレイグラウンド src/routes/admin.ts:1 — POST /admin/prompts/:name/preview はプロンプトをサーバーサイドでレンダリング。プレイグラウンドUIは /admin ダッシュボード内

• テスト tests/v2_2.test.ts:1（16テスト: プラグインSDK define/register/dup/ツール呼び出し可能、レジストリファイル、ハイブリッドモード、評価 p@5、プレイグラウンドプレビュー/UI/カウント）— 合計 163

📈 スケール & 運用性（フェーズ 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_ENABLED フラグ

• RedisEventStore（src/utils/redisEventStore.ts:1）— EventStore 実装で storeEvent/replayEventsAfter、インメモリフォールバック、水平スケール用の eventStoreFactory.create()（EVENT_STORE_TYPE=memory|redis、REDIS_URL）

• 管理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 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 スパン/メトリクス、RedisEventStore リプレイ、キャッシュTTL、キュー、管理HTML/メトリクス/トークン/準備、タスク作成/ポーリング、バージョン、k6 スクリプト）— 合計 130（v2.1 で現在 147）

• デプロイ Fly.io/Cloud Run 対応（ステートレス + RedisEventStore）、release.yml による GHCR、npm 2.0.0

🔒 堅牢化 & 可観測性（フェーズ 5 — v2.1）— 新規

• OTEL 実装 src/observability/otel-real.ts:1 — initOtel() は @opentelemetry/sdk-node + OTLPTraceExporter を動的インポート（コンソールフォールバック）、OTEL_ENABLED + OTEL_EXPORTER_OTLP_ENDPOINT、SIGTERM でグレースフル shutdown

• SLO src/observability/slo.ts:1 — checkSlo()（メモリ/RAG/キャッシュ/稼働時間、latencyMs）、GET /health → {status, checks, uptime, version, otel, eventStore} + GET /ready → ok でない場合は 503、GET /metrics → prom-client による Prometheus text/plain（mcp_http_requests_total、mcp_http_request_duration_ms、mcp_sessions_active）

• RBAC src/middleware/rbac.ts:1 — reader < writer < admin（X-Role ヘッダー、JWT スタブ）、TOOL_ROLES マップ（31ツール）、mcpRbacMiddleware は tools/call ボディを検査 → reader が write_file/shell_execute を試みると 403、GET /admin → admin 必須

• バックアップ src/utils/persistence.ts:1 — saveBackup()/loadBackup()/scheduleSave()（500ms デバウンス）で ALLOWED_ROOT/.backup.json へ（動的 getBackupFile()）、REDIS_URL 設定時に Redis 同期スタブをログ記録、src/index.ts:1 の起動時に loadBackup()

• メトリクス src/utils/metrics.ts:1 — prom-client の Registry + collectDefaultMetrics、httpRequestsTotal/httpRequestDuration/mcpToolCallsTotal/mcpSessionsActive、GET /metrics ハンドラー

• テスト tests/v2_1.test.ts:1（13テスト: SLO チェック、RBAC hasRole/X-Role 403/200、SLO health/metrics 200 + Prometheus テキスト、OTEL スパン、バックアップ save/load + memory_set による scheduleSave、initOtel 無効/有効）+ tests/unit/rbac.test.ts:1（4テスト）— 合計 147

• ロガーは stderr セーフ、シークレットをログに記録しない（リダクション）

• Zod → SDK による JSON Schema（src/types.ts:1、src/tools/*.tool.ts）

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

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

• ヘルス（GET /health）& 準備（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）、178テスト: ユニット + e2e HTTP/セキュリティ/機能/統合/スケール/v2.1/v2.2/v3.0

📚 ドキュメント

完全なドキュメントは docs/ にあります:

• アーキテクチャ — 図、モジュールマップ、リクエストライフサイクル

• 設定 — すべての環境変数 + 検証ルール

• API リファレンス — ツール/リソース/プロンプト/エンドポイント

• セキュリティ — 認証、RBAC、OIDC、テナント管理、堅牢化チェックリスト

• プラグイン — プラグインSDKガイド + レジストリ配布

• デプロイ — Docker、クラスター/マルチレプリカスケール、モニタリング、k6

• テスト — スイートマップ、パターン、CI

🤝 コントリビューション

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

• インスペクター: https://github.com/modelcontextprotocol/inspector