Content
# egovframe-scaffold-mcp
[](https://github.com/EricSeokgon/egovframe-scaffold-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/egovframe-scaffold-mcp)
eGovFrame Project Scaffolding **MCP(Model Context Protocol) Server** — PoC
> [eGovFramework/egovframe-common-components#1120](https://github.com/eGovFramework/egovframe-common-components/issues/1120) Proof of Concept implementation.
> [#628](https://github.com/eGovFramework/egovframe-common-components/issues/628) (eGovFrame MCP Server proposal) has been materialized as a single "project generation" feature.
Claude, VS Code(Copilot), Cursor, and other AI tools that support MCP can **immediately generate** eGovFrame project skeletons during conversations. Start with official templates without installing eGovFrame IDE.
## Tool List
| Tool | Description |
|---|---|
| `create_egovframe_project` | Create a new project with official templates, applying projectName(artifactId), groupId, and DB type |
| `list_egovframe_templates` | List available official templates |
| `list_egovframe_components` | Selectable common component catalog (automatic repository scan generation, 68 types) |
| `add_egovframe_components` | Assemble common components - dependent source, mapper, and JSP copying, **component-specific DDL and DML generation** (`database`), with conflict prevention, `dryRun` preview |
| `search_egovframe_components` | Search components by keyword (id, name, description, top 10 results) |
| `remove_egovframe_components` | Remove components based on installation manifest - protect dependent components, `dryRun` preview |
| `validate_egovframe_project` | Diagnose project integrity - file existence, DbType ↔ DB script matching |
| `get_egovframe_guide` | Retrieve official guide documents for components (egovframe-docs, 45 types mapped) |
### create_egovframe_project Parameters
- `projectName` — Project name (artifactId). lowercase, numbers, and hyphens (e.g., `my-egov-app`)
- `groupId` — Java groupId (e.g., `egovframework.example`)
- `database` — `hsql` (default) | `mysql` | `oracle` | `altibase` | `tibero` (template `Globals.DbType` supported values)
- `template` — `simple-backend` (default, Spring Boot REST) | `simple-react`
- `outputDir` — Top-level directory for generation
- `ref` — (optional) Branch/tag to download. If not specified, use the template's default branch (e.g., `main`, `v4.3.0`)
- `dryRun` — (optional, default `false`) If `true`, preview file count and applied settings without writing to disk
Operation: Official template zip download → unzip (zip-slip prevention) → apply `pom.xml` groupId/artifactId/name (maintaining parent POM coordinates) → set `Globals.DbType` in `application.properties`, and set `name` in `package.json` for frontend templates. Refuse if the target directory already exists. A 30-second timeout is applied to downloads to prevent infinite waiting.
## Installation and Usage
[Deployed on npm](https://www.npmjs.com/package/egovframe-scaffold-mcp), can be executed directly without installation:
```json
{
"mcpServers": {
"egovframe-scaffold": {
"command": "npx",
"args": ["-y", "egovframe-scaffold-mcp"]
}
}
}
```
To build from source:
```bash
npm install
npm run build
```
Example settings for Claude Desktop / Claude Code (`mcpServers`):
```json
{
"mcpServers": {
"egovframe-scaffold": {
"command": "node",
"args": ["/absolute/path/to/egovframe-scaffold-mcp/dist/index.js"]
}
}
}
```
Execute without building (after local cloning):
```json
{
"mcpServers": {
"egovframe-scaffold": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/egovframe-scaffold-mcp/src/index.ts"]
}
}
}
```
Usage example (in AI tools):
> "Create a `my-egov-app` project with eGovFrame in `~/work`. The groupId is `egovframework.example`, and the DB is mysql."
## Verification
- Function level: Actual template (~296 files) generation, pom coordinates and DbType application, duplicate generation prevention, and `dryRun` preview confirmation (`npm run smoke`)
- Catalog level: Integrity (duplicate id, dependency existence), topological sorting, cycle detection, and preview verification (`npm run test:catalog`, no network required)
- Assembly level: Actual common component repository assembly, file copying, DB script, and conflict prevention verification (`npm run test:components`)
- Lifecycle level: Installation manifest recording, duplicate installation prevention, dependent component removal protection, removal, and verification operations (`npm run test:components`)
- Protocol level: MCP initialize/tools/list handshake and `ref` and `dryRun` parameter exposure confirmation
## PoC Scope and Limitations (Known Constraints)
- Java package structure changes (groupId-based source directory movement) are not supported — IDE rename refactoring recommended
- Common component selection and assembly (253 types) is a roadmap item — currently, only official template unit generation
- Network access to GitHub (codeload.github.com) required
## Roadmap (Proposal)
1. Common component selection and installation — **M3 completed (v0.4.0)**: Automatic catalog generation based on repository scanning (`npm run generate:catalog`, 68 types) + assembly pipeline. Remaining items: component-specific table DDL, name and dependency curation expansion (`catalog/overrides.json` contribution welcome) (Design: [docs/design-components-parameter.md](docs/design-components-parameter.md))
2. Execution environment boilerplate (e.g., egovframe-msa) template addition
3. Subsequent tooling (e.g., `validate_egovframe_config`)
4. Official repository incorporation into eGovFramework organization after verification
## Change History
- **0.7.0** — `get_egovframe_guide`: Retrieve official guide documents (egovframe-docs) by component id. Automatic document mapping generation (`--docs`, 45 types) added. Korean name curation expanded from 12 to 27 types.
- **0.6.0** — Component-specific table DDL (M4): Automatic extraction of referenced tables based on catalog mappers (48/68 types), and generation of corresponding component syntax only when `database` is specified, in `ddl|dml/<componentid>.sql` (fallback to integrated script for components without tables). Component-specific script attribution to manifest (cleanup during removal).
- **0.5.0** — Completed assembly lifecycle: `search_egovframe_components` (keyword search), installation manifest (`.egovframe-components.json`) recording, `remove_egovframe_components` (dependency protection, `dryRun`), `validate_egovframe_project` (file integrity and DbType ↔ DDL matching diagnosis), and duplicate installation prevention.
- **0.4.0** — Common component selection and installation M3: Automatic catalog generation through repository structure scanning (`scripts/generate-catalog.mjs`), coverage expanded from 3 to 68 types (2-stage package-level, cmm sub-integration). Name, description, and dependency curation using `catalog/overrides.json`.
- **0.3.0** — Common component selection and installation M2: Actual assembly implementation (`add_egovframe_components`) with dependency-inclusive file copying, pre-conflict checks, and atomic rejection, zip-slip prevention, and DDL/DML copying when `database` is specified.
- **0.2.2** — Common component selection and installation M1: Component catalog (`catalog/components.json`, 3 representative types), `list_egovframe_components` and `add_egovframe_components` (with `dryRun` preview) tooling added, and offline catalog testing.
- **0.2.1** — Frontend (simple-react) template `package.json` name application (project name). Backend maintains existing pom and DbType.
- **0.2.0** — Download timeout (30 seconds), `ref` (branch/tag) parameter, and `dryRun` preview mode added. `list_egovframe_templates` returns supported DB lists.
- **0.1.0** — Initial PoC: `create_egovframe_project`, `list_egovframe_templates`.
## License
Apache License 2.0
