MCP 服务

用 AI 做业务模块时，除了项目自带的 rules 与 .ai/ 规范，还可以接入两个 MCP 服务，分别提供源码事实与运行时事实：

MCP	包名	职责
官方 MCP	elysia-admin-mcp	组件 props、Hook 签名、后端方法、Drizzle 表结构、模块权限码
数据库 MCP	pg-mcp-server	只读查询 dict / menu / 权限等运行时数据

两者互补，不重复：官方 MCP 不连数据库；数据库 MCP 不扫源码。规范与流程仍由 .ai/、AGENTS.md 负责。

一、官方 MCP（elysia-admin-mcp）

Elysia Admin MCP 是项目的源码活索引 MCP 服务器。它实时扫描前端与后端源码（默认 admin/ 与 server/，可通过环境变量自定义），把组件 props、后端方法签名、Drizzle 表结构等必须与代码同步的事实变成可查询接口。

定位

• 镜头而非仓库：只索引源码事实，约定/流程/文档的家仍在 .ai/ 与 AGENTS.md
• 只读安全：不连业务数据库、不执行 SQL、不写文件
• 落盘缓存：源码未变时秒级启动（mtime 指纹失效）
• 中文检索：内置高频后端方法中文别名，搜「分页」「事务」「软删」直接命中

工具清单

分 3 组，共 14 个工具。每个工具返回结果均带 path，便于 AI 跳转核实。

A. 统一检索

工具	用途
search_asset	全局模糊搜索组件/Hook/工具/后端方法/表/模块，不确定「有没有现成的 X」时的第一站

B. 前端源码索引

工具	用途
list_components	列出 Art 组件清单（可按分类过滤）
get_component	获取组件 props/emits/slots + 最小用法示例
get_hook	获取 useTable/useAuth 等 Hook 的参数与返回值
get_util	获取 request/validator 等工具导出成员
list_api_types	列出 Api.* 类型命名空间
get_api_type	获取某命名空间的 ListItem/List/SearchParams 类型

C. 后端源码索引

工具	用途
list_backend_methods	按 core/shared/infrastructure 列出方法（重点方法优先）
get_backend_method	获取 FindPage/WithTransaction 等方法签名
get_infra_capability	获取 payment/storage/queue/cron/mail 入口用法
list_modules	列出模块及权限码数量
get_module	获取模块路由、权限码与文件构成
list_schemas	列出 Drizzle 表名
get_schema	获取表字段、类型、主键与软删标记

客户端接入

所有客户端均需设置环境变量 ELYSIA_ADMIN_ROOT 指向你的 Elysia Admin 项目根目录。若前端/后端目录名非 admin/ / server/，可额外设置 ELYSIA_ADMIN_DIR / ELYSIA_SERVER_DIR。

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "elysia-admin": {
      "command": "npx",
      "args": ["-y", "elysia-admin-mcp"],
      "env": {
        "ELYSIA_ADMIN_ROOT": "D:/path/to/elysia-admin",
        "ELYSIA_ADMIN_DIR": "",
        "ELYSIA_SERVER_DIR": ""
      }
    }
  }
}

ELYSIA_ADMIN_DIR / ELYSIA_SERVER_DIR 留空即使用默认 admin/ / server/。填相对名（如 "webapp"）会拼到 ELYSIA_ADMIN_ROOT 下；填绝对路径则直接使用（可在 root 之外）。

本地开发时可将 command 改为 node、args 指向本仓库 dist/index.js。

Claude Code

claude mcp add elysia-admin -- npx -y elysia-admin-mcp
# 并在环境或配置中设置 ELYSIA_ADMIN_ROOT（可选 ELYSIA_ADMIN_DIR / ELYSIA_SERVER_DIR）

Codex

~/.codex/config.toml：

[mcp_servers.elysia-admin]
command = "npx"
args = ["-y", "elysia-admin-mcp"]

