MCP 开发助手

元点 AI MCP（npm 包名：yd-mcp-server）把当前元点Admin项目的框架信息、数据库表结构、代码文件、框架编码规范、安全写入和本地检查能力提供给 Claude Code、Cursor、Kimi Code、Claude Desktop、Windsurf 等支持 MCP 的 AI 编码工具。

它解决的核心问题是：通用 AI 不认识元点框架。没有 MCP 时，模型只能按通用 ThinkPHP 直觉写代码，字段靠猜、分层靠蒙、路由命名各写各的；接入 MCP 后，模型能读到真实表结构、框架规范原文和项目里的既有实现，并在写盘后立即跑语法与路由校验，生成质量明显高于裸用通用 AI。

上手路径：先按第 2 节让客户端连上 MCP，再按 5.1 让助手执行一次 init_client_assets 写入引导资产，之后按按数据表开发业务走完整实战。

它支持两种使用方式：

模式	代码由谁生成	是否需要元点 AI Token	适用场景
客户端原生模式	Cursor/Claude/Windsurf 当前模型	否	使用已有 IDE 订阅或模型额度开发
元点云增强模式	元点 AI Engine	是	使用元点专项 Prompt、RAG 和结构化多文件生成

两种 Token 不是一回事

Cursor、Claude 等客户端的模型订阅只供客户端自身推理，不会传递给 MCP，也不能代替元点 AI Token。反过来，只使用客户端原生模式时，不需要配置 YD_AI_TOKEN。

1. 环境要求

Node.js 20 或更高版本。
一个已经安装并可运行的元点Admin项目。
Claude Code、Cursor、Kimi Code、Claude Desktop、Windsurf 或其他支持 stdio MCP 的客户端。

确认 Node.js 版本：

bash

node -v

当前 npm 正式包为 yd-mcp-server，最新版本 0.6.0（提供十个工具，含引导资产初始化与框架规范查询）。检查线上版本：

bash

npm view yd-mcp-server version

2. 零配置快速开始

框架自带配置，下载即用

元点Admin 框架仓库已内置 .mcp.json（Claude Code）与 .cursor/mcp.json（Cursor，${workspaceFolder} 自动定位），两处均已钉定版本号 yd-mcp-server@0.6.0——随框架发货、由 npx 自动执行的命令必须是确定性的，避免供应链风险。下载框架后用支持 MCP 的客户端打开项目，按提示允许启用即可，通常无需手工创建下述配置；本节内容供理解机制与自定义时参考。首次使用前你的旧全局配置（如 ~/.cursor/mcp.json 里指向本地 dist 的旧条目）建议删除，避免出现两个重复的 MCP server。

从 0.4.0 起，MCP 会自动定位项目并自动读取数据库配置，多数场景下只需三行：

json

{
  "mcpServers": {
    "yuandian": { "command": "npx", "args": ["-y", "yd-mcp-server"] }
  }
}

最佳努力零配置

零配置能否生效取决于客户端是否支持 MCP Roots（见 2.2 差异表），不承诺对所有客户端必然生效。零配置未命中时，MCP 不会静默猜测项目，而是明确进入「未定位」状态并在 get_project_info 里给出诊断，此时改为显式设置 YD_PROJECT_ROOT 即可。

2.1 项目自动定位机制

MCP 按以下优先级确定项目根目录：

YD_PROJECT_ROOT（显式配置）：一旦设置，只信任这一个值。验证失败会 fail closed——本地文件与数据库工具全部禁用，绝不降级去尝试其他来源，因为显式配置代表用户的明确意图。
MCP Roots（客户端工作区）：客户端声明 roots 能力时，依次验证每个工作区目录，取第一个通过验证的，请求 3 秒超时。
MCP 进程当前目录（cwd）：以上都不可用时的兜底，同样必须通过验证。

「通过验证」指目录含元点项目特征：server/think，以及 server/app/adminapi 或 server/app/tenantapi。

三级都未命中时进入未定位态：read_file / apply_patch / run_check / list_tables / show_table_schema 全部拒绝执行；generate_code 仍可调用，但仅限 instruction-only（不能传 tables），且必须显式传 framework 参数或设置 YD_FRAMEWORK，不会静默假设框架。

2.2 客户端差异

