Лёгкий MCP-сервер на основе stdio для операций с локальной файловой системой — чтение, запись, редактирование, поиск, exec для AI-ассистентов. Специально оптимизирован для Chatbox: bat-bypass для exec (CVE-2026-6130), кодирование b64 для устранения проблем с экранированием и многопатерновый regex для точного нацеливания на блоки кода.
Сервер MCP с нулевыми зависимостями для локальных операций с файлами. 13 инструментов файловой системы + 3 мета-инструмента для прогрессивного обнаружения — не требуется SDK, фреймворков или npm install.
Протокол MCP: 2024-11-05 · Транспорт: stdio + Streamable HTTP · Среда выполнения: Node.js ≥ 22.0.0
local-mcp.mjs — 595 lines, 13 tools, entry point
lib/mcp-core.mjs — 229 lines, stdio + HTTP transport, 9 MCP methods
lib/config.mjs — 31 lines, MCP_WORKSPACE/DATA env config with validation
Всего: ~855 строк, нулевые зависимости времени выполнения.
| Инструмент | Описание | Аннотация |
|---|---|---|
read | Чтение файла с номерами строк, опциональное усечение head/tail | readOnlyHint |
search | Поиск файлов по имени (glob) затем по содержимому (grep) | readOnlyHint |
ls | Компактный список каталогов с ленивым stat | readOnlyHint |
exec | Потоковое выполнение команд с поддержкой stdin и таймаутом | destructiveHint |
diff | Сравнение двух файлов или текстовых строк (Myers O(ND)) | readOnlyHint |
copy | Копирование файла или каталога | destructiveHint |
move | Перемещение или переименование файла/каталога | destructiveHint |
batch | Выполнение нескольких операций последовательно; атомарный откат, ссылки $prev | destructiveHint |
file | Унифицированная: чтение, запись, редактирование, добавление, удаление, информация, mkdir, перемещение | — |
block | Чтение/замена/вставка/удаление блоков кода по диапазону или имени функции | — |
bookmark | Постоянные псевдонимы путей (добавить/получить/список/удалить) | — |
grep | Компактный формат file:line:content с адаптивной параллельностью | readOnlyHint |
watch | Отслеживание файла/каталога на изменения; макс. 20 одновременных наблюдателей | — |
| Инструмент | Описание |
|---|---|
search_tools | Поиск доступных инструментов по ключевому слову — экономит ~90% токенов по сравнению со списком всех |
describe_tool | Получение полной схемы ввода для конкретного инструмента (загружается по запросу) |
call_tool | Выполнение любого инструмента по имени с аргументами |
Вместо отправки всех 13 схем инструментов (~3000 токенов) в каждом запросе, прогрессивное обнаружение с помощью этих 3 мета-инструментов сокращает это до ~50 токенов — ~90% экономии токенов.
| # | Оптимизация | Влияние |
|---|---|---|
| A | Потоковое чтение head/tail | streamHead() избегает чтения всего файла. 500МБ логи: 3с → 5мс, память: 500МБ → несколько КБ |
| B | Ленивый stat в ls | Вызывает statSync только при sort=size. Каталог с 1000 файлов: 50мс → 2мс |
| C | Адаптивная параллельность grep | os.availableParallelism() (макс. 16, мин. 4) вместо жестко заданных 16 рабочих |
| D | Вытеснение LRU-кэша | LRU на основе порядка вставки Map — горячие маленькие файлы больше не вытесняются холодными большими файлами |
| E | Защита объема байт в grep | Защита MAX_GREP_TOTAL_MB=100 + MAX_GREP_FILES=1000 предотвращает OOM |
| F | Уведомление о прогрессе | Пропуск _meta.progressToken для спецификации MCP 2025 (TODO: события для длительного выполнения) |
| Область | Подробности |
|---|---|
| Кэш чтения | Вытеснение с учетом размера (макс. 50 элементов, 10 МБ) + TTL 5 с |
| Myers diff | Алгоритм O(ND), используется edit, block и diff |
| Оценка поиска | Сначала совпадение имени (без I/O), затем stat только для топ-50 кандидатов |
| Формат вывода | grep: file:line:content, ls: компактные столбцы, read: номера строк + подсказка об усечении |
| Протокол | Диспетчеризация Map O(1), короткое замыкание синхронного обработчика |
# Zero install — no dependencies
node local-mcp.mjs
# With configuration
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
Поддерживает JSON-RPC 2.0 POST, потоковую передачу SSE (Accept: text/event-stream), CORS и GET /tools.
node local-mcp.mjs --help # Show usage + env vars
node local-mcp.mjs --list-tools # Print available tools and exit
node local-mcp.mjs --http # Start HTTP mode
node local-mcp.mjs --http --port 3456
| Переменная | По умолчанию | Описание |
|---|---|---|
MCP_WORKSPACE | process.cwd() | Корень рабочего каталога (граница безопасности) |
MCP_DATA | {WORKSPACE}/.mcp-data | Каталог данных (закладки, временные файлы) |
MCP_DIR | {WORKSPACE} | Каталог по умолчанию для команд tree/ls |
MCP_PORT | 3100 | Порт HTTP-сервера (при использовании --http) |
MCP_READONLY | false | Установите true, чтобы заблокировать все операции записи |
MCP_EXCLUDE | — | Дополнительные каталоги (через запятую) для исключения из поиска |
MCP_WORKSPACE и подкаталогами__proto__/constructor/prototype).gitignore и стандартные исключаемые каталоги (node_modules, .git и т.д.)Нулевые зависимости времени выполнения. Используются только встроенные модули Node.js:
| Модуль | Назначение |
|---|---|
fs | Файловая система + glob (Node 22) |
child_process | Потоковое выполнение команд оболочки |
http | HTTP-транспорт (Express не требуется) |
path | Разрешение путей |
os | availableParallelism() для адаптивной параллельности |
readline | Потоковая обработка построчно |
availableParallelism()streamHead — done определен вне колбэка Promise# Run tests
node --test test/*.test.mjs
# Adding a tool
# 1. Define schema + handler in local-mcp.mjs
# 2. Register with server.tool()
# 3. Add tests
MIT