local-mcp
Servidor MCP sin dependencias para operaciones locales de archivos. 13 herramientas del sistema de archivos + 3 metaherramientas para descubrimiento progresivo — sin SDKs, sin frameworks, sin necesidad de npm install.
Protocolo MCP: 2024-11-05 · Transporte: stdio + HTTP transmisible · Ejecución: Node.js ≥ 22.0.0
Arquitectura
local-mcp.mjs — 595 líneas, 13 herramientas, punto de entrada
lib/mcp-core.mjs — 229 líneas, transporte stdio + HTTP, 9 métodos MCP
lib/config.mjs — 31 líneas, configuración de entorno MCP_WORKSPACE/DATA con validación
Total: ~855 líneas, cero dependencias en tiempo de ejecución.
Herramientas
Herramientas del sistema de archivos (13)
| Herramienta | Descripción |
|---|
search_tools | Buscar herramientas disponibles por palabra clave — ahorra ~90% de tokens comparado con listar todas |
describe_tool | Obtener el esquema de entrada completo de una herramienta específica (cargado bajo demanda) |
call_tool | Ejecutar cualquier herramienta por nombre con argumentos |
En lugar de enviar los 13 esquemas de herramientas (~3000 tokens) en cada solicitud, el descubrimiento progresivo con estas 3 metaherramientas lo reduce a ~50 tokens — ~90% de ahorro de tokens.
Optimizaciones de rendimiento (v1.1.1)
Optimizaciones adicionales
Primeros pasos
# Sin instalación — sin dependencias
node local-mcp.mjs
# Con configuración
MCP_WORKSPACE=D:/projects node local-mcp.mjs
Modo stdio (predeterminado)
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
Modo HTTP
node local-mcp.mjs --http
node local-mcp.mjs --http --port 3456
Soporta POST JSON-RPC 2.0, transmisión SSE (Accept: text/event-stream), CORS y GET /tools.
Banderas de CLI
node local-mcp.mjs --help # Mostrar uso + variables de entorno
node local-mcp.mjs --list-tools # Imprimir herramientas disponibles y salir
node local-mcp.mjs --http # Iniciar modo HTTP
node local-mcp.mjs --http --port 3456
Configuración
Seguridad
- Todas las operaciones de archivos restringidas a
MCP_WORKSPACE y subdirectorios
- Claves de marcador a prueba de prototipos (bloquea inyección de
__proto__/constructor/prototype)
- Escrituras atómicas (temp + renombrar) previenen escrituras parciales de archivos
- Detección de archivos binarios impide leer archivos no textuales
.gitignore y directorios comunes excluidos (node_modules, .git, etc.) respetados
Dependencias
Cero dependencias en tiempo de ejecución. Usa solo módulos integrados de Node.js:
Registro de cambios
v1.1.1 — Optimizaciones de rendimiento
- A. Lectura de head/tail en streaming: logs de 500MB 3s → 5ms
- B. Stat perezoso en ls: directorio de 1000 archivos 50ms → 2ms
- C. Concurrencia adaptativa en grep con
availableParallelism()
- D. Eliminación de caché LRU mediante orden de inserción en Map
- E. Protección de bytes en grep (100MB / 1000 archivos)
- F. Pase directo de notificación de progreso para especificación MCP 2025
- Corrección: Error de ámbito en
streamHead — done definido fuera del callback de Promise
v1.1.0
- 13 herramientas del sistema de archivos + 3 metaherramientas para descubrimiento progresivo
- Transporte stdio + HTTP transmisible
- Motor diff de Myers, caché de lectura, ejecución en streaming
- Configuración basada en entorno con validación
Desarrollo
# Ejecutar pruebas
node --test test/*.test.mjs
# Añadir una herramienta
# 1. Definir esquema + manejador en local-mcp.mjs
# 2. Registrar con server.tool()
# 3. Añadir pruebas
Contribuciones
- Mantener la restricción de cero dependencias
- Añadir pruebas para nueva funcionalidad
- Actualizar la tabla de Optimizaciones para cambios de rendimiento
Licencia
MIT