客户端	零配置可用性	说明
Claude Code	支持，可真正零配置	原生支持 MCP Roots，自动传递当前工作区
Cursor	推荐项目级 `${workspaceFolder}` 插值	实测不声明 MCP Roots，且 MCP 子进程 cwd 不是工作区目录，零配置会落入未定位态；在项目内 `.cursor/mcp.json` 的 `env` 中写 `"YD_PROJECT_ROOT": "${workspaceFolder}"`，内容跨项目/跨机器一致，可直接提交入库（见 2.2.1）
Kimi Code	视版本而定	在项目目录内启动 CLI 时可尝试零配置，未命中则在 MCP 配置里显式设置 `YD_PROJECT_ROOT`
Claude Desktop	不支持	没有工作区概念，必须显式设置 `YD_PROJECT_ROOT`
Windsurf	视版本而定	项目内启动时可尝试零配置，未命中则显式设置 `YD_PROJECT_ROOT`

2.2.1 Cursor 推荐姿势：`${workspaceFolder}`

项目内 .cursor/mcp.json：

json

{
  "mcpServers": {
    "yuandian": {
      "command": "npx",
      "args": ["-y", "yd-mcp-server"],
      "env": { "YD_PROJECT_ROOT": "${workspaceFolder}" }
    }
  }
}

这份配置对团队里每个人、每台机器都一样，可以放心提交进仓库。若 Cursor 版本不支持插值该模板变量，MCP 收到的是字面量 ${workspaceFolder}——不会当成真实路径去校验，而是按「未设置」处理并落入自动探测链，同时在 warnings 里给出 PROJECT_ROOT_TEMPLATE_UNRESOLVED 告警（不会锁死后续定位）。仍未命中时，助手可调用 set_project_root（见第 5 节）传入当前工作区绝对路径一次性兜底，通常不需要人工修改配置。

全局 ~/.cursor/mcp.json 下 ${workspaceFolder} 能否解析取决于 Cursor 版本，需自行实测，本文不作承诺；不确定时优先用项目级配置。

2.3 数据库自动接入

项目定位成功后，MCP 自动读取项目 server/.env 的 [DB] 段（仅支持 TYPE=mysql）建立只读 Schema 连接，无需手工配置 YD_DB_*。

密码安全

数据库密码只用于 MCP 内部建立连接，绝不返回给 AI 模型，也不写入任何日志。

3. 各客户端配置文件位置

三行零配置 JSON（或加了 env 的扩展版）写入的位置：

