Local Dev MCP

Локальный MCP-сервер для работы AI-агента с несколькими проектами на одной Windows-машине.

Local Dev MCP предоставляет AI-клиенту доступ к локальным проектам, файловой системе и выполнению команд через PowerShell. Один экземпляр сервера может работать сразу с несколькими репозиториями, расположенными в одной или нескольких корневых директориях.

Docker не является обязательной зависимостью. Проекты могут использовать Docker, Node.js, PHP, Python или любой другой локально установленный стек.

Установка

1. Установите Node.js

Для работы Local Dev MCP требуется Node.js версии 20 или новее.

Проверьте текущую версию:

node --version
npm --version

Если Node.js не установлен, установите актуальную LTS-версию с официального сайта Node.js.

После установки закройте и повторно откройте PowerShell или Windows Terminal.

2. Получите Local Dev MCP

Склонируйте репозиторий:

git clone https://github.com/mfokusnik/LocalDevMCP
cd LocalDevMCP

Либо скачайте архив репозитория и распакуйте его в удобную директорию, например:

C:\Tools\local-dev-mcp

3. Выполните первичную настройку

Запустите:

FIRST_RUN.cmd

Скрипт автоматически:

• проверит наличие Node.js;
• запросит корневую директорию с локальными проектами;
• создаст config.local.json;
• установит npm-зависимости;
• проверит TypeScript;
• запустит MCP-сервер.

Например, если проекты сотрудника находятся здесь:

C:\Users\User\Documents\GitHub

необходимо указать эту директорию при первом запуске.

У другого сотрудника путь может быть любым:

D:\Projects

или:

C:\Development

Настройка хранится локально и не попадает в Git.

4. Проверьте запуск

После успешного запуска откройте:

http://127.0.0.1:7676/health

Ожидаемый ответ:

{
  "ok": true,
  "name": "local-dev-mcp",
  "version": "0.1.0",
  "mcp": "http://127.0.0.1:7676/mcp"
}

MCP endpoint:

http://127.0.0.1:7676/mcp

5. Подключите MCP-клиент

В используемом локальном MCP tunnel укажите:

http://127.0.0.1:7676/mcp

После подключения AI-клиент получит доступ к зарегистрированным MCP tools.

6. Проверьте MCP-интерфейс

При запущенном сервере выполните:

SMOKE_TEST.cmd

или:

npm run smoke

Тест должен успешно подключиться к MCP endpoint и вернуть список доступных инструментов.

Последующие запуски

После первой установки повторная настройка не требуется.

Для запуска сервера используйте:

START.cmd

или:

npm run dev

Локальная конфигурация сохраняется в:

config.local.json

Для смены директории с проектами можно отредактировать этот файл вручную или повторно выполнить первичную настройку.

Возможности

• автоматическое обнаружение проектов в одной или нескольких корневых директориях;
• выбор активного проекта по имени или alias;
• файловые операции внутри выбранного проекта;
• выполнение PowerShell-команд с рабочей директорией выбранного проекта;
• базовое определение используемого стека;
• проверка доступности локальных CLI-инструментов;
• работа с Git и GitHub CLI через локальный shell;
• Streamable HTTP MCP endpoint;
• локальный health-check endpoint;
• защита файловых MCP-операций от выхода за пределы активного проекта.

Поддерживается автоматическое определение следующих технологий и инструментов:

• Git;
• Node.js;
• PHP / Composer;
• Laravel;
• Docker / Docker Compose;
• Python;
• Go;
• Rust.

Архитектура

AI-клиент
    │
    │ MCP
    ▼
Local Dev MCP
    │
    ├── обнаружение проектов
    ├── выбор workspace
    ├── файловые операции
    └── PowerShell
            │
            ├── git
            ├── gh
            ├── docker
            ├── npm
            ├── composer
            ├── php / artisan
            ├── python
            └── другие локальные CLI

Сервер не реализует отдельные MCP-инструменты для каждого фреймворка или среды выполнения.

Команды вида:

npm test
php artisan test
docker compose ps
git status
gh pr create

выполняются через универсальный инструмент shell.run.

За счёт этого MCP-сервер не зависит от технологического стека конкретного проекта.

Требования

Обязательно:

• Windows 10 или Windows 11;
• Node.js 20 или новее;
• хотя бы одна локальная директория с проектами.

Дополнительные инструменты устанавливаются только при необходимости:

• Git;
• GitHub CLI;
• Docker Desktop;
• PHP;
• Composer;
• Python;
• другие CLI и runtime, используемые проектами.

Docker для работы Local Dev MCP не требуется.

Первый запуск

1. Склонируйте или распакуйте проект

Например:

C:\Tools\local-dev-mcp

2. Запустите первичную настройку

FIRST_RUN.cmd

Скрипт:

1. проверит наличие Node.js;
2. запросит путь к директории с проектами;
3. создаст локальный конфигурационный файл;
4. установит npm-зависимости;
5. выполнит проверку TypeScript;
6. запустит MCP-сервер.

По умолчанию предлагается путь:

%USERPROFILE%\Documents\GitHub

При необходимости можно указать другой:

D:\Projects

3. Проверьте запуск

Откройте:

http://127.0.0.1:7676/health

Ожидаемый ответ:

{
  "ok": true,
  "name": "local-dev-mcp",
  "version": "0.1.0",
  "mcp": "http://127.0.0.1:7676/mcp"
}

MCP endpoint:

http://127.0.0.1:7676/mcp

По умолчанию сервер слушает только 127.0.0.1 и напрямую не публикуется в локальную сеть или интернет.

4. Подключите MCP-клиент

В локальном MCP tunnel или другом совместимом клиенте укажите:

http://127.0.0.1:7676/mcp

5. Выполните smoke test

При запущенном сервере:

SMOKE_TEST.cmd

или:

npm run smoke

Тест проверяет подключение к MCP и выводит список зарегистрированных tools.

Обычный запуск

После первичной настройки:

START.cmd

или:

npm run dev

Конфигурация

Локальная конфигурация хранится в:

config.local.json

Файл исключён из Git через .gitignore и предназначен для настроек конкретной рабочей станции.

Пример:

{
  "roots": [
    "C:\\Users\\YourName\\Documents\\GitHub"
  ],
  "scanDepth": 1,
  "host": "127.0.0.1",
  "port": 7676,
  "mcpPath": "/mcp",
  "shell": {
    "executable": "powershell.exe",
    "timeoutMs": 120000,
    "maxOutputChars": 200000
  },
  "skipDirectories": [
    ".git",
    "node_modules",
    "vendor",
    ".next",
    "dist",
    "build"
  ],
  "projects": []
}

Несколько корневых директорий

{
  "roots": [
    "C:\\Users\\YourName\\Documents\\GitHub",
    "D:\\Work",
    "D:\\Experiments"
  ]
}

Каждая директория сканируется независимо.

Глубина сканирования

Если структура проектов вложенная:

D:\Work
├── clients
│   ├── project-a
│   └── project-b
└── internal
    └── project-c

можно увеличить:

{
  "scanDepth": 2
}

Максимальное значение в текущей версии — 5.

Явное добавление проекта и alias

Проекты можно добавлять вручную:

{
  "projects": [
    {
      "name": "sample-app",
      "path": "D:\\Projects\\sample-app",
      "aliases": [
        "sample",
        "app"
      ]
    }
  ]
}

После этого проект можно выбрать как по основному имени, так и по alias.

Обнаружение проектов

Директория считается проектом, если содержит хотя бы один из поддерживаемых markers:

.git
package.json
composer.json
artisan
compose.yml
compose.yaml
docker-compose.yml
docker-compose.yaml
Dockerfile
pyproject.toml
requirements.txt
go.mod
Cargo.toml

После определения директории как проекта сканирование её внутренних папок прекращается.

Это позволяет не определять внутренние зависимости и служебные директории как отдельные workspace.

MCP tools

projects.list

Возвращает список обнаруженных и явно настроенных проектов.

projects.select

Выбирает активный проект по имени или alias.

Пример:

Пользователь:
Работаем с sample-app

AI:
projects.select({ "name": "sample-app" })

В ответ сервер возвращает:

• абсолютный путь проекта;
• обнаруженный стек;
• текущую Git-ветку;
• состояние working tree;
• список доступных локальных CLI-инструментов.

projects.current

Возвращает текущий активный проект и его состояние.

fs.list

Выводит содержимое директорий внутри активного проекта.

fs.read

Читает UTF-8 файлы.

Поддерживается чтение диапазона строк.

fs.write

Создаёт новый файл или полностью перезаписывает существующий.

fs.replace

Выполняет точную замену текста в файле.

Поддерживается замена одного или всех совпадений.

