local-mcp
Сервер 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 строк, нулевые зависимости времени выполнения.
Инструменты
Инструменты файловой системы (13)
Мета-инструменты (3) — Прогрессивное обнаружение
| Инструмент | Описание |
|---|
search_tools | Поиск доступных инструментов по ключевому слову — экономит ~90% токенов по сравнению со списком всех |
describe_tool | Получение полной схемы ввода для конкретного инструмента (загружается по запросу) |
call_tool | Выполнение любого инструмента по имени с аргументами |
Вместо отправки всех 13 схем инструментов (~3000 токенов) в каждом запросе, прогрессивное обнаружение с помощью этих 3 мета-инструментов сокращает это до ~50 токенов — ~90% экономии токенов.
Оптимизации производительности (v1.1.1)
Дополнительные оптимизации
Начало работы
# Zero install — no dependencies
node local-mcp.mjs
# With configuration
MCP_WORKSPACE=D:/projects node local-mcp.mjs
Режим stdio (по умолчанию)
{
"mcpServers": {
"local-mcp": {
"command": "node",
"args": ["D:/path/to/local-mcp.mjs"],
"env": {
"MCP_WORKSPACE": "D:/projects"
}
}
}
}
Режим HTTP
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.
Флаги CLI
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 и подкаталогами
- Ключи закладок, безопасные для прототипов (блокирует внедрение
__proto__/constructor/prototype)
- Атомарная запись (temp + rename) предотвращает частичную запись файлов
- Обнаружение двоичных файлов предотвращает чтение нетекстовых файлов
- Учитываются
.gitignore и стандартные исключаемые каталоги (node_modules, .git и т.д.)
Зависимости
Нулевые зависимости времени выполнения. Используются только встроенные модули Node.js:
Журнал изменений
v1.1.1 — Оптимизации производительности
- A. Потоковое чтение head/tail: 500МБ логи 3с → 5мс
- B. Ленивый stat в ls: каталог с 1000 файлов 50мс → 2мс
- C. Адаптивная параллельность grep с
availableParallelism()
- D. Вытеснение LRU-кэша через порядок вставки Map
- E. Защита объема байт в grep (100МБ / 1000 файлов)
- F. Пропуск уведомления о прогрессе для спецификации MCP 2025
- Исправление: ошибка области видимости
streamHead — done определен вне колбэка Promise
v1.1.0
- 13 инструментов файловой системы + 3 мета-инструмента для прогрессивного обнаружения
- Транспорт stdio + Streamable HTTP
- Движок Myers diff, кэш чтения, потоковое выполнение
- Конфигурация на основе переменных среды с проверкой
Разработка
# 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