客户端	配置文件路径
Claude Code	项目内 `.mcp.json`，或 `claude mcp add` 命令
Cursor	项目内 `.cursor/mcp.json`，或全局 `~/.cursor/mcp.json`，或 Settings → MCP 界面添加
Kimi Code	`kimi mcp` 命令管理，或对话内 `/mcp-config` 交互式添加；也支持标准格式的 MCP 配置文件
Claude Desktop	macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`；Windows：`%APPDATA%\Claude\claude_desktop_config.json`
Windsurf	Windsurf 的 MCP 设置中添加 stdio 服务，命令 `npx -y yd-mcp-server`

Claude Desktop 的最小可用配置（无工作区概念，必须给出项目根）：

json

{
  "mcpServers": {
    "yuandian": {
      "command": "npx",
      "args": ["-y", "yd-mcp-server"],
      "env": { "YD_PROJECT_ROOT": "/absolute/path/to/your/ydadmin-project" }
    }
  }
}

保存配置后，在客户端 MCP 设置里重新加载服务或重启客户端。

4. 高级配置

以下全部可选，按需添加到 env 块。

4.1 元点云增强

json

{
  "YD_AI_TOKEN": "yd_live_your_token_here",
  "YD_AI_ENDPOINT": "https://your-yuandian-ai-endpoint"
}

元点 AI Token 在元点 Site 用户中心的 AI 服务页面创建。明文 Token 只在创建时显示一次，不要提交到 Git 仓库。不配置时其余九个本地工具不受影响，只是生产引擎会拒绝 generate_code。

4.2 数据库覆盖

YD_DB_HOST / YD_DB_PORT / YD_DB_USER / YD_DB_PASS / YD_DB_NAME 按「该环境变量是否存在」逐项覆盖项目 .env 的对应值——覆盖成空字符串也算显式值。常见场景：

改用只读账号（推荐）：

json

{ "YD_DB_USER": "mcp_readonly", "YD_DB_PASS": "your_password" }

项目跑在 Docker 里、.env 的 HOST 是容器内部域名（如 mysql）时，宿主机上的 MCP 进程需覆盖：

json

{ "YD_DB_HOST": "127.0.0.1" }

4.3 monorepo / 多项目

仓库里有多个元点项目子目录时，用 YD_PROJECT_ROOT 显式指向目标子项目根目录，避免自动定位选错。

4.4 团队共享项目标识

零配置下 projectId 由项目根路径哈希派生（yd_ + 12 位十六进制），项目目录移动后会变化。团队共享 RAG、云端归因等跨机器场景必须显式设置：

json

{ "YD_PROJECT_ID": "team-shared-project-id" }

5. 可用工具

当前 MCP 提供十个工具：

工具	是否需要元点 Token	作用
`get_project_info`	否	定位与识别诊断：`workspace_state`、`root_candidates`、`warnings`、框架、数据库状态、引导资产状态、安全策略
`list_tables`	否	列出数据库表、注释和基础信息
`show_table_schema`	否	读取指定表的字段、类型、索引、默认值和注释
`read_file`	否	读取项目根目录内的非敏感代码文件
`get_conventions`	否	按主题返回元点框架编码规范全文（分层 / 路由 / 权限 / 验证器 / 前端等），规范随包发布、离线可用；项目未定位时也能调用
`generate_code`	是（生产云端）	调用元点 AI Engine 生成结构化多文件代码
`apply_patch`	否	预览或写入 AI 生成的文件，默认仅预览
`run_check`	否	根据框架 Adapter 运行 PHP 语法和路由检查
`init_client_assets`	否	把 AI 引导资产写入当前项目（见 5.1），默认仅预览
`set_project_root`	否	项目未定位时的一次性兜底：由助手传入当前工作区绝对路径完成定位，须通过元点项目特征验证；已定位、已进入陈旧态或已显式配置 `YD_PROJECT_ROOT` 时拒绝调用

get_conventions 不传参数时返回主题目录，传 topic 返回该主题规范全文。八个主题：

topic	内容
`architecture`	四层分工与调用规则、禁止事项、目录地图
`controller`	响应格式、参数校验签名
`service`	Service 骨架、事务边界、副作用触发
`repository-model`	查询封装、分页结构、命名与字段约定
`route`	路径与命名空间对照、`{module}` 推导算法、路由动作命名细则
`permission`	中间件三件套、菜单与权限节点初始化
`validation`	验证器规则覆盖与场景
`frontend`	`admin/src` 目录约定与构建流程

无 Token 时不要调用 generate_code

不配置 YD_AI_TOKEN 时，其他本地工具仍可使用，但生产环境的元点 AI Engine 会拒绝 generate_code 请求。客户端原生模式应由 Cursor/Claude/Windsurf 自己生成代码，然后把文件传给 apply_patch。

5.1 引导资产初始化（强烈建议做一次）

工具能力再强，也得助手主动去用。init_client_assets 把一组引导资产写进你的项目，让客户端在每次对话中自动加载元点框架的开发规约与标准流程——这是「生成质量高于通用 AI」最省力的一步。

在对话里说一句即可：

text

帮我初始化元点 AI 配置

助手会调用 init_client_assets，默认先 dry_run 列出将写入的文件，你确认后它再传 dry_run: false 落盘。写入三类资产：

资产	路径	谁加载
开发规约块	`AGENTS.md` 中的 `<!-- yd:begin -->` 标记块	Cursor 全版本、Kimi Code
标准流程 Skills	`.claude/skills/yuandian-new-module/`、`.claude/skills/yuandian-modify/`	Cursor 2.4+、Kimi Code、Claude Code
Cursor 垫片	`.cursor/rules/yuandian.mdc`	Cursor 全版本（含 2.4 以下）

资产内容分三层，避免占满上下文：常驻层（约 30 行铁律，始终在场）→ Skills（新增模块 / 修改存量代码两套标准流程，按需加载）→ 规范文档（篇幅不限，助手用 get_conventions 按需拉取）。

幂等，可以放心重跑

AGENTS.md 只维护 yd:begin / yd:end 之间的内容，块外你自己写的东西一字不动；重跑时内容一致会报「无变化」。若标记块被改坏（begin/end 不成对），工具会拒绝改动该文件并提示你手工修复，绝不猜边界——宁可不做，也不误删你的内容。

升级 MCP 后资产不会自动更新。get_project_info 的 client_assets 字段会显示每份资产的状态（installed@0.6.0 / outdated(0.5.0 → 0.6.0) / missing / broken），显示 outdated 时重跑一次 init_client_assets 即可同步。

资产建议提交入库，团队成员拉下来就享有同一套 AI 开发约束。

6. 客户端原生模式操作流程

完成 5.1 的资产初始化后，助手已经知道该走什么流程，一句话即可：

text

帮我给 brands 表开发商品品牌管理模块（列表 / 新增 / 编辑 / 删除 / 状态切换）

若尚未初始化资产，或想显式约束流程，可以写完整指令：

text

请使用元点 MCP 开发商品品牌管理模块。
先调用 get_project_info，读取 brands 表结构和项目中的相似模块；
拿不准框架写法时调用 get_conventions 查对应主题规范；
代码必须遵守项目 AGENTS.md 和 Controller → Service → Repository → Model 分层。
请使用你当前的模型生成代码，不要调用 generate_code。
先调用 apply_patch 的 dry_run 模式展示写入文件，等我确认后再写入，最后运行 run_check。

典型工具链：

text

get_project_info
→ show_table_schema
→ get_conventions（架构 / 路由 / 权限等主题）
→ read_file（参考项目内既有实现）
→ 客户端模型生成代码
→ apply_patch(dry_run=true)
→ 用户确认
→ apply_patch(dry_run=false)
→ run_check
→ 客户端根据错误修复并再次检查

get_conventions 是本模式的质量关键：客户端模型不联网、也没读过元点框架源码，规范全文直接喂给它，才不会退化成通用 ThinkPHP 写法。

此模式消耗的是当前 Cursor、Claude 或 Windsurf 账户的模型额度，不消耗元点 AI 套餐。

7. 元点云增强模式操作流程

配置 YD_AI_TOKEN 后，可以让客户端调用元点专项生成：

text

请使用元点 MCP 为 brands 表生成品牌管理模块，包含列表、新增、编辑、删除和状态切换。
先读取项目和表结构，然后调用 generate_code。
生成完成后先 dry-run 预览，等我确认后写入并运行检查。

典型工具链：

text

get_project_info
→ show_table_schema
→ read_file（可选）
→ generate_code
→ apply_patch(dry_run=true)
→ 用户确认
→ apply_patch(dry_run=false)
→ run_check

云增强模式的价值包括：

使用元点框架专项 Prompt。
按框架类型匹配 RAG 规范和代码示例。
返回结构化多文件生成结果。
记录生成版本、用量和反馈，持续改善生成质量。

8. 环境变量

全部可选；零配置命中时一个都不用设。

变量	默认行为	说明
`YD_PROJECT_ROOT`	自动定位（MCP Roots → cwd）	项目根目录绝对路径。一旦设置只信任它，验证失败直接禁用本地工具（fail closed），不降级
`YD_FRAMEWORK`	自动识别	显式指定 `ydadmin_php` 或 `ydsaas_php`；与检测结果冲突时 `run_check` 拒绝执行
`YD_FRAMEWORK_FORCE`	关闭	设为 `1` 时强制放行 `YD_FRAMEWORK` 与检测结果的冲突
`YD_PROJECT_ID`	项目根路径哈希派生（`yd_` + 12 hex）	云端 RAG 和用量归因的项目标识；派生值随本机路径变化，团队共享场景必须显式设置
`YD_AI_TOKEN`	空（仅云增强模式需要）	Site 创建的元点 AI Token
`YD_AI_ENDPOINT`	`http://127.0.0.1:8000`（仅云增强模式需要改）	元点 AI Engine 地址
`YD_DB_HOST` / `YD_DB_PORT` / `YD_DB_USER` / `YD_DB_PASS` / `YD_DB_NAME`	自动读取项目 `server/.env` 的 `[DB]` 段	逐项覆盖 `.env` 值（变量存在即覆盖，空值也算显式值）；仅支持 mysql

