Yii2 MCP 服务器

Yii2 框架的 Model Context Protocol (MCP) 服务器，提供数据库模式检查、控制台命令执行以及 Claude Code 的项目管理工具。

功能

数据库工具

• db_list_tables: 列出所有数据库表及其详情（行数、大小、注释）
• db_describe_table: 获取特定表的详细模式信息
• db_table_relationships: 分析外键关系
• db_execute_query: 安全地执行 SELECT 查询并返回结果

数据库优化与分析（新）

• db_analyze_table: 全面的表分析，包括碎片化、索引效率及存储引擎建议
• db_get_index_suggestions: 基于表结构和查询模式的智能索引建议
• db_profile_query: 查询性能剖析，包括执行计划和优化建议
• db_monitor_connections: 实时数据库连接监控及告警

Yii2 控制台工具

• yii_list_commands: 列出所有可用的 Yii 控制台命令及其描述
• yii_command_help: 获取特定命令的详细帮助
• yii_execute_command: 执行安全的控制台命令（危险命令被阻止）
• yii_list_migrations: 显示迁移状态（已应用和待处理）

模型与项目工具

• yii_list_models: 列出所有 ActiveRecord 模型及其关系
• yii_analyze_model: 分析特定模型类
• project_structure: 获取项目目录结构概览
• module_info: 特定模块的详细信息
• config_inspect: 检查应用程序配置文件

高级模块分析

• module_detailed_analysis: 全面的模块分析，包括控制器、模型、资源包、小部件、作业、服务和特性
• asset_list_bundles: 列出所有资源包及其 CSS/JS 文件和依赖项
• asset_analyze_dependencies: 分析资源依赖链及注册顺序
• widget_list: 发现小部件及其关联的资源包

迁移管理

• migration_create: 创建新的数据库迁移
• migration_diff: 根据模型/数据库差异生成迁移
• migration_rollback: 安全回滚迁移
• migration_generate_from_model: 从 ActiveRecord 模型生成迁移

代码生成工具

• generate_crud: 生成 CRUD 控制器和视图
• generate_model: 从数据库表生成 ActiveRecord 模型
• generate_api: 生成 REST API 控制器
• generate_form: 生成表单类

缓存管理

• cache_clear: 清除应用程序缓存（可选参数）
• cache_inspect: 检查缓存配置和状态
• cache_performance: 分析缓存性能及命中率

RBAC（基于角色的访问控制）

• rbac_permission_tree: 可视化权限层次结构
• rbac_user_access: 检查用户权限及访问级别
• rbac_role_analysis: 分析角色分配及权限
• rb_ access_debug: 调试访问控制问题

队列系统管理

• queue_job_status: 监控队列作业状态及进度
• queue_retry_failed: 重试失败的队列作业
• queue_worker_status: 检查队列工作者状态
• queue_clear_failed: 从队列中清除失败的作业

日志与调试

• log_error_analysis: 分析错误日志及模式
• log_performance_issues: 在日志中识别性能瓶颈
• log_search: 搜索应用程序日志
• log_tail: 实时日志监控

高级数据库分析

• db_index_suggestions: 高级索引优化建议
• db_query_profiler: 详细的查询性能剖析
• db_table_analysis: 深入的表结构分析
• db_connection_monitor: 实时数据库连接监控

测试与质量保证

• test_run: 执行测试套件
• test_generate: 生成测试用例
• test_coverage_report: 生成代码覆盖率报告

性能分析

• performance_profile: 应用程序性能剖析
• asset_performance_analysis: 前端资源性能分析

安装

方案 1：NPM 安装（推荐）

npm install -g yii2-mcp-server

然后从你的 Yii2 项目目录配置 Claude Code：

cd /path/to/your/yii2/project
claude mcp add yii2 yii2-mcp-server

方案 2：手动安装

1. 克隆并安装

   git clone https://github.com/ArtMin96/yii2-mcp-server.git
   cd yii2-mcp-server
   npm install
   npm run build
   

2. 配置 Claude Code

   使用 Claude CLI：

   cd /path/to/your/yii2/project
   claude mcp add yii2 node /path/to/yii2-mcp-server/dist/index.js
   

   手动 JSON 配置：

   {
     "mcpServers": {
       "yii2": {
         "command": "node",
         "args": ["/path/to/yii2-mcp-server/dist/index.js"],
         "cwd": "/path/to/your/yii2/project"
       }
     }
   }
   

配置

MCP 服务器会自动检测你的 Yii2 项目配置：

数据库配置

服务器按以下顺序查找数据库配置：

