高性能MCPサーバー

TypeScriptと最新のMCP v2 SDK（@modelcontextprotocol/server）で構築された、高性能・モジュール式のModel Context Protocol（MCP）サーバーです。デフォルトで安全なセキュリティプロファイル、プロファイル対応のサーバー指示、モジュール式MCPプロンプト、検索機能とホストパスプライバシーを備えた読み取り専用ワークスペースアクセス、Streamable HTTP、Stdioトランスポート、再利用可能なワーカースレッドプール、シングルフライト・スタンピード保護付きの本番用LRUキャッシュ、構造化テレメトリを特長としています。

プロジェクトステータス: パブリックプレビュー (v0.1.0)

[!NOTE] ステータス: 0.1.0 パブリックプレビュー。 このパッケージは、デフォルトで安全なMCPツール、読み取り専用ワークスペース検査、高性能ワーカー実行を提供します。Node.js >= 22.0.0 が必要です。

Related MCP server: VSCode LSP MCP Server

特長

• 最新のMCP v2アーキテクチャ: @modelcontextprotocol/server をネイティブに採用し、標準のJSON Schema draft 2020-12バリデーションと完全な2026-07-28プロトコルサポートを備えています。

• デュアルトランスポートサポート: 標準入出力（stdio）または最新のStreamable HTTP（node:http + /mcp）でシームレスに実行できます。

• プロファイル対応サーバー指示: アクティブなプロファイルに基づいて、接続されたLLMに推奨ワークフロー、ツール実行順序、安全境界を案内する動的なサーバー指示を提供します。

• モジュール式MCPプロンプト: 再利用可能なタスクプロンプト（explore_workspace、find_and_explain、review_file、trace_symbol）を workspace プロファイルと all プロファイルでのみ公開します。

• デフォルトで安全なツールプロファイル: デフォルトの safe プロファイルはファイルシステムやハードウェア検査を一切公開しません。workspace、diagnostics、benchmark、admin、all への明示的なオプトインが必要です。

• 読み取り専用ワークスペースとホストパスプライバシー: パストラバーサルとシンボリックリンクエスケープ防止、論理ルートマッピング（root-1、root-2）、1 MiBのハードリミット、バイナリファイル保護を備えたセキュアな許可リスト方式のディレクトリアクセスを提供し、ホストの絶対パスをクライアントやモデルに公開しません。

• ワークスペース検索v1: 高速で制限付きのリテラルファイル・テキスト検索（search_files、search_text）で、無視ディレクトリのデフォルト設定、制限付き並行性、座標マッピング、クライアントキャンセルに対応しています。

• ワーカースレッドプール: CPU負荷の高いタスクをNode.jsイベントループからオフロードし、自動ライフサイクルリカバリとゼロドリフト不変条件を実現します。

• 本番用LRUキャッシュ: TTLサポート付きのメモリ制限キャッシュと、キャッシュスタンピードを排除するシングルフライトリクエスト合流を備えています。

• 内部構造化ロギング: stderr のみを使用したStdioセーフなJSONロギング。

クイックスタート

MCPクライアント設定（Claude Desktop、Cursorなど）

MCP設定（例: claude_desktop_config.json）に追加します:

デフォルトのセーフプロファイル（Stdio）

{
  "mcpServers": {
    "high-performance-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "high-performance-mcp-server"
      ]
    }
  }
}

読み取り専用ワークスペースプロファイル

{
  "mcpServers": {
    "workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "high-performance-mcp-server",
        "--profile=workspace",
        "--root=/path/to/project"
      ]
    }
  }
}

ローカル開発 / ソースからの実行

# Clone and build
git clone https://github.com/eminyilmz/high-performance-mcp-server.git
cd high-performance-mcp-server
npm install
npm run build

# Run default safe profile
node dist/index.js

# Run workspace profile with allowlisted root
node dist/index.js --profile=workspace --root=.

デフォルトで安全なプロファイル

ホストマシンを保護し、意図しないリソース消費やメタデータ漏洩を防ぐため、ツール、リソース、指示、プロンプトはセキュリティプロファイルに分類されます:

サーバー指示とプロンプト

プロファイル対応サーバー指示

MCPクライアントが接続すると、サーバーはMCPプロトコルを介して簡潔でプロファイルに合わせた指示を配信します:

• safe: ファイルシステムとハードウェアの検査が利用できないことをモデルに指示します。

• workspace: 推奨される調査手順（workspace_roots -> search_files / search_text -> file_info -> read_text_file）の概要を示し、読み取り専用の制約を強調し、ルート相対パスの使用を重視します。

• diagnostics と benchmark: 観測メトリクスの解釈をガイドし、不要なCPU負荷の高い計算呼び出しを警告します。

• admin: 変更操作はプロセスローカルのキャッシュとテレメトリ状態にのみ影響することを説明します。

モジュール式MCPプロンプト

workspace または all プロファイルで実行すると、サーバーは一般的なエンジニアリングタスクのための構造化ワークフローを提供するモジュール式プロンプトを公開します:

[!NOTE] プロンプト引数は制限付きタスクデータとして扱われ、再利用可能なMCPプロンプトテンプレートに挿入される前にエスケープされます。プロンプト自体は直接ファイルシステムI/Oを実行しません。実際のファイル読み取りと検索は、厳格なルート許可リスト制御の下で、標準のMCPツールとリソースを使用してモデルが実行します。

読み取り専用ワークスペースアクセス

ファイルシステムアクセスはデフォルトで無効です。読み取り専用ワークスペースアクセスを有効にするには、--profile=workspace（または --profile=all）と、少なくとも1つの許可リスト化された --root ディレクトリを明示的に指定します:

# POSIX / macOS / Linux
npx high-performance-mcp-server --profile=workspace --root=/home/user/my-project

# Windows
npx high-performance-mcp-server --profile=workspace --root="C:\Projects\app"

# Multiple roots
npx high-performance-mcp-server --profile=workspace --root=./packages/core --root=./packages/cli

セキュリティ保証と制約

• ホストパスプライバシー: 設定された絶対ファイルシステムパスはサーバー内部に留まります。workspace_roots ツールと workspace://roots リソースは、ホストの絶対パスではなく論理ルート識別子（id: "root-1"、name: "my-project"）を返します:

  {
    "roots": [
      {
        "id": "root-1",
        "name": "my-project"
      }
    ]
  }

• 厳格な許可リスト: 明示的に渡された --root ディレクトリのみアクセス可能です。一意のルートは最大16個（重複排除前の生パスは最大64個）です。

• 読み取り専用: サーバーコードベースにはファイルシステム変更関数（writeFile、unlink、rm、mkdir、rename など）は存在しません。

• トラバーサルとシンボリックリンク保護: ターゲットパスは fs.realpath を使用して正規化され、ルート境界を決して越えないことが厳密に検証されます。

• サニタイズされたエラー: エラーレスポンスは論理ルートID、ルート名、要求された相対パスのみを参照し、内部ディレクトリ構造が漏洩しないことを保証します。

• ファイル読み取り制限: デフォルトのテキスト読み取り制限は256 KiB、ハード上限は1 MiB（MAX_TEXT_READ_BYTES）です。

• バイナリファイル検出: NULバイト（\0）を含むファイルは、コンテキスト汚染を防ぐために read_text_file で拒否されます。

• MCPリソース: workspace://roots（ルートの静的リスト）と workspace://file/{rootId}{?path}（動的テキストリーダー）を公開します。

ワークスペースの検索

workspace プロファイルは、制限付きの読み取り専用検索ツールを提供します:

1. search_files:

   • リテラル部分文字列マッチングを使用してファイル名とディレクトリ名を検索します。

   • 種類（file、directory、all）、大文字小文字の区別、開始パスでフィルタリングします。

   • 一般的なビルド・ベンダーディレクトリ（.git、node_modules、.next、dist、build、target など）はデフォルトでスキップします。検索するには includeIgnored: true を渡します。

   • 再帰サイクルとエスケープを防ぐため、シンボリックリンク・ジャンクションディレクトリには決してトラバースしません。

