Yudao Pilot MCP

中文 | English

中文

Yudao Pilot MCP 是面向 yudao / ruoyi-vue-pro 生态的工作区感知型 MCP 服务。它帮助 AI 编码工具识别本地后端、前端、数据库和代码生成目标，让 AI 生成的代码准确落到正确项目结构里。

严肃声明

yudao、ruoyi-vue-pro 生态与 ruoyi / RuoYi / 若依原生生态不是同一个项目。当前 MCP 只支持 yudao、ruoyi-vue-pro、ruoyi-vue-pro-jdk17、yudao-cloud 相关项目，不支持若依原生生态项目。

核心价值

• 让 AI 不再猜 yudao 项目目录和生成位置
• 用 .yudao-pilot/config.yaml 固化后端、前端和数据库配置
• 基于项目指纹校验路径，避免代码写错仓库或模块
• 生成前后端代码、菜单、表字段派生字典和 H2 SQL 内容，由 AI 写入普通文件
• 使用专用工具合并错误码、前端 DICT_TYPE 常量，显式应用菜单与派生字典到数据库
• 当工作目录不明确时停止初始化，并要求 AI 先询问真实项目目录

安装

项目提供 yudao-pilot 命令入口，适合通过 pipx 或 uv 作为隔离的命令行工具安装。

推荐使用 pipx：

pipx install yudao-pilot-mcp
pipx ensurepath

也可以使用 uv：

uv tool install yudao-pilot-mcp

没有 pipx 或 uv 时，使用标准虚拟环境和 pip：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install yudao-pilot-mcp

Windows 使用 .venv\Scripts\activate 激活虚拟环境。如果当前 PyPI 镜像尚未同步新版本，显式使用官方索引：

python -m pip install --index-url https://pypi.org/simple/ yudao-pilot-mcp

从源码安装仅用于开发：

git clone https://github.com/chanshawoh/yudao-pilot-mcp.git
cd yudao-pilot-mcp
python -m pip install -e ".[dev]"

查看版本与升级

yudao-pilot --version    # 打印已安装版本，等价于 yudao-pilot version
yudao-pilot upgrade      # 按当前安装方式升级

upgrade 会根据运行环境自动选择 uv tool upgrade、pipx upgrade 或 python -m pip install --upgrade。升级后需要重启 MCP 客户端，已经运行的旧进程不会自动切换。

配置 MCP 客户端

通过 pipx、uv tool 或 PATH 中的 pip 环境安装后：

{
  "mcpServers": {
    "yudao-pilot": {
      "command": "yudao-pilot",
      "args": []
    }
  }
}

如果使用项目内虚拟环境，或 MCP 客户端读取不到 shell 的 PATH：

{
  "mcpServers": {
    "yudao-pilot": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "yudao_pilot.server"]
    }
  }
}

Windows 将 command 改为 .venv\\Scripts\\python.exe 的绝对路径。临时试用也可以让 pipx 自动创建缓存环境：

{
  "mcpServers": {
    "yudao-pilot": {
      "command": "pipx",
      "args": ["run", "--spec", "yudao-pilot-mcp", "yudao-pilot"]
    }
  }
}

长期使用推荐先执行 pipx install，避免 MCP 首次启动时等待下载依赖。

使用

先调用 load_workspace_config。缺少配置时显式调用 init_workspace_config，检查识别到的后端与前端路径。

load_workspace_config(workspace_root=...)
validate_workspace_projects(workspace_root=...)
inspect_codegen_context(table_name=..., workspace_root=...)
generate_codegen_scaffold(table_name=..., workspace_root=...)

生成工具只返回内容和目标路径；普通文件由 AI 写入，错误码与前端字典通过返回的 merge_operations 调用专用合并工具。需要 SQL 时单独调用 generate_codegen_sql；需要应用菜单/派生字典到数据库时，显式调用 apply_codegen_sql 并满足配置许可。

“只预览”展示生成结果即可，不会创建预览目录。完整的 12 个工具及参数示例见 工具文档。

配套 Skill

仓库提供 yudao-pilot-mcp skill，包含工具选择、表生成、错误码与前端常量合并、SQL 生成和数据库应用流程。将 skills/yudao-pilot-mcp/ 整个目录安装到客户端的技能目录；更新时同步 SKILL.md 和 agents/openai.yaml。

给 AI Agent 的说明

将下面的要求交给使用该 MCP 的 AI Agent：

请安装并配置 yudao-pilot-mcp。不要克隆源码仓库，除非用户明确要参与开发。

1. 确认 Python 版本不低于 3.11。
2. 优先执行 pipx install yudao-pilot-mcp，将 MCP Server 安装为隔离的命令行工具。
3. 如果没有 pipx 但有 uv，执行 uv tool install yudao-pilot-mcp。
4. 如果两者都没有，创建 Python 虚拟环境并执行 python -m pip install yudao-pilot-mcp。
5. 如果当前包镜像找不到该包，使用 --index-url https://pypi.org/simple/ 从官方 PyPI 安装。
6. 验证 yudao-pilot 命令存在。不要把 stdio MCP Server 持续运行在测试终端中。
7. 在用户的 MCP 客户端配置中注册 command=yudao-pilot、args=[]。
8. 如果 MCP 客户端读取不到 PATH，使用虚拟环境 Python 的绝对路径，并配置 args=["-m", "yudao_pilot.server"]。
9. 配置完成后提醒用户重启或重新加载 MCP 客户端。

安装后的业务操作方式以 yudao-pilot-mcp Skill 为准，不要在安装阶段自行执行代码生成或数据库写入。

开源协议

