Un servidor MCP ligero basado en stdio para operaciones del sistema de archivos local — lectura, escritura, edición, búsqueda, ejecución para asistentes de IA. Especialmente optimizado para Chatbox: bat-bypass para exec (CVE-2026-6130), codificación b64 para eliminar problemas de escape y regex de múltiples patrones para un direccionamiento preciso de bloques de código.
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
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.
| Herramienta | Descripción | Anotación |
|---|---|---|
read | Leer archivo con números de línea, truncamiento opcional head/tail | readOnlyHint |
search | Búsqueda de archivos por nombre (glob) y luego por contenido (grep) | readOnlyHint |
ls | Listado compacto de directorios con stat perezoso | readOnlyHint |
exec | Ejecución de comandos en streaming con soporte de stdin y tiempo de espera | destructiveHint |
diff | Comparar dos archivos o cadenas de texto (Myers O(ND)) | readOnlyHint |
copy | Copiar archivo o directorio | destructiveHint |
move | Mover o renombrar archivo/directorio | destructiveHint |
batch | Ejecutar múltiples operaciones secuencialmente; reversión atómica, referencias $prev | destructiveHint |
file | Unificado: leer, escribir, editar, añadir, eliminar, información, mkdir, mover | — |
block | Leer/reemplazar/insertar/eliminar bloques de código por rango o nombre de función | — |
bookmark | Alias de ruta persistentes (añadir/obtener/listar/eliminar) | — |
grep | Formato compacto archivo:línea:contenido con concurrencia adaptativa | readOnlyHint |
watch | Vigilar archivo/directorio para cambios; máximo 20 vigilantes concurrentes | — |
| 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.
| # | Optimización | Impacto |
|---|---|---|
| A | Lectura de head/tail en streaming | streamHead() evita leer archivos completos. Logs de 500MB: 3s → 5ms, memoria: 500MB → pocos KB |
| B | Stat perezoso en ls | Solo llama a statSync cuando sort=size. Directorio de 1000 archivos: 50ms → 2ms |
| C | Concurrencia adaptativa en grep | os.availableParallelism() (máx. 16, mín. 4) en lugar de 16 trabajadores fijos |
| D | Eliminación de caché LRU | LRU por orden de inserción en Map — archivos pequeños calientes ya no son eliminados por archivos grandes fríos |
| E | Protección de bytes en grep | MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 previenen desbordamiento de memoria |
| F | Notificación de progreso | Pase directo de _meta.progressToken para especificación MCP 2025 (TODO: eventos para ejecuciones largas) |
| Área | Detalle |
|---|---|
| Caché de lectura | Eliminación consciente del tamaño (máx. 50 elementos, 10 MB) + TTL de 5s |
| Diff de Myers | Algoritmo O(ND), usado por edit, block y diff |
| Puntuación de búsqueda | Primero coincidencia de nombre (sin E/S), luego stat solo de los 50 mejores candidatos |
| Formato de salida | grep: archivo:línea:contenido, ls: columnas compactas, read: números de línea + sugerencia de truncamiento |
| Protocolo | Despacho en Map O(1), cortocircuito de manejador síncrono |
# Sin instalación — sin dependencias
node local-mcp.mjs
# Con configuración
MCP_WORKSPACE=D:/projects node local-mcp.mjs
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
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.
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
| Variable | Predeterminado | Descripción |
|---|---|---|
MCP_WORKSPACE | process.cwd() | Directorio raíz del espacio de trabajo (límite de seguridad) |
MCP_DATA | {WORKSPACE}/.mcp-data | Directorio de datos (marcadores, archivos temporales) |
MCP_DIR | {WORKSPACE} | Directorio predeterminado para comandos tree/ls |
MCP_PORT | 3100 | Puerto del servidor HTTP (cuando se usa --http) |
MCP_READONLY | false | Establecer a true para bloquear todas las operaciones de escritura |
MCP_EXCLUDE | — | Directorios adicionales separados por coma para excluir de la búsqueda |
MCP_WORKSPACE y subdirectorios__proto__/constructor/prototype).gitignore y directorios comunes excluidos (node_modules, .git, etc.) respetadosCero dependencias en tiempo de ejecución. Usa solo módulos integrados de Node.js:
| Módulo | Propósito |
|---|---|
fs | Sistema de archivos + glob (Node 22) |
child_process | Ejecución de shell en streaming |
http | Transporte HTTP (sin necesidad de Express) |
path | Resolución de rutas |
os | availableParallelism() para concurrencia adaptativa |
readline | Procesamiento línea por línea en streaming |
availableParallelism()streamHead — done definido fuera del callback de Promise# 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
MIT