2. search_text:

   • 固定並行性（8ワーカー）で制限付きリテラルマッチングを使用してUTF-8テキストファイルを検索します。

   • 1ベースの行、列、トリミングされたプレビュースニペット（最大300文字）を返します。

   • ファイル拡張子フィルターをサポートします（例: extensions: [".ts", ".md"] または extensions: ["ts", "md"]）。

   • バイナリファイル（NULバイト）と1 MiB（MAX_SEARCH_FILE_BYTES）を超えるファイルを自動的にスキップします。

   • 制限: ハードデフォルト（maxResults: 100 [最大500]、maxFiles: 5000 [最大50000]、timeoutMs: 10000 [最大30000]）。

   • クライアントの AbortSignal による完全キャンセルに対応しています。

コマンドラインインターフェース（CLI）

Usage:
  high-performance-mcp-server [options]

Options:
  --transport=<stdio|http>   Transport protocol to run (default: stdio)
  --port=<number>            HTTP server port (default: 3000, only for http transport)
  --profile=<profile>        Security tool profile (default: safe)
  --root=<path>              Allowlisted read-only workspace root (repeatable, max 16)
  --list-tools               Display available tools for the active profile and exit
  --help, -h                 Show this help message and exit
  --version, -v              Show version and exit

例

# Start default safe server on stdio
high-performance-mcp-server

# List tools available under the workspace profile
high-performance-mcp-server --profile=workspace --list-tools

# Run Streamable HTTP transport on port 8080 with workspace profile
high-performance-mcp-server --transport=http --port=8080 --profile=workspace --root=./project

HTTPトランスポートの詳細

--transport=http で起動すると、サーバーはNode.js組み込みの node:http を使用してStreamable HTTPトランスポートを起動します:

• エンドポイント: http://127.0.0.1:<port>/mcp

• セキュリティ: サーバーは厳密に 127.0.0.1 にバインドし、DNSリバインディングとクロスサイトリクエストフォージェリを防ぐために Host ヘッダーと Origin ヘッダーを検証します。

• 警告: 認証用のリバースプロキシやゲートウェイなしで、HTTPトランスポートを信頼できないネットワークに直接公開しないでください。

環境変数

開発

# Install dependencies
npm install

# Run code generator and TypeScript typecheck
npm run typecheck

# Execute unit, security, search, and modern protocol integration test suites
npm test

# Build production bundle
npm run build

# Validate npm package payload without publishing
npm run pack:check

# Run package payload security & privacy scan
npm run security:package

# Run end-to-end tarball installation smoke test
npm run smoke:package

アーキテクチャ

MCP Clients (Claude Desktop, Cursor, Custom SDK Clients)
                       │
       ┌───────────────┴───────────────┐
       ▼                               ▼
  Stdio Transport             Streamable HTTP Transport
(process.stdin / stdout)         (127.0.0.1:3000/mcp)
       │                               │
       └───────────────┬───────────────┘
                       ▼
                McpServer Instance
      (Profile-Aware Server Instructions)
                       │
       ┌───────────────┴───────────────┐
       ▼                               ▼
  Tool & Prompt Profiles       Internal Telemetry
(safe, workspace, diag, ...)    (Metrics & Stderr Logger)
       │                               │
       ├──────► Read-Only Workspace, Search, Resources & Prompts (Allowlisted Roots, Host Privacy)
       │
       ├──────► In-Memory LRU Cache (Single-Flight Stampede Protection)
       │
       └──────► Reusable Worker Thread Pool (CPU Offloading)

セキュリティ

• デフォルトのセキュリティプロファイル（safe）は、明示的なオプトインなしにはファイルシステムやハードウェアの検査が公開されないことを保証します。

• 読み取り専用のワークスペースアクセスは、ホストのファイルシステムの絶対パスを明かすことなく、設定された--rootディレクトリへのファイルアクセスを厳密に分離します。

• サーバーの指示とプロンプトは、文字エスケープにより、安全なツールの実行順序と明確なタスク境界を強化します。

• StdioトランスポートはJSON-RPCメッセージ専用にstdoutを予約し、内部のデバッグログとテレメトリログはすべてstderrに送信されます。

• HTTPトランスポートは、厳格なlocalhostオリジンとホストヘッダーの検証を強制します。

詳細については、SECURITY.mdを参照してください。

コントリビューションとリリース

コントリビューションとフィードバックを歓迎します！コードスタイル、ツール開発の規約、テスト要件、メンテナーによるリリースワークフローの詳細については、CONTRIBUTING.mdをお読みください。

ライセンス

このプロジェクトはMIT Licenseの下でライセンスされています。