YD_API_BASE_URL 是旧版 Endpoint 变量，仍兼容，但新配置统一使用 YD_AI_ENDPOINT。

9. 安全机制

显式 YD_PROJECT_ROOT 验证失败 fail closed，绝不降级猜测项目，防止把文件写进错误目录。
apply_patch 默认 dry_run=true，不会直接写入。
只允许访问项目根目录内的相对路径。
拒绝 ..、绝对路径、Windows 盘符路径和空字节路径。
拒绝读取或写入 .env、.git、私钥、证书和凭证文件（MCP 内部读取 server/.env 的 [DB] 段仅用于建立连接，内容不经过模型）。
数据库工具只读取 Schema 元数据，不写业务数据；密码绝不返回给 AI 模型、不打日志。
切换客户端工作区（roots/list_changed）后，MCP 不动态跟随，所有工具报「请重启 MCP 进程」——防止误操作旧项目。
元点 AI Token 只能放在 MCP 客户端本地环境变量中，不得提交到仓库。

即使启用了真实写入，也应在 Git 工作区中使用 MCP，便于检查和撤销变更。

10. 常见问题

10.1 MCP 没有启动

先在终端检查：

bash

npx -y yd-mcp-server

MCP 使用 stdio 通信，直接运行后没有普通 Web 页面属于正常现象。重点检查 Node.js 是否达到 20，以及客户端日志中是否存在 npm 下载或配置解析错误。

