AI导哈

Laravel诊断工具

一个可安装的CLI和生产安全的MCP服务器，允许Codex CLI通过强化的SSH远程运行器运行常见的Laravel诊断，而无需授予交互式shell访问权限。

  • by alex-engvall
  • PHP
  • 本地部署
  • 更新于
在 GitHub 查看 Alemil-Group-AB/laravel-debug-mcp

使用说明

laravel调试mcp

一 可安装的CLI+生产安全MCP服务器 这让 Codex 命令行界面 通过强化的SSH远程运行器运行常见的Laravel诊断，而无需授予交互式shell访问权限。

建筑

  • Codex 命令行界面⇄ 通过stdio的本地MCP服务器
  • 本地MCP服务器⇄ SSH ⇄ /usr/local/bin/laravel-diag
  • laravel-diag 执行严格的诊断列表并返回JSON
  • SSH访问可以通过以下方式进行限制 authorized_keys 强制命令

快速启动

建议的安装路径是交互式安装程序：

npx @alex-engvall/laravel-debug-mcp init

向导会询问配置文件名称、服务器主机、SSH设置用户、Laravel应用程序路径、诊断用户、SSH密钥选择、Codex配置首选项和变异策略。然后：

  1. 创建或重用专用本地Ed25519密钥；
  2. 通过SSH连接到服务器；
  3. 在需要时创建诊断用户；
  4. 安装 /usr/local/bin/laravel-diag;
  5. 写 /etc/laravel-diag.env 作为 root:<diag-user> 带模式 0640;
  6. 在中安装公钥 ~<diag-user>/.ssh/authorized_keys 强制命令；
  7. 将本地配置文件保存在 ~/.config/laravel-debug-mcp/profiles/;
  8. 跑 codex mcp add 当Codex CLI可用时；
  9. 跑 doctor 烟雾检查。

您还可以全局安装：

npm install -g @alex-engvall/laravel-debug-mcp
laravel-debug-mcp init

非交互式/CI设置

使用 --config --yes 对于从CI/CD或签入的非机密配置文件进行的可重复设置：

laravel-debug-mcp init --config ./laravel-debug-mcp.prod.json --yes

配置示例：

{
  "profile": "easytoday-prod",
  "host": "app.easytoday.se",
  "port": 22,
  "setupUser": "root",
  "diagUser": "codexdiag",
  "appDir": "/home/easytoday/domains/app.easytoday.se/app",
  "healthUrl": "http://127.0.0.1/up",
  "enableMutations": false,
  "codex": {
    "configure": true,
    "serverName": "laravelProdEasyToday"
  }
}

将SSH私钥保存在CI密钥存储中。不要将机密提交到此存储库。

CLI命令

laravel-debug-mcp init [--profile <name>] [--config <path>] [--yes] [--dry-run]
laravel-debug-mcp doctor --profile <name>
laravel-debug-mcp rotate-key --profile <name>

rotate-key 生成新的每个配置文件密钥，使用相同的强制命令引导程序安装它，更新本地配置文件和Codex MCP条目，运行 doctor，并从中删除之前的公钥 authorized_keys 经核实。

医生检查

安装后，运行：

laravel-debug-mcp doctor --profile easytoday-prod

doctor 验证本地先决条件并执行远程烟雾检查：

  • Node.js版本；
  • SSH二进制可用性；
  • 私钥的存在和权限；
  • 远程 sys.info 行动；
  • 拉瑞维尔 health 行动；
  • artisan.version 行动。

本地配置文件格式

个人资料发送至：

~/.config/laravel-debug-mcp/profiles/<profile>.json

配置文件包含主机、端口、诊断用户、密钥路径、远程命令、变异策略、输出上限、超时和Codex服务器名称。MCP服务器仍然通过以下方式读取运行时配置 LARAVEL_PROD_* 环境变量，这使得Codex和CI集成变得简单。

手动远程安装

首选完整的安装程序，但传统的帮助程序仍然可用：

sudo DIAG_USER=codexdiag scripts/remote/install-remote.sh

