内容
# 本地开发MCP
[](https://github.com/mehrdad03/localdev-mcp/actions/workflows/ci.yml)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](LICENSE)
一个安全且专注于性能的模型上下文协议服务器，允许AI助手检查、编辑、测试和验证已批准的本地软件项目。
本地开发MCP可以与不同的编程语言、框架和项目类型一起使用。它限制对明确批准的项目文件夹的访问，并对文件更改、Git操作和命令执行应用安全检查。
## 亮点
- **39种专注的MCP工具**，用于项目发现、集中安装的技能、代码搜索、安全编辑、Git检查、测试、构建、Laravel诊断和验证。
- **项目允许列表**，通过本地配置文件实现。
- **SHA-256并发保护**，在修改、替换、重命名或删除现有文件之前。
- **批量操作**，用于快速读取和多文件补丁，并尝试回滚。
- **受保护的Git分支切换**，具有干净树检查、分支名称验证、预期HEAD验证和干运行支持。
- **命令允许列表**，而不是任意的shell访问。
- **机密感知路径阻塞和输出编辑**。
- **缓存的项目快照**和可选的ripgrep加速。
- **MCP原生技能注册表**，通过`list_skills`、`get_skill`和`read_skill_reference`实现渐进式披露。
- **捆绑的前端Craft Director**，用于设计、重新设计、实施、响应式修复、反AI-slop审查和渲染的视觉QA。
- **可配置的命令超时**，最高可达3,600秒（1小时），用于长时间运行的构建、测试、安装和验证工作流。
## 架构
```text
MCP客户端
|
v
本地开发MCP（stdio）
|
+-- 项目配置允许列表
+-- 中心MCP原生技能注册表
+-- 路径和机密防护
+-- SHA-256写入保护
+-- 命令策略允许列表
+-- 审计、备份和缓存层
|
v
仅限批准的本地存储库
```
## 工具组
### 技能
`list_skills`、`get_skill`、`read_skill_reference`
### 项目发现和读取
`list_projects`、`get_project_info`、`get_project_snapshot`、`get_project_tree`、`list_directory`、`read_file`、`batch_read_files`、`search_files`、`search_code`
### 安全文件编辑
`write_file`、`create_file`、`replace_text`、`apply_patch`、`batch_apply_patches`、`rename_file`、`delete_file`
### Git和验证
`git_status`、`git_diff`、`git_switch_branch`、`inspect_changed_files`、`run_command`、`run_tests`、`run_validation_plan`
### Laravel和PHP
`read_laravel_logs`、`inspect_routes`、`inspect_database_schema`、`run_artisan`、`run_phpunit`、`run_pest`、`composer_install`、`clear_laravel_cache`、`restart_queue_workers`
### 前端和Node.js
`run_npm`、`run_eslint`、`run_build`、`npm_install`
## MCP原生技能
技能位于`skills/<skill-name>/`，对于每个配置的项目都可用，无需将它们复制到应用程序存储库中。
捆绑的技能是：
```text
frontend-craft-director
```
推荐的前端调用：
```text
@本地开发
项目：<项目密钥>
使用frontend-craft-director技能作为此前端任务的强制工作流。
在编辑文件之前加载技能，检查真实存储库，生成设计读取，
保留路由/API/行为，不要在未经批准的情况下安装软件包，运行存储库
验证，并诚实地报告渲染的视觉QA证据。
```
MCP客户端应调用：
```text
list_skills
get_skill(name: "frontend-craft-director")
read_skill_reference(skill: "frontend-craft-director", reference: "references/visual-qa.md")
```
`get_skill`返回完整的自包含技能。`read_skill_reference`提供聚焦的支持引用和`templates/DESIGN.md`合约，当渐进式披露更合适时。
## 要求
- Node.js 22或更高版本
- npm
- Git
- 可选：PHP和Composer，用于Laravel/PHP项目
- 可选：ripgrep（`rg`）用于更快的代码搜索
## 安装
```bash
git clone https://github.com/mehrdad03/localdev-mcp.git
cd localdev-mcp
npm ci
npm run typecheck
npm run build
npm run smoke
```
## 配置批准的项目
复制示例配置：
### Windows PowerShell
```powershell
Copy-Item projects.example.json projects.json
```
### macOS或Linux
```bash
cp projects.example.json projects.json
```
编辑`projects.json`，仅列出MCP服务器可以访问的本地存储库：
```json
{
"projects": {
"my-laravel-app": {
"root": "C:\\Projects\\my-laravel-app",
"stack": ["laravel", "vue", "vite"]
}
}
}
```
`projects.json`被Git忽略，因此本地路径不会被公开。
可以通过以下方式提供替代配置文件：
```text
LOCALDEV_MCP_PROJECTS=/absolute/path/to/projects.json
```
在Windows上，当`PATH`中没有PHP时，设置自定义PHP可执行文件：
```powershell
$env:LOCALDEV_MCP_PHP = "C:\path\to\php.exe"
```
## 运行服务器
```bash
npm start
```
服务器通过MCP stdio通信。配置MCP客户端启动：
```text
command: node
args: [<absolute-path>/dist/index.js]
```
## 验证
```bash
npm run typecheck
npm run build
npm run smoke
npm run integration-smoke
npm run benchmark
```
集成烟雾测试锻炼本地开发MCP本身，不依赖于任何私有应用程序存储库。
## 安全默认值
- 只有在本地项目配置中列出的根目录才可访问。
- 拒绝绝对目标路径和`..`遍历。
- `.env`、凭证、私钥、`.git`、`vendor`和`node_modules`被文件工具阻止。
- 现有文件更改需要读取工具返回的SHA-256值。
- 补丁、替换、重命名和删除操作创建本地备份。
- 批量补丁验证每个目标在写入之前，并在部分失败后尝试回滚。
- 阻止任意可执行文件、shell运算符、部署、生产标志、破坏性数据库操作和破坏性Git命令。
- Laravel日志和紧凑命令输出会编辑常见的令牌和密码模式。
- 命令在本地`logs/audit.log`下审计。
参见[SECURITY.md](SECURITY.md)，了解安全模型和报告指南。
## 刻意限制
本地开发MCP故意不是一个通用的终端、部署代理、浏览器自动化系统或操作系统沙盒。它的目的是在保持暴露的能力表面狭窄和可审查的同时，提供有用的本地编码工作流。
## 示例工作流
```text
1. 在适用治理工作流时获取技能
2. 获取项目快照
3. 搜索代码/批量读取文件
4. 应用补丁/批量应用补丁
5. 运行测试/运行验证计划
6. 检查更改的文件
7. 在需要干净的分支转换时切换Git分支
```
## 许可
MIT许可。参见[LICENSE](LICENSE)。
