Local Dev MCP

用于在单台 Windows 机器上让 AI 代理处理多个项目的本地 MCP 服务器。

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，请从 Node.js 官方网站安装最新的 LTS 版本。

安装后，关闭并重新打开 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 端点：

http://127.0.0.1:7676/mcp

5. 连接 MCP 客户端

在所使用的本地 MCP 隧道中指定：

http://127.0.0.1:7676/mcp

连接后，AI 客户端将获得对已注册 MCP 工具的访问权限。

6. 检查 MCP 接口

在服务器运行时执行：

SMOKE_TEST.cmd

或：

npm run smoke

测试应成功连接到 MCP 端点并返回可用工具列表。

Related MCP server: Windows-MCP

后续启动

首次安装后，无需重复配置。

要启动服务器，请使用：

START.cmd

或：

npm run dev

本地配置保存在：

config.local.json

要更改项目目录，可以手动编辑此文件，或重新执行初始配置。

功能

• 在一个或多个根目录中自动发现项目；

• 按名称或别名选择活动项目；

• 在所选项目内进行文件操作；

• 以所选项目的工作目录执行 PowerShell 命令；

• 基本检测所使用的技术栈；

• 检查本地 CLI 工具的可用性；

• 通过本地 shell 使用 Git 和 GitHub CLI；

• Streamable HTTP MCP 端点；

• 本地健康检查端点；

• 保护文件 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 和运行时。

Local Dev MCP 不需要 Docker。

首次启动

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 端点：

http://127.0.0.1:7676/mcp

默认情况下，服务器仅监听 127.0.0.1，不会直接发布到局域网或互联网。

4. 连接 MCP 客户端

在本地 MCP 隧道或其他兼容客户端中指定：

http://127.0.0.1:7676/mcp

5. 执行冒烟测试

在服务器运行时：

SMOKE_TEST.cmd

或：

npm run smoke

测试检查 MCP 连接并输出已注册工具列表。

常规启动

初始配置后：

START.cmd

或：

npm run dev

配置

本地配置存储在：

config.local.json

该文件通过 .gitignore 从 Git 中排除，用于特定工作站的设置。

示例：

{
  "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。

显式添加项目和别名

可以手动添加项目：

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

之后，可以通过主名称或别名选择项目。

项目发现

如果目录包含至少一个受支持的标记，则将其视为项目：

.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

将目录确定为项目后，将停止扫描其内部子文件夹。

这样可以避免将内部依赖项和服务目录识别为单独的工作区。

MCP 工具

projects.list

返回已发现和显式配置的项目列表。

projects.select

按名称或别名选择活动项目。

示例：

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

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

服务器响应包含：

• 项目的绝对路径；

• 检测到的技术栈；

• 当前 Git 分支；

• 工作树状态；

• 可用的本地 CLI 工具列表。

projects.current

返回当前活动项目及其状态。

fs.list

列出活动项目内目录的内容。

fs.read

读取 UTF-8 文件。

支持读取行范围。

fs.write

创建新文件或完全覆盖现有文件。

fs.replace

在文件中执行精确文本替换。

支持替换一个或所有匹配项。

fs.move

在活动项目内移动或重命名文件或目录。

fs.delete

删除活动项目内的文件或目录。

通过此工具禁止删除活动项目的根目录。

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 客户端可以通过 shell.run 使用 Docker CLI。

例如：

docker compose ps

或：

docker compose exec app npm test

如果未安装 Docker，MCP 服务器仍可正常运行，不影响其他工具。

PHP、Composer、Python、GitHub CLI 和其他运行时也是如此。

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 工具仅限于活动项目。

尝试通过超出工作区范围的路径访问文件将被阻止。

例如：

..\..\some-file.txt

不应允许 fs.read、fs.write 或其他文件工具超出所选项目。

同时，shell.run 不是沙箱。

命令从活动项目的目录执行：

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

冒烟测试：

npm run smoke

当前版本的限制

当前版本缺少：

• Web 界面；

• 用户系统；

• 数据库；

• 针对单个 shell 命令的 ACL；

• 服务器级别的潜在危险命令确认；

• 用于 MCP 本身的 Docker 容器；

• 单独的运行时配置文件；

• 重启后保存活动项目；

• 公共远程端点；

• 多用户模式。

这些功能可能会根据需要添加。

诊断

未找到 Node.js

检查：

node --version
npm --version

需要 Node.js 20 或更高版本。

MCP 已启动，但客户端无法连接

首先检查：

http://127.0.0.1:7676/health

如果 /health 不可用，则问题出在本地 MCP 端。

如果 /health 正常，请检查 MCP 端点：

http://127.0.0.1:7676/mcp

以及所使用的 MCP 隧道的配置。

端口 7676 被占用

在 config.local.json 中更改端口：

{
  "port": 7677
}

之后在 MCP 客户端中使用新端口。

项目未被发现

检查：

1. 项目是否位于某个 roots 内；

2. 目录是否包含受支持的项目标记；

3. scanDepth 值是否足够；

4. 如有必要，通过 projects 显式添加项目。

技术

• TypeScript；

• Node.js；

• Model Context Protocol；

• 官方 MCP TypeScript SDK。

文档：

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