然后编辑 /etc/laravel-diag.env 并手动配置SSH授权密钥。完整版 init flow会自动执行此操作。

MCP服务器环境变量

直接运行MCP服务器时，至少提供：

LARAVEL_PROD_HOST=prod.example.com
LARAVEL_PROD_USER=codexdiag
LARAVEL_PROD_SSH_KEY=/home/alex/.ssh/laravel-debug-mcp/prod_ed25519

可选变量：

LARAVEL_PROD_SSH_PORT=22
LARAVEL_PROD_REMOTE_COMMAND=/usr/local/bin/laravel-diag
LARAVEL_PROD_TOOL_TIMEOUT_SEC=45
LARAVEL_PROD_MAX_OUTPUT_CHARS=200000
LARAVEL_PROD_ENABLE_MUTATIONS=0

可用诊断

应用程序/级别

  • health
  • artisan_version
  • artisan_about
  • artisan_migrate_status
  • artisan_schedule_list
  • artisan_queue_failed
  • artisan_horizon_status
  • file_list
  • file_read
  • env_read

日志

  • logs_list
  • logs_tail
  • logs_grep
  • logs_last_error

系统

  • sys_info
  • sys_disk
  • sys_memory
  • sys_top
  • php_version
  • php_extensions

Laravel缓存工件

  • cache_status

数据库只读

  • database_connections
  • database_schema
  • database_query (SELECT, SHOW, EXPLAIN，以及 DESCRIBE 仅）

碎玻璃突变

默认情况下禁用突变，并在本地和远程双重门控：

  1. 本地MCP配置： LARAVEL_PROD_ENABLE_MUTATIONS=1
  2. 远程运行器配置： LARAVEL_DIAG_ENABLE_MUTATIONS=1

突变工具：

  • artisan_optimize_clear
  • artisan_config_cache
  • artisan_queue_restart
  • artisan_queue_retry
  • artisan_pulse_restart

SSH硬化

安装程序以这种形式写入授权密钥：

command="/usr/local/bin/laravel-diag",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA...

这使得OpenSSH只运行该密钥的诊断运行器，即使客户端要求shell或其他命令。

发展

npm install
npm run typecheck
npm run build
node dist/cli.js --help

版本控制

当前版本： 0.1.0.

在每次发布之前保持这些版本值同步：

  • package.json
  • package-lock.json
  • src/cli.ts
  • src/index.ts

发布验证器检查包名称、公共包状态、semver格式、GitHub发布标签、预发布/稳定发布类型、CLI版本和MCP服务器版本：

npm run release:verify

对于候选版本，请使用semver预发布版本，例如 0.1.0 并将GitHub Release作为预发布版发布。对于稳定版本，请使用简单的semver版本，例如 0.0.1 并将GitHub Release作为稳定版本发布。

发布

发布清单：

  1. 更新包版本和匹配的源版本。

  2. 运行本地验证：

    npm ci
npm run release:verify
npm run typecheck
npm run build
npm pack --dry-run

  3. 提交发布更改。

  4. 创建并发布一个GitHub Release，其标签完全正确 v<package.json version>例如 v0.1.0.

CI工作流在拉取请求上运行，并推送到 main。它安装依赖关系，验证发布元数据，类型检查，构建，并使用以下命令检查包内容 npm pack --dry-run.

出版

发布由以下人员处理 .github/workflows/npm-publish.yml 当GitHub发布时。

发布工作流：

  • 验证发布标签是否匹配 v<package.json version>;
  • 验证GitHub预发布是否使用semver预发布版本；
  • 验证稳定的GitHub版本是否使用稳定的semver版本；
  • 跑 npm run typecheck;
  • 检查包裹内容 npm pack --dry-run;
  • 使用源代码发布到npm npm publish --access public --provenance.

GitHub预发布发布到npm next dist标签。稳定的GitHub版本发布于 latest dist标签。

工作流程要求配置npm可信发布/OIDC @alex-engvall/laravel-debug-mcp 因为它使用 id-token: write 并且不从存储库秘密中读取npm令牌。

相关 MCP