Servidor MCP de Alto Rendimiento

Un servidor de Model Context Protocol (MCP) modular y de alto rendimiento, construido con TypeScript y el moderno SDK de MCP v2 (@modelcontextprotocol/server). Incluye perfiles de seguridad seguros por defecto, instrucciones de servidor conscientes del perfil, prompts MCP modulares, acceso de solo lectura al espacio de trabajo con búsqueda y privacidad de rutas del host, HTTP Streamable, transporte Stdio, agrupación reutilizable de subprocesos de trabajo, caché LRU de producción con protección contra avalanchas de un solo vuelo y telemetría estructurada.

Estado del Proyecto: Vista Previa Pública (v0.1.0)

[!NOTA] Estado: 0.1.0 Vista Previa Pública. Este paquete proporciona herramientas MCP seguras por defecto, inspección de espacio de trabajo de solo lectura y ejecución de trabajadores de alto rendimiento. Requiere Node.js >= 22.0.0.

Related MCP server: VSCode LSP MCP Server

Características

• Arquitectura MCP v2 Moderna: Construido nativamente sobre @modelcontextprotocol/server con validación estándar de JSON Schema draft 2020-12 y soporte completo del protocolo 2026-07-28.

• Soporte de Doble Transporte: Ejecútese sin problemas sobre entrada/salida estándar (stdio) o HTTP Streamable moderno (node:http + /mcp).

• Instrucciones de Servidor Conscientes del Perfil: Instrucciones dinámicas del servidor que guían a los LLM conectados sobre flujos de trabajo recomendados, secuenciación de herramientas y límites de seguridad según el perfil activo.

• Prompts MCP Modulares: Prompts de tareas reutilizables (explore_workspace, find_and_explain, review_file, trace_symbol) expuestos exclusivamente en los perfiles workspace y all.

• Perfiles de Herramientas Seguros por Defecto: El perfil safe predeterminado expone cero inspección de sistema de archivos o hardware. Opt-in explícito para workspace, diagnostics, benchmark, admin o all.

• Privacidad de Rutas del Host y Espacio de Trabajo de Solo Lectura: Acceso seguro a directorios en lista blanca con prevención de traversal de rutas y escapes de enlaces simbólicos, mapeo de raíces lógicas (root-1, root-2), límites estrictos de 1 MiB y protección de archivos binarios sin exponer rutas absolutas del host a clientes o modelos.

• Búsqueda de Espacio de Trabajo v1: Búsqueda rápida y acotada de archivos y texto literal (search_files, search_text) con directorios ignorados por defecto, concurrencia acotada, mapeo de coordenadas y cancelación por parte del cliente.

• Grupo de Subprocesos de Trabajo: Descargue tareas pesadas de CPU del bucle de eventos de Node.js con recuperación automática del ciclo de vida e invariantes sin desviación.

• Caché LRU de Producción: Caché con límite de memoria, soporte de TTL y coalescencia de solicitudes de un solo vuelo para eliminar avalanchas de caché.

• Registro Estructurado Interno: Registro JSON seguro para stdio exclusivamente en stderr.

Inicio Rápido

Configuración del Cliente MCP (Claude Desktop, Cursor, etc.)

Agregue a su configuración de MCP (por ejemplo, claude_desktop_config.json):

Perfil Seguro Predeterminado (Stdio)

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

Perfil de Espacio de Trabajo de Solo Lectura

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

Desarrollo Local / Ejecución desde el Código Fuente

# 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=.

Perfiles Seguros por Defecto

Para proteger las máquinas host y prevenir el consumo no intencionado de recursos o la fuga de metadatos, las herramientas, recursos, instrucciones y prompts se categorizan en perfiles de seguridad:

Instrucciones del Servidor y Prompts

Instrucciones del Servidor Conscientes del Perfil

Cuando un cliente MCP se conecta, el servidor entrega instrucciones concisas y adaptadas al perfil a través del protocolo MCP:

• safe: Indica al modelo que la inspección del sistema de archivos y del hardware no está disponible.

• workspace: Describe la secuencia de investigación recomendada (workspace_roots -> search_files / search_text -> file_info -> read_text_file), refuerza las restricciones de solo lectura y enfatiza el uso de rutas relativas a la raíz.

• diagnostics y benchmark: Guía la interpretación de métricas observacionales y advierte contra invocaciones innecesarias de cómputo intensivo en CPU.

• admin: Señala que las operaciones de mutación afectan solo a las cachés locales del proceso y al estado de telemetría.

Prompts MCP Modulares

Cuando se ejecuta en el perfil workspace o all, el servidor expone prompts modulares que proporcionan flujos de trabajo estructurados para tareas comunes de ingeniería:

[!NOTA] Los argumentos de los prompts se tratan como datos de tarea acotados y se escapan antes de insertarse en las plantillas de prompts MCP reutilizables. Los prompts no ejecutan E/S directa del sistema de archivos por sí mismos; la lectura y búsqueda real de archivos la realiza el modelo utilizando herramientas y recursos MCP estándar bajo estrictos controles de lista blanca de raíces.

Acceso de Solo Lectura al Espacio de Trabajo

