Высокопроизводительный MCP-сервер

Высокопроизводительный, модульный сервер Model Context Protocol (MCP), написанный на TypeScript с использованием современного MCP v2 SDK (@modelcontextprotocol/server). Особенности: безопасные по умолчанию профили безопасности, зависящие от профиля инструкции сервера, модульные MCP-промпты, доступ к рабочей области только для чтения с поиском и защитой конфиденциальности путей хоста, Streamable HTTP, транспорт Stdio, переиспользуемый пул рабочих потоков, производственное LRU-кэширование с защитой от лавинообразных запросов (single-flight) и структурированная телеметрия.

Статус проекта: публичная предварительная версия (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 МиБ и защита от бинарных файлов без раскрытия абсолютных путей хоста клиентам или моделям.

• Поиск по рабочей области v1: Быстрый, ограниченный поиск файлов и текста (search_files, search_text) с игнорируемыми по умолчанию каталогами, ограниченным параллелизмом, сопоставлением координат и отменой со стороны клиента.

• Пул рабочих потоков: Выгрузка ресурсоёмких задач из цикла событий Node.js с автоматическим восстановлением жизненного цикла и инвариантами без дрейфа.

• Производственное LRU-кэширование: Кэш с ограничением памяти, поддержкой TTL и объединением запросов (single-flight) для устранения лавинообразных запросов.

• Внутреннее структурированное логирование: Безопасное для stdio JSON-логирование исключительно в stderr.

Быстрый старт

Конфигурация MCP-клиента (Claude Desktop, Cursor и т.д.)

Добавьте в вашу MCP-конфигурацию (например, claude_desktop_config.json):

Профиль Safe по умолчанию (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: Направляет на интерпретацию наблюдательных метрик и предупреждает о ненужных вызовах ресурсоёмких вычислений.

• admin: Отмечает, что операции изменения затрагивают только локальные для процесса кэши и состояние телеметрии.

Модульные MCP-промпты

При работе в профиле workspace или all сервер предоставляет модульные промпты, обеспечивающие структурированные рабочие процессы для типовых инженерных задач:

[!NOTE] Аргументы промптов рассматриваются как ограниченные данные задач и экранируются перед вставкой в переиспользуемые шаблоны MCP-промптов. Промпты не выполняют прямой ввод-вывод файловой системы; фактическое чтение файлов и поиск выполняются моделью с использованием стандартных MCP-инструментов и ресурсов под строгим контролем разрешённых корней.

Доступ к рабочей области только для чтения

Доступ к файловой системе отключён по умолчанию. Чтобы включить доступ к рабочей области только для чтения, явно укажите --profile=workspace (или --profile=all) и хотя бы один разрешённый каталог --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 и строго проверяются на невозможность выхода за границы корней.

• Очищенные ошибки: Ответы об ошибках ссылаются только на логические идентификаторы корней, имена корней и запрошенные относительные пути, что гарантирует отсутствие утечки внутренней структуры каталогов.

• Лимиты чтения файлов: Лимит чтения текста по умолчанию — 256 КиБ; жёсткий верхний предел — 1 МиБ (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:

   • Ищет в UTF-8 текстовых файлах с помощью ограниченного буквального сопоставления с фиксированным параллелизмом (8 рабочих потоков).

   • Возвращает 1-индексированные строки, столбцы и обрезанные фрагменты предпросмотра (до 300 символов).

   • Поддерживает фильтры по расширениям файлов (например, extensions: [".ts", ".md"] или extensions: ["ts", "md"]).

   • Автоматически пропускает бинарные файлы (NUL-байты) и файлы размером более 1 МиБ (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 сервер запускает транспорт Streamable HTTP с использованием встроенного node:http:

• Конечная точка: http://127.0.0.1:<port>/mcp

• Безопасность: Сервер привязывается строго к 127.0.0.1 и проверяет заголовки Host и Origin для защиты от DNS-реббиндинга и межсайтовой подделки запросов.

• Предупреждение: Не открывайте 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 резервирует stdout исключительно для сообщений JSON-RPC; все внутренние журналы отладки и телеметрии направляются в stderr.

• HTTP-транспорт обеспечивает строгую проверку источника localhost и заголовка Host.

Подробнее см. в SECURITY.md.

Участие в разработке и релизы

Вклад и отзывы приветствуются! Пожалуйста, прочитайте CONTRIBUTING.md, чтобы узнать подробности о стиле кода, соглашениях по разработке инструментов, требованиях к тестированию и процессе выпуска релизов мейнтейнером.

Лицензия

Этот проект лицензирован на условиях лицензии MIT.