Local MCP Easy

Локальные файловые инструменты, команды и Git через MCP — по Streamable HTTP с OAuth 2.1.

One-click MCP-сервер для Windows: агент получает безопасные инструменты для чтения, поиска и изменения файлов в выбранной рабочей папке. Отдельно включается доверенный developer-режим (Python, Git, Node) с защитным git setup-flow. Стабильный публичный адрес — через зарезервированный Serveo hostname, собственный домен за обратным прокси или self-hosted sish-туннель (см. SISH_SETUP.md и REVERSE_PROXY.md). На Linux/macOS вместо .bat используйте .sh-обёртки (./setup.sh, ./start.sh, …).

Совместим с Hyperagent, Notion и другими MCP-клиентами.

Режимы авторизации

• dual — Bearer token и OAuth 2.1 одновременно на одном /mcp (по умолчанию с 2.1.0);
• oauth — только OAuth 2.1 с Dynamic Client Registration и PKCE (S256) для любых OAuth MCP-клиентов;
• legacy — только статический Bearer token (классическое поведение 1.x).

Клиент со статическим токеном ── Bearer ─┐
                                         ├─ /mcp → общий набор MCP-инструментов
OAuth-клиент ────────── OAuth 2.1 ───────┘

Проект предназначен для собственного компьютера и доверенного агента. Это не многопользовательский публичный сервис.

Запуск за несколько минут

1. Распакуйте архив в любую папку.
2. Дважды кликните START.bat.
3. При первом запуске выберите рабочую папку.
4. Оставьте trusted developer mode выключенным, если нужны только файловые инструменты. Для написания и запуска кода его можно включить ответом y.
5. Подключите клиента: для статического токена (например, Notion Custom MCP) скопируйте показанные URL и Bearer token; для OAuth-клиента (например, Hyperagent) запустите OAUTH_SETUP.bat, выберите dual или oauth и добавьте URL сервера в клиент — дальше DCR и страница /consent с owner-кодом.
6. Не закрывайте окно запуска во время работы.

При последующих запусках повторная настройка не требуется. Конфигурация хранится в %LOCALAPPDATA%\LocalMcpEasy и не входит в архив проекта (настройки из старого каталога NotionMcpEasy переносятся автоматически при первом запуске 2.0). Начиная с 1.4.2 список быстрых переключений между рабочими областями хранится в %LOCALAPPDATA%\LocalMcpEasy\connections.cfg: при MENU = on сервер показывает сохранённые пути и меняет только текущий workspace в config.json, не пересоздавая токен. При stable Serveo hostname адрес MCP сохраняется; в temporary mode после перезапуска URL меняется и его нужно обновить в клиенте.

Управление

• START.bat — создать локальное .venv, установить зависимости и запустить сервер с туннелем. Если connections.cfg содержит MENU = on, перед стартом появится меню сохранённых рабочих областей.
• STOP.bat — остановить только процессы этого MCP после проверки их идентичности.
• SETUP.bat — заново пройти мастер настройки; токен при повторном setup сохраняется, а выбранная рабочая область попадает в connections.cfg.
• SHOW_CONNECTION.bat — показать текущие URL, workspace и режимы; токен и OAuth owner code маскируются, --full показывает их полностью.
• OAUTH_SETUP.bat — выбрать режим авторизации legacy / oauth / dual и сгенерировать OAuth owner code.
• REGISTER_OAUTH_CLIENT.bat — заранее зарегистрировать OAuth-клиент для режима «Bring my own OAuth app».
• DOCTOR.bat / ./doctor.sh (2.4.0) — диагностика сломанной установки одной командой: версия Python, зависимости, config, токен, workspace, режим авторизации, owner code, tunnel backend, наличие ssh и git, занят ли порт. Возвращает ненулевой код, если что-то сломано.
• launcher.py --add-command ИМЯ / --remove-command ИМЯ — безопасно изменить список разрешённых команд без ручной правки JSON (ручная правка с BOM/лишней запятой раньше сбрасывала настройку — теперь launcher останавливается с понятной ошибкой и ничего не перезаписывает).