fs.move

Перемещает или переименовывает файл или директорию внутри активного проекта.

fs.delete

Удаляет файл или директорию внутри активного проекта.

Удаление корневой директории активного проекта через этот tool запрещено.

shell.run

Выполняет PowerShell-команду с рабочей директорией активного проекта.

Примеры:

git status

git switch -c feature/example

npm test

php artisan test

docker compose ps

docker compose exec app php artisan test

gh pr create

Отдельные инструменты docker.*, git.* или artisan.* в текущей версии не реализуются.

Универсальным интерфейсом выполнения команд является локальный shell.

Docker

Docker является опциональным инструментом.

Если Docker Desktop установлен, AI-клиент может использовать Docker CLI через shell.run.

Например:

docker compose ps

или:

docker compose exec app npm test

Если Docker отсутствует, MCP-сервер продолжает работать без ограничений для остальных инструментов.

То же относится к PHP, Composer, Python, GitHub CLI и другим runtime.

Git и GitHub

Git-операции выполняются через локально установленный Git CLI.

Например:

git status
git diff
git switch -c feature/example
git commit

При установленном и авторизованном GitHub CLI доступны операции через gh:

gh pr create
gh pr view
gh issue list
gh issue comment

Local Dev MCP не хранит GitHub-токены и использует существующую локальную авторизацию.

Модель безопасности

Файловые MCP-tools ограничены активным проектом.

Попытки обратиться к файлу через путь, выходящий за пределы workspace, блокируются.

Например:

..\..\some-file.txt

не должен позволить fs.read, fs.write или другим файловым tools выйти за пределы выбранного проекта.

При этом shell.run не является sandbox.

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

cwd = active project

но сам PowerShell технически может обращаться к другим директориям и локальным ресурсам, если это указано непосредственно в команде.

Поэтому текущая версия рассчитана на доверенную локальную среду разработки:

один сотрудник
=
один локальный MCP
=
одна рабочая станция

Состояние активного проекта

Выбранный проект хранится в памяти процесса MCP.

После перезапуска сервера проект необходимо выбрать повторно.

Текущая версия не рассчитана на одновременную работу нескольких независимых пользователей через один экземпляр сервера.

Структура проекта

local-dev-mcp/
├── src/
│   ├── index.ts
│   ├── server.ts
│   ├── config.ts
│   ├── projects.ts
│   ├── fs-tools.ts
│   ├── shell.ts
│   ├── smoke.ts
│   └── types.ts
├── scripts/
│   └── setup.ps1
├── FIRST_RUN.cmd
├── START.cmd
├── SMOKE_TEST.cmd
├── config.example.json
├── package.json
└── tsconfig.json

Команды разработки

Установка зависимостей:

npm install

Запуск:

npm run dev

Проверка типов:

npm run check

Сборка:

npm run build

Запуск собранной версии:

npm start

Smoke test:

npm run smoke

Ограничения текущей версии

В текущей версии отсутствуют:

• web-интерфейс;
• система пользователей;
• база данных;
• ACL для отдельных shell-команд;
• подтверждение потенциально опасных команд на уровне сервера;
• Docker-контейнер для самого MCP;
• отдельные runtime profiles;
• сохранение активного проекта после перезапуска;
• публичный удалённый endpoint;
• многопользовательский режим.

Эти возможности могут быть добавлены по мере необходимости.

Диагностика

Node.js не найден

Проверьте:

node --version
npm --version

Требуется Node.js 20 или новее.

MCP запущен, но клиент не подключается

Сначала проверьте:

http://127.0.0.1:7676/health

Если /health недоступен, проблема находится на стороне локального MCP.

Если /health работает, проверьте MCP endpoint:

http://127.0.0.1:7676/mcp

и конфигурацию используемого MCP tunnel.

Порт 7676 занят

Измените порт в config.local.json:

{
  "port": 7677
}

После этого используйте новый порт в MCP-клиенте.

Проект не обнаруживается

Проверьте:

1. находится ли проект внутри одной из roots;
2. содержит ли директория поддерживаемый project marker;
3. достаточно ли значения scanDepth;
4. при необходимости добавьте проект явно через projects.

Технологии

• TypeScript;
• Node.js;
• Model Context Protocol;
• официальный MCP TypeScript SDK.

Документация:

https://modelcontextprotocol.io/
https://github.com/modelcontextprotocol/typescript-sdk