10.2 项目未定位 / 本地工具全部报错

get_project_info 是第一诊断入口，重点看三个字段：

workspace_state：ready 正常；unlocated 表示三级定位都未命中；workspace_changed_restart_required 见 10.3。
root_candidates：定位时依次尝试了哪些来源（env / mcp_roots / cwd）、各自是否通过验证，可直接看出「为什么没定位到」。
warnings：结构化错误码 + 说明，如 PROJECT_ROOT_ENV_INVALID（显式路径验证失败）、PROJECT_ROOT_TEMPLATE_UNRESOLVED（客户端未插值 ${workspaceFolder} 等模板变量，已按未设置处理）、PROJECT_ROOT_UNLOCATED。

处理方式：

设置了 YD_PROJECT_ROOT 的，检查路径是否指向项目根（含 server/think 和 server/app/adminapi 或 tenantapi），而不是 server/ 子目录；显式配置验证失败不会自动降级，必须修正该变量本身。
未设置且客户端不支持 MCP Roots（如 Claude Desktop）的，显式加上 YD_PROJECT_ROOT。
出现 PROJECT_ROOT_TEMPLATE_UNRESOLVED 或未定位态时，一般不需要手动改配置：MCP 的错误消息已内置引导，助手会自动调用第 8 个工具 set_project_root 传入当前工作区绝对路径完成定位（一次性生效；已定位、陈旧态或已显式配置 YD_PROJECT_ROOT 时会拒绝，见第 5 节工具表）。

10.3 切换工作区后工具报「请重启 MCP 进程」

预期行为，不是故障。客户端切换项目触发 roots/list_changed 后，MCP 为防止误操作旧项目不会动态跟随，重启 MCP 进程（重新加载 MCP 服务或重启客户端）即可重新定位。

10.4 表结构工具连接失败

默认自动读取项目 server/.env 的 [DB] 段，先确认该文件存在、TYPE=mysql、HOST/USER/NAME 不为空。
用了 YD_DB_* 覆盖的，检查覆盖值是否正确；Docker 项目常见问题是 .env 里 HOST=mysql 在宿主机不可解析，需 YD_DB_HOST=127.0.0.1 覆盖。
确认 MySQL 已启动并允许当前用户连接。
建议为 MCP 创建只具备 Schema 读取权限的数据库账号（YD_DB_USER / YD_DB_PASS 覆盖即可，见 4.2）。

10.5 项目识别为 unknown 或框架冲突

调用 get_project_info 查看识别结果与 warnings。
必要时增加 YD_FRAMEWORK=ydadmin_php。
YD_FRAMEWORK 与自动检测结果冲突时，run_check 会直接拒绝执行；确认无误后设置 YD_FRAMEWORK_FORCE=1 强制放行。

10.6 generate_code 返回 401

