内容
# egovframe-scaffold-mcp
[](https://github.com/EricSeokgon/egovframe-scaffold-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/egovframe-scaffold-mcp)
电子政务标准框架（eGovFrame）项目脚手架 **MCP(Model Context Protocol) 服务器** — 验证概念
> [eGovFramework/egovframe-common-components#1120](https://github.com/eGovFramework/egovframe-common-components/issues/1120) 提案的概念验证（Proof of Concept）实现。
> [#628](https://github.com/eGovFramework/egovframe-common-components/issues/628)（eGovFrame MCP Server 提案）具体化为“项目生成”单一功能。
Claude, VS Code(Copilot), Cursor 等支持 MCP 的 AI 工具中 **对话中立即** 生成标准框架项目骨架。无需安装 eGovFrame IDE，直接基于官方模板开始。
## 提供工具
| 工具 | 说明 |
|---|---|
| `create_egovframe_project` | 下载官方模板，应用 projectName（artifactId）、groupId、DB 类型，生成新项目 |
| `list_egovframe_templates` | 列出可用的官方模板列表 |
| `list_egovframe_components` | 选择安装的通用组件目录（存储库扫描自动生成，68种） |
| `add_egovframe_components` | 选择组件组装 — 依赖关系包含源代码、映射器、JSP 复制，**组件별 선별 DDL·DML 生成**（`database`），冲突时全部拒绝，`dryRun` 预览 |
| `search_egovframe_components` | 按关键词搜索组件（id·名称·说明，分数顺序前10项） |
| `remove_egovframe_components` | 基于安装清单的组件删除 — 保护依赖组件，`dryRun` 预览 |
| `validate_egovframe_project` | 组装项目完整性诊断 — 文件存在·DbType↔DB 脚本匹配 |
| `get_egovframe_guide` | 查询组件的官方指南文档（egovframe-docs，45种映射） |
### create_egovframe_project 参数
- `projectName` — 项目名称（artifactId）。小写字母·数字·连字符（例：`my-egov-app`）
- `groupId` — Java groupId（例：`egovframework.example`）
- `database` — `hsql`（默认）| `mysql` | `oracle` | `altibase` | `tibero`（模板 `Globals.DbType` 支持值）
- `template` — `simple-backend`（默认，Spring Boot REST）| `simple-react`
- `outputDir` — 生成位置上级目录
- `ref` — （可选）下载的分支/标签。未指定时，模板默认分支。例：`main`，`v4.3.0`
- `dryRun` — （可选，默认 `false`）`true` 则不写入磁盘，仅预览生成文件数·适用设置
动作：下载官方模板 zip → 解压（防止 zip-slip）→ `pom.xml` 应用 groupId/artifactId/name（保持父 POM 坐标）→ `application.properties` 设置 `Globals.DbType`，前端模板设置 `package.json` 的 `name`。如果已有目录，则拒绝。下载有 30 秒超时，如果无响应，则不无限等待。可以使用 `dryRun` 安全预览。
## 安装·使用
[npm 上发布](https://www.npmjs.com/package/egovframe-scaffold-mcp)，无需安装，直接运行：
```json
{
"mcpServers": {
"egovframe-scaffold": {
"command": "npx",
"args": ["-y", "egovframe-scaffold-mcp"]
}
}
}
```
从源码直接构建：
```bash
npm install
npm run build
```
Claude Desktop / Claude Code 设置示例（`mcpServers`）：
```json
{
"mcpServers": {
"egovframe-scaffold": {
"command": "node",
"args": ["/绝对路径/egovframe-scaffold-mcp/dist/index.js"]
}
}
}
```
无需构建，直接运行（本地克隆后）：
```json
{
"mcpServers": {
"egovframe-scaffold": {
"command": "npx",
"args": ["-y", "tsx", "/绝对路径/egovframe-scaffold-mcp/src/index.ts"]
}
}
}
```
使用示例（在 AI 工具中）：
> "用标准框架为 `my-egov-app` 项目生成到 `~/work`。groupId 为 `egovframework.example`，DB 为 mysql。"
## 验证
- 函数级别：实际模板（约 296 文件）生成，pom 坐标·DbType 应用，重复生成拒绝，`dryRun` 预览（无记录）确认（`npm run smoke`）
- 目录级别：完整性（重复 id·依赖存在）·拓扑排序·循环检测·预览验证（`npm run test:catalog`，无需网络）
- 组装级别：实际通用组件存储库为 bbs+login(+cmm) 组装，文件复制·DB 脚本·冲突全部拒绝验证（`npm run test:components`）
- 生命周期级别：安装清单记录，重复安装拒绝，依赖组件删除保护，删除·验证动作（`npm run test:components`）
- 协议级别：MCP 初始化 / 工具/列表握手及 `ref`·`dryRun` 参数暴露确认
## 验证范围与限制（已知约束）
- Java 包结构变更（根据 groupId 匹配源码目录移动）不支持 — 建议 IDE 重命名重构
- 通用组件选择组装（253 种中选择安装）是路线图项目 — 目前仅支持官方模板单位生成
- 需要通过网络访问 GitHub（codeload.github.com）
## 路线图（提案）
1. 通用组件选择安装 — **M3 完成（v0.4.0）**：存储库扫描基目录录自动生成（`npm run generate:catalog`，68 种）+ 组装管道。剩余项目：组件별 선별 DDL，名称·依赖性精选扩大（`catalog/overrides.json` 贡献欢迎）（设计：[docs/design-components-parameter.md](docs/design-components-parameter.md)）
2. 执行环境 boilerplate（egovframe-msa 等）模板添加
3. 验证工具（`validate_egovframe_config`）等后续工具
4. 验证后 eGovFramework 组织官方存储库纳入提案
## 变更历史
- **0.7.0** — `get_egovframe_guide`：通过组件 id 查询标准框架官方指南文档（egovframe-docs）。目录中文档映射自动生成（`--docs`，47 种支配 패키지 참조 기준）追加。韩文名称精选 12→27 种。
- **0.6.0** — 组件별 선별 DDL（M4）：目录中映射器基准参照表自动提取（48/68 种），`database` 指定时集成脚本中对应组件语句만 추출해 `ddl|dml/<组件id>.sql` 生成（表未组件综合 fallback），清单中组件脚本归属（删除时一并整理）。
- **0.5.0** — 组装生命周期完成：`search_egovframe_components`（关键词搜索），安装清单（`.egovframe-components.json`）记录，`remove_egovframe_components`（依赖保护·dryRun），`validate_egovframe_project`（文件完整性·DbType↔DDL 匹配诊断），重复安装拒绝。
- **0.4.0** — 通用组件选择安装 M3：存储库结构扫描生成目录（`scripts/generate-catalog.mjs`），覆盖率 3 种 → 68 种（2 级 패키지 单位，cmm 下级集成）。名称·说明·依赖性通过 `catalog/overrides.json` 精选（基本依赖性休闲主义：cmm）。
- **0.3.0** — 通用组件选择安装 M2：`add_egovframe_components` 实际组装实现（依赖关系包含文件复制，全部冲突前检查后原子拒绝，zip-slip 防御，`database` 指定时 DDL·DML 复制，zip 进程缓存）。综合测试（`test:components`）追加。
- **0.2.2** — 通用组件选择安装 M1：组件目录（`catalog/components.json`，代表 3 种 cmm·bbs·login），`list_egovframe_components`·`add_egovframe_components`（dryRun 预览）工具追加，目录离线测试追加。
- **0.2.1** — 前端（simple-react）模板的 `package.json` `name` 应用项目名称（后端依旧 pom·DbType）。
- **0.2.0** — 下载超时（30 秒），`ref`（分支/标签）参数，`dryRun` 预览模式追加。`list_egovframe_templates` 支持 DB 列表一并返回。
- **0.1.0** — 初次验证概念：`create_egovframe_project`，`list_egovframe_templates`。
## 许可证
Apache License 2.0