1. .env 文件（用于环境变量如 DB_HOST、DB_DATABASE 等）
2. config/db.php 文件（默认回退到 MySQL 设置）

项目检测

• 必须从包含 yii 控制台脚本的目录运行
• 自动扫描 modules/、models/、config/ 目录
• 支持标准的 Yii2 目录结构

使用示例

配置完成后，你可以通过 Claude Code 使用这些工具：

# 数据库分析
使用 db_list_tables 工具
使用 db_describe_table 并指定表名："user"
使用 db_table_relationships 并指定表名："user"

# 数据库优化（新）
使用 db_analyze_table 并指定表名："user"
使用 db_get_index_suggestions 并指定表名："user"
使用 db_profile_query 并指定查询："SELECT * FROM user WHERE status = 'active'"
使用 db_monitor_connections 并设置告警阈值：50

# Yii2 控制台命令
使用 yii_list_commands
使用 yii_list_migrations

# 项目结构
使用 project_structure
使用 yii_list_models 并指定模块："fastnet"

# 高级模块分析
使用 module_detailed_analysis 并指定模块名："fastnet"
使用 module_detailed_analysis 并指定模块名："billing"

# 资源包分析
使用 asset_list_bundles
使用 asset_list_bundles 并指定模块过滤器："rbac"
使用 asset_analyze_dependencies
使用 asset_analyze_dependencies 并指定资源包名："AppAsset"

# 小部件发现
使用 widget_list
使用 widget_list 并指定模块过滤器："fastnet"

# 迁移管理
使用 migration_create 并指定表名："user_profiles"
使用 migration_diff 以生成自模型更改
使用 migration_rollback 并指定步骤：1

# 代码生成
使用 generate_crud 并指定表名："posts"
使用 generate_model 并指定表名："categories" 
使用 generate_api 并指定模型类："User"

# 缓存操作
使用 cache_clear 并指定组件："db"
使用 cache_inspect
使用 cache_performance

# RBAC 分析
使用 rbac_permission_tree
使用 rbac_user_access 并指定用户 ID：1
使用 rbac_role_analysis 并指定角色："admin"

# 队列管理
使用 queue_job_status
使用 queue_retry_failed 并指定作业 ID：123
使用 queue_worker_status

# 日志与调试
使用 log_error_analysis 并指定小时数：24
使用 log_search 并指定模式："database error"
使用 log_tail 并指定行数：50

# 测试
使用 test_run 并指定套件："unit"
使用 test_coverage_report

# 性能分析
使用 performance_profile 并指定持续时间："5m"
使用 asset_performance_analysis

模块分析功能

全面理解模块：

• 控制器、模型、视图结构
• 资源包及其依赖项
• 小部件和自定义组件
• 队列作业和服务类
• 特性和实用工具类
• 引导配置

资源包智能：

• CSS 和 JavaScript 文件映射
• 依赖树分析
• 循环依赖检测
• 最优注册顺序
• 源路径解析

小部件发现：

• 小部件与资源包的关系
• 模块特定的小部件组织
• 依赖项映射

安全特性

• 只读数据库访问：仅允许 SELECT 查询
• 命令安全：危险命令（如 migrate/fresh）被阻止
• 配置安全性：敏感配置值不暴露
• 超时保护：命令有 30 秒超时限制
• 交互式命令检测：需要用户输入的命令会被标记

要求

• Node.js 18+
• 具有控制台访问权限的 Yii2 项目
• MySQL 数据库
• PATH 中可用的 PHP CLI

故障排除

常见问题

1. “未找到 Yii 脚本”

   • 确保你在 Yii2 项目的根目录运行
   • 检查 yii 控制台脚本是否存在且可执行

2. 数据库连接错误

   • 验证 .env 文件中的数据库凭证是否正确
   • 确保 MySQL 正在运行且可访问
   • 检查配置中指定的数据库是否存在

3. 权限错误

   • 确保服务器对项目文件具有读取权限
   • 检查 PHP CLI 是否可用且能够执行 Yii 脚本

调试模式

为了开发和调试，你可以直接运行服务器：

npm run dev

这将监视文件更改并自动重建。

开发

服务器使用 TypeScript 构建，主要包括：

• src/index.ts - 主 MCP 服务器设置和工具路由
• src/database.ts - 数据库连接和模式检查
• src/yii2.ts - Yii2 控制台命令执行和项目分析
• src/config.ts - 配置管理和项目检测

要贡献：

1. 分叉仓库
2. 进行修改
3. 运行 npm run build 编译
4. 使用你的 Yii2 项目进行测试
5. 提交拉取请求

许可证

MIT 许可证 - 随意在你的项目中使用！