本项目采用 MIT License。你可以自由使用、复制、修改、合并、发布和分发本项目，但必须保留原始版权和许可声明。软件按“原样”提供，不附带任何明示或默示担保。

文档

• 项目概览
• 配置指南
• MCP 工具与工作流
• SQL、菜单与字典生成
• 开发与测试
• 前端产物矩阵
• 产品说明
• 路线图

English

Yudao Pilot MCP is a workspace-aware MCP server for the yudao / ruoyi-vue-pro ecosystem. It helps AI coding tools understand local backend projects, frontend targets, database configuration, and code-generation routes so generated code lands in the right place.

Important Notice

The yudao / ruoyi-vue-pro ecosystem is not the same project as the original ruoyi / RuoYi ecosystem. This MCP currently supports yudao, ruoyi-vue-pro, ruoyi-vue-pro-jdk17, and yudao-cloud projects only. It does not support original RuoYi projects.

Core Value

• Stop AI tools from guessing yudao project paths
• Use .yudao-pilot/config.yaml as the routing source of truth
• Validate backend and frontend paths with project fingerprints
• Return backend/frontend code, menu SQL, table-derived dictionary SQL, and H2 contents for AI clients to write
• Merge error codes and frontend DICT_TYPE constants through dedicated tools; apply menu/dictionary database changes explicitly
• Refuse unsafe initialization when the project workspace is unknown

Installation

The package exposes a yudao-pilot command and is well suited to isolated CLI installation with pipx or uv.

Recommended with pipx:

pipx install yudao-pilot-mcp
pipx ensurepath

With uv:

uv tool install yudao-pilot-mcp

Without pipx or uv, use a standard virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install yudao-pilot-mcp

On Windows, activate with .venv\Scripts\activate. If your configured package mirror has not synchronized the release yet, use the official PyPI index:

python -m pip install --index-url https://pypi.org/simple/ yudao-pilot-mcp

Install from source only for development:

git clone https://github.com/chanshawoh/yudao-pilot-mcp.git
cd yudao-pilot-mcp
python -m pip install -e ".[dev]"

Check the Version and Upgrade

yudao-pilot --version    # print the installed version; same as yudao-pilot version
yudao-pilot upgrade      # upgrade with the installer that owns this environment

upgrade picks uv tool upgrade, pipx upgrade, or python -m pip install --upgrade based on how the command was installed. Restart your MCP client afterwards; an already running server keeps the old version.

MCP Client Configuration

After installing with pipx, uv tool, or a pip environment available on PATH:

{
  "mcpServers": {
    "yudao-pilot": {
      "command": "yudao-pilot",
      "args": []
    }
  }
}

When using a project virtual environment, or when the MCP client cannot see your shell PATH:

{
  "mcpServers": {
    "yudao-pilot": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "yudao_pilot.server"]
    }
  }
}

On Windows, set command to the absolute path of .venv\\Scripts\\python.exe. For temporary use, pipx can create a cached environment automatically:

{
  "mcpServers": {
    "yudao-pilot": {
      "command": "pipx",
      "args": ["run", "--spec", "yudao-pilot-mcp", "yudao-pilot"]
    }
  }
}

For regular use, run pipx install first to avoid dependency downloads during the first MCP startup.

Usage

Call load_workspace_config first. If missing, explicitly call init_workspace_config and check the detected project paths.

load_workspace_config(workspace_root=...)
validate_workspace_projects(workspace_root=...)
inspect_codegen_context(table_name=..., workspace_root=...)
generate_codegen_scaffold(table_name=..., workspace_root=...)

Generation returns contents and target paths. The AI writes ordinary files and calls the dedicated tools in merge_operations for error codes and frontend constants. Generate SQL separately with generate_codegen_sql; explicitly call apply_codegen_sql for authorized database changes, subject to config permission.

Preview means inspecting the returned contents; no preview directory is created. See all 12 tools and parameter examples.

Companion Skill

The yudao-pilot-mcp skill covers tool selection, table-based generation, constant merging, SQL generation, and database application. Install the complete skills/yudao-pilot-mcp/ directory in your client’s skill directory, keeping SKILL.md and agents/openai.yaml in sync.

Instructions for AI Agents

Give the following requirements to the AI Agent using this MCP server:

Install and configure yudao-pilot-mcp. Do not clone the source repository unless the user explicitly wants a development checkout.

1. Confirm that Python 3.11 or newer is available.
2. Prefer pipx install yudao-pilot-mcp to install the MCP server as an isolated CLI application.
3. If pipx is unavailable but uv is installed, run uv tool install yudao-pilot-mcp.
4. If neither tool is available, create a Python virtual environment and run python -m pip install yudao-pilot-mcp.
5. If the configured package mirror cannot find the package, install from the official index with --index-url https://pypi.org/simple/.
6. Verify that the yudao-pilot command exists. Do not leave the stdio MCP server running in the verification terminal.
7. Register the server in the user's MCP client with command=yudao-pilot and args=[].
8. If the MCP client cannot see the command on PATH, use the absolute path to the virtual-environment Python and set args=["-m", "yudao_pilot.server"].
9. Ask the user to restart or reload the MCP client after saving the configuration.

After installation, follow the yudao-pilot-mcp Skill for business operations. Do not start code generation or database writes during installation.

License

This project is released under the MIT License. You may use, copy, modify, merge, publish, and distribute it provided that the original copyright and permission notice are retained. The software is provided “as is”, without warranty of any kind.

Documentation

• Overview
• Configuration
• MCP Tools and Workflow
• SQL, Menu, and Dictionary Generation
• Development and Testing
• Frontend Output Matrix
• Product Notes
• Roadmap