生产元点 AI Engine 要求有效的 YD_AI_TOKEN。如果只想使用 Cursor 自带额度，请明确要求客户端不要调用 generate_code；如果需要元点云增强生成，请在 Site 创建 Token 并配置到 MCP。

10.7 run_check 失败

把完整检查结果交给当前 AI 客户端，让它定位文件并修复。修复后重新执行：

text

apply_patch(dry_run=true)
→ 确认
→ apply_patch(dry_run=false)
→ run_check

10.8 修改配置后没有生效

MCP Server 是客户端启动的子进程。修改 JSON 或环境变量后，需要在 MCP 设置中重新加载服务，或者完全重启客户端。

11. 与 CLI 和 AI Studio 的区别

入口	使用场景	模型来源
MCP	在 Cursor/Claude/Windsurf 对话中持续开发和修复	客户端模型或元点 AI Engine
`php think yd:ai`	终端中一次性生成模块	元点 AI Engine
AI Studio	在元点Admin后台选择表、预览 Diff 和写入	元点 AI Engine

需要命令行生成时参阅命令行生成，需要后台可视化操作时参阅后台 AI Studio。生成的代码都必须遵守分层架构规范。

12. 推荐实践

接入后先做一次 init_client_assets（见 5.1），把规约与标准流程装进项目，后续对话不必反复交代规矩。
每次会话先调用 get_project_info，确认 workspace_state 为 ready 再开工，顺带看一眼 client_assets 是否 outdated。
先阅读 AGENTS.md 和一组相似模块，写法拿不准时 get_conventions 查规范原文，再开始生成。
只提供当前任务必要的表结构和代码上下文。
始终先 dry-run，再确认写入。
每次写入后运行 run_check，不要把“已生成”当作“已完成”。
对复杂业务分阶段生成：数据层、业务层、接口、前端、测试。
团队共享 RAG 或云端项目使用显式且唯一的 YD_PROJECT_ID（自动派生的 ID 随本机路径变化），不要让多个无关项目共享私有上下文。

MCP 开发助手 ​

1. 环境要求 ​

2. 零配置快速开始 ​

2.1 项目自动定位机制 ​

2.2 客户端差异 ​

2.2.1 Cursor 推荐姿势：${workspaceFolder} ​

2.3 数据库自动接入 ​

3. 各客户端配置文件位置 ​

4. 高级配置 ​

4.1 元点云增强 ​

4.2 数据库覆盖 ​

4.3 monorepo / 多项目 ​

4.4 团队共享项目标识 ​

5. 可用工具 ​

5.1 引导资产初始化（强烈建议做一次） ​

6. 客户端原生模式操作流程 ​

7. 元点云增强模式操作流程 ​

8. 环境变量 ​

9. 安全机制 ​

10. 常见问题 ​

10.1 MCP 没有启动 ​

10.2 项目未定位 / 本地工具全部报错 ​

10.3 切换工作区后工具报「请重启 MCP 进程」 ​

10.4 表结构工具连接失败 ​

10.5 项目识别为 unknown 或框架冲突 ​

10.6 generate_code 返回 401 ​

10.7 run_check 失败 ​

10.8 修改配置后没有生效 ​

11. 与 CLI 和 AI Studio 的区别 ​

12. 推荐实践 ​

MCP 开发助手

1. 环境要求

2. 零配置快速开始

2.1 项目自动定位机制

2.2 客户端差异

2.2.1 Cursor 推荐姿势：`${workspaceFolder}`

2.3 数据库自动接入

3. 各客户端配置文件位置

4. 高级配置

4.1 元点云增强

4.2 数据库覆盖

4.3 monorepo / 多项目

4.4 团队共享项目标识

5. 可用工具

5.1 引导资产初始化（强烈建议做一次）

6. 客户端原生模式操作流程

7. 元点云增强模式操作流程

8. 环境变量

9. 安全机制

10. 常见问题

10.1 MCP 没有启动

10.2 项目未定位 / 本地工具全部报错

10.3 切换工作区后工具报「请重启 MCP 进程」

10.4 表结构工具连接失败

10.5 项目识别为 unknown 或框架冲突

10.6 generate_code 返回 401

10.7 run_check 失败

10.8 修改配置后没有生效

11. 与 CLI 和 AI Studio 的区别

12. 推荐实践