# 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 или новее.

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

```powershell
node --version
npm --version
```

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

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

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

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

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

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

```text
C:\Tools\local-dev-mcp
```

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

Запустите:

```text
FIRST_RUN.cmd
```

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

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

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

```text
C:\Users\User\Documents\GitHub
```

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

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

```text
D:\Projects
```

или:

```text
C:\Development
```

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

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

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

```text
http://127.0.0.1:7676/health
```

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

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

MCP endpoint:

```text
http://127.0.0.1:7676/mcp
```

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

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

```text
http://127.0.0.1:7676/mcp
```

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

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

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

```text
SMOKE_TEST.cmd
```

или:

```powershell
npm run smoke
```

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

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

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

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

```text
START.cmd
```

или:

```powershell
npm run dev
```

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

```text
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.

## Архитектура

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

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

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

```powershell
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. Склонируйте или распакуйте проект

Например:

```text
C:\Tools\local-dev-mcp
```

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

```text
FIRST_RUN.cmd
```

Скрипт:

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

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

```text
%USERPROFILE%\Documents\GitHub
```

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

```text
D:\Projects
```

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

Откройте:

```text
http://127.0.0.1:7676/health
```

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

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

MCP endpoint:

```text
http://127.0.0.1:7676/mcp
```

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

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

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

```text
http://127.0.0.1:7676/mcp
```

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

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

```text
SMOKE_TEST.cmd
```

или:

```powershell
npm run smoke
```

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

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

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

```text
START.cmd
```

или:

```powershell
npm run dev
```

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

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

```text
config.local.json
```

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

Пример:

```json
{
  "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": []
}
```

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

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

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

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

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

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

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

```json
{
  "scanDepth": 2
}
```

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

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

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

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

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

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

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

```text
.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.

Пример:

```text
Пользователь:
Работаем с 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-команду с рабочей директорией активного проекта.

Примеры:

```powershell
git status
```

```powershell
git switch -c feature/example
```

```powershell
npm test
```

```powershell
php artisan test
```

```powershell
docker compose ps
```

```powershell
docker compose exec app php artisan test
```

```powershell
gh pr create
```

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

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

## Docker

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

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

Например:

```powershell
docker compose ps
```

или:

```powershell
docker compose exec app npm test
```

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

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

## Git и GitHub

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

Например:

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

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

```powershell
gh pr create
gh pr view
gh issue list
gh issue comment
```

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

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

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

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

Например:

```text
..\..\some-file.txt
```

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

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

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

```text
cwd = active project
```

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

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

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

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

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

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

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

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

```text
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
```

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

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

```powershell
npm install
```

Запуск:

```powershell
npm run dev
```

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

```powershell
npm run check
```

Сборка:

```powershell
npm run build
```

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

```powershell
npm start
```

Smoke test:

```powershell
npm run smoke
```

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

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

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

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

## Диагностика

### Node.js не найден

Проверьте:

```powershell
node --version
npm --version
```

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

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

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

```text
http://127.0.0.1:7676/health
```

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

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

```text
http://127.0.0.1:7676/mcp
```

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

### Порт 7676 занят

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

```json
{
  "port": 7677
}
```

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

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

Проверьте:

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

## Технологии

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

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

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