connections.cfg

Пользовательский файл %LOCALAPPDATA%\LocalMcpEasy\connections.cfg создаётся автоматически и содержит:

• MENU = on/off — показывать ли меню выбора рабочей области при старте;
• PATH[1] ... PATH[9] — стартовые слоты для сохранённых путей;
• дополнительные слоты PATH[10], PATH[11] и дальше можно добавлять вручную или через меню, если базовые места заняты.

Когда меню включено, запуск показывает только занятые слоты и предлагает:

• выбрать сохранённую рабочую область по номеру;
• нажать 0, чтобы задать новую папку и сохранить её в свободный слот;
• нажать q, чтобы отключить меню и оставить последнюю выбранную область в config.json.

Все подсказки во время запуска сообщают точные пути к connections.cfg и config.json. Файл connections.example.cfg в архиве служит только шаблоном и не содержит пользовательских путей.

Режимы

File-only mode — по умолчанию

Файловые инструменты разрешены только внутри выбранного workspace. Пути нормализуются, а выход через .., абсолютные пути и ссылки наружу отклоняется.

Trusted developer mode — опционально

Добавляет запуск разрешённых программ без cmd.exe и PowerShell:

python, py, pip, git, node, npm, npx, pytest, ruff, make, uv

Это не песочница. Python, Node, Git hooks, npm scripts и другие инструменты могут обращаться ко всей системе и сети с правами текущего пользователя Windows. Включайте режим только для личного доверенного агента.

С 2.4.0 аргументы к .cmd/.bat-программам (на Windows это npm и npx) отклоняются, если содержат метасимволы & | < > ^ " % !: Windows запускает batch-файлы через cmd.exe, который заново разбирает командную строку, поэтому npm с аргументом --version&whoami выполнял whoami в обход allow-list — при shell=False и argv списком (BatBadBut, тот же класс, что CVE-2024-24576).

Read-only mode — опционально (2.4.0)

MCP_READ_ONLY=1 вообще не регистрирует изменяющие инструменты: их нет в list_tools(), и до них не может дойти ни один запрос. Гарантия структурная, а не «проверка scope сработает». Подходит, чтобы дать агенту посмотреть рабочую папку через туннель, ничего не рискуя.

Аудит вызовов (2.4.0)

MCP_AUDIT_LOG=<путь> пишет по одной JSON-строке на каждый вызов инструмента — время, OAuth client_id, имя инструмента, именованные аргументы (обрезанные) и результат ok/error. Сервер, доступный из интернета и умеющий запускать команды, обязан оставлять след; больше это нигде не фиксировалось. Секреты в лог не попадают, а сбой записи никогда не ломает сам вызов.

{"ts":"2026-07-26T14:02:11+00:00","client":"mcp_client_a1b2","tool":"run_command","outcome":"ok","args":{"args":"['test']","cwd":".","program":"pytest"}}

Скилы и память (2.5.0)

Две вещи, которые обычно есть у автономного агента, но не у MCP-сервера: библиотека многоразовых процедур и память, переживающая сессию. Здесь их получает любой подключённый MCP-клиент, а не один конкретный агент.

Обе подсистемы едут в клиент через поле instructions MCP-ответа на initialize — единственный штатный канал сервера в системный промпт модели. Всё остальное клиенту пришлось бы вытягивать вызовом инструмента, о котором он должен догадаться.

Скилы

Скил — папка с SKILL.md: YAML-frontmatter плюс markdown-инструкции. Формат — переносимое ядро спецификации agentskills.io (name, description, license, compatibility, metadata), без расширений, специфичных для конкретного клиента, так что тот же скил читается и в Claude Code.

%LOCALAPPDATA%\LocalMcpEasy\skills\<имя>\SKILL.md   ← личные, доступны в любой рабочей папке
<workspace>\.mcp-skills\<имя>\SKILL.md              ← скилы проекта, только здесь