El acceso al sistema de archivos está deshabilitado por defecto. Para habilitar el acceso de solo lectura al espacio de trabajo, especifique explícitamente --profile=workspace (o --profile=all) y al menos un directorio --root en lista blanca:

# 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

Garantías y Restricciones de Seguridad

• Privacidad de Rutas del Host: Las rutas absolutas configuradas del sistema de archivos permanecen internas al servidor. La herramienta workspace_roots y el recurso workspace://roots devuelven identificadores de raíz lógicos (id: "root-1", name: "my-project") en lugar de rutas absolutas del host:

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

• Lista Blanca Estricta: Solo se pueden acceder a los directorios --root pasados explícitamente. Se permiten un máximo de 16 raíces únicas (y un máximo de 64 rutas crudas antes de la deduplicación).

• Solo Lectura: No existen funciones de mutación del sistema de archivos (writeFile, unlink, rm, mkdir, rename, etc.) en el código del servidor.

• Protección contra Traversal y Enlaces Simbólicos: Las rutas de destino se canonicalizan usando fs.realpath y se verifican estrictamente para que nunca escapen de los límites de la raíz.

• Errores Saneados: Las respuestas de error hacen referencia solo a IDs de raíz lógicos, nombres de raíz y rutas relativas solicitadas, asegurando que las estructuras de directorios internas nunca se filtren.

• Límites de Lectura de Archivos: El límite de lectura de texto predeterminado es de 256 KiB; el límite superior estricto es de 1 MiB (MAX_TEXT_READ_BYTES).

• Detección de Archivos Binarios: Los archivos que contienen bytes NUL (\0) son rechazados por read_text_file para prevenir la contaminación del contexto.

• Recursos MCP: Expone workspace://roots (lista estática de raíces) y workspace://file/{rootId}{?path} (lector de texto dinámico).

Búsqueda en el Espacio de Trabajo

El perfil workspace proporciona herramientas de búsqueda acotadas y de solo lectura:

1. search_files:

   • Busca nombres de archivos y directorios usando coincidencia de subcadenas literales.

   • Filtra por tipo (file, directory, all), sensibilidad a mayúsculas y ruta de inicio.

   • Omite directorios comunes de compilación/vendor (.git, node_modules, .next, dist, build, target, etc.) por defecto. Pase includeIgnored: true para buscarlos.

   • Nunca atraviesa directorios de enlaces simbólicos/junctions para prevenir ciclos de recursión y escapes.

2. search_text:

   • Busca archivos de texto UTF-8 usando coincidencia literal acotada con concurrencia fija (8 trabajadores).

   • Devuelve línea, columna y fragmentos de vista previa recortados (hasta 300 caracteres) basados en 1.

   • Soporta filtros de extensión de archivo (por ejemplo, extensions: [".ts", ".md"] o extensions: ["ts", "md"]).

   • Omite automáticamente archivos binarios (bytes NUL) y archivos mayores de 1 MiB (MAX_SEARCH_FILE_BYTES).

   • Límites: Valores predeterminados estrictos (maxResults: 100 [máx. 500], maxFiles: 5000 [máx. 50000], timeoutMs: 10000 [máx. 30000]).

   • Totalmente cancelable mediante AbortSignal del cliente.

Interfaz de Línea de Comandos (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

Ejemplos

# 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

Detalles del Transporte HTTP

Cuando se inicia con --transport=http, el servidor lanza un transporte HTTP Streamable usando el node:http integrado de Node.js:

• Endpoint: http://127.0.0.1:<port>/mcp

• Seguridad: El servidor se vincula estrictamente a 127.0.0.1 y valida los encabezados Host y Origin para proteger contra el rebinding de DNS y la falsificación de solicitudes entre sitios.

• Advertencia: No exponga el transporte HTTP directamente a redes no confiables sin un proxy inverso o puerta de enlace autenticada.

Variables de Entorno

Desarrollo

# 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

Arquitectura

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)

Seguridad

• El perfil de seguridad predeterminado (safe) garantiza que no se exponga ninguna inspección del sistema de archivos o del hardware sin una aceptación explícita.

• El acceso de solo lectura al espacio de trabajo aísla estrictamente el acceso a archivos en los directorios --root configurados, sin revelar rutas absolutas del sistema de archivos del host.

• Las instrucciones y las indicaciones del servidor refuerzan la secuenciación segura de las herramientas y los límites explícitos de las tareas con escape de caracteres.

• El transporte Stdio reserva stdout exclusivamente para mensajes JSON-RPC; todos los registros internos de depuración y telemetría se enrutan a stderr.

• El transporte HTTP aplica una validación estricta del origen localhost y de la cabecera Host.

Para obtener más detalles, revisa SECURITY.md.

Contribuciones y lanzamientos

¡Las contribuciones y los comentarios son bienvenidos! Por favor, lee CONTRIBUTING.md para obtener detalles sobre el estilo de código, las convenciones de desarrollo de herramientas, los requisitos de pruebas y el flujo de trabajo de lanzamientos para mantenedores.

Licencia

Este proyecto se distribuye bajo la Licencia MIT.