[mcp_servers.elysia-admin.env]
ELYSIA_ADMIN_ROOT = "D:/path/to/elysia-admin"
# ELYSIA_ADMIN_DIR = "webapp"                          # 可选，相对 root
# ELYSIA_SERVER_DIR = "D:/other/repo/backend"          # 可选，绝对路径

Qoder / Kiro / Trae

在各自的 MCP 配置中添加 stdio 服务，command / args / env 字段与 Cursor 一致。

环境变量

变量	说明
ELYSIA_ADMIN_ROOT	Elysia Admin 项目根目录。未设置时从 cwd 向上自动查找（需含 admin/ 与 server/）；若两个自定义目录均为绝对路径，则 root 回退为 cwd
ELYSIA_ADMIN_DIR	前端代码目录（可选）。为空 → {root}/admin；相对名 → {root}/{name}；绝对路径 → 直接使用
ELYSIA_SERVER_DIR	后端代码目录（可选）。为空 → {root}/server；相对名 → {root}/{name}；绝对路径 → 直接使用
ELYSIA_MCP_NO_CACHE	设为 1 强制重建索引，忽略缓存（等价于 --no-cache）

二、数据库 MCP（pg-mcp-server）

pg-mcp-server 是 PostgreSQL 的 MCP 服务器，让 AI 通过受控接口只读查询数据库，用于核对 dict、menu、权限等运行时数据。

Cursor 配置

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["--yes", "pg-mcp-server", "--transport", "stdio"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres"
      }
    }
  }
}

请将 DATABASE_URL 替换为你本机或测试环境的 PostgreSQL 连接串。

配置项

变量	说明
DATABASE_URL	PostgreSQL 连接串（必填）
DANGEROUSLY_ALLOW_WRITE_OPS	启用写入（默认 false，建议保持只读）
DEBUG	启用调试日志（默认 false）
PG_SSL_ROOT_CERT	可选 TLS CA 证书路径（如云数据库）

工具与资源

工具

工具	用途
query	执行 SQL 查询，例如 { "sql": "SELECT * FROM system_menu LIMIT 10" }

资源

资源 URI	用途
postgres://tables	列出所有表
postgres://table/{schema}/{table}	获取表结构与示例数据

只读纪律

与项目 .ai/AI_MCP_SETUP.md 对齐：

事项	说明
查 dict / menu / 权限	优先 Postgres MCP 只读查询
禁止读备份	不要让 AI 读 server/database/sql/pg.sql（全库备份，可能与现库不一致）
禁止 MCP 代跑 SQL	handoff SQL（server/database/sql/{模块}-init.sql）仍由开发者手动执行
禁止 MCP 写入	不要用 MCP 做 DDL、迁移或业务写入；DANGEROUSLY_ALLOW_WRITE_OPS 保持 false
Schema 真相源	Drizzle schema 文件仍是表结构权威，MCP 用于核对运行时数据

只读用途示例：

• 核对表与列是否与 schema 文件一致
• 查询 system_dict_type / system_dict_data 获取业务字典
• 查询 system_menu 获取父菜单 menu_id、MAX(sort)、重复 permission
• 查询 system_role 用于 system_role_menu 插入

MCP 不可用时，AI 应声明「Postgres MCP 未连接」，并在 handoff SQL 中优先用 SELECT ... INTO / CTE 子查询，仍输出完整 SQL 文件。

三、推荐使用顺序

1. 源码事实（elysia-admin-mcp）—— 查组件、Hook、后端方法、表结构、权限码
2. 运行时事实（pg-mcp-server 只读）—— 查 dict、menu、角色权限行
3. 生成代码 —— 后端 handle.ts → 前端 views
4. 输出 SQL —— server/database/sql/{模块}-init.sql（仅生成文件）
5. 手动执行 —— 开发者在本机执行 handoff SQL

相关

• AI 开发指南 —— 提示词、脚手架与 AI 交付物
• 数据库操作 —— repository 与 QueryBuilder 用法
• 仓库内 .ai/AI_MCP_SETUP.md —— Agent 侧 MCP 纪律（英文）