---
name: release-notes
description: >
  Собирает changelog из git diff, группируя по типу изменения.
  Использовать, когда просят release notes или саммари PR для пользователей.
license: MIT
---

# Release notes

1. `git diff <base>..<head>`
2. Разложить на Added / Changed / Fixed / Removed.
3. Один пункт на логическое изменение, языком пользователя.

Полная спецификация — в [references/format.md](references/format.md).

Раскрытие трёхуровневое, чтобы большая библиотека не съедала контекст:

1. Всегда — только имя: описание, одна строка на скил, в instructions и в skills_list().
2. По требованию — тело SKILL.md, через skill_view(name).
3. Отдельно — references/, scripts/, assets/ не инлайнятся даже на втором уровне: в конце тела появляется их список и подсказка skill_view(name, file_path=...).

Скил — это инструкции, которым модель следует, то есть граница доверия, а не данные. Отсюда два следствия, оба проверяются тестами: личный скил всегда побеждает одноимённый скил из рабочей папки (рабочую папку может писать любой клиент с mcp:files:write, так что обратный приоритет был бы повышением привилегий), а скил из рабочей папки помечается [workspace] везде, где отображается. Скил ничего не исполняет: он может попросить модель что-то запустить, и это пойдёт через run_command с его allow-list, как любая другая команда.

Память

Два плоских файла в %LOCALAPPDATA%\LocalMcpEasy\memory\: MEMORY.md — что агент узнал про окружение и работу, USER.md — что узнал про человека. Записи разделены строкой §. Ни базы, ни эмбеддингов: recall здесь означает «весь стор целиком показан модели», так что ранжировать нечего — индекс добавил бы зависимость, шаг сборки и точку отказа ради запроса, которого никогда не будет.

Ограничение — в символах, не в записях (2200 для MEMORY.md, 1375 для USER.md). Лимит на количество позволил бы одной пространной записи вытеснить десять полезных, а символьный управляет тем, что реально дефицитно, — местом в контексте. Запись сверх бюджета отклоняется и возвращает текущее содержимое, чтобы модель сократила и повторила; молча обрезать нельзя — так теряются записи.

Стор лежит вне рабочей папки, поэтому до него не дотягивается ни один файловый инструмент: изменить память можно только через memory_write, а значит каждое изменение проходит проверку scope.

| Инструмент | Scope | Что делает | | --- | --- | --- | | skills_list() | mcp:files:read | индекс скилов | | skill_view(name, file_path="") | mcp:files:read | тело скила или его вспомогательный файл | | memory_read(target="all") | mcp:files:read | текущая память с указанием бюджета | | memory_write(action, content, target, old_text) | mcp:files:write | add / replace / remove |

Новых OAuth-scope не появилось намеренно: уже выданные токены продолжают работать, а в MCP_READ_ONLY=1 инструмент memory_write просто не регистрируется.

Переменные окружения (выборочно)

| Переменная | По умолчанию | Назначение | | --- | --- | --- | | MCP_READ_ONLY | 0 | 1 — изменяющие инструменты не регистрируются вовсе | | MCP_AUDIT_LOG | (пусто) | путь к append-only JSONL-журналу вызовов | | MCP_SKILLS_DIR | <config>\skills | папка личных скилов | | MCP_MEMORY_DIR | <config>\memory | папка стора памяти | | MCP_MEMORY | 1 | 0 — выключить память целиком | | MCP_MEMORY_CHAR_LIMIT | 2200 | бюджет MEMORY.md в символах | | MCP_USER_CHAR_LIMIT | 1375 | бюджет USER.md в символах | | MCP_ALLOW_COMMANDS | 0 | 1 — включить trusted developer mode | | MCP_ALLOWED_COMMANDS | см. список выше | allow-list программ через запятую | | MCP_MAX_COMMAND_JOBS | 4 | сколько фоновых команд может идти параллельно | | MCP_MAX_COPY_MOVE_BYTES | 100 МБ | потолок для copy_file / move_file | | `MC