egovframe-scaffold-mcp

Name: egovframe-scaffold-mcp
Author: EricSeokgon

ローカル

github.com開発ツール31 日前に更新

リポジトリ公式サイト

egovframe-scaffold-mcp について

egovframe-scaffold-mcpは、eGovFrameプロジェクトの作成、組み立て、移行、検査、デプロイを行うMCPサーバー兼コマンドラインツールです。開発者や納品チーム向けに、プロジェクトのひな形作成、5.xへの移行、サプライチェーンとセキュリティの検査をまとめて提供します。

主な機能

01Initializrテンプレートから作成
02コンポーネントの追加とCRUD生成
03旧プロジェクトを5.xへ移行
04依存関係、SBOM、セキュリティ検査
05デプロイとCIファイルの生成
06オフラインバンドルとdryRun

活用シーン

01新しいeGovFrameアプリの作成とビルド
023.xまたは4.xからの移行評価とリハーサル
03セキュリティとSBOMの納品レポート作成
04コンテナとCIの設定生成

MCP 対応

MCPサーバーは、eGovFrameプロジェクトの作成、移行、検証、納品チェック、デプロイ用のツール、リソース、プロンプトを公開します。同じパッケージは、MCPクライアントのないCI環境向けにコマンドラインツールも提供します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "ericseokgon-egovframe-scaffold": {
      "command": "npx",
      "args": [
        "-y",
        "egovframe-scaffold-mcp"
      ],
      "env": {
        "EGOVFRAME_ALLOWED_ROOTS": "<EGOVFRAME_ALLOWED_ROOTS>",
        "EGOVFRAME_LANG": "<EGOVFRAME_LANG>",
        "EGOVFRAME_CACHE_DIR": "<EGOVFRAME_CACHE_DIR>",
        "EGOVFRAME_OFFLINE_BUNDLE": "<EGOVFRAME_OFFLINE_BUNDLE>"
      }
    }
  }
}

起動コマンドnpx -y egovframe-scaffold-mcp

設定が必要な環境変数

EGOVFRAME_ALLOWED_ROOTSOptional. Path-separator-delimited list of directories the write tools may touch (see README '보안 설정').

EGOVFRAME_LANGOptional. 'en' exposes English tool descriptions in tools/list (responses stay Korean).

EGOVFRAME_CACHE_DIROptional. Cache directory for the blobless git mirror of official common-component tags used by reassemble (default ~/.cache/egovframe-scaffold-mcp).

EGOVFRAME_OFFLINE_BUNDLEOptional. Directory of an offline bundle made by prepare_egovframe_offline_bundle for air-gapped networks: downloads, OSV lookups and reassembly origin tags are served from it after sha256 checks.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmegovframe-scaffold-mcp1.8.0stdio

ツール

掲載時のツール一覧 · 1 日前に更新

このツールにパラメーターはありません。

詳細

翻訳後に原文が更新されています。最新の内容は原文をご確認ください。

egovframe-scaffold-mcp

English summary: README.en.md · 도구 설명을 영문으로 받으려면 EGOVFRAME_LANG=en

전자정부 표준프레임워크(eGovFrame) 프로젝트 스캐폴딩·조립·진단을 제공하는 MCP(Model Context Protocol) 서버 — 커뮤니티 PoC

eGovFramework/egovframe-common-components#1120 제안의 개념 증명(Proof of Concept) 구현입니다. #628(eGovFrame MCP Server 제안)을 "프로젝트 생성 → 컴포넌트 조립 → 진단·업그레이드" 수명주기로 구체화했습니다.

Claude, VS Code(Copilot), Cursor 등 MCP를 지원하는 AI 도구에서 대화 중 즉시 표준프레임워크 프로젝트를 만들고 공통컴포넌트·AI 계층을 조립할 수 있습니다. 기존 프로젝트 진단, 리포트, 안전한 upstream 재동기화도 지원합니다.

현재 v0.43.0은 **도구 32종(title·annotations·구조화 출력 11종) + CLI 명령 10종, 공식 템플릿 22종, 설정 템플릿 21종, 5.x 전환 규칙(RTE 18모듈·클래스 331종 + 공통컴포넌트 1,089종 근거)과 적용·검증·재조립·사본 리허설, 의존성 기준(공식 parent 관리 좌표 139종+계열 6종+Spring Boot BOM 1,473종+RTE 전이 58종)·해석된 의존성 트리·CycloneDX·SPDX SBOM 생성·점검(최소 요소·비교·VEX), GitHub·GitLab·Jenkins CI 공급망 게이트, 규칙·기준 drift 감시, 폐쇄망 오프라인 번들, 네트워크 진단·AGENTS.md 생성, 공통컴포넌트 카탈로그 190항목(리프 176종+그룹 14종, v5.0.7)**을 제공합니다.

진행 현황 (2026-10-11)

ソース基準：v0.43.0（package.json）、ツール32種＋CLIコマンド10種・公式テンプレート22種・設定テンプレート21種・カタログ190項目（共通コンポーネント v5.0.7）。
安全性のベースライン完了：PR #7～#16を反映し、provenance・strict assertion・safe removeと、プロジェクト生成／レシピ／直接組み立て／AI 組み立て／アップグレードの transaction を備えました。
v0.22.0 追加：EGOVFRAME_ALLOWED_ROOTSを19個のツールのエントリーポイントに適用し、..・symlink/junction による逸脱を防止します。失敗時は rollback の結果を構造化して返します。PR #16は7ファイル（+340/−31）で、ローカルの16種スイートすべてに合格した後、マージされました。
v0.23.0 追加：build_egovframe_project — 生成したプロジェクトを実際にビルド（maven/gradle・mvnw/gradlew を自動検出）し、コンパイル・テストエラーをファイル／行単位で構造化して、生成→検証のループを完成させます。タイムアウト・ログ上限・許可 root・dryRun を含みます。PR #18は4ファイル（+458/−3）で、オフラインでの40件のアサーションと実際の spawn 経路を検証しました。
v0.24.0 追加：公式テンプレートのカバレッジを7種から10種に拡大（msa-common-components・mobile-device-api・ai-rag、すべてマルチプロジェクト）。PR #19。
v0.25.0 追加：test_egovframe_project — テストを実行し、ビルドツールが出力する JUnit XML レポート（surefire・gradle）を読み取って、スイート・ケース単位で結果を構造化します。失敗ケースのメッセージ・例外型・テストファイル／行、testFilter（クラス／メソッドパターン）、前回実行時のレポートの除外、終了コードが0でもレポートに失敗があれば失敗と判定する機能を備えます。オフラインでの54件のアサーション（npm run test:test）。
v0.25.2 追加：セキュリティ・安定性を強化 — generate_egovframe_ci の jdk 入力を検証（生成 YAML への注入を防止）、ビルド・テストがタイムアウトした場合にプロセスツリーを終了（ラッパーが起動した JVM のためにタイムアウトしても呼び出しが終了しなかった問題を解決）、MCP handshake のサーバーバージョンを package.json と一致させ、依存関係を更新して npm audit の検出件数を0件にしました。
v0.25.3 追加：Linux・macOS で npx egovframe-scaffold-mcp（bin symlink 経由）を実行すると、サーバーが起動せず終了していた問題を修正し、CI を ubuntu・windows × Node 18・20・22 のマトリックスに拡張しました。
v0.26.0 追加：sync_egovframe_templates ＋ catalog/templates.json — これまで Initializr（プロジェクト22種の zip カタログ）・MCP（TEMPLATES 10種のリポジトリ取得）・Development（wizards.xml 設定ウィザード）に分散していた「公式プロジェクトには何があるか」を、単一のスキーマに統合しました。マッピングは catalog/template-mapping.json でキュレーションし（自動推論なし）、上流との追加・削除・変更や、MCP のカバレッジの差（現在は22種中9種に対応）をツールで確認できます。オフラインでの148件のアサーション（npm run test:template-catalog）。
v0.27.0 追加：公式テンプレートのカバレッジを10種から22種に拡大（Initializr の22種を基準に、対応数を9種から21種に拡大）。単独のリポジトリがないバッチ6種・空の骨組み（web・boot-web）・モバイル2種・MSA ポータル2種は、Initializr の zip（Git LFS）から取得し、commit と sha256・サイズを固定してダウンロードしたバイト列を検証します。sync_egovframe_templates は zip のフィンガープリントの上流での変更も報告します（設計：docs/design-initializr-zip-templates.md）。
v0.28.0 追加：generate_egovframe_config — 公式 Initializr 設定テンプレート21種（datasource・transaction・cache・logging・scheduling・idGeneration・property）をパッケージに同梱し、オフラインで Spring 設定ファイルを生成します。xml・javaConfig・yaml・properties 形式、Initializr フォームと同じフィールド名・既定値に対応し、既存ファイルを保護します。リソース egovframe://catalog/config-templates からフィールド・既定値・選択肢を確認でき、sync_egovframe_templates は同梱テンプレートの上流での変更を報告します（設計：docs/design-config-generation.md）。
v0.29.0 追加：migrate_egovframe_project 第1段階 — 3.x/4.x プロジェクトを5.x（Jakarta EE 9+、Spring 6、Java 17）基準でスキャンし、RTE Maven 座標・パッケージ・削除／移動クラス・javax→jakarta・web.xml スキーマ・削除された egov-* XML 名前空間・置き換えが必要なライブラリをファイル／行単位で報告します（読み取り専用、auto/manual を区別）。ルールは egovframe-runtime タグ（v3.10.0・v4.3.0-Final・v5.0.2-Final）のソースツリー比較から作成した catalog/migration-rules.json に格納し、移行先の座標61件が実際に Maven リポジトリに存在することを CI で確認します。公式5.xテンプレート2種で項目は0件です（設計：docs/design-migration.md）。
v0.30.0 追加：migrate_egovframe_project 第2段階（apply=true）— 診断の auto 項目を1つの transaction として実際に置換します（既定では dryRun、元ファイルを migration-backup/ に保存、migration-plan.json を作成し、失敗時は復元）。3.10 の座標・javax のフィクスチャを適用した後、JDK 17 の mvn compile が通ることを CI で確認します。check_egovframe_dependencies — 公式5.x parent 2種から抽出した基準（管理対象の座標139種＋BOM 系列7種、catalog/dependency-baseline.json）と依存関係を照合し、基準を満たす／下回る／parent 管理／移行対象／置き換えが必要／基準なしに分類します。また、セキュリティ設定（sec.security・CSRF・XSS フィルター・セキュリティヘッダー・HTTPS リポジトリ）の有無を根拠とともに報告します。既定ではオフラインで動作し、offline=false の場合は OSV の脆弱性を照会します（設計：docs/design-dependency-check.md）。
v0.31.0 追加：運用性を向上 — diagnose_egovframe_network（ツールが使用する7種のホストに DNS・HEAD プローブを実行し、失敗の種類を分類。HTTPS_PROXY+NODE_USE_ENV_PROXY・IPv4 優先・社内 CA の対処法を bash/cmd/PowerShell コマンドで提示）、すべてのダウンロード失敗メッセージに同じ対処法を1行追加、generate_agents_md（診断結果から AI コーディングツール用の AGENTS.md を生成、ko/en）、英語版 README（README.en.md）と EGOVFRAME_LANG=en による英語のツール説明、MCP Registry メタデータ（server.json・mcpName）。企画した3つのバージョン（v0.29–v0.31）がすべて完了しました。
v0.32.0 追加：MCP プロトコルを最新化 — 27種のツールを registerTool に切り替え、title（ko/en）と annotations（readOnlyHint 14種・destructiveHint 4種・idempotentHint・openWorldHint）を tools/list に公開します。format=json を提供する5種（diagnose_egovframe_project・validate_egovframe_project・migrate_egovframe_project・check_egovframe_dependencies・diagnose_egovframe_network）は outputSchema と structuredContent を返します（従来の text も維持）。テストの移植性ガード（scripts/check-test-portability.mjs、ゲートを含む）とプラットフォーム注入のアサーションにより、Windows 固有の失敗の再発を防止します。
v0.43.0 追加：CI・提出形式を多様化 — generate_egovframe_ci(platform="gitlab"|"jenkins") が GitHub Actions と同じビルド・サプライチェーンゲートを .gitlab-ci.yml（JUnit・CycloneDX レポート）・Jenkinsfile（Declarative、Linux sh・Windows bat 共用）として作成し、ゲートにSBOM の最小要素チェック（sbom-check --fail-on minimum）を3つのプラットフォームすべてに追加しました。社内 npm レジストリ（npmRegistry）・オフラインバンドルのパス（offlineBundle）は環境変数で渡され、サプライヤー情報がない場合はゲートが失敗することを事前に知らせます。SBOM は SPDX 2.3 JSON 形式でも出力します — generate_egovframe_sbom(bomFormat="spdx-json") はパッケージ・DEPENDS_ON 関係（依存関係がない場合は NONE）・purl・サプライヤー・creators・created・チェックサム・宣言されたライセンス・OSV 推奨事項・基準判定（annotations）を含めます。check_egovframe_sbom は形式を自動判定し、SPDX も同じ最小要素7種・再判定・比較でチェックします（VEX は CycloneDX のみ）。公式 web テンプレートを実際に Maven で作成した SBOM は、SPDX に変換しても component 67・最小要素の判定（要素ごとの充足数も含む）が同じで、SPDX ↔ CycloneDX の比較差分は0件です。また、生成された .gitlab-ci.yml は GitLab の公式 CI スキーマに、SPDX 出力は公式 spdx-spec v2.3 スキーマに合格します。ツール数は32種のままです。
v0.42.0 追加：閉域網（ネットワーク分離）での運用 — 新しいツール prepare_egovframe_offline_bundle（32番目）が、インターネット接続された PC で OSV Maven 脆弱性の全ダンプ（約10MB、7,190件）・固定された共通コンポーネントのアーカイブ（sha256 検証）・Initializr zip テンプレート（固定フィンガープリント）・再組み立て用の公式共通コンポーネントタグ22個のミラー（約37MB）を1つのディレクトリにまとめ、bundle-manifest.json（ファイルごとの sha256・サイズ・取得元 URL・取得時刻）を作成します。閉域網の PC で EGOVFRAME_OFFLINE_BUNDLE のみを指定すると、ダウンロードではバンドル内のファイルをフィンガープリントで検証してから使用し（改ざんは拒否）、offline=false の OSV 照会はローカルダンプで判定します（スナップショットの基準日を表示し、30日を超えると警告）。再組み立てではバンドルのミラーを使用します。同じ日に取得したダンプを使ったローカル判定は、オンライン OSV とクエリ73/73・ID 134/134 が一致しました。また、ネットワークを遮断した状態で、プロジェクト生成・共通コンポーネントの組み立て・再組み立てプレビュー・SBOM の再チェックがバンドルだけで完了すること（ネットワーク試行0件）を CI で確認します。CLI の bundle、ネットワーク診断のオフラインバンドル対処法。
v0.41.0 追加：移行リハーサル — 新しいツール rehearse_egovframe_migration（31番目）は、プロジェクトを変更せずにコピー上で共通コンポーネントの再組み立て → 移行の自動項目の適用 → コンパイル → pom を公式共通コンポーネント v5.0.7 基準に更新 → 再コンパイルまで実行し、「自動化の後に人が修正する必要がある項目は実際に何件か」を測定します（javac のエラーは上限の100件を設けずすべてカウントし、実行前後のフィンガープリントで元ファイルが変更されていないことを確認）。公式共通コンポーネント v4.3.2 の全ツリー（6,523ファイル）では、自動化後のコンパイルエラー 6,003件（CI・JDK 17、JDK 21 では6,335件）のうち、4件を除くすべてが不足パッケージとその連鎖（pom の依存関係、それが原因で Lombok が動作しなかったことによる getter など）でした。pom を更新すると、残るのは 1件（GPKI ベンダー jar の javax 参照）のみです — CI ではこの値を期待値として固定します。実測中に見つかった2つの不具合も修正しました。再組み立ては移行の適用より先に実行する必要があります。そうすることで元のタグが特定されます（逆の順序では4.3.2 が v5.0.1 と誤認されます）。また、4.x の org.egovframe.rte 座標が5.xに分類される問題と、Maven の警告・fork 形式がコンパイルエラーとして誤って読み取られる問題も修正しました。評価書の第6節には最新のリハーサル実測結果も掲載しています。
v0.40.0 追加：SBOM の運用 — 新しいツール check_egovframe_sbom（30番目）が、作成済みの CycloneDX SBOM を提出物としてチェックします。（1）最小要素7種（サプライヤー・コンポーネント名・バージョン・一意の識別子・依存関係・作成者・生成日時。NTIA 最小要素＝国内のソフトウェアサプライチェーンセキュリティガイドラインの主要構成要素）を component ごとに数え、「提出可能／補完が必要」を判定します。（2）ビルドツールを使わず、purl のみで基準と OSV を再判定し、生成後に変わった判定や新たに判明した脆弱性を検出します。（3）以前の SBOM と比較し、追加・削除・バージョン・判定・脆弱性の差分を確認します。（4）vex=true の場合は CycloneDX VEX のドラフトを出力します（新しい脆弱性は in_triage とし、人が記入した判定は保持します）。generate_egovframe_sbom は supplier・author オプション（既定値は pom の <organization>）とサプライヤー表を使い、生成時に最小要素を補います。公式 web テンプレートの SBOM はサプライヤー（主 component を含む18種）・作成者が空欄で「補完が必要」ですが、オプションを指定して再作成すると「提出可能」になります。SBOM・VEX はいずれも CycloneDX 1.6 の公式スキーマに合格します。CLI の sbom-check、評価書の第5節に最小要素・VEX の状態を記載します。企画した3つのバージョン（v0.38–v0.40）がすべて完了しました。
v0.39.0 追加：CLI モードと CI サプライチェーンゲート — npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate|diagnose|network> は、AI クライアントなしで同じ分析を実行して終了します（引数を指定しない場合は従来の stdio サーバー）。--json は MCP の structuredContent と同じオブジェクトを返し、--fail-on supplyChain:C・vulnerabilities・manual>20 などの基準を超えると終了コード2でパイプラインを停止します。generate_egovframe_ci(supplyChain=true) は、SBOM 生成 → 評価書（PR の概要に評価を記載）→ 成果物の順につなぐゲート job を作成します（生成結果は CI で actionlint による検査を実行）。MCP SDK を1.32.1（プロトコル 2025-11-25）に更新しました。
v0.38.0 追加：共通コンポーネントの再組み立てを実行 — 新しいツール reassemble_egovframe_components（29番目）は、3.x/4.x プロジェクトにコピーされた共通コンポーネントのソースの元タグを、公式リポジトリのタグと git blob id で照合して特定し（ファイルの内容はダウンロードしません）、元・現在・目標の3者を基にファイルごとに判定した後、v5.0.7 で再組み立てします。ユーザーによる変更は元との差分を示す unified diff パッチとして保持し、作業一覧を返します。マニフェストを残すため、その後の upgrade・validate・remove でもそのまま適用できます。共通コンポーネントカタログ・移行ルールの対応表を、上流の新しいタグ v5.0.7（2026-10-06）に更新しました。公式 v3.10.0 ツリーの cmm・bbs を修正したフィクスチャで、元の v3.10.0 の特定（99%）、780ファイルが v5.0.7 の tree と一致、validate の不足0件・upgrade の変更0件を CI で確認します。
v0.37.0 追加：移行準備度の評価書＋回帰コーパス — generate_egovframe_report(sections=["assessment"]) は、診断・移行診断・依存関係・セキュリティ設定・SBOM チェックを一括で実行し、6つの節（概要・移行範囲・依存関係の対応一覧・セキュリティ・SBOM・評価と根拠）からなる評価書を作成します。移行難易度とサプライチェーンの状態をそれぞれ A–D で評価し、要因・区分・スコアの計算式をレポートにそのまま記載するため、人が再計算できます（テストで実際に再計算します）。format=json（outputSchema）・outputPath（新規ファイルのみ、transaction）に対応します。回帰コーパス test:migrate-corpus は、公式共通コンポーネント v3.10.0・v4.3.2 の部分ツリー（コミットを固定、sparse clone は約3秒）に対して診断・dryRun 適用・依存関係チェック・評価書作成を実行し、catalog/migration-corpus.json の期待値との差が ±1% 以内であることを CI でアサーションします — 4.x→5.x の経路を実資産で初めて確認しました。両世代とも、要確認クラスは0件・基準なしは1件（xerces）です。リリースワークフローは停止していたリリースを再開します（npm の gitHead コミットにタグを付け、反映を10分待ってから警告のみ）。企画した3つのバージョン（v0.35–v0.37）がすべて完了しました（設計：docs/design-assessment-report.md）。
v0.36.0 追加：解決済み依存関係ツリー＋SBOM — check_egovframe_dependencies(resolve=true) が Maven（dependency:tree）・Gradle（dependencies）で推移的依存関係まで解決し、基準・OSV と照合します（項目ごとに origin・ツリーのパス via を記録し、宣言とは異なるバージョンに解決された場合は differs を示します）。公式 egovframe-web テンプレートは宣言上19件・対応が必要な項目は0件ですが、解決後は65 artifact のうち基準未満が11件・OSV 推奨事項が24件あることが分かります。新しいツール generate_egovframe_sbom（28番目）は、ビルドファイルを変更せずに CycloneDX 1.6 JSON を生成し（Maven は cyclonedx-maven-plugin でハッシュ・ライセンスを含め、Gradle は解決済みツリーから構成）、各 component に基準判定（egovframe:status·basis·baseline）を記録します。offline=false の場合は OSV の結果を vulnerabilities[] に含めます — 2027年から段階的に進められる公共機関の SBOM 登録・提出に使用できる形式です。
v0.35.0 追加：リリースを自動化 — main で CI が成功すると、release.yml が4つの条件（server.json のバージョン一致・変更履歴の項目・タグなし・npm 未公開）を確認し、npm（OIDC trusted publishing、provenance は自動）→そのコミットにタグ付け→GitHub Release（変更履歴から抽出）→MCP Registry の順に公開します。人が行うのは PR のマージだけです。ゲートに test:release（判定関数・リリースノート・npm pack の内容・サイズ上限）と、server.json の説明の文字数を100字以内に制限するチェック（レジストリ検証条件 — 実際の mcp-publisher validate で発見した不具合を修正）を追加しました。
v0.34.0 追加：依存関係の基準を完成＋ルール・基準の drift を監視 — check_egovframe_dependencies の基準にSpring Boot BOM 全体（spring-boot-dependencies の3.5.6直接項目＋BOM import 44種を1段階展開した1,473座標）と、RTE モジュール18種の推移的依存関係（58座標、どのモジュールが取り込むか）を追加しました。項目ごとに基準の出典（parent 直接・系列・Boot BOM・RTE 推移・移行ルール）を示します。国内ベンダー・機関が配布する座標は vendor に分類し、EOL・旧座標（旧 MySQL/Oracle ドライバー・Jackson 1・xmlbeans・Ehcache 2・HttpClient 4・ANTLR 3・Spring Social）は置き換えルールに分類することで、公式共通コンポーネント 3.10 pom の「基準なし」を17件から1件に減らしました。sync_egovframe_templates は同梱するルール・基準の上流 drift（egovframe-runtime・共通コンポーネントの新しいタグ、公式 parent の新しいバージョン、固定された pom の sha256 の変更）を、更新手順とともに報告します。基準となる parent を5.0.2に更新しました。
v0.33.0 追加：migrate_egovframe_project 第3段階 — verify=true が compile を実行してコンパイルエラーを手動項目に紐付け、「対応すると解消されるエラー数」の多い順に作業一覧を返します（javac の symbol:/location: を解析）。ルールカタログ（schemaVersion 2）に共通コンポーネント3.x→5.x の対応表（egovframe-common-components v3.10.0↔v5.0.6、削除54・移動4）を追加し、egovframework.com.* の削除・移動クラスを診断します。また、3.x の共通コンポーネントのソースが混在するプロジェクトには、コンポーネント単位での再組み立てを推奨します（skipComponents で置換対象から除外）。
次の計画：v0.41–v0.43 の企画はすべて完了しました（企画の原文と結果）。次の3つのバージョンの企画はまだありません。
配布状況：npm の最新配布バージョンは、上部の npm バッジと npm パッケージページを唯一の情報源として確認してください。このドキュメントのバージョン表記はリポジトリのソース（package.json）に基づいており、git タグ vX.Y.Z は該当する配布版のコミットを指します。

제공 도구

도구	설명
`create_egovframe_project`	공식 템플릿을 내려받아 projectName(artifactId)·groupId·DB 타입을 적용한 새 프로젝트 생성
`list_egovframe_templates`	사용 가능한 공식 템플릿 목록
`sync_egovframe_catalog`	공식 common-components 태그·commit·archive SHA-256/크기/파일 수 검증, `sec.security`와 미매핑 upstream 경로 탐지
`list_egovframe_components`	선택 설치 가능한 공통컴포넌트 카탈로그 (공식 v5.0.7 고정, 리프 176종 + 그룹 14종 — 리프는 서비스 단위, 그룹 id는 하위 일괄 설치)
`add_egovframe_components`	공통컴포넌트 완전 조립 — 소스·매퍼·JSP와 message·IDGN·scheduling·정적 자산·Spring/web fragment 복사, Maven 좌표 탐지, 컴포넌트별 선별 DDL·DML 생성(`database`), archive 검증·충돌 전체 거부·쓰기 실패 롤백·`dryRun`
`search_egovframe_components`	키워드로 컴포넌트 검색 (id·이름·설명, 점수순 상위 10건)
`remove_egovframe_components`	설치 매니페스트 기반 트랜잭션 제거 — 의존 컴포넌트·사용자 수정 hash 보호, `dryRun` 분류, `force` 시 `remove-backup/` 백업 후 제거
`validate_egovframe_project`	조립 프로젝트 무결성 진단 — 파일 존재·DbType↔DB 스크립트 일치
`get_egovframe_guide`	컴포넌트의 공식 가이드 문서 조회 (egovframe-docs, 151종 매핑)
`add_ai_components`	공식 egovframe-ai-rag 샘플 기반 AI RAG 챗봇 조립 — Spring AI(Redis Stack)·LangChain4j(PGVector) 스택 선택(상호 배타), 소스·설정(`application-ai.yml` 프로필)·UI·인프라 복사, pom 누락 의존성만 마커 구간 삽입(백업 생성, 제거 시 원복), 충돌 시 전체 거부, `dryRun` 미리보기 (설계: docs/design-ai-components.md)
`list_egovframe_recipes`	큐레이션된 레시피(템플릿+컴포넌트 번들) 목록
`apply_egovframe_recipe`	레시피 하나로 생성→컴포넌트(→AI 계층)까지 조립하고 전체 성공 시에만 최종 경로로 atomic commit. 공식 템플릿이 제공하는 공통기반은 확인·보존하고 추가 컴포넌트만 설치 (`dryRun` 지원)
`diagnose_egovframe_project`	기존/레거시 프로젝트를 스캔해 빌드시스템·RTE 버전·DbType·설치 공통컴포넌트(pathPrefixes 지문)·설정 문제 진단 (읽기 전용)
`search_egovframe_docs`	공식 가이드 문서(egovframe-docs) 인덱스를 키워드로 검색 — 제목·경로·연계 컴포넌트, 문서 URL·조립용 id 반환 (오프라인)
`generate_egovframe_report`	프로젝트 리포트 — `sections=["components"]`(기본) 설치 컴포넌트·참조 테이블·가이드 링크·이슈, `sections=["assessment"]` 5.x 전환 준비도 평가서(개요·전환 범위·의존성 조치·보안·SBOM·A–D 등급과 산식). Markdown/json, `outputPath` 로 새 파일 저장(선택)
`reassemble_egovframe_components`	3.x/4.x 프로젝트에 복사된 공통컴포넌트 소스를 v5.0.7 로 재조립 — 원본 태그 식별(git blob id 대조), 원본·현재·목표 3-way 판정, 사용자 수정은 패치·작업 목록으로 보존, 5.x 에서 없어진 파일은 백업 후 삭제, 매니페스트 생성, dryRun 기본·transaction·verify(compile)
`rehearse_egovframe_migration`	전환 리허설 — 프로젝트 사본에서 재조립 → 전환 적용 → 컴파일 → pom 맞춤(공식 공통컴포넌트 v5.0.7 기준 parent·좌표·버전·scope) → 컴파일. 두 시점의 오류 수(javac 상한 없이), 누락 패키지·후보 좌표·연쇄 오류, 남는 수동 항목·파일, 사라지는 오류 순 작업 목록, 사본 pom 패치. 원본 불변(지문 비교), 최근 결과는 평가서에 실측으로
`upgrade_egovframe_project`	설치 컴포넌트를 upstream과 3-way 비교해 갱신 — 사용자 수정 보존, dryRun 기본, 적용 직전 재검증, 파일·백업·매니페스트 단일 transaction (파괴적, 게이트)
`explain_egovframe_component`	컴포넌트 하나의 상세(설명·직접/전이 의존성·역의존·참조 테이블·가이드 링크·설치 명령)를 한 번에 반환 (읽기 전용)
`generate_egovframe_ci`	CI 설정 생성 — `platform` 으로 GitHub Actions(기본)·GitLab CI(`.gitlab-ci.yml`)·Jenkins(`Jenkinsfile`, Declarative), maven/gradle 자동 감지, dryRun, 기존 파일 보호. `supplyChain=true` 면 SBOM → 최소 요소 점검 → 전환 준비도 평가서 게이트(`failOn` 기준 초과 시 실패, 보고서·SBOM 보관), `npmRegistry`·`offlineBundle` 환경 변수
`build_egovframe_project`	생성한 프로젝트를 실제로 빌드(compile·test·package) — maven/gradle·mvnw/gradlew 자동 감지, 타임아웃·로그 상한, 컴파일 오류 파일/라인 구조화, dryRun
`test_egovframe_project`	테스트 실행 + JUnit XML 리포트(surefire·gradle) 구조화 — 스위트별 통과/실패/오류/건너뜀, 실패 케이스 메시지·예외 타입·테스트 파일/라인, `testFilter`, 이전 실행 리포트 제외, dryRun
`generate_egovframe_crud`	공식 Development CRUD wizard 입력 체계 기반 코드 생성 — VO·Mapper(XML)·Service·Controller·JSP(선택)·JUnit 5(선택), Classic/Boot 분기, 전체 충돌 사전 검사
`sync_egovframe_templates`	공식 프로젝트 템플릿 통합 카탈로그(Initializr·MCP·Development) upstream 대조 — 추가/삭제/변경 항목과 MCP 커버리지 격차, zip 조달 템플릿의 고정 지문(sha256·크기)과 동봉 설정 템플릿의 변화 보고, 동봉 5.x 전환 규칙·의존성 기준 카탈로그의 drift(새 RTE·공통컴포넌트 태그, 새 parent 버전, 고정 pom sha256 변화)와 갱신 절차 보고, 네트워크 필요
`generate_egovframe_config`	공식 Initializr 설정 템플릿 21종으로 Spring 설정 파일 생성(오프라인 동봉) — datasource(DBCP/C3P0/JDBC·JNDI)·transaction(datasource/JPA/JTA)·cache·logging(log4j2 5종)·scheduling(Quartz 5종)·idGeneration(3종)·property, xml/javaConfig/yaml/properties, Initializr 폼과 같은 필드·기본값, 기존 파일 거부, dryRun
`migrate_egovframe_project`	3.x/4.x 프로젝트의 5.x(Jakarta EE 9+·Spring 6·Java 17) 전환 — 진단(기본, 읽기 전용): RTE Maven 좌표(`egovframework.rte:egovframework.rte.`·`org.egovframe.rte:org.egovframe.rte.` → `org.egovframe.rte:egovframe-rte-*`)·RTE 버전·저장소 URL·5.x parent, 패키지 접두어·이름 변경·제거 클래스(대체 안내), `javax→jakarta` 패키지·의존성 좌표, web.xml 스키마, 제거된 `egov-security/access/crypto` 네임스페이스, 교체 필요 라이브러리를 파일·라인 단위 `auto`/`manual` 항목으로 보고. 적용(`apply=true`): auto 항목을 transaction 으로 치환, dryRun 기본, 원본 `migration-backup/` 보관·`migration-plan.json`, 실패 시 복구, 적용 후 재진단. 검증(`verify=true`): compile 실행 후 컴파일 오류를 수동 항목과 연결한 작업 목록(해결될 오류 수 순). 공통컴포넌트 3.x→5.x 대응표(제거·이동 클래스)와 컴포넌트 단위 재조립 권고, `skipComponents`
`check_egovframe_dependencies`	의존성 점검(읽기 전용) — 선언된 의존성(`resolve=true` 면 Maven `dependency:tree`·Gradle `dependencies` 로 해석한 전이 의존성까지, 트리 경로·선언/해석 버전 차이 포함)을 공식 5.x parent 기준(관리 좌표 139종 + Spring/Security/Boot 등 BOM 계열) + Spring Boot BOM 전체(1,473종) + RTE 모듈 전이 의존성(58종)과 대조해 기준 충족/기준 미만/parent 관리/전환 대상(3.x·4.x RTE·javax)/교체 필요(DBCP 1.x·Log4j 1.x·Jackson 1·Ehcache 2 등)/벤더 배포(국내 DBMS·GPKI)/기준 없음 분류(항목마다 기준 출처 표시), 5.x parent·Java 버전 판정, 보안 설정 존재 점검(sec.security·CSRF·XSS 필터·보안 헤더·HTTPS 저장소, 파일·라인 근거). 기본 오프라인, `offline=false` 면 OSV 취약점 조회
`diagnose_egovframe_network`	도구가 내려받는 호스트 7종(codeload·raw·media.githubusercontent, maven.egovframe.go.kr, repo1.maven.org, registry.npmjs.org, api.osv.dev)에 DNS 조회·HEAD 요청을 보내 도달 여부·소요 시간·실패 종류(DNS·타임아웃·TLS·프록시 인증·거부)를 보고하고, 환경에 맞는 처방(`HTTPS_PROXY`+`NODE_USE_ENV_PROXY=1`, `NODE_OPTIONS=--dns-result-order=ipv4first`, `NODE_EXTRA_CA_CERTS`)을 bash/cmd/PowerShell 명령으로 안내. 프로젝트 디렉터리 불필요, 파일 무기록
`prepare_egovframe_offline_bundle`	폐쇄망 오프라인 번들 — 인터넷 PC 에서 OSV Maven 덤프·고정 공통컴포넌트 아카이브·Initializr zip 템플릿·공통컴포넌트 태그 미러를 sha256 manifest 와 함께 새 디렉터리에 담음(dryRun 기본). 폐쇄망에서는 `EGOVFRAME_OFFLINE_BUNDLE` 로 다운로드·OSV·재조립 원본을 번들로 대체
`generate_egovframe_sbom`	SBOM 생성 — Maven/Gradle 프로젝트의 CycloneDX 1.6 JSON(기본) 또는 SPDX 2.3 JSON(`bomFormat="spdx-json"`)을 빌드 파일 변경 없이 생성(Maven: cyclonedx-maven-plugin makeAggregateBom, 해시·라이선스 포함 / Gradle: 해석된 의존성 트리로 구성). `enrich` 로 component 마다 기준 판정(`egovframe:status·basis·baseline`) 속성, `offline=false` 로 OSV 취약점을 `vulnerabilities[]` 에 포함. 출력은 프로젝트 안 경로(기본 `sbom/bom.cdx.json`, SPDX 는 `sbom/bom.spdx.json`), 기존 파일은 `overwrite` 없이는 거부, `dryRun`(기본)은 계획만
`check_egovframe_sbom`	SBOM 점검 — 기존 CycloneDX·SPDX 2.x SBOM(형식 자동 판별)의 최소 요소 7종(공급자·구성요소명·버전·고유식별자·의존관계·작성자·생성 시각) 충족 여부와 빠진 component, 빌드 도구 없이 purl 로 기준 재판정·OSV 재조회(생성 이후 새 취약점), `baselinePath` 와 비교(추가·제거·버전·판정·취약점), `vex=true` 면 CycloneDX VEX 초안(`in_triage`, BOM-Link, 사람의 판단 보존, CycloneDX 입력만). SBOM 파일은 바꾸지 않음
`generate_agents_md`	프로젝트 진단 결과로 AI 코딩 도구용 `AGENTS.md` 생성 — 빌드·테스트 명령(래퍼 감지), RTE·5.x 전환 상태, DbType, 기본 패키지·설정 디렉터리, 설치 컴포넌트(매니페스트 여부), 규칙(좌표·백업 디렉터리·비밀 정보·의존성 기준), MCP 도구 목록. 기존 파일은 `overwrite` 없이는 거부, `dryRun`, ko/en, 파일명 변경(`CLAUDE.md` 등)

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 | simple-homepage | portal-site | enterprise-business | web-sample | msa-edu | msa-common-components | mobile-device-api | ai-rag | web | boot-web | batch-file-scheduler | batch-file-commandline | batch-file-web | batch-db-scheduler | batch-db-commandline | batch-db-web | mobile-web | mobile-common-components | msa-portal-backend | msa-portal-frontend（全22種類。list_egovframe_templatesで確認）
- レガシーテンプレート（simple-homepage・portal-site・enterprise-business・web-sample）は、egovProps/globals.propertiesのGlobals.DbTypeにDBタイプを適用します。
- msa-edu・msa-common-components・mobile-device-api・ai-ragはマルチプロジェクトのため、座標・DBの自動適用は行わず、元のまま生成してREADMEの案内を返します。
- webからmsa-portal-frontendまでの12種類はInitializr zip 調達テンプレートです。固定 commit の zip を取得してsha256・サイズを検証した後、pom.xmlの###GROUP_ID###などのプレースホルダーを埋め、globals.properties（バッチはegovframework/batch/properties/）にDBタイプを適用します。msa-portal-*の2種類はマルチプロジェクトのため、自動適用はありません。
outputDir — 生成先の親ディレクトリ
ref — （任意）ダウンロードするブランチ／タグ。指定しない場合はテンプレートのデフォルトブランチを使用します。例：main、v4.3.0。zip 調達テンプレートにrefを指定すると、固定フィンガープリントの検証をスキップし、その旨が結果に表示されます。
dryRun — （任意、デフォルトはfalse）trueの場合はディスクに書き込まず、生成予定のファイル数と適用設定のみをプレビューします。

動作：公式テンプレート zip をダウンロード → 展開（zip-slip を防止） → pom.xmlのgroupId/artifactId/nameを適用（親POMの座標は維持） → application.propertiesのGlobals.DbTypeを設定し、フロントエンドテンプレートではpackage.jsonのnameを設定します。既存のディレクトリがある場合は拒否します。ダウンロードには30秒のタイムアウトが適用されるため、応答がない場合も無期限に待機しません。まずdryRunで安全にプレビューできます。

generate_egovframe_crud の主要パラメーター

projectDir — 対象のMaven／Gradleプロジェクト
tableName、entityName — DBテーブルと生成するクラス名（entityNameを省略した場合はテーブル名から変換）
basePackage — 基本パッケージ。mapper・VO・service・impl・controllerの各パッケージを個別に上書きすることもできます。
fields — columnName、javaType、jdbcType、primaryKey、generated、nullable、labelの列仕様。安全にupdate/deleteを生成するため、主キーが1つ以上必要です。
profile — classic（Spring MVC+JSP）またはboot（REST Controller）
checkDataAccess、checkService、checkWeb — 公式wizard.xmlの生成グループに対応
includeJsp、withTest、dryRun — JSP・JUnit 5テストの選択的な生成と、書き込みなしのプレビュー

generate_egovframe_crud(
  projectDir="/work/my-egov-app",
  tableName="SAMPLE_BOARD",
  entityName="Board",
  basePackage="egovframework.example.board",
  profile="classic",
  fields=[
    { columnName: "BOARD_ID", javaType: "Long", jdbcType: "BIGINT", primaryKey: true, generated: true },
    { columnName: "TITLE", javaType: "String", jdbcType: "VARCHAR", nullable: false }
  ],
  withTest=true,
  dryRun=true
)

生成前にすべての対象パスを検査し、既存ファイルが1つでもある場合はファイルを一切書き込みません。サポートされる型と出力仕様については、CRUD生成設計を参照してください。

generate_egovframe_config の主要パラメーター

projectDir — 対象プロジェクト
configId — 設定テンプレートID。datasource datasource-jndi transaction-datasource transaction-jpa transaction-jta cache-ehcache-default cache-spring logging-console logging-file logging-rolling-file logging-time-rolling-file logging-jdbc scheduling-bean-job scheduling-method-job scheduling-simple-trigger scheduling-cron-trigger scheduling-scheduler idgen-sequence idgen-table idgen-uuid property
format — xml（デフォルト） | javaConfig | yaml | properties（yaml・propertiesはlogging系のみ）
fields — テンプレート変数の上書き。フィールド名とデフォルト値はInitializrのWebビューのフォームと同じです（例：txtDatasourceName、rdoType（DBCP|C3P0|JDBC）、txtDriver、txtUrl、txtUser、txtPasswd、txtConfigPackage）。テンプレートにないフィールドや、選択肢にない値は拒否します。全一覧はリソースegovframe://catalog/config-templatesを参照してください。
fileName — ファイル名（拡張子を除く）またはJavaConfigのクラス名。指定しない場合はInitializrのデフォルト値（context-datasource、EgovDataSourceConfigなど）
outputDir — プロジェクト相対パス。指定しない場合、xml → src/main/resources/egovframework/spring（loggingはsrc/main/resources）、javaConfig → src/main/java/<パッケージ>
dryRun — 内容・パス・コンテキストのみを返します

generate_egovframe_config(
  projectDir="/work/my-egov-app",
  configId="datasource",
  format="javaConfig",
  fields={ txtConfigPackage: "kr.go.sample.config", rdoType: "C3P0", txtUrl: "jdbc:mysql://db:3306/app", txtUser: "app", txtPasswd: "…" }
)

既存ファイルがある場合は書き込まずに拒否し、結果のコンテキストではパスワードフィールドがマスクされます。テンプレートはeGovFramework/egovframe-vscode-initializr（Apache-2.0）のtemplates/configを、commit・sha256を固定して同梱しています。設計およびupstreamで見つかった問題については、設定ファイル生成設計を参照してください。

migrate_egovframe_project 파라미터

projectDir — 진단할 프로젝트(허용 root 적용). pom.xml(다중 모듈 포함)·build.gradle(.kts)·*.java·*.xml·*.jsp·web.xml·*.properties/yml 을 읽으며 target/·build/·.git/·node_modules/ 는 건너뜁니다
target — 5.x(기본이자 현재 유일)
format — markdown(기본, 수동 항목 → 자동 항목 순 요약) | json(항목 배열 {file, line, kind, from, to, action, reason, edits?} 과 summary.byKind, sourceEra)
apply — true 면 2단계(적용). dryRun(기본 true)이면 파일별 변경 미리보기만, false 면 실제 치환
verify — true 면 3단계(검증): 진단 뒤 compile 을 실행해 컴파일 오류를 수동 항목과 연결한 작업 목록을 반환(빌드 도구 필요, 파일 무기록)
skipComponents — true 면 3.x 공통컴포넌트 디렉터리(재조립 권고 대상)의 자동 항목을 치환하지 않고 수동으로 남김

migrate_egovframe_project(projectDir="/work/legacy-3.10-app")                       # 1단계 진단
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", apply=true)           # 적용 계획(미리보기)
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", apply=true, dryRun=false)  # 적용
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", verify=true)   # 컴파일 → 오류 ↔ 수동 항목 작업 목록

action 이 auto 인 항목(좌표·RTE 버전 속성·패키지 접두어·패키지 이름 변경·javax→jakarta 패키지와 의존성 좌표·저장소 URL·Java 버전·web.xml 스키마)은 적용 단계가 원문 오프셋 기준으로 치환하고, manual(제거된 클래스·네임스페이스·교체 필요 라이브러리·Spring 버전·5.x parent 권고)은 사유와 대체 API 를 함께 남깁니다. 적용은 하나의 transaction 이며 원본을 migration-backup/<시각>-<id>/ 에 보관하고 migration-plan.json 을 남깁니다. 중간에 실패하면 작업 전 상태로 되돌립니다. 규칙의 출처와 제거 클래스 38종의 대체 근거는 전환 진단 설계를, 규칙 자체는 리소스 egovframe://catalog/migration-rules 를 참고하세요. 이 도구는 파일을 쓰지 않습니다.

check_egovframe_dependencies 파라미터

projectDir — 점검할 프로젝트(허용 root 적용). Maven(다중 모듈 pom, <properties> 해석) 또는 Gradle
offline — true(기본) 오프라인 기준 대조만 | false OSV(api.osv.dev) 취약점 조회 추가
resolve — true 면 빌드 도구로 의존성 트리를 해석해 전이 의존성까지 판정(Maven maven-dependency-plugin:3.8.1:tree, Gradle dependencies --configuration runtimeClasspath; 빌드 도구·저장소 접근 필요). resolveScope runtime(기본) | all(test·provided 포함), resolveTimeoutMs
format — markdown | json

check_egovframe_dependencies(projectDir="/work/my-egov-app", offline=false)
check_egovframe_dependencies(projectDir="/work/my-egov-app", resolve=true, offline=false)   # 실제로 실리는 artifact 전부

resolve=true 결과는 항목마다 origin(declared·transitive)과 전이 경로 via(예 egovframe-rte-ptl-mvc → spring-webmvc), 선언과 다르게 해석된 버전(treeVersion·resolution.differs)을 담고, parent 가 관리하는 좌표가 기준 미만 버전으로 해석되면 비고에 알립니다. 해석에 실패하면 선언 기준 결과에 이유를 붙여 돌려줍니다.

기준은 공식 5.x parent(org.egovframe.web:egovframe-web-config-parent·org.egovframe.boot:egovframe-boot-starter-parent 5.0.2)의 properties·dependencyManagement, Boot parent 가 상속하는 Spring Boot BOM 전체(spring-boot-dependencies 3.5.6 + import 한 단계), RTE 모듈 18종의 전이 의존성에서 추출한 catalog/dependency-baseline.json(schemaVersion 2) 이며 리소스 egovframe://catalog/dependency-baseline 로 조회할 수 있습니다. 대조 순서는 parent 직접 → 계열 → (Boot parent 프로젝트) Boot BOM → RTE 전이, 그 밖은 RTE 전이 → Boot BOM 이고 항목마다 basis 로 출처를 적습니다. RTE 전이 버전보다 낮게 명시한 좌표는 "충돌 가능" 사유와 함께 기준 미만으로 봅니다. 국내 벤더·기관 배포 좌표(Altibase·Tibero·CUBRID·GPKI·mGov)는 vendor, 기준에 없는 좌표는 unknown(판단 보류)으로 두고 둘 다 조치 목록에 넣지 않습니다. 보안 점검은 설정의 존재 여부와 근거만 보고합니다(설계: 의존성 점검 설계).

generate_egovframe_sbom 파라미터

projectDir — Maven 또는 Gradle 프로젝트(허용 root 적용)
bomFormat — cyclonedx-json(기본, CycloneDX 1.6) | spdx-json(v0.43, SPDX 2.3 — CycloneDX 로 만든 뒤 변환)
outputPath — 프로젝트 상대 경로(기본 sbom/bom.cdx.json, SPDX 는 sbom/bom.spdx.json; ..·절대 경로·symlink 이탈 거부), overwrite — 기존 파일 덮어쓰기(기본 거부)
scope — runtime(기본: compile+runtime) | all(test·provided 포함)
enrich — true(기본) component 마다 egovframe:status·egovframe:basis·egovframe:baseline 속성 부착
offline — true(기본) | false OSV 결과를 CycloneDX vulnerabilities[](affects 로 component 참조)로 포함
dryRun — true(기본) 실행 없이 명령·출력 경로만 | false 생성·기록, timeoutMs(기본 600000)
v0.40: supplier(공급자 — 주 component 와 metadata.supplier, 기본 pom <organization><name>)·author(metadata.authors, 기본 supplier)·componentName·componentVersion(주 component 덮어쓰기), fillSuppliers(기본 enrich 와 같음 — 공급자가 없는 component 를 catalog/sbom-rules.json 공급자 표로 보완하고 egovframe:supplierBasis=catalog 로 표시). 응답의 minimum 이 최소 요소 7종 판정을 요약합니다.

generate_egovframe_sbom(projectDir="/work/my-egov-app")                              # 계획만
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, offline=false)  # sbom/bom.cdx.json + OSV
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, supplier="○○기관", author="○○정보기술")  # 최소 요소까지
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, bomFormat="spdx-json", supplier="○○기관")  # sbom/bom.spdx.json (SPDX 2.3)

Maven 은 org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom 을 좌표를 완전히 적어 호출하므로 pom 을 바꾸지 않으며(해시·라이선스 포함, 멀티 모듈 합산), Gradle 은 해석된 트리로 이 서버가 문서를 구성합니다(해시·라이선스 없음, 빌드 파일 변경 없음). 문서의 metadata.tools 에 이 서버가 기록됩니다. 기준 판정은 check_egovframe_dependencies 와 같은 규칙입니다(설계: 의존성 점검 설계).

check_egovframe_sbom 파라미터 (SBOM 점검)

sbomPath — 점검할 SBOM(기본 sbom/bom.cdx.json; CycloneDX JSON 또는 SPDX 2.x JSON, 형식 자동 판별), baselinePath — 비교할 이전 SBOM(선택, 형식이 달라도 purl 좌표로 비교)
offline — true(기본) | false OSV 재조회(생성 이후 새로 알려진 취약점·지금 조회되지 않는 취약점)
vex — true 면 VEX 초안 작성·갱신(vexPath, 기본 sbom/vex.cdx.json, CycloneDX 입력만), dryRun — vex 미리보기
SBOM 파일은 바꾸지 않습니다. VEX 는 새 파일로 만들고, 다음 실행은 기존 판단을 그대로 두고 새 항목만 덧붙입니다(깨진 VEX 는 덮어쓰지 않고 중단)

SBOM 제출 준비

2027년까지 공공 분야에 도입되는 IT 시스템·SW 제품의 SBOM 제출이 제도화됩니다(SW 공급망 보안 로드맵, 2026-06). 제출물에는 "만들었다"보다 빠진 요소가 없고, 이전 제출본과 무엇이 달라졌으며, 알려진 취약점을 어떻게 판단했는지가 함께 있어야 합니다.

generate_egovframe_sbom(projectDir, dryRun=false, offline=false, supplier="○○기관", author="○○정보기술")   # 1. 생성(최소 요소 포함)
check_egovframe_sbom(projectDir)                                     # 2. 최소 요소 7종 — 제출 가능/보완 필요
check_egovframe_sbom(projectDir, offline=false, vex=true)            # 3. 새 취약점 확인 + VEX 초안(in_triage)
#    → 담당자가 sbom/vex.cdx.json 의 analysis.state 를 not_affected(+justification)·exploitable·resolved 등으로 기록
check_egovframe_sbom(projectDir, baselinePath="sbom/bom-2026Q3.cdx.json", offline=false, vex=true)   # 4. 다음 제출 전: 비교 + 새 취약점만 VEX 에 추가

최소 요소	CycloneDX 위치	SPDX 2.3 위치 (v0.43)	비고
공급자	component `supplier`·`publisher`·`manufacturer` (주 component 는 `metadata.supplier` 도)	`PackageSupplier`(없으면 `PackageOriginator`)	플러그인은 pom `<organization>` 이 있는 라이브러리만 `publisher` 를 채움 — 공식 web 템플릿 67종 중 17종(RTE 등)이 비어 공급자 표로 보완
구성요소명 · 버전	`name` · `version`	`PackageName` · `PackageVersion`(`versionInfo`)
고유식별자	`purl`(또는 `cpe`·`swid`)	`externalRefs` 의 `purl`(또는 `cpe23Type`·`cpe22Type`·`swid`)
의존관계	`dependencies[]` 에 그 component 의 `bom-ref` 항목	그 패키지가 주어인 `DEPENDS_ON`(또는 `*_DEPENDENCY_OF` 의 대상)	의존이 없어도 빈 `dependsOn` / `DEPENDS_ON NONE` 이 있어야 함(`NOASSERTION` 은 모름)
작성자	`metadata.authors`(또는 `metadata.manufacturer`)	`creationInfo.creators` 의 `Person:`·`Organization:`	생성 도구(`metadata.tools` / `Tool:`)만으로는 작성 주체가 드러나지 않음
생성 시각	`metadata.timestamp`	`creationInfo.created`	ISO 8601 — SPDX 는 필수 항목이라 원본에 없으면 변환 시각을 넣고 알림

규칙은 catalog/sbom-rules.json 데이터입니다(출처: NTIA 최소 요소 2021, SW 공급망 보안 가이드라인 1.0) — 국내 지침이 요소를 더하면 데이터로 추가합니다. CI 에서는 npx -y egovframe-scaffold-mcp sbom-check --offline=false --fail-on "minimum,newVulns" 로 제출 전 점검을 게이트로 걸 수 있습니다.

제출처가 SPDX 를 요구하면(가이드라인 1.0 은 SPDX·CycloneDX 를 모두 언급) bomFormat="spdx-json" 으로 같은 내용을 SPDX 2.3 JSON 으로 냅니다. 체크섬·선언 라이선스(이름만 있는 라이선스는 LicenseRef- + hasExtractedLicensingInfos)·OSV 권고(SECURITY/advisory externalRefs)·기준 판정(egovframe:* annotations)도 옮기므로, SPDX 로 낸 뒤 check_egovframe_sbom(sbomPath="sbom/bom.spdx.json") 의 재판정·비교가 CycloneDX 와 같은 결과를 냅니다. SPDX 3.0, 취약점 판단 자동화(VEX 상태는 사람의 결정), 중앙 저장소 제출 API 는 범위 밖입니다.

generate_egovframe_report 파라미터 (전환 준비도 평가서)

projectDir — 평가할 프로젝트(허용 root 적용)
sections — ["components"](기본, v0.16 리포트 그대로) | ["assessment"](평가서) | 둘 다(이어 붙임)
resolve·resolveScope·resolveTimeoutMs — 평가서의 의존성 절을 빌드 도구로 해석한 전이 의존성까지 판정(기본 선언만)
offline — true(기본) | false OSV 로 알려진 취약점 조회 — 공급망 등급은 취약점을 조회해야 "확정"으로 표시
sbomPath — 요약할 SBOM(기본 sbom/bom.cdx.json; 없으면 "없음"으로 표시하고 만들지 않음), topN — 예상 수동 작업 상위 N(기본 20)
outputPath — 프로젝트 상대 .md 경로. 주면 새 파일로만 저장(기존 파일 거부, ..·절대·symlink 이탈 거부, transaction), dryRun — 쓰지 않고 내용만
format — markdown(기본) | json(outputSchema·structuredContent, 평가 데이터 포함)

generate_egovframe_report(projectDir="/work/legacy-app", sections=["assessment"])
generate_egovframe_report(projectDir="/work/legacy-app", sections=["assessment"], offline=false, resolve=true, outputPath="docs/assessment.md")

평가서 6절의 등급은 두 축입니다. 전환 난이도 = 수동 전환 항목 수(0 / 1–20 / 21–100 / 101+ → 0–3점) + 재조립 권고 공통컴포넌트 수(0 / 1–5 / 6–20 / 21+) + 제거된 API 참조 수(0 / 1–10 / 11–100 / 101+) + 현재 좌표 세대(5.x 0 · 4.x 1 · 3.x 2), 공급망 상태 = 기준 미만 의존성 수(0 / 1–3 / 4–10 / 11+) + 전환 대상·교체 필요 수(같은 구간) + 알려진 취약점이 있는 의존성 수(0 / 1–2 / 3–9 / 10+, 미조회면 0점으로 계산하고 주의) + 보안 설정 누락 수(0 / 1–2 / 3+ → 0–2점) + 5.x parent·Java 기준(각 미달 +1). 합계로 A=0 · B≤3 · C≤7 · D>7. 산식 전문은 리포트 안에 인쇄되며, 공식 5.x 템플릿은 전환 A, 공식 공통컴포넌트 3.10.0·4.3.2 전체 트리는 두 축 모두 D 입니다(구간을 정한 근거와 예시: docs/design-assessment-report.md). 비용·공수는 산정하지 않습니다.

평가서 발췌(공통컴포넌트 v4.3.2 전체 트리):

- **전환 난이도 D · 공급망 상태 D** (산식은 6절)
## 2. 전환 범위
- 항목 1352건 = 자동 치환 635 + 수동 717 · 대상 파일 689개
- 재조립 권고 공통컴포넌트 155종: cmm, cop.adb, bbs, …
- 제거된 API 참조 552건 (제거된 RTE 클래스 · 제거된 공통컴포넌트 클래스 · 제거된 RTE 모듈 · 제거된 XML 네임스페이스)
## 6. 등급과 근거
### 전환 난이도: **D** (10/11점, A=0 · B≤3 · C≤7 · D>7)
| 요인 | 값 | 구간 | 점수 | 비고 |
| 수동 전환 항목 수 | 717 | 101+ | 3 |  |
| 재조립 권고 공통컴포넌트 수 | 155 | 21+ | 3 |  |
| 제거된 API 참조 수 | 552 | 101+ | 3 |  |
| 현재 좌표 세대 | 1 | 1 | 1 | sourceEra=4.x |

reassemble_egovframe_components 파라미터 (공통컴포넌트 재조립)

projectDir — 대상 프로젝트(허용 root 적용)
components — 재조립할 컴포넌트 id(그룹 id 는 하위로 펼침). 미지정 시 diagnose_egovframe_project 가 감지한 컴포넌트 전부
sourceTag — 원본 태그(기본 auto: 프로젝트 파일의 git blob id 를 좌표 세대에 맞는 공식 태그와 대조해 일치가 가장 많은 태그), 예: v3.10.0
database — 지정 시 컴포넌트별 DDL·DML 을 scripts/egovframe-components/<db>/ 에 함께 생성
dryRun — true(기본) 분류·계획만(파일 내용을 내려받지 않음) | false 적용, verify — 적용 뒤 compile 해 오류를 작업 목록 파일에 붙임
format — markdown(기본) | json(outputSchema)

파일마다 판정은 목표와 같음(유지)·원본 그대로(교체)·사용자 수정(소스는 교체 + 원본 대비 패치 보존, 메시지·설정 조각·웹 자산은 사용자본 유지 + 목표본 참고 저장)·5.x 신규(추가)·5.x 에서 제거(백업 후 삭제, 사용자 수정이면 패치도)·원본 미확인(백업 후 교체)·사용자 추가(유지)입니다. 백업·패치·reassemble-plan.json 은 migration-backup/<시각>-reassemble-*/ 에, 매니페스트는 .egovframe-components.json 에 남습니다. 원본 태그 비교에는 git 이 필요하고, blob 없는 bare 미러를 EGOVFRAME_CACHE_DIR(기본 ~/.cache/egovframe-scaffold-mcp)에 태그당 수백 KB 로 캐시합니다. 사용자 패치를 자동으로 다시 적용하지는 않습니다(5.x 소스가 많이 바뀌어 fuzz 적용이 오히려 위험).

rehearse_egovframe_migration 파라미터 (전환 리허설)

projectDir — 대상 프로젝트(읽기만 함, 허용 root 적용)
steps — 기본 ["reassemble","migrate","verify","align-pom"](순서 고정, 일부만 고를 수 있음)
components·sourceTag — 재조립 단계에 그대로 전달
keepWorkspace — true 면 사본(EGOVFRAME_CACHE_DIR/rehearsal/<이름>-*)을 남기고 경로를 돌려줌(기본: 끝나면 삭제), timeoutMs — 컴파일 1회(기본 900000), topN — 작업 목록 수

사본은 빌드 산출물·VCS·백업 디렉터리를 빼고 만듭니다. 재조립을 전환 적용보다 먼저 하는 이유는 적용이 컴포넌트 소스를 바꾸면 원본 태그 지문이 깨지기 때문입니다(공식 4.3.2 트리를 거꾸로 돌리면 v5.0.1 로 오인되고 1,489개 파일이 "사용자 수정"이 됩니다). Maven 은 -Dmaven.compiler.fork=true 와 JDK_JAVAC_OPTIONS=-Xmaxerrs 100000 으로 javac 의 오류 100개 상한 없이 셉니다. pom 맞춤은 사본에만 적용하고 패치로 돌려주므로, 검토해서 실제 pom 에 반영하면 됩니다. 실측(공식 공통컴포넌트 v4.3.2 전체): 자동 단계 후 6,003건(JDK 17)·6,335건(JDK 21) → pom 맞춤 후 1건. javac 판본마다 같은 원인을 다른 모양으로 보고하므로(JDK 17 은 없는 패키지의 import 대신 쓰는 곳마다 "cannot find symbol") 분석은 파일의 import 문·타입 선언 파일·Lombok 사용 여부로 원인을 묶습니다. pom 에 소스 인코딩이 없으면 UTF-8 로 컴파일합니다(JDK 18+ 기본값).

3.x/4.x 프로젝트 전환 흐름:

generate_egovframe_report(projectDir, sections=["assessment"])        # 평가서: 재조립 권고·수동 항목·등급
rehearse_egovframe_migration(projectDir)                               # 사본에서 전 과정 실측: 남는 컴파일 오류·pom 변경안(원본 불변)
reassemble_egovframe_components(projectDir)                            # 미리보기: 원본 태그·파일별 판정
reassemble_egovframe_components(projectDir, dryRun=false)              # 공통컴포넌트 v5.0.7 재조립 + 패치·작업 목록
migrate_egovframe_project(projectDir, apply=true, dryRun=false)        # 나머지 좌표·패키지·Jakarta 자동 치환
migrate_egovframe_project(projectDir, verify=true)                     # compile 오류 ↔ 수동 항목 작업 목록

diagnose_egovframe_network / generate_agents_md

diagnose_egovframe_network()                       # 호스트 7종 전부, 호스트당 10초
diagnose_egovframe_network(hosts=["codeload.github.com"], timeoutMs=20000)
generate_agents_md(projectDir="/work/my-egov-app", dryRun=true)   # 내용만
generate_agents_md(projectDir="/work/my-egov-app", lang="en", fileName="CLAUDE.md", overwrite=true)

네트워크 진단은 프록시 URL 의 자격 증명을 가려서 보고하며, NODE_TLS_REJECT_UNAUTHORIZED=0 이 설정돼 있으면 경고합니다. 다운로드가 실패하는 다른 도구들도 오류 메시지 끝에 같은 분류와 한 줄 처방을 붙입니다([네트워크 timeout] … 자세한 진단: diagnose_egovframe_network). AGENTS.md 의 사실 항목은 diagnose_egovframe_project·migrate_egovframe_project·빌드 도구 감지에서 오고, 규칙 항목은 이 서버의 도구가 지키는 원칙입니다.

sync_egovframe_catalog / 컴포넌트 조립

카탈로그는 common-components 공식 v5.0.7 태그와 commit 7912e13c…에 고정됩니다(v0.38 에서 v5.0.6 → v5.0.7, v0.39 에서 upstream 이 태그를 옮겨 3756ab2c… → 7912e13c… 로 재고정).
sync_egovframe_catalog()는 태그 이동, archive SHA-256·크기·파일 수 불일치, sec.security 누락, 미매핑 Java·Mapper·JSP를 검사합니다.
add_egovframe_components는 기존 파일이 upstream과 동일하면 재사용하고 내용이 다르면 전체 조립을 거부합니다.
감지된 mavenDependencies는 결과에 반환합니다. 프로젝트별 dependency management·버전 정책을 보호하기 위해 기존 pom.xml과 web.xml은 자동 덮어쓰지 않습니다.

상세 스키마와 안전 게이트는 카탈로그 동기화·완전 조립 설계를 참고하세요.

설치·사용

npm에 배포되어 설치 없이 바로 실행할 수 있습니다:

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "npx",
      "args": ["-y", "egovframe-scaffold-mcp"]
    }
  }
}

영문 도구 설명이 필요하면(응답은 한국어 그대로) env 에 "EGOVFRAME_LANG": "en" 을 추가합니다. 사내 프록시 환경에서 프로젝트 생성이 타임아웃되면 "HTTPS_PROXY": "http://proxy:8080", "NODE_USE_ENV_PROXY": "1" 을 같은 env 에 넣고, 원인 확인은 diagnose_egovframe_network 로 합니다.

소스에서 직접 빌드하려면:

npm install
npm run build

Claude Desktop / Claude Code 설정 예 (mcpServers):

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "node",
      "args": ["/절대경로/egovframe-scaffold-mcp/dist/index.js"]
    }
  }
}

빌드 없이 실행하려면 (로컬 클론 후):

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "npx",
      "args": ["-y", "tsx", "/절대경로/egovframe-scaffold-mcp/src/index.ts"]
    }
  }
}

사용 예 (AI 도구에서):

"표준프레임워크로 my-egov-app 프로젝트를 ~/work에 만들어줘. groupId는 egovframework.example, DB는 mysql."

CI 에서 쓰기 (CLI 모드)

AI 클라이언트가 없는 빌드 서버에서는 같은 패키지를 명령으로 실행합니다. 인자가 없으면 MCP 서버, 명령이 있으면 그 도구를 한 번 실행하고 종료합니다.

npx -y egovframe-scaffold-mcp assess --project . --offline=false --out assessment.md --fail-on supplyChain:C
npx -y egovframe-scaffold-mcp check --project . --resolve --json --fail-on "vulnerabilities,outdated>10"
npx -y egovframe-scaffold-mcp sbom --project . --write --offline=false
npx -y egovframe-scaffold-mcp sbom-check --project . --offline=false --fail-on "minimum,newVulns"
npx -y egovframe-scaffold-mcp migrate --project . --fail-on manual
npx -y egovframe-scaffold-mcp rehearse --project . --fail-on "errors>50"

명령	도구	비고
`assess`	`generate_egovframe_report(sections=["assessment"])`	등급 지표 `migration`·`supplyChain`(예: `supplyChain:C` = C 이상이면 실패)
`check`	`check_egovframe_dependencies`	`outdated`·`legacy`·`replace`·`unknown`·`vulnerabilities`·`securityMissing`
`sbom`	`generate_egovframe_sbom`	`--write` 가 있어야 파일을 씀(기본 계획만), `--bom-format spdx-json` 이면 SPDX 2.3
`bundle`	`prepare_egovframe_offline_bundle`	인터넷 PC 용, `--output-dir` 필수, `--write` 가 있어야 받음(기본 목록만)
`rehearse`	`rehearse_egovframe_migration`	사본에서 실측(원본 불변), 지표 `errors`(최종)·`automation`·`aligned`·`files`·`unlinked`·`failedSteps`
`sbom-check`	`check_egovframe_sbom`	CycloneDX·SPDX 자동 판별, `minimum`(보완 필요면 1)·`gaps`·`newVulns`·`changed`·비교 `added`·`removed`·`versionChanged`·`diffVulns`·VEX `triage`, `--write` 면 VEX 작성·갱신
`migrate`	`migrate_egovframe_project`	진단만(`--apply` 차단), `manual`·`auto`·`items`
`validate` · `diagnose` · `network`	같은 이름의 도구	`invalid`·`missing` · `issues` · `failed`

옵션은 도구 파라미터와 같은 이름(kebab-case 가능)이고, 공통 옵션은 --project·--json(MCP structuredContent 와 같은 객체)·--out·--step-summary(Markdown 을 $GITHUB_STEP_SUMMARY 에)·--fail-on 입니다. 종료 코드는 0 통과 · 2 --fail-on 기준 초과 · 3 실행 실패 · 64 사용법 오류, 본문은 stdout·한 줄 요약은 stderr 입니다. 쓰기 도구(생성·조립·적용·재조립)는 CLI 에 노출하지 않습니다.

CI 설정 생성: GitHub Actions · GitLab CI · Jenkins

generate_egovframe_ci(projectDir, platform, supplyChain=true) 가 세 플랫폼에 같은 빌드와 같은 게이트를 만듭니다. 게이트는 SBOM 생성(sbom --write --offline=false) → 최소 요소 7종 점검(sbom-check --fail-on minimum, v0.43) → 전환 준비도 평가서(assess --fail-on <failOn>) 순서이고, CLI 의 종료 코드 2(기준 초과)·3(실행 실패)는 job 실패입니다. 보고서(egovframe-assessment.md·egovframe-sbom-check.md)와 sbom/bom.cdx.json 은 실패해도 보관하며, 패키지 버전은 생성 시점의 서버 버전으로 고정됩니다.

platform	파일	빌드	게이트
`github`(기본)	`.github/workflows/egovframe-ci.yml`	`mvn -B verify` · `./gradlew build`	별도 job, 등급을 PR 요약(`--step-summary`)에, upload-artifact
`gitlab`	`.gitlab-ci.yml`	`maven:3.9-eclipse-temurin-<JDK>`(Gradle 은 `eclipse-temurin:<JDK>`) 이미지, 로컬 저장소 캐시, JUnit 리포트	`supply-chain` job(`needs: []`), Node 가 없으면 apt 로 설치 시도, `artifacts:reports:cyclonedx`
`jenkins`	`Jenkinsfile`(Declarative)	`stage('Build')` — Linux `sh`·Windows `bat` 공용	`SBOM` → `SBOM check` → `Assessment` 단계, `post { always { archiveArtifacts } }`

generate_egovframe_ci(projectDir="/work/my-egov-app", platform="gitlab", supplyChain=true, supplier="○○기관")
generate_egovframe_ci(projectDir="/work/my-egov-app", platform="jenkins", supplyChain=true, failOn="supplyChain:C",
                      npmRegistry="https://nexus.example.go.kr/repository/npm-group/", offlineBundle="/opt/egov-bundle")

npmRegistry 는 NPM_CONFIG_REGISTRY(npx 가 이 서버를 받는 사내 레지스트리), offlineBundle 은 EGOVFRAME_OFFLINE_BUNDLE(러너·에이전트에서 본 번들 경로)로 들어갑니다. 값은 따옴표·$·줄바꿈 없는 URL·절대 경로만 허용합니다(설정 파일 주입 차단).
공급자 단서가 없으면(supplier 미지정, pom <organization><name> 없음) SBOM 의 주 component 공급자·작성자가 비어 sbom-check 단계가 실패하므로, 생성 응답이 이를 미리 알립니다.
GitLab 이미지는 공개 Docker Hub 기준입니다. 폐쇄망에서는 사내 레지스트리의 같은 이미지(JDK + Node.js 18 이상)로 바꾸세요. Jenkins 는 Pipeline 기본 단계(sh·bat·archiveArtifacts)만 쓰며 에이전트에 JDK·Maven·Node.js 가 있어야 합니다.
생성 .gitlab-ci.yml 은 테스트에서 GitLab 공식 CI 스키마로 검증하고, Jenkinsfile 은 Declarative 구조를 단언합니다(실제 Jenkins 실행 검증은 보류). 설계: docs/design-cli.md.

폐쇄망에서 쓰기 (오프라인 번들)

공공 개발 환경은 대부분 망분리라 인터넷 PC 에서 받은 자료를 반입해 씁니다. 이 서버가 실행 중에 인터넷을 쓰는 곳(공통컴포넌트 아카이브·Initializr zip 템플릿 다운로드, OSV 취약점 조회, 재조립 원본 태그 조회)을 번들 하나로 대신합니다.

# 1) 인터넷 PC — 번들 만들기(≈110MB: OSV 10 · 아카이브 45 · web 템플릿 15 · 태그 미러 37, 템플릿 12종 전부면 ≈150MB)
npx -y egovframe-scaffold-mcp bundle --output-dir ./egov-bundle --write
npx -y egovframe-scaffold-mcp bundle --output-dir ./egov-bundle --templates web,boot-web --write   # 템플릿 골라 담기

# 2) 폐쇄망 PC — 옮긴 디렉터리를 지정(MCP 클라이언트 설정의 env 에도 같은 값)
export EGOVFRAME_OFFLINE_BUNDLE=/opt/egov-bundle        # cmd: setx EGOVFRAME_OFFLINE_BUNDLE D:\egov-bundle

번들 항목	대신하는 것	검증
`osv/Maven-all.zip` (OSV Maven 전체 덤프)	`offline=false` 의 OSV 조회(`check_egovframe_dependencies`·`generate_egovframe_sbom`·`check_egovframe_sbom`·평가서)	결과에 "스냅숏 YYYY-MM-DD 기준" 표시, 30일(`EGOVFRAME_BUNDLE_MAX_AGE_DAYS`) 넘으면 경고
`archives/…-7912e13ca5a0.zip` (공통컴포넌트 v5.0.7)	`add_egovframe_components`·재조립·업그레이드의 아카이브 다운로드	카탈로그 고정 sha256·크기·파일 수
`templates/<id>.zip` (Initializr zip 템플릿)	`create_egovframe_project` 의 zip 템플릿	템플릿 고정 sha256·크기
`origin/…git` (공식 태그 22개, 내용 포함)	재조립·리허설의 원본 태그 식별·패치	원격 조회 없이 로컬 미러만

번들 파일은 쓸 때마다 manifest 의 sha256·크기와 대조하고 다르면 거부합니다. 번들에 없는 URL 은 평소처럼 네트워크로 가므로, 저장소 템플릿(simple-backend 등)이 필요하면 --templates 로 지정해 함께 담으세요. Maven 의존성 jar 는 번들에 넣지 않습니다 — 기관 Nexus·Artifactory 미러를 settings.xml 에 지정하세요. upstream 대조 도구(sync_egovframe_*)와 가이드 문서 조회는 인터넷이 필요합니다. 설계: docs/design-offline-bundle.md.

리소스·프롬프트 (MCP Resources/Prompts)

도구(tools)뿐 아니라 MCP의 리소스·프롬프트도 제공합니다 (MCP 3대 프리미티브 완비).

Resources (읽기 전용) — 지원 클라이언트에서 도구 호출 없이 카탈로그를 탐색·인용:

모든 도구는 MCP annotations(readOnlyHint·destructiveHint·idempotentHint·openWorldHint)와 ko/en title 을 노출합니다 — 읽기 전용 14종(목록·검색·진단·검증·리포트·점검·upstream 대조), 파괴 가능 4종(remove_egovframe_components·upgrade_egovframe_project·migrate_egovframe_project(apply)·generate_agents_md(overwrite)), 네트워크 사용 도구는 openWorldHint. diagnose_egovframe_project·validate_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network 는 outputSchema 를 선언하고 structuredContent 로 같은 결과를 구조화해 돌려줍니다(text 는 그대로).

egovframe://catalog/components · egovframe://catalog/components/{id} · egovframe://catalog/templates · egovframe://catalog/recipes · egovframe://catalog/ai-components · egovframe://catalog/config-templates · egovframe://catalog/migration-rules · egovframe://catalog/dependency-baseline

Prompts — 가이드형 워크플로: scaffold_board_login, scaffold_ai_chatbot, scaffold_portal, maintain_existing

레시피 — 자주 쓰는 조합을 한 번에 조립합니다. 예: apply_egovframe_recipe(recipeId="board-login", projectName="my-egov-app", outputDir="~/work"). 목록은 catalog/recipes.json에서 관리하며 기여 환영합니다.

MCP Registry

MCP Registry 용 메타데이터는 저장소의 server.json(이름 io.github.EricSeokgon/egovframe-scaffold-mcp)과 package.json 의 mcpName 이며, npm run test:registry 가 두 파일의 이름·버전·npm 좌표 일치를 검사합니다. 등록은 npm 배포 뒤 저장소 루트에서:

mcp-publisher login github     # GitHub device flow — io.github.EricSeokgon/ 네임스페이스 권한
mcp-publisher publish          # server.json 을 레지스트리에 게시
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.EricSeokgon/egovframe-scaffold-mcp"

버전을 올릴 때 server.json 의 version·packages[0].version 도 함께 올립니다(릴리스 절차 참조).

보안 설정 — 허용 root (선택)

환경변수 EGOVFRAME_ALLOWED_ROOTS를 설정하면, 모든 도구의 디렉터리 인자(outputDir·projectDir)가 지정한 root 내부일 때만 실행됩니다. 미설정 시 기존과 동일하게 제한이 없습니다.

// MCP 클라이언트 설정 예 (여러 root는 OS 경로 구분자로 연결: POSIX ":", Windows ";")
{ "mcpServers": { "egovframe-scaffold": {
    "command": "npx", "args": ["-y", "egovframe-scaffold-mcp"],
    "env": { "EGOVFRAME_ALLOWED_ROOTS": "/home/user/workspaces" }
} } }

검사는 realpath 기준이라 symlink를 통한 우회도 차단합니다.
위반 시 도구는 아무 파일도 만들지 않고 AllowedRootsError(허용 root 목록 포함)로 거부합니다.
transaction 실패 메시지에는 사람용 문구와 함께 기계가 읽을 수 있는 rollback-report: {...} JSON 한 줄(복원·제거·정리 건수, 실패 목록)이 포함됩니다.

검증

함수 레벨: 실제 템플릿(약 296파일) 생성, pom 좌표·DbType 적용, 중복 생성 거부, dryRun 미리보기(무기록) 확인 (npm run smoke)
Maven 좌표 레벨: 프로젝트 직접 groupId/artifactId/name만 변경하고 parent·dependency artifactId 보존 (npm run test:pom, 네트워크 불필요)
카탈로그 레벨: schema v2, 고정 source/archive 지문, 자산 메타데이터, 무결성·위상 정렬·미리보기 검증 (npm run test:catalog, npm run test:catalog-sync, 네트워크 불필요)
zip 조달 레벨: 자리표시자 치환·globals 경로 판별·12종 정의 유효성(npm run test:pom, 네트워크 불필요), batch-file-commandline 실생성으로 지문 검증·좌표·DbType·zip 루트 보존, 지문 불일치 거부와 무기록, ref 지정 시 검증 생략 표시(npm run test:templates, 네트워크 필요, CI 실행)
설정 생성 레벨: 동봉 템플릿 지문·카탈로그 무결성, 49건 전 형식 기본값 렌더링, 분기·필드 덮어쓰기, 필드·선택지·파일명·패키지 거부, dryRun 무기록, 충돌 거부, 비밀번호 가림, ..·절대경로·symlink 이탈 거부, CRLF 체크아웃 시뮬레이션 (npm run test:config, 506단언, 네트워크 불필요)
템플릿 카탈로그 레벨: catalog/templates.json 스키마·커버리지 계산·큐레이션 매핑 정합·변환기·upstream 차이 계산(추가/삭제/필드 변경) 검증 (npm run test:template-catalog, 256단언, zip 지문·동봉 설정 템플릿 drift·LFS 포인터 해석 포함, 네트워크 불필요)
동기화 레벨: 공식 v5.0.7 태그→commit, SHA-256·크기·파일 수, sec.security, 미매핑 경로 0건 검증 (npm run test:catalog-sync-live, 네트워크 필요)
조립 레벨: 실제 공통컴포넌트 저장소로 bbs+login+sec.security(+cmm) 843파일 조립, message·IDGN·웹 자산·공용 fragment·Maven 좌표·선별 DB 스크립트·충돌 전체 거부·파일/SQL/매니페스트 fault-injection rollback·상위 symlink 경계 검증 (npm run test:components)
수명주기 레벨: 설치 매니페스트 기록, 중복 설치 거부, 의존 컴포넌트 제거 보호, 제거·검증 동작 (npm run test:components)
프로토콜 레벨: 빌드된 서버를 실제 프로세스로 띄워 MCP initialize / tools/list 핸드셰이크, serverInfo.version↔package.json 일치, 핵심 도구 노출, jdk 패턴 제약 노출 확인 (npm run test:handshake, 네트워크 불필요)
릴리스 레벨: 배포 판정(버전·server.json·변경 이력·태그·npm 네 조건)과 릴리스 노트 추출, npm pack --dry-run 의 tarball 내용(포함·제외·크기 상한), server.json 설명 100자 제한 (npm run test:release·npm run test:registry, 네트워크 불필요); CI 통합이 mcp-publisher validate 로 레지스트리 스키마를 실제 검증
플랫폼 레벨: CI가 릴리스 게이트를 ubuntu·windows × Node 18·20·22 매트릭스로 실행하고, 공식 저장소를 내려받는 통합 테스트는 ubuntu/Node 20에서 실행합니다. 타임아웃 시 프로세스 트리 종료는 POSIX·Windows 모두 실제 프로세스로 검증합니다 (npm run test:build).
레시피 레벨: catalog/recipes.json의 컴포넌트 id·의존성·템플릿 제공 컴포넌트 정합 검증 (npm run test:recipes, 네트워크 불필요). 공식 simple-backend의 기존 cmm을 보존하고 board-login의 bbs 88파일·login 41파일·SQL 4건(총 133파일)을 조립한 뒤 검증하며, 컴포넌트 이후 fault injection의 전체 staging rollback도 확인 (npm run test:recipe-transaction)
진단 레벨: 픽스처(pom·DbType·컴포넌트 패키지)로 diagnose_egovframe_project의 빌드·버전·DbType·컴포넌트 지문·의존성 검출 검증 (npm run test:diagnose, 네트워크 불필요)
전환 진단 레벨: 3.10 스타일 픽스처(pom·gradle·java·Spring XML·MyBatis XML·web.xml·JSP)에서 항목 종류·auto/manual·라인·대응 좌표를 단언하고, 5.x 스타일 픽스처에서 항목 0건과 진단 전후 디스크 불변을 확인 (npm run test:migrate, 87단언, 네트워크 불필요). 규칙 카탈로그는 스키마·좌표 규칙성·제거 클래스의 대체가 동봉된 5.x 소스 트리에 존재하는지·JDK 내장 javax.* 제외·큐레이션과 생성물 일치를 검증 (npm run test:migration-rules, 579단언, 네트워크 불필요). 목적지 좌표(RTE 5.x 24종·3.x 원본 18종·parent 2종·Jakarta 좌표)가 표준프레임워크 Maven 저장소와 Maven Central 에 실제로 존재하는지는 CI 통합 job 에서 확인 (npm run test:migration-rules-live, 61건, 네트워크 필요)
전환 검증 레벨: 공통컴포넌트 대응표 판정(제거·이동·사용자 클래스 무시), 재조립 권고와 skipComponents, linkBuildError 8케이스(심볼·패키지 부재·라인 근접·규칙 심볼·javax 부재·무관), javac symbol:/location: 파싱(maven·gradle), 가짜 runner 로 verify 결과·작업 목록·Markdown·빌드 파일 없음 (npm run test:migrate 에 포함, 총 162단언). 실제 mvn compile 오류 3건이 수동 항목 2건에 전부 연결되는지는 CI 통합 job (npm run test:migrate-integration)
전환 적용 레벨: 3.10 픽스처에 대해 auto 항목의 편집 원문 일치, dryRun 무기록, fault-injection 롤백(내용·mtime 불변), 적용 후 pom·java·XML·web.xml·gradle·JSP 내용, 백업·migration-plan.json, 재적용 무기록, manual 항목 불변을 단언 (npm run test:migrate, 132단언, 네트워크 불필요). 3.10 좌표·javax 픽스처를 적용한 뒤 JDK 17 로 mvn compile 통과는 CI 통합 job 에서 확인 (npm run test:migrate-integration, 네트워크·JDK·Maven 필요)
의존성 점검 레벨: 기준 카탈로그 스키마·출처 sha256·RTE 5.x 모듈·BOM 계열, 분류 함수 12케이스, 3.10·5.x parent·gradle·빈 디렉터리 픽스처, OSV 모의 질의·매핑·실패 처리, 디스크 불변 (npm run test:dependencies, 68단언, 네트워크 불필요). 실제 OSV 조회는 CI 통합 job (npm run test:dependencies-live)
네트워크 진단 레벨: 오류 분류 8종, 프로브·DNS 주입으로 7가지 시나리오(전부 도달, 405/404/407/503, 프록시+타임아웃, 프록시 없음+IPv6 혼재, TLS, DNS, 필터)의 처방·안내·자격 증명 가림·셸별 명령을 단언하고, fetchWithTimeout 실패 메시지에 처방이 붙는지 확인 (npm run test:network, 33단언, 네트워크 불필요). 실제 호스트 7종 프로브는 CI 통합 job (npm run test:network-live)
AGENTS.md 레벨: 5.x(매니페스트·래퍼·컴포넌트 2종·백업 디렉터리)와 3.x gradle 픽스처, 빈 디렉터리에서 사실 수집·ko/en 렌더링·dryRun 무기록·기존 파일 거부·overwrite·파일명 검증·staging 정리 (npm run test:agents-md, 22단언, 네트워크 불필요)
레지스트리 메타데이터 레벨: server.json ↔ package.json 의 이름(mcpName)·버전·npm 좌표·스키마 URL·환경변수 문서화 정합 (npm run test:registry, 네트워크 불필요)
프로토콜 레벨(추가): EGOVFRAME_LANG=en 으로 띄운 서버의 도구 32종 설명이 모두 영문이고 표에 빠진 도구가 없는지, tools/list 에 title·annotations(readOnly 13종·destructive 5종)·outputSchema 11종이 노출되는지 확인 (npm run test:handshake)
SBOM·해석 레벨: Maven·Gradle 트리 파서(실제 출력 픽스처), resolve=true 의 전이 항목·경로·선언/해석 차이·실패 경로, CycloneDX 문서 구성·보강·취약점 병합·출력 경로 거부·overwrite·dryRun (npm run test:dependencies, npm run test:sbom, 네트워크 불필요); CI 통합이 공식 egovframe-web 템플릿을 실제 Maven 으로 해석하고 SBOM 을 생성 (npm run test:sbom-live)
오프라인 번들 레벨: Maven 버전 비교(숫자·한정자 순서·같은 표기), OSV 범위(여러 구간·fixed·last_affected), 덤프 색인(Maven 만·철회 제외·GIT 범위 무시)과 querybatch 같은 모양의 결과, 번들 만들기(dryRun·manifest 지문·고정 지문 불일치 거부·실패 시 무흔적·덮어쓰기 거부·로컬 git 원본 미러), 번들 읽기(fetch 훅·POST 제외·변조 거부·깨진 manifest), 원본 미러(태그·커밋·트리·blob, 없는 태그 안내), OSV 출처 노트와 30일 경고, 의존성 점검 연동, 네트워크 진단 처방 (npm run test:offline-bundle, 30단언, 네트워크 불필요); CI 통합이 실제 번들을 만들고 로컬 OSV 와 온라인 OSV 를 대조(97% 이상 일치 요구, 실측 100%)한 뒤 fetch 를 막고 생성·조립·재조립 미리보기·SBOM 재점검을 번들만으로 확인 (npm run test:bundle-live)
전환 리허설 레벨: pom 맞춤(parent 추가·교체, 누락 좌표, 버전·scope, parent 관리 속성, 주석·dependencyManagement·plugin 제외, 멱등), 누락 패키지·연쇄·수동 항목 분류와 후보 좌표, Maven fork 형식·경고 제외 파서, 사본 제외 규칙·원본 지문 불변, 단계 순서(재조립 → 적용 → 컴파일 → pom 맞춤 → 컴파일)·javac 상한 해제 인자, 단계 실패 계속, 기록과 평가서 6절 (npm run test:rehearse, 38단언, 네트워크 불필요); CI 통합이 공식 공통컴포넌트 v4.3.2 전체 트리를 실제로 리허설해 재조립·적용 수와 오류 6,003(±10%, 누락 패키지·연쇄 95% 이상)→≤5 를 단언 (npm run test:rehearse-live)
SPDX 레벨: 실제 플러그인 출력 고정물을 SPDX 2.3 으로 바꿔 공식 spdx-spec v2.3 스키마 통과, 패키지 68·DEPENDS_ON 간선 수 = CycloneDX 의존 간선·의존 없음 NONE·체크섬·라이선스(LicenseRef)·DESCRIBES, 되읽었을 때 최소 요소 요소별 충족 수·purl·의존 간선·기준 판정(annotations)·취약점(advisory) 보존, 다른 도구 모양 SPDX(DEPENDENCY_OF·NOASSERTION·여러 DESCRIBES·Person/Organization/Tool)의 필드 대응, bomFormat="spdx-json" 생성·SPDX 입력 점검(형식 판별·CycloneDX 와 같은 판정·SPDX↔CycloneDX 비교 차이 0·VEX 거부)·outputSchema (npm run test:spdx, 43단언, 네트워크 불필요). 실제 Maven SBOM 의 SPDX 판정 일치는 CI 통합 test:sbom-live 가 확인
SBOM 운영 레벨: 실제 플러그인 출력 고정물(공식 web 템플릿 67 component)로 최소 요소 7종(빠진 항목별)·공급자 표 보완·purl 재판정·가짜 OSV(새/사라진 ID)·비교(추가·제거·버전·판정·취약점)·VEX 생성/판단 보존/같은 ID 의 새 영향 component·깨진 VEX 중단을 단언하고, 생성 SBOM·VEX 를 CycloneDX 1.6 공식 JSON 스키마(specification 1.6.1)로 검증 (npm run test:sbom-check, 54단언, 네트워크 불필요); CI 통합이 실제 SBOM 으로 보완 필요(주 component 공급자·작성자) → supplier·author 로 보완(환경에 따른 다른 공백은 info: 로그), 두 SBOM 비교 차이 0, 실제 OSV VEX 초안·판단 보존을 확인 (npm run test:sbom-live)
메타데이터·구조화 출력 레벨: TOOL_META ↔ 등록 도구 일치, 읽기 전용·파괴·네트워크 힌트 배정, 영문 title, 7종 도구의 실제 결과(진단·검증·전환 진단/적용·의존성·네트워크·리포트, 빈 프로젝트 포함)가 outputSchema 를 통과하고 최상위 키가 전부 선언돼 있으며 잘못된 값은 거부 (npm run test:output-schemas, 47단언, 네트워크 불필요). MCP 프로토콜 경유 호출 시 SDK 가 structuredContent 를 스키마로 검증합니다
테스트 이식성 레벨: scripts/check-test-portability.mjs 가 test/*.mjs 에서 Windows 에서 깨지는 가정(정규화 없는 path.relative 비교, ./mvnw 리터럴 기대값, POSIX 절대 경로)을 찾아 실패시킵니다(npm run check:portability, 게이트 포함, 의도된 줄은 // portability: ok <사유>). 플랫폼 분기 함수(resolveCommand·collectAgentsFacts)는 platform 주입으로 linux·win32 양쪽을 단언합니다
문서 검색 레벨: search_egovframe_docs의 키워드 매칭·점수 정렬·컴포넌트 매핑·빈질의/미존재어 처리 검증 (npm run test:docs, 네트워크 불필요)
리포트 레벨: 픽스처로 generate_egovframe_report의 컴포넌트·테이블·가이드 링크 렌더링 검증 (npm run test:report, 네트워크 불필요)
평가서 레벨: 등급 산식 경계(구간·등급)와 리포트 숫자로의 재계산, 3.x(공통컴포넌트 소스·교체 라이브러리·http 저장소·벤더)·4.x 소형·5.x parent 픽스처의 절별 내용과 등급(5.x 는 전환 범위 0·A), OSV 조회·실패 시 취약점 요인, SBOM 요약·깨진 파일, 절 조립·중복 제거, outputPath 저장·dryRun·기존 파일/프로젝트 밖/절대 경로/symlink/.md 아님 거부, structuredContent 스키마 (npm run test:assessment, 55단언, 네트워크 불필요). CI 통합이 공식 5.x 템플릿 2종에서 전환 A 를 확인 (npm run test:dependencies-live)
CLI 레벨: 인자 해석(--x·--x=v·--no-x)·스키마 형 변환·모르는 옵션, --fail-on 등급·임계값·오류, 종료 코드 0/2/3/64, 쓰기 옵션 차단, --json = 라이브러리 결과, --out·--step-summary, 실제 프로세스(인자 유무로 서버/CLI) (npm run test:cli, 32단언, 네트워크 불필요). CI 생성 레벨에 공급망 게이트 job·failOn 주입 거부 추가(npm run test:ci), CI 통합에서 생성 워크플로를 actionlint 로 검사하고 4.3.2 코퍼스 트리로 CLI 평가서를 실행해 job 요약에 등급을 남깁니다
재조립 레벨: 메모리 원본 저장소로 원본 태그 식별(세대 후보·지정·없는 태그), 8가지 판정(CRLF 체크아웃 포함)·처리, dryRun 무기록, 적용 후 파일·백업·자산 참고본·패치(원문 바이트 보존)·매니페스트·계획 파일, validate 누락 0, 매니페스트 관리 컴포넌트 거부, fault-injection rollback, 목표 내용 blob 불일치 거부, verify 오류 연결 (npm run test:reassemble, 46단언, 네트워크 불필요). CI 통합이 공식 v3.10.0 트리의 cmm·bbs 를 고친 픽스처를 실제 git 원본·sha256 검증 아카이브로 재조립해 v5.0.7 tree 일치·패치·validate·upgrade 변경 0 을 확인 (npm run test:reassemble-live)
회귀 코퍼스 레벨: 공식 공통컴포넌트 v3.10.0·v4.3.2 부분 트리(커밋 고정, sparse 클론, 캐시)에 진단·dryRun 적용·의존성 점검·평가서를 돌려 catalog/migration-corpus.json 기대값과 ±1% 안인지, 세대 판정·확인 필요 클래스 0·기준 없음은 xerces 뿐·계획=자동 전부·재조립 권고·등급 D/D·60초 미만을 단언 (npm run test:migrate-corpus, 20단언, git·네트워크 필요, CI 통합). 기대값 갱신은 npm run generate:migration-corpus(--check 는 차이만)
업그레이드 레벨: 3-way 판정 6분류(unchanged/update/user-modified/conflict/added/removed)·v1 보수모드·정상 적용/백업 계획·파일/매니페스트 fault-injection rollback·상위 symlink 경계 검증 (npm run test:upgrade, 네트워크 불필요)
컴포넌트 설명 레벨: explain_egovframe_component의 의존성(직접·전이)·역의존·테이블·가이드 URL·미존재 예외 검증 (npm run test:explain, 네트워크 불필요)
CI 생성 레벨: generate_egovframe_ci의 maven/gradle 감지·YAML·dryRun 무기록·기존 파일 거부·빌드파일 부재 예외·jdk·failOn·supplier·환경 변수 주입 입력 거부, 세 플랫폼 공통 게이트 명령(sbom → sbom-check → assess), 생성 .gitlab-ci.yml 의 GitLab 공식 CI 스키마(v19.4.1-ee 고정물) 통과, Jenkinsfile 의 Declarative 구조(pipeline·agent·options·stages·post, 괄호 짝, 단계 순서)·Windows 경로 이스케이프, 공급자 단서 없을 때 게이트 실패 예고 (npm run test:ci, 네트워크 불필요)
CRUD 생성 레벨: 공식 wizard 그룹, Classic/Boot 분기, DB 생성키, JUnit 5, dryRun, PK·경로 검증, 충돌 시 전체 무기록 검증 (npm run test:crud, 네트워크 불필요)
CRUD 컴파일 레벨: 공식 simple-backend/Boot CRUD 7파일과 web-sample/Classic CRUD 9파일 생성 → JDK 17에서 mvn -q -DskipTests compile (npm run test:crud-integration, 네트워크 필요, CI 실행)
안전성 레벨: 19개 도구 공통 허용 root의 미설정 호환·격리·.. 이탈·symlink 우회·다중 root·비대상 인자 무해 6케이스와 구조화 rollback 필드를 검증합니다 (npm run test:allowed-roots, npm run test:transaction, 네트워크 불필요).

현재 지원 범위와 알려진 제약

공통컴포넌트 실행 자산과 Maven 좌표 탐지는 지원합니다. 기존 pom.xml·web.xml의 구조적 노드 병합은 프로젝트별 dependency management·설정 경로를 보호하기 위해 자동 수행하지 않습니다.
카탈로그는 공식 v5.0.7 태그·commit·archive 지문에 고정됩니다. 최신 main 변경은 sync_egovframe_catalog(ref="main") 결과를 검토한 뒤 생성 스크립트로 승격합니다.
build_egovframe_project·test_egovframe_project는 로컬에 설치된 JDK와 maven/gradle(또는 프로젝트 래퍼)을 사용합니다. DB 등 외부 의존성이 필요한 테스트는 그 환경이 준비되지 않으면 오류(error)로 집계됩니다.
자바 패키지 구조 변경(groupId에 맞춘 소스 디렉터리 이동)은 미지원입니다. 현재는 IDE rename refactoring을 권장합니다.
migrate_egovframe_project 의 적용은 진단이 auto 로 표시한 항목만 치환합니다. 정적 텍스트 스캔이므로 리플렉션·문자열 조립으로 만든 클래스명, 프로젝트 밖 라이브러리 안의 javax 사용, Spring Security 6·Hibernate 6 등 라이브러리 자체의 API 변경으로 인한 코드 수정 범위는 보고하지 않습니다(라이브러리 단위로 manual 안내만 합니다).
템플릿·컴포넌트·가이드 원본을 받을 때 GitHub(codeload.github.com, raw.githubusercontent.com, zip 조달 템플릿은 media.githubusercontent.com) 네트워크 접근이 필요합니다.

로드맵

v0.31.0까지 프로젝트·CRUD 생성, 검증된 공통컴포넌트 실행 자산 조립, 안전성 기반(테스트 판정 강제·사용자 파일 보호·전 도구 트랜잭션·허용 root·구조화 rollback 보고), 생성→검증 루프(실제 빌드·오류 구조화·테스트 리포트 구조화), 공식 템플릿 카탈로그 단일화와 커버리지 확대(22종 중 21종), 설정 파일 생성, 5.x 전환(진단·적용), 의존성 점검, 운영 편의(네트워크 진단·AGENTS.md·영문 설명·레지스트리 메타데이터)를 완료했습니다.

v0.32–v0.34 로 MCP 프로토콜 현대화, 5.x 전환 3단계(검증)와 공통컴포넌트 대응표, 의존성 기준 완성과 규칙·기준 drift 감시를, v0.35–v0.37 로 릴리스 자동화, 해석된 의존성 트리와 SBOM, 전환 준비도 평가서와 회귀 코퍼스를, v0.38–v0.40 으로 공통컴포넌트 재조립 실행, CLI 모드와 CI 공급망 게이트, SBOM 운영(최소 요소·비교·VEX)을, v0.41–v0.43 으로 전환 리허설, 폐쇄망 오프라인 번들, GitLab·Jenkins CI 와 SPDX 를 마쳤습니다(기획 원문과 결과: v0.41–v0.43 · v0.38–v0.40 · v0.35–v0.37). Homebrew 탭은 후순위에서 내렸습니다(npx 로 충분).

バージョン	主な機能	目標
v0.20 完了	`generate_egovframe_crud`	公式 `wizard.xml` のグループとパス入力、VO・Mapper（XML）・Service・Controller・JSP（選択式）、Classic/Boot、JUnit 5、dryRun・競合の原子的な拒否を実装。オフラインテストと公式 simple-backend/Boot・web-sample/Classic の Maven compile に合格
v0.21 完了	`sync_egovframe_catalog` + コンポーネントの完全組み立て	common-components v5.0.6 のタグ／commit／archive を固定、190項目、message・IDGN・scheduling・静的アセット・web fragment の組み立て、Maven 座標の検出、sec.security・未マッピングパスの検証、マニフェスト v3
v0.22 完了	全ツールの安全性基盤	すべての書き込み経路をtransaction化、ユーザーファイルを保護、全ツールで許可 root を適用、symlink/junction による逸脱を防止、構造化 rollback レポート
v0.23 完了	`build_egovframe_project`	Maven/Gradle・ラッパー（mvnw/gradlew）を自動検出、タイムアウト・ログ上限、ファイル／行単位のエラー構造化により、生成→検証のエージェントループを完成（PR #18）。`test_egovframe_project` は v0.25 で完了
v0.24 完了	公式テンプレートのカバレッジ拡大（7 → 10種）	Initializr カタログ（22項目）との照合により、未対応の公式アセットを特定し、`msa-common-components`（KRDS）・`mobile-device-api`・`ai-rag` を追加。すべてをマルチプロジェクトとして扱い、座標／DB の自動書き換えをスキップしてサブモジュール参照を保護し、実際のアーカイブをダウンロードする統合テストで検証
v0.25 完了	`test_egovframe_project`	テスト実行後に JUnit XML レポート（surefire `target/surefire-reports`、gradle `build/test-results/test`）を読み取り、スイート・ケース単位で集計。失敗メッセージ・例外型・テストファイル／行、`testFilter`、古いレポートの除外に対応し、終了コードが 0 でもレポートに失敗があれば失敗と判定
v0.26 完了	IDE・Initializr・MCP 共通カタログ	Initializr `templates-projects.json`（22種）、MCP `TEMPLATES`（10種）、Development `wizards.xml`（8カテゴリ）を `schemaVersion: 1` の単一スキーマ `catalog/templates.json` に統合。変換器（`fromInitializr`・`fromMcpTemplates`）とキュレーションマッピング（`catalog/template-mapping.json`）、upstream 照合ツール `sync_egovframe_templates` により、カバレッジの差を手作業で比較せずに確認
v0.27 完了	公式テンプレートのカバレッジ拡大（10 → 22種）	統合カタログで算出した未対応 13種のうち、12種を Initializr zip（Git LFS）の取得により追加。commit・sha256・サイズの固定とダウンロード検証、pom プレースホルダーの置換、テンプレートごとの `globals.properties` パス対応、`sync_egovframe_templates` による zip フィンガープリントの drift レポート
v0.28 完了	`generate_egovframe_config`	Initializr 設定テンプレート 21種（Handlebars）を commit・sha256 固定で同梱し、オフライン生成に対応。xml・javaConfig・yaml・properties、Initializr フォームと同じフィールド・デフォルト値、選択肢・ファイル名・パッケージの検証、既存ファイルの拒否、`sync_egovframe_templates` による同梱テンプレートの drift レポート
v0.29 完了	`migrate_egovframe_project`（第1段階：診断）	3.x/4.x プロジェクトを 5.x（Jakarta）基準でスキャンし、RTE 座標・パッケージ・削除／移動クラス・`javax→jakarta`・web.xml・XML 名前空間・ライブラリ移行項目を、読み取り専用で auto/manual に分類してレポート。ルールは `egovframe-runtime` の3タグ比較から生成（`catalog/migration-rules.json`）。移行先座標は CI で実際のリポジトリと照合
v0.30 完了	`migrate_egovframe_project`（第2段階：適用）+ `check_egovframe_dependencies`	診断の auto 項目を原文のオフセット編集で transaction 適用（バックアップ・デフォルトで dryRun・計画ファイル・失敗時の復旧、適用後に JDK 17 `mvn compile` を CI 検証）。公式 5.x parent から抽出した基準（管理対象座標 139種 + BOM 系列 7種）に対する依存関係の照合、セキュリティ設定の存在確認、任意の OSV 照会
v0.31 完了	運用の利便性	`diagnose_egovframe_network`（7種のホストプローブ・失敗分類・シェル別の対処法、ダウンロードエラーメッセージに対処法を付加）、`generate_agents_md`（ko/en）、英語版 README と `EGOVFRAME_LANG=en` のツール説明、MCP Registry `server.json`・`mcpName`・整合性テスト
v0.32 完了	MCP プロトコルの最新化	`registerTool` に移行（deprecated の `tool()` は0件）、27種のツールに ko/en `title`・annotations（readOnly 14・destructive 4・openWorld）、5種に `outputSchema`+`structuredContent`、テストの移植性検査スクリプト（ゲート）とプラットフォーム注入アサーション
v0.33 完了	`migrate_egovframe_project` 第3段階：検証	`verify=true` により、compile エラーと手動項目を結び付けた作業リストを生成（javac symbol/location の解析、4段階の関連付け）。共通コンポーネント 3.x→5.x 対応表（削除 54・移動 4、schemaVersion 2）と再組み立ての推奨・`skipComponents`
v0.34 完了	依存関係基準の完成 + drift 監視	Spring Boot BOM 全体（1,473種）・RTE モジュールの推移的依存関係（58種）を基準に含め、項目ごとに基準の出典を表示。`vendor` 分類・EOL 座標の置換ルールにより、共通コンポーネント 3.10 の pom における `unknown` を17 → 1に削減。`sync_egovframe_templates` がルール・基準カタログの upstream drift（新しいタグ・新しい parent・pom sha256）と更新手順をレポート
v0.35 完了	リリース自動化（配布サプライチェーン）	`release.yml`：`main` の CI 成功 → 4条件の検査 → npm（OIDC trusted publishing、provenance）→ そのコミットにタグを付与 → GitHub Release（変更履歴を抽出）→ MCP Registry（OIDC）。`test:release`（判定・ノート・tarball の内容・サイズ）、`server.json` の説明文を100文字に制限、CI 統合に `mcp-publisher validate`
v0.36 完了	解決済み依存関係ツリー + SBOM	`check_egovframe_dependencies(resolve=true)`：Maven `dependency:tree`・Gradle `dependencies` により、推移的依存関係まで判定（`origin`・`via`・`differs`）。新しいツール `generate_egovframe_sbom`（28種）：CycloneDX 1.6 JSON（Maven プラグイン／Gradle ツリー構成）+ 基準判定プロパティ + OSV `vulnerabilities[]`。公式 web テンプレートの解決結果は65 artifact・SBOM は67 component・OSV は24件
v0.37 完了	移行準備状況レポート + 回帰コーパス	`generate_egovframe_report(sections=["assessment"])`：概要・移行範囲・依存関係への対応・セキュリティ・SBOM・A–D 評価（計算式を表示、再計算テスト）、json・outputPath。`test:migrate-corpus`：公式共通コンポーネント v3.10.0・v4.3.2 の部分ツリー期待値を固定（±1%、CI）、4.x→5.x の実アセットを初確認。リリースワークフローを再開（npm gitHead タグ）
v0.38 完了	共通コンポーネントの再組み立て実行	評価レポートの「再組み立ての推奨」を実行する `reassemble_egovframe_components`：3.x/4.x のソースの元タグをフィンガープリントから特定して3-way比較（元・現在・5.0.7）→ 最新の共通コンポーネント v5.0.7（`7912e13`）で組み立て + ユーザーの変更はパッチ・作業リストとして保持。マニフェストを生成（以降 upgrade・validate を適用）、dryRun・transaction・compile 検証
v0.39 完了	CLI モード + CI サプライチェーンゲート	`npx egovframe-scaffold-mcp <assess\|check\|sbom\|migrate\|validate>` — AI クライアントなしで CI・バッチから同じ分析を実行（JSON/Markdown、`--fail-on` 評価などの判定しきい値、終了コード）。`generate_egovframe_ci` のサプライチェーンゲート段階（評価レポート・SBOM アーティファクト）、SDK 1.32（プロトコル 2025-11-25）
v0.40 完了	SBOM 運用：最低限の要素・比較・VEX	`check_egovframe_sbom`：既存 SBOM の最低限の要素（サプライヤー・コンポーネント名・バージョン・一意識別子・依存関係・作成者・生成日時）を満たすか確認。ビルドツールなしで purl による OSV 再照会、以前の SBOM との比較（追加・削除・バージョン変更・新たな脆弱性）、CycloneDX VEX の草案生成。`generate_egovframe_sbom` にサプライヤー・作成者のメタデータを追加 — 2027年の公共 SBOM 提出制度化に備える
v0.41 完了	移行リハーサル	`rehearse_egovframe_migration`：プロジェクトのコピーで migrate apply → reassemble → JDK 17 compile を実行し、残るコンパイルエラーの数・分布と「対応によって最も多くのエラーを減らせる作業」リストを実測（元のプロジェクトは変更なし）。評価レポートの評価の横に実測値を表示、CLI `rehearse` — 公式共通コンポーネント v4.3.2 の全ツリー期待値を固定
v0.42 完了	閉域網での運用：オフラインバンドル	`prepare_egovframe_offline_bundle`：OSV Maven ダンプ・固定コンポーネントアーカイブ・Initializr zip・元タグミラー + sha256 manifest。`EGOVFRAME_OFFLINE_BUNDLE` によりすべてのダウンロード・OSV 照会をバンドルで代替（スナップショット基準日を表示・古い場合は警告）
v0.43 完了	CI・提出形式の多様化	`generate_egovframe_ci(platform=gitlab\|jenkins)`（GitLab 公式スキーマに準拠・Declarative Jenkinsfile）と、3つのプラットフォームゲートに `sbom-check --fail-on minimum` を追加。社内 npm レジストリ・オフラインバンドルの変数、SBOM SPDX 2.3 JSON の出力・検査（公式 spdx-spec v2.3 スキーマ、実際の Maven SBOM で CycloneDX と判定が一致）

다음 버전 기획 (v0.41–v0.43)

v0.40.0 까지 끝난 상태(2026-10-07, 도구 30종 + CLI 명령 8종, 테스트 약 1,600건, npm 0.40.0 자동 배포)에서 다음 세 릴리스를 아래 순서로 진행합니다. 공통 원칙은 이전과 같습니다 — 규칙은 데이터로, 근거는 공식 저장소에서, 쓰기 도구는 dryRun·transaction, 각 버전은 "완료 정의"를 만족해야 릴리스합니다. 이번 세 버전의 공통 주제는 현장에서 그대로 쓰기 입니다 — 자동 단계를 모두 돌린 뒤 사람이 고칠 것이 실제로 얼마나 남는지를 사본에서 재고(v0.41), 망분리된 공공 개발 환경에서도 인터넷 없이 같은 결과를 내며(v0.42), GitHub Actions 와 CycloneDX 밖의 빌드 서버·제출 형식(Jenkins·GitLab, SPDX)으로 넓힙니다(v0.43). 선행 조사 근거는 맨 아래 "선행 조사 결과 (2026-10-07)"에 있습니다.

v0.41.0 — 전환 리허설 (`rehearse_egovframe_migration`)

목표: 평가서(v0.37)는 전환 난이도를 등급으로, migrate_egovframe_project(apply)와 reassemble_egovframe_components 는 각 단계의 실행을 맡지만, "자동 단계를 전부 돌린 뒤 컴파일 오류가 몇 개 남고, 무엇부터 고치면 가장 많이 줄어드는가"는 아직 실제로 재 보지 않습니다. 사용자 프로젝트를 건드리지 않고 사본에서 전 과정을 돌려 남는 작업을 실측합니다.

범위 (포함)

새 도구 rehearse_egovframe_migration(projectDir, steps=["migrate","reassemble","verify"], components?, sourceTag="auto", keepWorkspace=false, timeoutMs)(31번째, 프로젝트는 읽기 전용): (1) 사본 작성 — 캐시 디렉터리(EGOVFRAME_CACHE_DIR/rehearsal/<시각>)에 복사(.git·target·build·node_modules·migration-backup 제외, 원본 파일 수·바이트 기록) (2) 사본에 migrate apply → reassemble(dryRun=false) → JDK 17 compile (3) 결과 — 단계별 변경 파일 수, 컴파일 성공 여부, 남은 오류 수와 파일·패키지·오류 종류별 분포, 오류 ↔ 수동 항목·재조립 작업 목록 연결(v0.33 연결 로직 재사용), "이 작업을 처리하면 오류 N개가 사라진다" 순 상위 작업 목록. 단계 실패는 그 지점까지의 결과와 이유로 돌려줍니다.
keepWorkspace=true 면 사본 경로를 돌려 사람이 열어 볼 수 있게 하고, 기본은 끝나면 지웁니다. 원본은 실행 전후 디렉터리 지문(경로·크기·mtime)이 같음을 결과에 적습니다.
평가서 6절: 프로젝트에 리허설 결과(--out 로 남긴 rehearsal.json, 또는 generate_egovframe_report(rehearsal=true) 로 즉석 실행)가 있으면 등급 옆에 "실측: 자동 전환 후 컴파일 오류 N건"을 함께 표시합니다(등급 산식은 바꾸지 않음).
CLI rehearse(지표 errors·files·unlinked, 예: --fail-on errors>200).

범위 (제외): 남은 오류의 자동 수정(사람·AI 클라이언트의 일), 테스트 실행(컴파일까지), Gradle 멀티 프로젝트

검증 기준: 공식 공통컴포넌트 v4.3.2 전체 트리(선행 조사: 루트 pom 하나의 war 모듈, 6,523 파일, Java 1.8·Spring 5.3.37·의존성 70개)를 CI 통합에서 리허설해 자동 전환·재조립 뒤 남는 컴파일 오류 수와 상위 작업을 catalog/migration-corpus.json 에 기대값(±10%)으로 고정합니다 — v0.37 코퍼스가 "진단 항목 수"를 고정했다면 이번에는 "남는 오류 수"를 고정합니다. 원본 지문 불변, 단계별 실패 경로(가짜 runner), keepWorkspace 정리 확인.

완료 정의: 도구 31종, docs/design-migration.md 「리허설」 절, README 흐름 예시를 "진단 → 평가서 → 리허설 → 적용" 으로 갱신

결과(2026-10-08) — 완료: src/rehearse.ts. 실측(공식 공통컴포넌트 v4.3.2 전체 트리, 6,523 파일, 전 과정 약 1분): 재조립(원본 v4.3.2 식별, 교체 2,258·추가 69·삭제 62) → 전환 적용(자동 61건, 수동 38건 남음) → 컴파일 오류 6,003건(CI·JDK 17; 로컬 JDK 21 은 6,335건, 파일 503 — 4건을 뺀 전부가 누락 패키지 jakarta.annotation·org.egovframe.rte.ptl.reactive.validation·jakarta.websocket… 와 그 연쇄) → pom 맞춤(parent egovframe-web-config-parent 5.0.2 추가, 좌표 25 추가, 버전 44·scope 3 정리) → 1건(EgovCertInfoUtil — GPKI 벤더 jar 가 javax.servlet 을 참조). 계획과 달라진 점: (a) 단계 순서를 재조립 → 적용으로 바꿨습니다 — 계획대로 적용을 먼저 하면 적용이 컴포넌트 소스를 바꿔 원본 태그가 v5.0.1 로 오인되고 1,489개 파일이 사용자 수정으로 분류됩니다(실측). (b) 자동 단계 뒤 오류의 대부분이 pom 의존성이라 pom 맞춤 단계(align-pom, 사본 전용, 공식 고정 태그 pom 기준)를 더해 "코드 작업"을 분리했습니다. (c) javac 기본 상한(100)을 피하려고 Maven 은 fork + -Xmaxerrs 로 셉니다. 첫 CI 실행에서 JDK 17 이 같은 원인을 JDK 21 과 다른 모양으로 보고해(없는 패키지 import 대신 사용처마다 cannot find symbol, 다른 오류 때문에 Lombok 이 멈춰 getter 가 없음) 누락 의존성 비율이 15% 로 나왔으므로, 분석이 파일의 import 문·타입 선언 파일·Lombok 사용으로 원인을 묶게 고쳤고(두 JDK 모두 99.9%), pom 에 소스 인코딩이 없으면 -Dproject.build.sourceEncoding=UTF-8 을 줍니다(JDK 17 + POSIX 로케일의 한글 주석 오류 방지). (d) 리허설 결과는 프로젝트 안 파일이 아니라 캐시 디렉터리(EGOVFRAME_CACHE_DIR/rehearsal/records)에 남기고 평가서가 읽습니다(프로젝트 읽기 전용 유지). 함께 고친 결함: 4.x 의 org.egovframe.rte 좌표를 5.x 세대로 분류하던 문제(재조립 후보 태그가 5.x 로만 좁혀짐), Maven 출력의 [WARNING]·린트 경고 줄을 컴파일 오류로 세던 문제(build_egovframe_project·verify 에도 영향).

v0.42.0 — 폐쇄망(망분리) 운영: 오프라인 번들

목표: 공공 개발 환경은 대부분 망분리라 인터넷 PC 에서 받은 자료를 반입해 씁니다. 지금은 OSV 조회·공통컴포넌트 아카이브·Initializr zip·재조립 원본 태그·upstream 대조가 실행 시점에 인터넷을 씁니다. 반입 가능한 번들 하나로 같은 결과를 내게 합니다.

범위 (포함)

새 도구 prepare_egovframe_offline_bundle(outputDir, include=["osv","components","templates","origin"], dryRun=true)(32번째, 인터넷 쪽에서 실행): OSV Maven 전체 덤프(osv-vulnerabilities/Maven/all.zip)·고정 공통컴포넌트 아카이브(카탈로그 sha256 검증분)·Initializr zip 템플릿·재조립용 원본 태그 bare 미러를 한 디렉터리에 담고 bundle-manifest.json(파일별 sha256·크기·출처 URL·받은 시각·서버 버전)을 씁니다.
폐쇄망 쪽: EGOVFRAME_OFFLINE_BUNDLE=<dir> 가 있으면 모든 다운로드가 번들에서 먼저 찾고(지문 검증, 불일치 거부), offline=false 의 OSV 조회(check_egovframe_dependencies·generate_egovframe_sbom·check_egovframe_sbom·평가서)는 로컬 덤프로 대체합니다 — affected[].versions 목록 대조를 기본으로, 목록 없이 ECOSYSTEM 범위만 있는 레코드는 Maven 버전 비교로. 결과에 "OSV 스냅숏 YYYY-MM-DD 기준"을 표시하고 기준일이 오래되면(기본 30일) 경고합니다.
diagnose_egovframe_network 의 처방에 번들 경로를 추가하고, CLI bundle 명령과 server.json 환경변수 EGOVFRAME_OFFLINE_BUNDLE 을 더합니다.

범위 (제외): Maven 의존성 jar 미러링(기관 Nexus·Artifactory 미러 설정 안내만), 번들 서명(manifest sha256 으로 대신, 요청 시 추가)

검증 기준: 같은 날 받은 덤프로 공식 web 템플릿 SBOM(67 component)의 로컬 OSV 결과가 온라인 querybatch 결과와 같은 ID 집합(차이가 있으면 원인 — 철회·범위 표기 — 를 기록), 프록시를 막은 상태에서 프로젝트 생성(zip 템플릿)·컴포넌트 조립·재조립·SBOM 점검이 번들만으로 성공, 지문이 다른 번들 파일 거부

완료 정의: 도구 32종, README 「폐쇄망에서 쓰기」 절, docs/design-offline-bundle.md

결과(2026-10-10) — 완료: src/offline-bundle.ts(번들 만들기·읽기·로컬 OSV·Maven 버전 비교)와 src/offline-bundle-plan.ts. 실측: 번들 106.8MB(OSV 덤프 9.9MB·7,190건, 아카이브 44.7MB, web 템플릿 14.8MB, 태그 22개 미러 37.3MB), 만드는 데 약 10초. 같은 날 받은 덤프의 로컬 판정이 온라인 querybatch 와 공식 web 템플릿 SBOM 67 component + 옛 버전 표본 6개에서 질의 73/73·ID 134/134 일치, fetch 를 막고 git 을 file 프로토콜로 제한한 상태에서 web 템플릿 생성·bbs 조립(797파일)·4.3.2 재조립 미리보기(원본 v4.3.2 식별)·SBOM 재점검(OSV 27건)이 네트워크 시도 0건으로 끝났습니다. 계획과 달라진 점: (a) 다운로드 훅을 도구마다 두지 않고 공용 fetchWithTimeout(와 카탈로그 아카이브 다운로드)에서 manifest 의 URL 과 맞춰 대체해, 앞으로 생기는 GET 다운로드도 번들에 넣기만 하면 됩니다. (b) 원본 미러는 blob 없는 캐시가 아니라 태그마다 내용까지 받은 미러로 담았습니다 — 22개 태그가 37MB 라 패치 생성까지 폐쇄망에서 됩니다. (c) 저장소 템플릿(브랜치 기준)은 고정 지문이 없어 기본에서 빼고 templates 로 지정할 때만 담습니다. (d) 번들은 새(또는 빈) 디렉터리에만 임시 디렉터리를 거쳐 쓰고 실패하면 남기지 않습니다.

v0.43.0 — CI・提出形式の多様化：Jenkins・GitLab、SPDX

目標：公共事業のビルドサーバーでは GitHub Actions より Jenkins・GitLab が一般的で、SBOM の提出形式はまだ特定されていないため（ガイドライン 1.0 では SPDX・CycloneDX の両方に言及）、SPDX を求められる可能性があります。v0.39 のゲートと v0.40 のチェックを、そうした環境にも広げます。

範囲（含む）

generate_egovframe_ci(platform="github"|"gitlab"|"jenkins")：.gitlab-ci.yml・Jenkinsfile（Declarative）でのビルド・テストとサプライチェーンゲート（同じ CLI コマンド — sbom --write → sbom-check --fail-on minimum → assess --fail-on <failOn>。終了コード 2 を失敗として扱い、アーティファクトを保管）。社内 npm レジストリ・オフラインバンドルのパスを変数として受け取ります。ゲート job への sbom-check ステップの追加は、GitHub 側にも同時に適用します。
SPDX：generate_egovframe_sbom(bomFormat="spdx-json") — CycloneDX ドキュメントを SPDX 2.3 JSON に変換します（パッケージ・DEPENDS_ON 関係・purl externalRefs・supplier・creationInfo.creators・created）。check_egovframe_sbom は SPDX 2.3 入力も読み込み、最小 7 要素を SPDX フィールドに対応させてチェックします（VEX は CycloneDX のみ）。
テスト：生成した .gitlab-ci.yml を GitLab 公式 CI JSON スキーマで、SPDX 出力を公式 spdx-spec v2.3 スキーマで検証します（v0.40 と同様、テストフィクスチャと ajv を固定）。

範囲（除外）：SPDX 3.0、その他の CI（Azure DevOps・Bamboo など）、Jenkins プラグインのインストール・サーバー設定

検証基準：公式 web テンプレートの SBOM を SPDX に変換しても、最小 7 要素の判定と component 数が一致し、SPDX 2.3 スキーマに合格すること。生成した .gitlab-ci.yml がスキーマに合格すること。Jenkinsfile は Declarative 構造（pipeline・agent・stages・post）をアサートします — 実際の Jenkins 実行は保留項目として残します

完了の定義：ツール 32 種（変更なし）、README の「CI での使用」に GitLab・Jenkins の例、「SBOM 提出の準備」に SPDX、docs/design-cli.md のプラットフォーム節

結果（2026-10-11）— 完了：src/ci-config.ts（3 プラットフォームすべてで同じゲートコマンド一覧 supplyChainCommands を使用）と src/spdx.ts（cdxToSpdx・spdxToCdx）。実測：公式 web テンプレートを実際の Maven・cyclonedx-maven-plugin で生成した SBOM（67 component、OSV 27 件）を SPDX 2.3 に変換すると、パッケージ 68・関係 165 で公式 spdx-spec v2.3 スキーマに合格します。SPDX をチェックした結果は CycloneDX のチェックと component 67・最小 7 要素の要素ごとの充足数（68/68 …）・判定 ready まで一致し、両者を比較した差は 0 です。生成した .gitlab-ci.yml は、maven・gradle・ゲートの有無・環境変数の組み合わせ 4 種すべてが GitLab 公式 CI スキーマ（v19.4.1-ee 固定）に合格します。計画からの変更点：（a）SPDX チェックには個別のルールを設けず、SPDX を内部の CycloneDX 形式に変換して、同じ最小要素・再判定・比較コードをそのまま使用します — 対応関係（サプライヤー = PackageSupplier/PackageOriginator、依存関係 = そのパッケージを主語とする DEPENDS_ON、作成者 = creators の Person・Organization）は src/spdx.ts の冒頭コメントと「SBOM 提出の準備」表に記載しています。（b）「依存関係なし」と「不明」を区別するため、依存関係のないパッケージは DEPENDS_ON NONE（SPDX 2.3 §11.1）として記述し、NOASSERTION は不明として読み取ります。（c）基準判定（egovframe:*）と OSV の結果を SPDX の annotations・SECURITY/advisory externalRefs に変換するため、SPDX で出力した後も再判定の「生成後に変わった判定」・「新たに判明した脆弱性」が機能します。（d）生成時刻は SPDX の必須項目であるため、元データにない場合は変換時刻を設定して通知します（この場合に限り、判定が変わる可能性があります）。（e）ゲートの sbom-check --fail-on minimum はサプライヤーの手がかり（supplier または pom <organization>）がないと失敗するため、supplier パラメーターを追加し、生成レスポンスで事前に通知します。（f）GitLab には JUnit レポートと artifacts:reports:cyclonedx を、Jenkins には Linux・Windows エージェント共通の実行（isUnix() による sh/bat）を追加しました。Jenkins の実際の実行検証は保留項目として残します。

保留・運用項目

Jenkins 実行検証：生成した Jenkinsfile は Declarative 構造のみをアサートします。実際の Jenkins（コンテナー）で実行する統合検証はまだありません。
ブランチ保護（オーナーが 1 回実施）：main で「Require status checks to pass」（gate 6 + integration）を有効にすると、失敗状態でのマージが再発しなくなります。gh api -X PUT repos/EricSeokgon/egovframe-scaffold-mcp/branches/main/protection --input protection.json（required_status_checks.contexts にチェック名 7 個、enforce_admins: false、required_pull_request_reviews: null、restrictions: null）。
Initializr upstream：最新タグ v5.0.6（84d3682）と main（bc18641）のどちらも、テンプレート pom の parent は依然として 5.0.0 です（公式 parent の最新は 5.0.2）。既存の 3 件とあわせて upstream に問題として提出する価値があります。
sbom-live の断続的な失敗 — 原因を確認・解決（v0.43）：CI ランナーでは cyclonedx-maven-plugin の出力から metadata.timestamp が欠落する場合があり（ローカルでは再現しません）、最小要素の「生成時刻」が空になっていました。v0.40 PR の最初の失敗と v0.43 PR の SPDX 判定不一致（SPDX では生成時刻が必須のため、変換時刻が設定される）は同じ原因によるもので、現在は生成器が生成時刻の欠落時に補完して通知します。
基準なしの残項目：xerces:xercesImpl は公開基準がないため、そのままにします。
レスポンス本文の英語化：評価書・チェック結果のラベル・ヘッダーの英語化（--lang en）は引き続き優先度を下げています。
MCP の新機能：tasks（長時間実行するツールの非同期実行）は SDK で実験段階のため保留です — v0.41 のリハーサルでは数分かかる最初のツールなので、安定したら最優先で適用します。elicitInput は dryRun パターンで十分なため使用しません。

事前調査結果（2026-10-07）

upstream タグ：egovframe-runtime の最新 v5.0.2-Final（同梱ルールと同じ）、egovframe-common-components v5.0.7（2026-10-07 に 7912e13 で再タグ付け — v0.39 で反映）、egovframe-vscode-initializr の最新タグ v5.0.6（84d3682）・main bc18641（固定 commit f8f5725）、テンプレートの pom parent は v5.0.6・main ともに 5.0.0 です。
リハーサル対象：公式の共通コンポーネント v4.3.2 は、ルートに pom.xml が 1 つある（war）単一 Maven モジュールで、6,523 ファイル、java.version 1.8・Spring 5.3.37・<dependency> 70 個です。そのまま JDK 17 でのコンパイルまで行う実資産リハーサルに使用できます（v0.38 の再組み立てテストで使用した v5.0.7 アーカイブ・元タグのミラーを再利用します）。
OSV オフラインダンプ：https://osv-vulnerabilities.storage.googleapis.com/Maven/all.zip は 10,356,728 bytes（2026-10-06 19:47 GMT 更新、毎日更新）で、レコードは 7,168 件、展開後は 24MB です。affected の範囲は ECOSYSTEM が 13,321 件、SEMVER が 121 件で、11,700 件の affected に明示的なバージョン一覧があるため、大半は一覧との照合だけで判定できます。サンプルとして、org.springframework:spring-webmvc 6.2.11 はローカルダンプで 12 件ヒットします（オンラインとの一致は v0.42 の検証基準です）。
SPDX：spdx/spdx-spec タグ v2.3 の schemas/spdx-schema.json（45,312 bytes）をテスト用の固定データとして使用できます。
ツールの依存関係：@modelcontextprotocol/sdk の最新バージョンは 1.32.1（2026-10-05、同梱バージョンと同じ）です。@cyclonedx/cyclonedx-library 10.3.0 は Node ≥20.18 が必要なため、ゲート（Node 18 を含む）では v0.40 と同様に ajv + 公式スキーマの固定データ方式を維持します。

以前の計画（v0.38–v0.40、完了）

v0.37.0 まで完了した状態（2026-10-05、ツール 28 種、テスト約 1,500 件、npm 0.36.1 まで自動公開済み・0.37.0 は公開進行中）から、次の 3 リリースを以下の順で進めました。3 つのバージョンすべて 2026-10-07 までに完了し、計画の原文は記録として残し、結果を各項目の下に記載しています。共通の原則は以前と同じです — ルールはデータで、根拠は公式リポジトリから、書き込みツールには dryRun・transaction を使用し、各バージョンは「完了の定義」を満たしてからリリースします。今回の 3 バージョンに共通するテーマは評価から実行へです — 評価書が最も大きな手作業として挙げた共通コンポーネントの再組み立てをツールが実行し（v0.38）、同じ分析を AI クライアントなしで CI とバッチから実行し（v0.39）、SBOM の作成だけで終わらせず、提出物として検証・比較・追跡します（v0.40）。事前調査の根拠は、最下部の「事前調査結果（2026-10-05）」にあります。

v0.38.0 — 공통컴포넌트 재조립 실행 (`reassemble_egovframe_components`)

목표: 코퍼스가 보여 준 대로 3.x/4.x 프로젝트의 수동 전환 항목 대부분은 복사해 넣은 공통컴포넌트 소스 안에 있습니다(4.3.2 트리: 수동 717건 중 제거된 공통컴포넌트 클래스 524·재조립 권고 155). 지금은 "add_egovframe_components 로 5.0.6 을 다시 조립하고 사용자 수정은 백업과 diff 로 옮기세요"라고 안내만 합니다. 이 과정을 도구가 수행하되, 사용자가 손댄 파일을 한 줄도 잃지 않게 합니다.

범위 (포함)

선행: 공통컴포넌트 v5.0.7 대응 — upstream 이 2026-10-06 v5.0.7 을 냈습니다(v5.0.6 대비 1,672파일, 주로 uss·sym·cop 매퍼·JSP·uss/ion·cop/smt). 재조립 대상 버전이 곧 이 태그이므로, 먼저 컴포넌트 카탈로그(generate:catalog)·전환 규칙의 공통컴포넌트 대응표(components.toTag)·sync_egovframe_catalog 고정을 v5.0.7 로 올리고 회귀 코퍼스 기대값을 갱신합니다(drift 감시가 CI 에서 이미 경고 중).
새 도구 reassemble_egovframe_components(projectDir, components?, sourceTag="auto", database?, dryRun=true, verify=false)(29번째): (1) diagnose_egovframe_project 가 감지한 컴포넌트 중 전환 항목이 있는 것(평가서의 재조립 권고와 같은 기준)을 대상으로 삼고 components 로 좁힐 수 있습니다. (2) 원본 태그 식별 — 프로젝트의 컴포넌트 파일 해시를 세대에 맞는 후보 태그(3.x: v3.9.0·v3.10.0 / 4.x: v4.0.0–v4.3.2, 공식 저장소 태그 21종 중)의 같은 경로와 대조해 일치 비율이 가장 높은 태그를 고릅니다. 후보 트리는 v0.37 코퍼스의 sparse 부분 클론을 컴포넌트 접두어 단위로 재사용해(태그당 수 MB) .egov-cache 에 캐시하고, sourceTag 로 고정할 수 있습니다. (3) 3-way 분류 — 원본(식별한 태그)·현재·5.0.6 의 파일 해시로 unchanged(교체)·user-modified(교체 + 사용자 변경을 unified diff 패치로 보존)·added(사용자 파일, 유지)·removed-in-5.x(5.0.6 에 없는 파일, 백업 후 제거 — sec/rnc 실명확인·utl/sec 등 코퍼스에서 확인된 미대응 디렉터리는 작업 목록에 올림)로 나눕니다. upgrade_egovframe_project 의 classifyUpgrade 와 같은 규칙이며 매니페스트 대신 원본 태그가 기준선입니다. (4) 조립 — add_egovframe_components 의 계획기로 5.0.6 파일(소스·매퍼·JSP·메시지·설정 조각·DB 스크립트)을 내려받아 넣고 매니페스트(.egovframe-components.json, 해시 포함)를 기록해 이후 upgrade·validate·remove 수명주기 도구가 적용되게 합니다. 모든 변경은 하나의 transaction, 원본은 migration-backup/<timestamp>/, 사용자 패치는 migration-backup/<timestamp>/patches/<component>/*.patch 와 reassemble-plan.json(파일별 분류·패치 경로·작업 목록). (5) 작업 목록 — 사용자 수정 파일마다 "5.0.6 의 같은 파일에 이 패치를 다시 적용" 항목을, 5.x 에 없는 파일마다 "대체 방법" 항목을 내고, verify=true 면 build_egovframe_project(compile) 을 돌려 v0.33 의 연결 규칙으로 오류를 항목에 붙입니다. 결과는 Markdown·format=json(outputSchema), 도구 메타는 파괴적(destructive, 기존 파일 교체)·openWorld.
migrate_egovframe_project 진단의 component-reassemble 항목 to 에 새 도구 호출을 안내하고, 평가서 2절의 재조립 권고에 "원본 태그 추정"을 미리 보여 줍니다(일치 비율).
회귀 코퍼스 확장: 4.3.2 트리에서 cmm·bbs 를 재조립(dryRun)했을 때 분류 건수(unchanged 전부, user-modified 0)와 원본 태그 식별(v4.3.2, 일치 100%)을 기대값으로 고정하고, 한 파일을 바꾼 뒤 user-modified 1·패치 1 을 단언합니다.

범위 (제외): 사용자 패치의 자동 재적용(5.0.6 소스가 많이 바뀌어 fuzz 적용은 오히려 위험 — 패치와 작업 목록까지), 컴포넌트 밖 애플리케이션 코드가 호출하는 제거 클래스의 수정(기존 class-removed 수동 항목 유지), DB 스키마 변경 스크립트 실행

검증 기준: 공식 5.x 템플릿에 공통컴포넌트 v3.10.0 의 bbs(+의존 cmm) 소스를 복사하고 파일 2개를 수정한 픽스처에서 — 원본 태그 v3.10.0 식별, 분류(unchanged·user-modified 2·added 0·removed-in-5.x ≥ 0), dryRun 무기록, 적용 후 5.0.6 파일 해시 일치·패치 2개·매니페스트 생성·validate_egovframe_project 통과, JDK 17 mvn compile 통과(CI 통합), fault-injection rollback. 코퍼스 기대값 갱신. Windows 게이트 3개 통과

완료 정의: 도구 29종, docs/design-migration.md 에 재조립 절(원본 태그 식별·3-way·보존 규칙), README 에 흐름 예시(진단 → 평가서 → 재조립 → apply → verify)

결과(2026-10-06) — 완료: 선행 작업으로 컴포넌트 카탈로그(190항목, 아카이브 sha256·크기·파일 수 6,604)와 전환 규칙의 공통컴포넌트 대응표를 v5.0.7 로 올렸습니다(제거 클래스 54 → 55, EgovDtaUseStatsContoller 추가; 회귀 코퍼스 기대값 변화 없음). 원본 태그 식별은 계획한 "파일 해시 대조"를 git blob id 로 구현해, 태그마다 blob 없는 shallow fetch(≈1초·수백 KB)와 ls-tree 만으로 끝나고 파일 내용은 사용자 수정 파일의 패치를 만들 때 그 blob 하나만 받습니다. CRLF 체크아웃도 LF 정규화 id 로 같은 파일로 봅니다. 계획과 다른 점: (a) 메시지·설정 조각·웹 자산은 사용자 수정이면 덮어쓰지 않고 유지하며 목표본을 참고로 저장(설정 파일 교체가 실행 환경을 깨뜨릴 위험), (b) CI 통합의 mvn compile 은 넣지 않았습니다 — cmm·bbs 만으로는 5.0.7 의 다른 컴포넌트 참조 때문에 단독 컴파일이 성립하지 않아, 대신 쓴 파일 전부가 v5.0.7 tree 의 blob 과 같은지(780개)와 validate·upgrade 정합을 단언합니다, (c) 평가서의 "원본 태그 추정" 미리보기는 평가서가 기본 오프라인이라 넣지 않고 재조립 dryRun 으로 대신합니다. 부수 수정: upgrade_egovframe_project 가 조립 때 함께 설치된 자산 파일을 upstream 에 없는 것으로 보고하던 결함(재조립 픽스처에서 621건 "removed"), 만료 토큰(401)이면 비인증으로 다시 조회.

v0.39.0 — CLI 모드 + CI 공급망 게이트

목표: 공공 사업의 빌드 서버(Jenkins·GitHub Actions·GitLab CI)에는 AI 클라이언트가 없습니다. 평가서·의존성 점검·SBOM 을 그 자리에서 사람 없이 돌리고, 등급·판정이 기준을 넘으면 파이프라인을 멈추게 합니다. 도구 로직은 그대로 두고 호출 통로만 하나 더 엽니다.

범위 (포함)

CLI: npx egovframe-scaffold-mcp <command> [options] — 인자가 없으면 지금처럼 MCP stdio 서버로 뜨고(기존 호환), 명령이 있으면 그 도구를 실행하고 종료합니다. 명령은 읽기 전용·dryRun 도구로 한정: assess(평가서), check(의존성), sbom(--write 없으면 dryRun), migrate(진단만), validate, diagnose, network. 공통 옵션 --project <dir>, --json(structuredContent 그대로), --out <file>, --lang ko|en(라벨·헤더), 도구별 옵션은 MCP 파라미터와 같은 이름(--resolve, --offline=false, --scope all). 허용 root·네트워크 처방·오류 메시지는 MCP 경로와 동일. 구현은 src/cli.ts 가 server.ts 의 핸들러를 직접 호출(프로토콜 왕복 없음).
게이트 옵션 --fail-on: assess 에 migration:C·supplyChain:C(이 등급 이상이면 종료 코드 2), check 에 outdated·legacy·replace·vulnerabilities(건수 임계값 vulnerabilities>0), migrate 에 manual>0. 종료 코드 규약: 0 통과 · 2 기준 초과 · 3 실행 실패(빌드 도구 없음·네트워크) · 64 인자 오류. 결과 요약은 stderr 한 줄, 본문은 stdout — 파이프라인 로그와 아티팩트 둘 다에 맞춥니다.
generate_egovframe_ci(supplyChain=true): 생성하는 워크플로에 "공급망 게이트" job 을 추가 — npx egovframe-scaffold-mcp@<이 버전> assess --json --out assessment.json --fail-on supplyChain:D 와 sbom --write --offline=false, 결과를 아티팩트로 업로드, PR 요약($GITHUB_STEP_SUMMARY)에 등급 표. 기존 빌드·테스트 job 은 그대로.
SDK @modelcontextprotocol/sdk 1.29 → 1.32(프로토콜 2025-11-25): 변경 없는 업그레이드인지 핸드셰이크·구조화 출력 테스트로 확인하고, 실험 단계인 tasks(장시간 도구의 비동기 실행)는 안정화될 때까지 쓰지 않습니다(선행 조사 참조).
테스트: CLI 오프라인 스위트(명령·옵션 매핑·종료 코드·JSON 동일성 — 같은 입력에 MCP structuredContent 와 CLI --json 이 같은 객체), CI 생성 스냅샷, 통합 job 에서 생성된 워크플로 YAML 을 actionlint 로 검사하고 CLI 로 평가서를 실제 실행.

범위 (제외): 쓰기 도구의 CLI 노출(프로젝트 생성·조립·적용은 사람이 결과를 보는 MCP 경로로 유지), 대화형 프롬프트, 응답 본문 전체의 영문화(--lang en 은 평가서·점검 결과의 라벨·헤더까지 — 사유 문장은 한국어 유지)

검증 기준: npx egovframe-scaffold-mcp assess --project <공식 5.x 템플릿> --json 이 MCP 호출과 같은 JSON, --fail-on migration:B 로 코퍼스 트리에서 종료 코드 2, 인자 없는 실행은 기존 핸드셰이크 테스트 통과(stdio 서버), 생성 워크플로가 GitHub Actions 에서 실제로 등급 표를 남김(이 저장소의 통합 job 에서 1회)

완료 정의: 도구 29종(변화 없음) + CLI 명령 7종, README 「CI 에서 쓰기」 절, docs/design-cli.md

결과(2026-10-06) — 완료: src/cli.ts 는 핸들러를 직접 부르지 않고 SDK 의 InMemoryTransport 로 같은 서버에 붙은 클라이언트가 tools/call 을 보내게 했습니다 — 입력 검증·허용 root·outputSchema 검증이 MCP 경로와 같아 --json 동일성이 구조적으로 보장되고 SDK 내부 필드에 기대지 않습니다. 계획보다 늘어난 것: 명령 7종에 diagnose·network 포함, --fail-on 지표를 명령별로 정의(평가서의 등급 2종·건수 8종 등), sbom 은 --write 로만 기록. 계획과 다른 점: (a) --lang en 라벨 영문화는 넣지 않았습니다(렌더러마다 바꾸는 일이라 별도로), (b) 생성 워크플로의 "실제 Actions 실행"은 이 저장소 통합 job 에서 actionlint 검사와 CLI 평가서 실행(job 요약에 등급 표)으로 대신했습니다 — 게이트 job 자체는 npm 에 이 버전이 게시돼야 돌 수 있기 때문입니다. SDK 는 1.29 → 1.32.1(프로토콜 2025-11-25)로 올렸고 기존 테스트가 변화 없이 통과했습니다(tasks 는 실험 단계라 미사용).

v0.40.0 — SBOM 運用：最小要素・比較・VEX

目標：2027年までに、公共分野のITシステム・ソフトウェア製品におけるSBOMの提出が制度化されます（先行調査）。提出物には「作成した」だけでなく、不足している要素がないこと、前回の提出版から何が変わったか、既知の脆弱性についてどのように判断したかも含まれている必要があります。v0.36 の生成器に、この3つを追加します。

範囲（含む）

新しいツール check_egovframe_sbom(projectDir, sbomPath="sbom/bom.cdx.json", baselinePath?, offline=true, vex=false, format)（30番目、読み取り専用・任意の書き込み）：（1）最小要素の点検 — 文書・component ごとに、供給者（supplier/publisher）・component 名・バージョン・一意識別子（purl/cpe）・依存関係（dependencies[] で参照）・作成者（metadata.authors/tools）・生成日時（metadata.timestamp）が満たされているかを数え、「提出可能／要補完」と不足している component の一覧を出力します（NTIA の最小要素7種類をデフォルトのルールとし、国内ガイドラインで要件が追加された場合はデータに反映します）。（2）ビルドツールを使わない再点検 — SBOM の purl のみを使って基準判定（v0.34 分類器）と OSV 照会を再実行し、「生成後に新たに判明した脆弱性」を報告します（運用中の定期点検用）。（3）比較 — baselinePath（前回の SBOM）と component 集合を比較し、追加・削除・バージョン変更・判定の変化・新たな脆弱性を表に出力します（デプロイ前後・提出版間の差分）。（4）VEX のドラフト — vex=true の場合、検出された脆弱性ごとに CycloneDX VEX 文書（vulnerabilities[].analysis.state=in_triage、affects で component を参照、bom-link で元の SBOM を参照）を sbom/vex.cdx.json に新しいファイルとして書き込みます。判断（not_affected・exploitable など）は人が入力し、次回実行時には既存の VEX の判断を保持したうえで、新たな脆弱性のみを追加します。
generate_egovframe_sbom に supplier・author・componentName・componentVersion オプション（指定がない場合は pom の organization・name・version から取得し、それでもない場合は空欄のままとして、点検時に要補完と表示）と metadata.lifecycles（build）の記録を追加 — 最小要素を生成段階で補います。
評価書の5節（SBOM）に、最小要素の充足状況・最終点検日・VEX の有無をまとめて表示します。
テスト：最小要素のルール（不足項目ごと）、purl による再判定・OSV のモック照会、比較（追加・削除・バージョン・脆弱性）、VEX の生成・保持・bom-link、公式 web テンプレート SBOM に対する実際の OSV 再点検（CI 統合）。

範囲（含まない）：SPDX 出力・変換（要望があれば CycloneDX → SPDX 変換器と連携）、脆弱性判断の自動化（VEX の状態は人が判断）、中央リポジトリへの提出 API 連携（制度確定前）

検証基準：v0.36 が生成した公式 web テンプレート SBOM（69 component）について、最小要素の点検でどの項目が不足しているかを報告し（予想：supplier・authors）、補完オプションを指定して再生成すると合格し、2つの SBOM の比較では意図した差分のみを報告し、VEX の再実行時には人が入力した状態を保持すること

完了の定義：ツール30種、docs/design-dependency-check.md に SBOM 運用の節、README に「SBOM 提出の準備」の節

結果（2026-10-07）— 完了：src/sbom-check.ts（ルールは catalog/sbom-rules.json — 要素ごとに認定するフィールドパスをデータとして定義し、依存関係・生成日時のみを特別に検査）と generate_egovframe_sbom のメタデータオプション。実測：公式 web テンプレートで cyclonedx-maven-plugin 2.9.3 を実際に実行した SBOM（67 component。計画上の69は v0.36 当時の解釈数）は、供給者 50/68（主要 component・RTE・AspectJ・Micrometer など、pom に <organization> がない18種）と作成者（プラグインは metadata.tools のみを記録）が空欄で「要補完」となり、残りの5要素は68/68でした。計画から変更した点：（a）ライブラリの供給者はオプションでは補えないため、供給者表（suppliers、groupId 接頭辞10件、各項目に pom の根拠を記載）を用意し、空欄の component のみを補完して egovframe:supplierBasis=catalog で出典を記録します — この表と supplier・author を使って再生成すると、7要素すべてを満たします。（b）主要 component 名は pom の <name> ではなく artifactId をそのまま使用し（componentName でのみ上書き）、（c）fillSuppliers のデフォルト値は enrich に従います（enrich=false の場合、文書をそのまま保持）。（d）SBOM に vulnerabilities[] がない場合（offline 生成）、再照会の結果は「新たに判明したもの」ではなく「記録されていないもの」として表示します。（e）VEX では、判断済みの ID に新たな影響 component が加わっても、その判断の適用範囲を広げず、同じ ID の新しい in_triage 項目を作成します。生成された SBOM・VEX は、CycloneDX specification 1.6.1 の公式 JSON スキーマを使ってテストで検証します（スキーマはテスト用フィクスチャで、パッケージには含まれません）。CLI コマンド sbom-check を追加しました（minimum・newVulns などの指標、VEX は --write で書き込み）。

保留・運用項目（当時）

ブランチ保護（所有者が1回実施）：main で「Require status checks to pass」（gate 6 + integration）を有効にすると、#33・#36 のような失敗状態でのマージを防げます。gh api -X PUT repos/EricSeokgon/egovframe-scaffold-mcp/branches/main/protection --input protection.json（required_status_checks.contexts にチェック名を7つ指定、enforce_admins: false、required_pull_request_reviews: null、restrictions: null）で一度に設定できます。
MCP Registry への登録確認：v0.37.0 の自動デプロイ（Release #4）が初回の公開です。失敗した場合、次の main のマージで Release が Registry のステップのみを再試行します（v0.37 の再開判定）。
Initializr upstream：固定 commit（f8f5725）と現在の main（bc18641）のどちらも、テンプレート pom の parent は5.0.0です（公式 parent の最新は5.0.2）。評価書で公式テンプレートのサプライチェーン評価を B とする理由の一つであるため、upstream の課題として報告する価値があります（既存の3件と合わせて）。
基準がないものの残り：xerces:xercesImpl は公開されている基準がないため、そのままにします。v0.40 の purl による再判定でも結果は同じです。
応答本文の英語化：v0.39 の --lang en で評価書・点検結果のラベル・ヘッダーまで対象を広げ、理由文全体の英語化は引き続き後回しです。Homebrew タップは後回しの対象から外しました（npx で十分です）。

선행 조사 결과 (2026-10-05)

재조립 가능성(코퍼스): 3.10.0 트리의 java 디렉터리 454개 중 5.0.6 카탈로그 접두어에 대응하는 컴포넌트 id 153종(java 1,095개 중 1,085개 = 99%), 미대응은 com/sec/rnc(실명확인)·com/utl/sec 6개 디렉터리·10개 파일뿐. 4.3.2 는 154종·미대응 3개 디렉터리·5개 파일. 즉 재조립은 거의 전부에 적용되고, 5.x 에 없는 소수만 작업 목록으로 남습니다. 공식 공통컴포넌트 저장소 태그는 21종(v3.9.0·v3.10.0·v3.10.0-FINAL·v4.0.0–v4.3.2·v5.0.0–v5.0.6)이라 원본 태그 후보가 유한하고, v0.37 의 sparse 부분 클론(접두어 단위)으로 후보를 싸게 받을 수 있습니다.
공급망 보안 제도: 과기정통부·국정원의 SW 공급망 보안 로드맵(2026-06-24, 9개 분야)은 개발 단계 보안 내재화·SBOM 확산·위협 탐지·제도 정비를 담고, "공공분야에 도입되는 IT시스템 및 소프트웨어 제품에 대한 SBOM 제출을 2027년까지 제도화"가 명시됐습니다. SW 공급망 보안 가이드라인 1.0(2024-05)은 SBOM 유효성 검증·구성요소 관리·SBOM 기반 관리 방안을 다루며 형식(SPDX/CycloneDX)은 특정하지 않습니다. SBOM 핵심 구성요소는 NTIA 최소 요소와 같은 7종(공급자·구성요소명·버전·고유식별자·의존관계·작성자·생성 시각)으로 통용됩니다 — v0.40 의 점검 규칙 기본값.
MCP SDK·프로토콜: @modelcontextprotocol/sdk 최신 1.32.0(2026-10-02), 동봉 1.29.0. 최신 프로토콜 2025-11-25(tasks/* 요청은 SDK 에서 experimental 네임스페이스 — 장시간 도구의 비동기 실행이지만 클라이언트 지원과 API 안정성이 확인되기 전까지 보류), elicitInput(서버가 사용자 입력을 요청)은 안정 API 로 존재하나 승인 UX 는 dryRun 패턴으로 충분해 쓰지 않습니다. 업그레이드는 v0.39 에서 테스트 변화 없음을 확인하며 수행.
CycloneDX: cyclonedx-maven-plugin 최신 2.9.3(동봉과 같음), CycloneDX 1.6 은 VEX 를 같은 스키마의 vulnerabilities[].analysis(state·justification·response·detail)와 bom-link 로 표현하므로 별도 포맷 없이 VEX 문서를 낼 수 있습니다.
upstream 상태: egovframe-runtime 최신 태그 v5.0.2-Final(동봉 규칙과 같음), egovframe-common-components v5.0.6(같음 — 단 2026-10-06 v5.0.7 이 나와 v0.38 선행 작업으로 반영), Initializr main 은 bc18641(고정 commit f8f5725 이후 변경이 있으나 템플릿 pom 의 parent 는 여전히 5.0.0).
CLI 선례: Node MCP 서버가 같은 바이너리로 CLI 명령을 겸하는 패턴(인자 없음 → stdio 서버, 명령 → 실행 후 종료)은 기존 bin 과 핸드셰이크 테스트(인자 없는 기동)를 그대로 유지할 수 있습니다. 종료 코드 규약은 sysexits(64 = 사용법 오류)를 따릅니다.

이전 기획 (v0.35–v0.37, 완료)

v0.34.0 까지 끝난 상태(2026-10-04, 도구 27종, 테스트 약 1,300건, npm 0.33.1 배포·0.34.0 배포 대기)에서 다음 세 릴리스를 아래 순서로 진행했습니다. 세 버전 모두 2026-10-05 까지 완료했으며 기획 원문은 기록으로 남기고 결과를 항목 아래에 적었습니다. 공통 원칙은 이전과 같습니다 — 규칙은 데이터로, 근거는 공식 저장소에서, 쓰기 도구는 dryRun·transaction, 각 버전은 "완료 정의"를 만족해야 릴리스합니다. 이번 세 버전의 공통 주제는 배포와 운영을 사람 손에서 떼어 내는 것(v0.35), 선언된 의존성이 아니라 실제로 실리는 의존성을 보는 것(v0.36), 지금까지 만든 분석을 한 장의 평가서와 회귀 코퍼스로 묶는 것(v0.37)입니다. 선행 조사 근거는 맨 아래 "선행 조사 결과 (2026-10-04)"에 있습니다.

v0.35.0 — 릴리스 자동화 (배포 공급망)

목표: v0.29–v0.34 여섯 번의 릴리스에서 태그를 잘못된 커밋에 단 일(2회), npm 배포를 빠뜨린 일(0.32.0·0.33.0), Windows 게이트 실패 상태로 병합한 일(2회)이 모두 사람이 명령을 순서대로 치는 과정에서 났습니다. main 에 병합되면 나머지(게이트 재확인 → 태그 → npm → GitHub Release → MCP Registry)는 CI 가 하고, 사람은 PR 병합만 합니다. 배포물에는 provenance 가 붙어 "이 npm 패키지는 이 저장소의 이 커밋에서 이 워크플로가 만들었다"를 소비자가 검증할 수 있게 합니다.

범위 (포함)

.github/workflows/release.yml: CI 워크플로가 main 에서 성공한 뒤(workflow_run)에만 실행. package.json 버전을 읽어 (a) server.json 두 version 과 같고, (b) README 변경 이력에 그 버전 항목이 있고, (c) 태그 vX.Y.Z 가 아직 없고, (d) npm 에 그 버전이 없을 때만 진행합니다. 네 조건 중 하나라도 어긋나면 이유를 적고 성공 종료(병합마다 도는 워크플로가 빨간불이 되지 않게).
npm: trusted publishing(OIDC) 으로 토큰 없이 npm publish --access public. 공개 저장소·공개 패키지이므로 provenance 가 자동으로 붙습니다. 요구 조건은 npm CLI 11.5.1+·Node 22.14+·id-token: write·self-hosted 러너 금지이며, npmjs.com 의 패키지 설정에서 trusted publisher(저장소 EricSeokgon/egovframe-scaffold-mcp, 워크플로 파일명 release.yml)를 저장소 소유자가 한 번 등록해야 합니다(README 절차에 적음).
태그·Release: 배포가 성공한 그 main 커밋에 vX.Y.Z 태그를 만들고, scripts/release-notes.mjs 가 README 변경 이력에서 해당 버전 항목을 뽑아 GitHub Release 본문으로 씁니다(태그가 병합 전 커밋에 달리는 사고가 구조적으로 사라집니다).
MCP Registry: mcp-publisher login github-oidc → mcp-publisher publish(io.github.EricSeokgon/* 네임스페이스는 GitHub OIDC 로 소유 증명, 비밀 없음). npm 에 패키지가 먼저 있어야 하므로 npm 단계 뒤에 둡니다. 첫 실행이 곧 "MCP Registry 첫 등록"(보류 항목)이 됩니다.
패키지 내용 검사: npm pack --dry-run --json 으로 tarball 에 dist/·catalog/·server.json·README*·LICENSE 만 들어가고 test/·scripts/·.github/ 가 없는지, 크기 상한(현재 약 1.2MB → 2MB)을 넘지 않는지 게이트에서 단언(test:package). test:registry 에 "변경 이력에 현재 버전 항목 존재" 단언 추가(변경 이력 누락을 게이트가 막음).
README 릴리스 절차를 "PR 병합 → CI 가 나머지 수행 → npm view·Release 페이지 확인" 3단계로 줄이고, 수동 절차는 비상용으로만 남깁니다.

범위 (제외): 브랜치 보호 설정(저장소 설정이라 코드로 못 함 — 보류 항목에 유지), Homebrew 탭, Windows 서명

검증 기준: test:package·test:registry 게이트 통과. 워크플로는 실제 병합으로만 검증할 수 있으므로 v0.35.0 자체는 마지막 수동 릴리스로 내고, 병합 직후 release.yml 의 "조건 불충족 → 성공 종료" 경로(이미 태그·npm 이 있음)를 로그로 확인합니다. v0.36.0 부터 자동 배포. 배포 뒤 npm view egovframe-scaffold-mcp --json 의 dist.attestations 와 GitHub Release·MCP Registry 검색 결과를 확인합니다.

완료 정의: 도구 27종(변화 없음), release.yml 병합, npmjs.com trusted publisher 등록(소유자 수동 1회, README 에 체크리스트), v0.36.0 이 사람 명령 없이 npm·태그·Release·Registry 에 게시

결과(2026-10-04) — 완료: release.yml(workflow_run: CI 성공 후, workflow_dispatch 로 수동 재실행 가능) + scripts/release-check.mjs(네 조건 판정, GITHUB_OUTPUT) + scripts/release-notes.mjs(변경 이력 항목 → Release 본문에 설치 스니펫·검증 안내) + test/release.mjs 32단언. 기획과 달라진 점: (1) mcp-publisher validate 를 실제로 돌려 보니 server.json 의 description 이 레지스트리 상한 100자를 넘어 첫 등록이 실패할 상태였습니다 — 98자로 줄이고 test:registry 가 100자 이하를 단언하며, CI 통합과 release.yml 이 npm 게시 전에 validate 를 돌립니다(npm 에 없는 버전도 스키마 검증은 통과함을 확인). (2) 레지스트리 게시 단계는 continue-on-error 로 두어 npm·태그·Release 가 끝난 뒤의 실패가 릴리스 자체를 되돌리지 않게 하고 경고로 남깁니다. (3) 릴리스 노트는 변경 이력 항목의 "(1) (2)" 번호 앞에서 단락을 나눠 읽기 쉽게 합니다. 바이너리는 mcp-publisher v1.8.1(자산 이름 mcp-publisher_<os>_<arch>.tar.gz, 버전 접두 없음)로 고정했습니다. v0.35.0 자체는 마지막 수동 릴리스이며, 병합 뒤 release.yml 이 "태그·npm 이미 있음 → 배포 안 함" 으로 성공 종료하는지 확인합니다.

v0.36.0 — 해석된 의존성 트리 + SBOM

목표: check_egovframe_dependencies 는 pom 에 적힌 의존성만 봅니다. 공식 egovframe-web 템플릿은 선언 19건·조치 0건이지만, Maven 으로 실제 해석하면 런타임에 69개 artifact 가 실리고 그중 11개가 기준 미만, 9개가 기준 밖, 8개에 OSV 권고가 붙어 있습니다(선행 조사). 전이 의존성까지 보는 resolve=true 와, 2027년부터 공공기관 SW 등록에 요구될 SBOM 을 표준 형식(CycloneDX 1.6)으로 만들어 주는 도구를 추가합니다.

범위 (포함)

check_egovframe_dependencies(resolve=true, resolveScope="runtime"|"all", timeoutMs): build_egovframe_project 의 러너(타임아웃·프로세스 트리 종료·래퍼 감지)로 Maven org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputFile -DoutputType=text(pom 변경 없이 좌표를 완전히 적어 호출) 또는 Gradle dependencies --configuration runtimeClasspath 를 실행해 트리를 파싱합니다. 결과 findings 에 origin: "declared" | "transitive" 와 via(트리 경로, 예 egovframe-rte-ptl-mvc → spring-webmvc)를 붙이고, 해석된 집합 전체를 기존 분류기(parent → 계열 → Boot BOM/RTE 전이, v0.34)로 판정합니다. summary 는 선언/해석을 나눠 세고, 선언한 버전과 해석된 버전이 다른 좌표(가까운 선언이 이김)는 resolvedDiffers 로 따로 보입니다. offline=false 면 OSV 조회도 해석된 집합에 대해 합니다. 빌드 도구가 없거나 해석이 실패하면 선언 기준 결과에 이유를 붙여 돌려줍니다(기존 동작 유지).
새 도구 generate_egovframe_sbom(projectDir, format="cyclonedx-json", outputPath="sbom/bom.cdx.json", enrich=true, offline=true, dryRun=true): Maven 은 org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom(멀티 모듈 합산, pom 변경 없음), Gradle 은 --init-script 로 cyclonedx-gradle-plugin 3.4.1 을 적용(빌드 파일 변경 없음)해 CycloneDX 1.6 JSON 을 만듭니다. enrich=true 면 component 마다 properties 에 egovframe:status(기준 판정)·egovframe:basis·egovframe:baseline 을 붙이고, offline=false 면 OSV 결과를 CycloneDX vulnerabilities[](affects 로 component 참조)로 넣습니다. 출력은 프로젝트 안 경로만 허용, 기존 파일은 overwrite=true 가 아니면 거부, transaction·dryRun(요약만) 적용. 응답은 component 수·직접/전이 수·판정 집계·취약점 수·파일 경로.
도구 메타: generate_egovframe_sbom 은 openWorldHint(빌드 도구가 저장소 접근)·비파괴(새 파일만, overwrite 는 명시)·outputSchema 선언. 영문 설명·README·AGENTS.md 생성기(사용 가능 도구 목록)에 반영.
기준 카탈로그 소급: 선행 조사에서 드러난 공통컴포넌트 4.3.2 pom 의 project:* groupId(system scope 로 로컬 jar 를 붙이는 관행)는 vendor 로 분류하고 사유에 "system scope 로컬 jar — SBOM 에서 공급자 확인 필요" 를 적습니다.

범위 (제외): SPDX 형식(요구가 생기면 CycloneDX → SPDX 변환기로), 취약점 DB 동봉, 라이선스 정책 판정(SBOM 에 라이선스는 플러그인이 넣는 그대로)

검증 기준: 공식 egovframe-web 템플릿(자리표시자 채운 pom)에서 resolve=true 가 60개 이상 해석·transitive 표시·via 경로 존재, SBOM 이 bomFormat: CycloneDX·specVersion: 1.6·component 60개 이상·모든 component 에 purl(pkg:maven/…)·enrich 속성 존재; offline=false 로 vulnerabilities[] 가 OSV 결과와 같은 수; Gradle 템플릿(egovframe-boot-web 를 Gradle 로 변환한 픽스처 또는 공식 Gradle 샘플)에서 init script 경로 통과; 오프라인 테스트는 트리 파서(Maven·Gradle 출력 픽스처)와 SBOM 보강을 가짜 러너로 단언; CI 통합에 실제 Maven 해석·SBOM 생성 추가

완료 정의: 도구 28종, test:dependencies 에 해석 경로 단언, 신규 test:sbom(오프라인)·test:sbom-live(CI), docs/design-dependency-check.md 에 해석·SBOM 절, README 에 SBOM 사용 예

결과(2026-10-04) — 완료: src/dependency-tree.ts(Maven·Gradle 트리 파서, 가장 얕은 경로로 중복 제거, 래퍼 감지 명령), check_egovframe_dependencies 의 resolve·resolveScope·resolveTimeoutMs, src/sbom.ts(generate_egovframe_sbom). 기획과 달라진 점: (1) Gradle 은 cyclonedx-gradle-plugin 을 init script 로 적용하는 대신 해석된 트리로 이 서버가 CycloneDX 문서를 직접 구성합니다 — 플러그인 버전별 API 차이 없이 결정적으로 동작하고 오프라인 테스트가 가능하며, 대가로 해시·라이선스가 빠집니다(문서 metadata.tools 와 응답 노트에 명시). (2) Maven 범위는 -Dscope=runtime(dependency:tree)·includeProvidedScope=false(플러그인)로 "실리는 것"에 맞추고 all 로 test·provided 를 포함합니다. (3) 선행 조사의 project:* system scope 좌표를 vendor 로, javax.faces:javax.faces-api 를 Jakarta 규칙(→ jakarta.faces:jakarta.faces-api 4.1.2, Boot BOM 기준)으로 소급해 공통컴포넌트 4.3.2 pom 의 unknown 11 → 1(xerces)이 됐습니다. 실측: 공식 egovframe-web 템플릿 해석 65 artifact(직접 14, 선언에 없던 전이 51; 기준 미만 11·기준 없음 9), SBOM 67 component·205KB·OSV 24건, Gradle 샘플 40~46 artifact. Windows 게이트가 깨진 전력 때문에 트리·SBOM 명령은 플랫폼을 주입해 mvn.cmd·gradle.bat 분기를 단언합니다.

v0.37.0 — 移行準備度評価書 + 回帰コーパス

目標：公共 SI の現場で「この 3.x/4.x システムを 5.x に移行すると、何がどれくらいかかり、現在のサプライチェーンの状態はどうなのか」という問いに答えるには、今は 5 つのツールを順に呼び出す必要があります。1 回の呼び出しで評価書を作成し、公式 3.x/4.x 資産に対する結果をコーパスとして固定することで、ルールや基準が変わった際に回帰を検出します。

範囲（含む）

generate_egovframe_report(sections=["assessment"], resolve=false, offline=true): 既存のレポート（診断）に評価書のセクションを追加 — (1) プロジェクト概要（ビルドツール・RTE 世代・parent・Java・共通コンポーネント）、(2) 移行範囲（migrate_egovframe_project の診断概要：自動／手動、種類別、ファイル数、再構成を推奨するコンポーネント、予想される手動作業の上位 N 項目）、(3) 依存関係（基準判定の集計・対応一覧・resolve=true の場合は推移的依存関係を含む・OSV）、(4) セキュリティ設定の点検、(5) SBOM の概要（作成済みの場合はパス・component 数）、(6) 評価と根拠：移行難易度（手動項目数・再構成を推奨するコンポーネント数・削除対象クラスの参照数を基準に）とサプライチェーンの状態（基準未満・交換が必要・脆弱性数）をそれぞれ A–D で評価します。評価の算出式をレポートにそのまま記載し、誰でも再計算できるようにします。Markdown と format=json（outputSchema）に対応し、必要に応じて outputPath にファイルとして保存します（transaction・dryRun）。
回帰コーパス test:migrate-corpus（CI 統合）：公式 egovframe-common-components v3.10.0（1,148 java）と v4.3.2（1,295 java、4.x の座標 org.egovframe.rte:org.egovframe.rte.*）のソースツリー全体に対して診断・適用（dryRun）・依存関係の点検を実行し、種類別件数・unknown・再構成の推奨・適用計画数を catalog/migration-corpus.json に期待値として固定して、±許容範囲内であることを検証します。4.x→5.x の経路はこれまで単体テスト用フィクスチャでのみ検証していたため、実資産で初めて確認することになります。コーパスの結果は、評価書の評価算出式の基準範囲を定める根拠としても使用します。
コーパスで明らかになった不具合の修正（先行調査ですでに 1 件確認済み：4.3.2 の pom にある project:* system scope jar 11 件が unknown — v0.36 で vendor に遡及対応済み。そのほか、javax.faces など未処理の Jakarta 座標があればマッピングに追加）。

範囲（除外）：費用・工数の算定（人や組織によって異なるため、件数と評価まで）、PDF/HWP 出力（Markdown の変換は呼び出し元の担当）

検証基準：2 種類のコーパス（3.10.0・4.3.2）の期待値を固定した後、ゲート・CI を通過すること。評価書が公式 5.x テンプレートで「移行範囲 0・評価 A」となり、3.10 資産では手動項目・再構成の推奨が評価の根拠に示されること。format=json が outputSchema を通過すること。評価算出式の再計算テスト

完了の定義：ツール 28 種（評価書は既存ツールの拡張）、catalog/migration-corpus.json、docs/design-assessment-report.md、README に評価書の例を追加

結果（2026-10-04）— 完了：src/assessment.ts（評価・評価算出・Markdown）と src/report.ts（セクションの組み立て・保存）を追加し、generate_egovframe_report に sections・resolve・offline・sbomPath・topN・outputPath・dryRun・format を追加しました（デフォルトの ["components"] は v0.16 の出力と同じです）。評価算出式はデータ（MIGRATION_RUBRIC・SUPPLY_CHAIN_RUBRIC）として定義し、レポートの第 6 節に全文を掲載します。テストではレポートの数値から再計算します。基準範囲は公式 5.x テンプレート（移行 A）と、共通コンポーネント 3.10.0・4.3.2 の全ツリー（2 つの評価軸で D）を両端として定めました。計画と異なる点は 2 つあります。outputPath は上書きせず、新規ファイルのみを作成します（非破壊性を維持）— その代わり読み取り専用のヒントは外しました（13 種）。サプライチェーン評価は公式テンプレートで B です（pom しかないためセキュリティ設定 3 件が不足し、Initializr の固定 commit における parent が 5.0.0 < 5.0.2 — どちらも事実のため A を強制しませんでした）。コーパスではリポジトリ全体（約 250MB）ではなく、スキャン対象ディレクトリのみを sparse 部分クローンします（タグごとに約 3 秒・50MB）。新たな不具合は明らかにならず（v0.36 で遡及対応したものがすべて）、両世代とも確認が必要なクラスは 0 件、基準なしの xerces は 1 件として固定されました。同じ PR で、v0.36.1 の初回自動公開で明らかになったワークフローの不具合（伝播確認が 2 分を超える → タグ・Release が欠落し、再実行不可）を、再開判定で修正しました。

運用メモ（当時）：npm trusted publisher は 0.36.1 で登録され、初回の OIDC 公開が完了しました。MCP Registry への初回登録は v0.37.0 の自動公開に持ち越しました。

以前の計画（v0.32–v0.34、完了）

v0.31.0 まで完了した状態（2026-10-02、ツール 27 種、テスト約 1,100 件）から、次の 3 リリースを以下の順に進めました。3 バージョンすべて 2026-10-03 までに完了しました。計画の原文は記録として残し、結果を各項目の下に記載しました。共通原則はこれまでと同じです — ルールはデータとして定義し、根拠は公式リポジトリから取得し、書き込みツールには dryRun・transaction を適用します。各バージョンは「完了の定義」を満たしてからリリースします。先行調査の根拠は最下部の「先行調査の結果（2026-10-02）」に記載しています。

v0.32.0 — MCP 프로토콜 현대화 + 테스트 플랫폼 중립 가드

목표: 도구의 "무엇을 하는가"를 설명문뿐 아니라 프로토콜 메타데이터로도 알려 MCP 클라이언트가 승인 UX(읽기 전용은 자동 허용, 파괴적 도구는 확인)와 구조화된 결과 처리를 할 수 있게 합니다. 외부 동작 변화는 없고, 기존 text 응답은 그대로 유지합니다.

범위 (포함)

등록 API: server.tool(...)(SDK 1.29 에서 deprecated) → server.registerTool(name, { title, description, inputSchema, outputSchema?, annotations }, cb) 로 27종 전환. i18n 의 설명 선택은 그대로 description 에 적용하고 title 도 ko/en 으로 둡니다.
annotations: 읽기 전용 도구 14종(list_*·search_*·explain_*·get_*·diagnose_*·validate_*·generate_egovframe_report·check_egovframe_dependencies·migrate(apply=false)·sync_*)에 readOnlyHint: true, 파일을 지우거나 덮어쓰는 도구(remove_egovframe_components·upgrade_egovframe_project·migrate(apply)·generate_agents_md(overwrite))에 destructiveHint: true, 다시 실행해도 같은 결과인 도구에 idempotentHint, 네트워크를 쓰는 도구에 openWorldHint: true. migrate_egovframe_project 처럼 인자에 따라 성격이 바뀌는 도구는 보수적으로(파괴 가능) 표시하고 설명에 조건을 적습니다.
구조화 출력: 이미 format=json 을 제공하는 5종(diagnose_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network·validate_egovframe_project)에 zod outputSchema 를 선언하고 structuredContent 를 함께 돌려줍니다(text 는 유지). 스키마는 src/*.ts 의 결과 인터페이스에서 도출하며 테스트가 실제 결과를 스키마로 검증합니다.
테스트 플랫폼 중립 가드: v0.30·v0.31 에서 두 번 연속 Windows gate 만 깨진 원인(테스트가 POSIX 경로·래퍼 이름을 가정)을 구조적으로 막습니다 — (a) resolveCommand·walk·경로 비교처럼 플랫폼 분기가 있는 함수는 platform 주입 옵션을 두고 테스트가 win32·linux 양쪽을 명시적으로 단언, (b) scripts/check-test-portability.mjs 가 test/*.mjs 에서 "./mvnw"·endsWith("/…")·path.sep 미정규화 path.relative 같은 패턴을 찾아 실패시키고 prepublishOnly 에 포함, (c) README 릴리스 절차 2단계에 "Windows 체크아웃에서 통과" 조건을 명문화.

범위 (제외): 도구 추가, 응답 본문 변경, SDK 메이저 업그레이드(1.x 유지)

검증 기준: test:handshake 가 27종 전부 title·annotations 존재와 읽기 전용 도구의 readOnlyHint 를 단언, 구조화 출력 5종은 structuredContent 가 outputSchema 를 통과(오프라인 픽스처), 이식성 검사 스크립트가 현재 테스트에서 0건, Windows gate 3개 통과

완료 정의: 도구 27종(변화 없음), deprecated API 사용 0건, 기획 전 조사한 Claude Desktop·VS Code 에서 읽기 전용 도구가 승인 없이 실행되는지 수동 확인 1회

결과(2026-10-02) — 완료: server.tool() 27회 → registerTool 27회(deprecated 0건), src/tool-meta.ts(title ko/en·annotations)와 src/output-schemas.ts(zod, 핵심 필드 엄격·그 외 passthrough) 추가, test:output-schemas 41단언·handshake 확장. 이식성 검사는 과거 두 번의 Windows 실패 줄을 모두 잡는 것을 확인했고, 현재 테스트에서 잠복해 있던 같은 유형 1건(test/dependencies.mjs 의 path.relative 비교)을 추가로 고쳤습니다. 의도된 POSIX 경로 12줄은 사유를 달아 허용했습니다. 클라이언트 수동 확인(읽기 전용 도구 자동 승인)은 npm 배포 뒤 저장소 소유자가 수행합니다.

v0.33.0 — `migrate_egovframe_project` 3단계: 검증 + 공통컴포넌트 대응표

목표: 2단계 적용 뒤 남는 일(컴파일 오류 고치기)을 사람이 처음부터 찾지 않게 합니다. "컴파일 오류 N건 중 M건은 수동 항목 K 때문" 을 연결한 작업 목록을 돌려주고, 3.x 공통컴포넌트 소스가 섞인 프로젝트에는 5.0.6 기준 대응표와 재조립 권고를 냅니다.

범위 (포함)

migrate_egovframe_project(mode="verify")(또는 apply=true, verify=true): build_egovframe_project(goal="compile") 을 실행해 파일·라인 단위 오류를 받은 뒤, 각 오류를 (1) 같은 파일의 수동 항목 — 라인 근접·심볼 일치(cannot find symbol … Mapper ↔ class-removed Mapper→EgovMapper), (2) 규칙 카탈로그의 제거 클래스·제거 모듈 심볼, (3) 분류 불가 로 나누고, 수동 항목별로 "이 항목을 처리하면 해결될 오류" 수를 붙여 우선순위를 매깁니다. 빌드 도구가 없으면 verify 는 건너뛰고 이유를 적습니다.
공통컴포넌트 3.x→5.x 대응표: scripts/generate-migration-rules.mjs 에 egovframe-common-components 저장소(v3.10.0 ↔ v5.0.6)를 두 번째 근거로 추가해 egovframework.com.* 의 제거 클래스(조사 시점 58종, 예: cmm.util.EgovMybaitsUtil, sec.rnc.service.EgovSocketClient, ext.oauth.*)·추가 52종·이름 변경 4종을 packages.components 로 기록합니다. 진단은 사용자 소스가 제거 클래스를 참조하면 class-removed(manual) 로 보고합니다.
재조립 권고: 진단에서 diagnose_egovframe_project 가 감지한 공통컴포넌트 패키지가 3.x 소스(egovframework.rte import 또는 javax.servlet)이면 "add_egovframe_components 로 5.0.6 을 다시 조립하고 사용자 수정은 백업과 diff 로 옮기라" 는 항목을 컴포넌트 단위로 1건씩 내고, 2단계 적용은 그 디렉터리를 치환 대상에서 뺄 수 있는 옵션(skipComponents)을 둡니다.

범위 (제외): 컴파일 오류 자동 수정, 공통컴포넌트 소스의 3-way 병합(그건 upgrade_egovframe_project 가 매니페스트가 있을 때만 하는 일)

검증 기준: 픽스처(2단계 적용 후 제거 클래스를 참조하는 java 2개)로 verify 가 오류 ↔ 수동 항목을 정확히 연결, CI 통합에서 실제 mvn compile 오류 파싱 경로 통과, 규칙 정합 테스트가 공통컴포넌트 대응표의 목적지가 v5.0.6 트리에 있는지 검증, 공식 5.x 템플릿에서 verify 오류 0건

완료 정의: 도구 27종, test:migrate 에 verify 단언 추가, docs/design-migration.md 3단계 절, 규칙 카탈로그 schemaVersion 2(하위 호환 필드 유지)

결과(2026-10-02) — 완료: verify 는 apply·dryRun 과 같은 도구의 파라미터로 두었고(mode 문자열 대신), 연결은 심볼 일치 → 라인 근접 → 규칙 심볼 → 미분류 4단계입니다. 공통컴포넌트 대응표의 실제 수치는 제거 54·이동 4·추가 52(기획의 58 은 트리 비교에서 단순명 이동 4건을 빼기 전 값)이며, 생성기가 루트형(src/main/java/) 저장소도 읽도록 고쳤습니다. 큐레이션 대체는 EgovMybaitsUtil→EgovMybatisUtil(오타 정정) 1건입니다. CI 통합에서 실제 mvn compile 오류 3건이 수동 항목 2건에 전부 연결됐습니다.

v0.34.0 — 의존성 기준 완성 + 규칙 drift 감시

목표: check_egovframe_dependencies 의 unknown 을 줄이고, 동봉 규칙·기준이 upstream 과 어긋나면 사람이 알게 합니다.

범위 (포함)

Spring Boot BOM 전체: 생성기가 spring-boot-starter-parent → spring-boot-dependencies pom 을 Maven Central 에서 받아 dependencyManagement(약 300 좌표)와 그 안의 BOM import 를 한 단계 더 풀어 catalog/dependency-baseline.json 에 managedBoot 로 넣습니다(계열 규칙은 유지). Boot parent 프로젝트의 버전 없는 의존성은 managed 에 기준 버전을 함께 보입니다.
RTE 모듈 전이 의존성: egovframe-runtime v5.0.2 모듈 pom 18종의 <dependencies> 를 읽어 mybatis·mybatis-spring·poi·quartz 등 RTE 가 끌어오는 버전을 managedRte 로 기록하고, 프로젝트가 같은 좌표를 더 낮은 버전으로 명시하면 outdated(사유: RTE 전이 버전과 충돌 가능) 로 봅니다.
drift 감시: sync_egovframe_templates 에 migrationRules·dependencyBaseline 절을 추가해 (1) egovframe-runtime 최신 태그가 규칙의 toTag 보다 새로운지, (2) parent 2종의 최신 버전이 기준 sources 보다 새로운지, (3) parent pom sha256 이 바뀌었는지를 보고합니다(파일은 고치지 않음). 변화가 있으면 README 의 갱신 절차를 결과에 붙입니다.
check_egovframe_dependencies 결과에 "기준 출처"(parent 직접 / 계열 / Boot BOM / RTE 전이)를 항목마다 표시합니다.

범위 (제외): 자동 버전 올리기(파일 수정), 취약점 DB 동봉

검증 기준: 공식 5.x egovframe-boot-web 템플릿에서 unknown 0건, 공식 공통컴포넌트 v3.10.0 pom 에서 unknown 18 → 5 이하, drift 테스트는 네트워크(CI 통합)와 오프라인 모의 양쪽, 기준 카탈로그 생성이 재현 가능(sha256 고정)

완료 정의: 도구 27종, test:dependencies 확장, docs/design-dependency-check.md 갱신, 기준 파일 크기 200KB 이하 유지

결과(2026-10-03) — 완료: 기준 파일 schemaVersion 2 에 boot(spring-boot-dependencies 3.5.6 직접 362 + import 44종 → 1,473 좌표, 충돌 1건은 Maven 순서대로 직접 항목 유지)와 rteTransitive(모듈 18종 pom → 58 좌표, 버전·scope·via)를 넣었고 크기는 150KB 입니다. 기획과 달라진 점: (1) 표준프레임워크 저장소가 maven-metadata.xml·디렉터리 목록을 막아 두어 "최신 parent 버전" 대신 다음 patch 3개·minor·major 후보를 HEAD 로 탐침합니다 — 이 탐침이 기준(5.0.1)보다 새 parent 5.0.2 를 찾아 이번에 기준을 5.0.2 로 올렸습니다(차이는 RTE 버전뿐). (2) 태그 조회는 GitHub API 가 막히면 태그 페이지(HTML)로 대체합니다(GITHUB_TOKEN 이 있으면 API 에 씀). (3) 계열 규칙이 org.springframework.social·.ldap 까지 org.springframework 로 묶던 결함을 고쳐 groupId 정확 일치(jackson 만 하위 포함)로 좁히고 달력형 릴리스 트레인(spring-cloud-dependencies)은 계열에서 뺐습니다. (4) 공통컴포넌트 3.10 pom 의 unknown 17건 가운데 공개 기준이 있을 수 없는 국내 벤더·기관 배포 6건은 새 분류 vendor(사유 표시)로, EOL·이전 좌표 8건은 전환 규칙 libraries 에 교체 규칙을 추가해(migrate_egovframe_project 의 manual 항목으로도 나옵니다) 남은 unknown 은 xerces:xercesImpl 1건입니다. 검증: 공식 egovframe-boot-web·egovframe-web 템플릿 pom unknown 0, drift 테스트는 오프라인 주입 26단언 + CI 통합 실제 조회, 기준 생성은 --cache/--offline 으로 재현 가능(같은 입력 → 같은 파일).

이전 기획 (v0.29–v0.31, 완료)

v0.28.1 까지의 상태에서 다음 세 릴리스를 아래 순서로 진행합니다. 각 항목은 "완료 정의"를 만족해야 릴리스합니다. 기획 시점(2026-09-26)의 조사 근거는 맨 아래 "선행 조사 결과"에 있습니다. v0.29.0 은 2026-09-27 에 완료했으며 기획 원문은 기록으로 남기고 결과를 항목 아래에 적었습니다.

v0.29.0 — `migrate_egovframe_project` 第1段階：移行診断（読み取り専用）— 完了

結果（2026-09-27）：完了条件をすべて満たしました — ツール24種、test:migrate 87アサーション・test:migration-rules 579アサーションに合格、test:migration-rules-live 61件（RTE 5.x・3.x のソース・parent・Jakarta 座標）の実リポジトリでの存在確認、公式5.x egovframe-web・egovframe-boot-web テンプレートからの項目検出0件、公式 egovframe-common-components v3.10.0 の pom・web.xml・ソースの一部から57件（auto 48・manual 9）を検出、設計ドキュメント docs/design-migration.md。計画からの変更点：ルールの根拠を「5.x テンプレート pom ＋共通コンポーネントのパッケージツリー」ではなく、egovframe-runtime リポジトリの3つのタグ（v3.10.0・v4.3.0-Final・v5.0.2-Final）のソースツリー比較とし、クラス単位の移動・削除を機械的に導出しました（削除38種にはキュレーション理由が必須）。4.x 座標（org.egovframe.rte:org.egovframe.rte.*）もあわせて扱います。

目標：標準フレームワーク3.x／4.x で作成された既存プロジェクトを、5.x（Jakarta EE 9+、Spring 6）に準拠させるために何を変更すべきか、ファイル・行単位で報告します。この段階ではファイルを書き込みません。診断結果が正確でなければ第2段階の自動適用を信頼できないため、まず診断をリリースし、実際のプロジェクトで検証します。

範囲（含む）

Maven 座標：egovframework.rte:egovframework.rte.<layer>.<module> → org.egovframe.rte:egovframe-rte-<layer>-<module> の対応表、RTE バージョンプロパティ、リポジトリ URL（https://maven.egovframe.go.kr/maven/）の有無、parent（org.egovframe.web:egovframe-web-config-parent、org.egovframe.boot:egovframe-boot-starter-parent）の使用有無
Java ソース・XML：egovframework.rte.* の import・bean class → org.egovframe.rte.*
Jakarta への移行：javax.servlet・javax.servlet.jsp・javax.validation・javax.persistence・javax.annotation（Spring 6 で変更されたもののみ）→ jakarta.* の使用箇所一覧。javax.sql・javax.xml など、JDK に組み込まれたパッケージは対象外
JSP/TLD：web.xml のスキーマバージョン、JSTL 座標（jakarta.servlet.jsp.jstl）
自動変換できない項目の報告：3.x で削除・変更された RTE API（対応表で manual と表示されるもの）、Spring 4→6 で削除されたクラス、commons-dbcp（1.x）・log4j 1.x などの置き換えが必要なライブラリ

範囲（除外）：ファイルの変更、ビルドの実行、共通コンポーネントのソース自体のバージョン更新（これは upgrade_egovframe_project の範囲）

設計の要点

ルールはコードではなくデータとして保持します：catalog/migration-rules.json（schemaVersion 1）に座標対応表・パッケージ対応表・javax→jakarta 一覧・手動対応項目を収録し、生成スクリプトが公式リポジトリ（5.x テンプレート pom、egovframe-common-components 5.x パッケージツリー）で根拠を照合します。ルール整合性テスト（test:migration-rules）では、対応表の移行先座標・パッケージが実際の5.x アセットに存在するかを検証します。
ツール migrate_egovframe_project(projectDir, target="5.x", format="json|markdown") は diagnose_egovframe_project のスキャン結果（ビルドツール・RTE バージョン・インストール済みコンポーネント）を再利用し、項目ごとに {file, line, kind, from, to, auto|manual, reason} を返します。Markdown 要約（generate_egovframe_report 形式）も提供します。
許可された root・読み取り専用の保証は、既存ツールと同じです。

検証基準

オフラインのフィクスチャ：3.10 スタイルの pom・egovframework.rte import・javax.servlet の使用・XML bean が混在するプロジェクトを使い、項目の分類（auto/manual）・行位置・対応座標を検証
実プロジェクト：公式5.x web-sample を対象に、「移行項目0件」（誤検出なし）を確認
ルール整合性：対応表のすべての to 座標が https://maven.egovframe.go.kr/maven/ または Maven Central のメタデータに存在すること（ネットワークテスト、CI）

完了条件：ツール24種、フィクスチャ・ルール整合性テストに合格、設計ドキュメント docs/design-migration.md（対応表の出典・手動対応項目の根拠・第2段階の計画を含む）

v0.30.0 — 移行の適用＋依存関係の確認

migrate_egovframe_project の第2段階（適用）

第1段階のレポートにある auto 項目のみを適用します。pom 座標の置換、import・bean class の置換、javax→jakarta の置換を行います。manual 項目は結果にそのまま残し、人が対応できるようにします。
dryRun の既定値は true です。適用時は ProjectFileTransaction により、ファイル・バックアップ（migration-backup/）・レポート（migration-plan.json）をひとつの transaction として反映し、途中で失敗した場合は作業前の状態に復元します。ユーザーによる変更の有無にかかわらず、元のファイルをバックアップします（アップグレードツールと同じ方針です）。
適用後の推奨される次のステップとして build_egovframe_project(goal=compile) を案内し、コンパイルエラーがある場合は、関連する manual 項目とあわせて表示します。
検証：フィクスチャプロジェクトの変換後、JDK 17 で mvn compile が成功（CI 統合テスト）。適用中の fault-injection rollback も検証

check_egovframe_dependencies(projectDir, offline=true)

プロジェクトの RTE・Spring・共通コンポーネント・主要ライブラリのバージョンを、catalog/dependency-baseline.json（公式 5.x テンプレートから抽出した基準バージョン）と照合し、outdated・unknown・ok に分類します。閉域網を考慮し、既定ではオフラインで動作します。offline=false の場合に限り、OSV（https://api.osv.dev）で既知の脆弱性を照会します。
セキュリティ設定の確認（旧 security_patch_advisor）は、このツールの checks 項目に統合します。CSRF フィルター・sec.security コンポーネントのインストール有無・web.xml のセキュリティヘッダーフィルターの有無などを確認し、存在の有無のみを判定します。判定根拠（ファイル・行）もあわせて返します。

完了の定義：ツール 25 種、フィクスチャ変換後に mvn compile が成功、基準バージョンファイルの生成スクリプトと整合性テスト

結果（2026-09-28）— 完了：ツール 25 種。適用は、第1段階が auto 項目ごとに付与する元テキストのオフセット編集をそのまま反映する方式で実装しました（test:migrate 132 アサーション）。3.10 座標・javax フィクスチャの適用後、JDK 17 で mvn compile が成功（test:migrate-integration）。公式共通コンポーネント v3.10.0 のアセットに対し、auto 48 項目・86 箇所を適用した後に再診断し、auto が 0 であることを確認しました。依存関係の基準は公式 parent 2 種の pom から生成しました（scripts/generate-dependency-baseline.mjs、管理対象座標 139 種＋BOM 系 7 種）。test:dependencies 68 アサーション・test:dependencies-live（OSV）で検証しました。計画からの変更点：parent が spring-* を BOM で管理するため、「系列基準」（groupId 接頭辞）の概念を追加し、Spring Boot BOM の全一覧は含めず、managed に分類します。Jakarta 移行ルールの移行先バージョンを parent の基準以上に合わせました（jstl-api 3.0.2・jsp-api 4.0.0・validation-api 3.1.1・annotation-api 3.0.0・websocket-api 2.2.0）。

v0.31.0 — 運用の利便性

diagnose_egovframe_network：ツールが使用するホスト（codeload.github.com・raw.githubusercontent.com・media.githubusercontent.com・maven.egovframe.go.kr・registry.npmjs.org）への接続可否・所要時間・エラーの種類（DNS・タイムアウト・TLS・プロキシ認証）を報告し、環境変数による対処法（HTTPS_PROXY＋NODE_USE_ENV_PROXY=1、NODE_OPTIONS=--dns-result-order=ipv4first）を案内します。2026-09-21 に新しいノート PC で codeload.github.com への接続がタイムアウトし、test:templates が失敗した経験に基づいています。既存のダウンロード経路が失敗した場合も、同じ対処法をエラーメッセージに追加します。
英語版 README と、ツール説明の英語併記（応答言語は韓国語のまま維持し、EGOVFRAME_LANG=en オプションを検討）
MCP Registry への登録 と server.json メタデータ、Homebrew タップは後回し
generate_agents_md：プロジェクトの診断結果から、AI コーディングツール向けの AGENTS.md（ビルド・テストコマンド、インストール済みコンポーネント、禁止事項）を生成

結果（2026-09-30）— 完了：ツール 27 種。ネットワーク診断では、ホスト 7 種（計画時の 5 種＋repo1.maven.org・api.osv.dev）を実際にプローブし、失敗を 8 種に分類します。Node が --use-env-proxy をサポートしているかを実行時に検出し、NODE_USE_ENV_PROXY=1 を使った対処法を案内します。既存のダウンロード経路（fetchWithTimeout）は、失敗時に同じ分類と対処法を 1 行でエラーに追加します。英語は README.en.md と EGOVFRAME_LANG=en によるツール説明（全 27 種。handshake テストで漏れを防止）で提供し、応答は韓国語のまま維持します。MCP Registry については server.json・mcpName と整合性テストまで準備しました。実際の公開（mcp-publisher publish）は、npm のデプロイ後にリポジトリの所有者が実行します。Homebrew タップは引き続き後回しです。

リリース手順（v0.35以降、すべてのバージョンで共通）

main を最新化して機能ブランチを作成 → パッチを適用（git am）するか、直接コミットします。バージョンは package.json・server.json（2か所）を同時に更新し、README の変更履歴に - **X.Y.Z** — … の項目を記載します（test:release が3項目を検証します）。
npm ci && npm run prepublishOnly がローカルで成功することを確認します（Windows のクローンでも core.autocrlf にかかわらず成功する必要があります）。テストの期待値はプラットフォーム中立にします — プラットフォーム分岐関数には platform を注入して両方を検証し、npm run check:portability は0件である必要があります。
プッシュ → PR → CI 7件（ubuntu・windows × Node 18/20/22 + integration）がすべて成功 → squash マージします。ここまでが人間の作業です。
マージ後に main の CI が成功すると、Release ワークフロー（.github/workflows/release.yml）が scripts/release-check.mjs で前提条件（server.json のバージョン一致・変更履歴の項目）を確認し、リモートの状態（npm・タグ・GitHub Release・MCP Registry）を見て、残りの手順だけを実行します：npm（OIDC trusted publishing、provenance は自動）→ 公開済みコミットに vX.Y.Z タグを作成 → GitHub Release（scripts/release-notes.mjs）→ MCP Registry（GitHub OIDC）。条件に合わない場合は理由を記載して正常終了します（ドキュメントのみを変更したマージでは何も公開されません）。
確認：Actions の Release の概要（手順ごとの結果）、npm view egovframe-scaffold-mcp version、Releases ページ、レジストリ検索。途中で中断した場合（v0.36.1 のような npm の反映遅延、Registry の失敗など）も、手動で対応する必要はありません。次の main マージ（または Run workflow）で Release が続きから実行します — npm だけが公開済みの場合は、npm が記録した gitHead コミットにタグを作成するため、パッケージとタグが同じコードを指します（そのコミットが main の祖先でなければ、手動でタグを作成するよう案内して停止します）。

緊急時の手動手順（ワークフローを使用できない場合）：main で node -p "require('./package.json').version" を実行してバージョンを確認してから、main のコミットにタグを作成してプッシュ → npm publish → mcp-publisher publish。タグは必ずマージ済みの main コミットに付けます（v0.25.2・v0.28.0・v0.28.1・v0.30.0・v0.33.0 で誤ったコミットに付けたことがあり、自動化しました）。

事前調査の結果（2026-10-04）

npm trusted publishing：2025-07-31 に GA。npm CLI 11.5.1+・Node 22.14+、ワークフローの permissions: id-token: write、npmjs.com で trusted publisher（組織／ユーザー・リポジトリ・ワークフローファイル名・任意の environment）を登録します。公開リポジトリ・公開パッケージの場合、provenance が自動で付与されます（provenance=false で無効にできます）。セルフホストランナーは未対応です。workflow_call で再利用するワークフローは呼び出し元のワークフロー名で検証されるため、単一の release.yml にします。
MCP Registry：mcp-publisher login github-oidc でシークレットなしでログインします（id-token: write）。io.github.<owner>/* 名前空間は GitHub アカウントの所有権によって証明します。バイナリは github.com/modelcontextprotocol/registry/releases から OS/ARCH ごとの tar.gz を取得します。npm に mcpName を持つパッケージが先に公開されている必要があるため、npm 手順の後に実行します。リポジトリの検索結果はまだ0件です。
解決済みの依存関係：公式の egovframe-web テンプレート pom（プレースホルダーのみを埋める）に対して、maven-dependency-plugin:3.8.1:list -DincludeScope=runtime → 67 artifact、cyclonedx-maven-plugin:2.9.3:makeBom -DschemaVersion=1.6 → pom の変更なしで186KBのJSON、component 69件（purl・MD5/SHA ハッシュ・ライセンスを含む）。解決済みの集合を v0.34 の分類器で判定すると、parent からの直接依存23・系列13・RTE の推移的依存9・Boot BOM 4 は ok、基準未満11（RTE 5.0.0 が7 + Boot BOM 4）、基準なし9（commons-collections 3・commons-logging・antlr ランタイムなど）、OSV の勧告が付く component 8件（spring-webmvc/-core/-web/-webflux/-expression 6.2.11、log4j-core/-api 2.25.3、commons-configuration2 2.11.0）。宣言のみを見ていた結果（対応0件）とは大きく異なります。プラグインの最新バージョン：maven-dependency-plugin 3.11.0、cyclonedx-maven-plugin 2.9.3、cyclonedx-gradle-plugin 3.4.1（検証済みのバージョンに固定）。
SBOM ポリシー：科学技術情報通信部・国家情報院のソフトウェアサプライチェーンセキュリティロードマップ（2026-06）では、2027年から公共機関が導入ソフトウェアの SBOM を統合管理体系に登録し、サプライチェーンのリスクを継続的に点検するとともに、公共 IT 事業で SBOM と脆弱性対応手順の提出を求めるよう段階的に進めるとしています（形式は SPDX/CycloneDX を指定していません — CycloneDX 1.6 JSON を標準とし、SPDX は変換で対応します）。
4.x の資産：egovframe-common-components は v4.3.2 が4.x最後のタグです（java 1,295件、依存関係70件）。pom に現行の診断を実行すると、4.x 座標9・Jakarta 8・ライブラリ8・削除モジュール1（auto 19・manual 11）が検出されます。また、依存関係チェックでは project:* groupId の system scope のローカル jar 10件（ojdbc6・altibase・tibero5・cubrid・goldilocks8・smeapi・gpki 2件・onepass）と javax.faces:javax.faces-api が unknown のまま残っており、v0.36 への遡及対応・v0.37 コーパスで最初に修正する対象です。
リリース事故の記録（背景）：v0.30.0 のタグをマージ前のコミットに作成（復旧）、v0.33.0 のタグをローカルの main コミットに作成（復旧）、0.32.0・0.33.0 が npm 未公開（0.33.0 は Windows ゲートの不具合により意図的にスキップ）、#33・#36 を Windows ゲート失敗の状態でマージ。いずれも手動手順で発生しました。

事前調査結果（2026-10-02）

@modelcontextprotocol/sdk のインストール済みバージョン 1.29.0（最新 1.31.0）では、McpServer.tool() は非推奨で、registerTool() は title・inputSchema・outputSchema・annotations（readOnlyHint・destructiveHint・idempotentHint・openWorldHint）を受け取ります。現在のサーバーでは tool() が 27 回呼び出されており、annotations・outputSchema は使用していません。
egovframe-common-components の最新バージョンは v5.0.6（カタログと同じ）で、src/main/java のクラス数は v3.10.0 の 1,095 から v5.0.6 の 1,089 へと変化し、削除 58・追加 52・単純な名前ベースの変更 4 です。パッケージ構造（egovframework.com.<domain>）は維持されているため、対応表は小規模です。
egovframe-runtime の最新タグは v5.0.2-Final（ルールカタログと同じ）で、公式 parent は web・boot ともに 5.0.1 であり、基準カタログと同じです — 2026-10-02 時点でドリフトはありません。
MCP Registry で io.github.EricSeokgon/egovframe-scaffold-mcp を検索した結果は 0 件で、まだ公開前です。

事前調査結果（2026-09-26）

公式テンプレートはすでに 5.x です。egovframe-web-sample は org.egovframe.web:egovframe-web-config-parent:5.0.1、egovframe-template-simple-backend は org.egovframe.boot:egovframe-boot-starter-parent:5.0.1（プロジェクトは 5.0.2、Java 17）を使用しています。依存関係は jakarta.servlet・jakarta.validation・jakarta.json で、一部のライブラリは jakarta classifier を使用します。したがって、移行ツールの移行先は「4.x」ではなく 5.x（Jakarta） とします。
5.x 実行環境の座標は org.egovframe.rte:egovframe-rte-<layer>-<module>（例：egovframe-rte-ptl-mvc、egovframe-rte-psl-dataaccess、egovframe-rte-fdl-idgnr、egovframe-rte-fdl-property）で、リポジトリは Maven Central と https://maven.egovframe.go.kr/maven/ の 2 か所です。3.x の egovframework.rte:egovframework.rte.<layer>.<module> とは命名規則が異なるため、対応表が必要です。
egovframe-docs リポジトリには 3.x→4.x/5.x の移行ガイド文書がありません（2026-09-26 時点）。対応表は公式 5.x pom と egovframe-common-components 5.x のパッケージツリーから導出する必要があり、その導出スクリプトと根拠を docs/design-migration.md に記載します。
diagnose_egovframe_project は pom の文字列パターンから RTE バージョンを推定します。移行診断では、これに座標ベースの判定（egovframework.rte の groupId が存在 = 3.x 系列）を加えて精度を高めます。
Initializr upstream で発見した問題 3 件（v0.28.0 の変更履歴を参照）は、別途 issue として提出する候補です。

ロードマップの根拠：

egovframe-development には公式 CRUD ウィザードの入力項目と 2 つのテンプレートツリーがあり、MCP も同じ入力方式を使用すれば、IDE と対話型ツールの体験を統一できます。
egovframe-vscode-initializr には機械可読なプロジェクト・context XML カタログがすでにあるため、新しい一覧を作成するよりも、共通スキーマに昇格させるほうが保守に有利です。
egovframe-common-components v5.0.6 の分析結果から、実際の実行にはソース・Mapper・JSP 以外に、リソース・設定・機能別の依存関係・セキュリティパッチの追跡が必要です。

詳細な企画と調査根拠は、egovframe-contribution-notes の v0.20+ ロードマップで管理します。

開発基盤の改善も並行して進めます。GitHub Actions と prepublishOnly の全テストを一致させ、lockfile に基づく再現可能なインストールを実現し、Windows・韓国語のパス・大容量 zip の検証を強化します。単一ファイルだった src/index.ts（約 3,200 行）はドメイン別の 14 個のモジュールに分割しました（公開 export・MCP プロトコルの表面は不変）。index.ts はエントリーポイントと公開 API の再エクスポートのみを担当します。

変更履歴

0.43.0 — CI・提出形式の多様化：GitLab・Jenkins、SPDX（ツール数は32種を維持）。（1）generate_egovframe_ci に platform="github"|"gitlab"|"jenkins" を追加：src/ci-config.ts — generateGitlabCi（.gitlab-ci.yml、maven:3.9-eclipse-temurin-<JDK>・eclipse-temurin:<JDK> イメージ、ローカルリポジトリーキャッシュ、JUnit レポート、supply-chain job は needs: []・Node の準備・artifacts:reports:cyclonedx）・generateJenkinsfile（Declarative — options・environment・Build／SBOM／SBOM check／Assessment ステージ・post { always { archiveArtifacts } }、isUnix() で sh／bat を切り替え）、3つのプラットフォーム共通のゲートコマンド supplyChainCommands（sbom → sbom-check --fail-on minimum（GitHub ゲートにも追加）→ assess）、新しいパラメーター supplier（SBOM のサプライヤー）・npmRegistry（NPM_CONFIG_REGISTRY）・offlineBundle（EGOVFRAME_OFFLINE_BUNDLE）を追加 — すべて形式を制限して設定ファイルの注入を防止し、サプライヤーの手掛かりがない場合はゲート失敗を予告（notes）します。（2）SPDX 2.3：src/spdx.ts — cdxToSpdx（パッケージ・DESCRIBES・DEPENDS_ON（依存関係がない場合は NONE）・purl/cpe/swid externalRefs・supplier/originator・creators・created・チェックサム・宣言ライセンス（LicenseRef- ＋ hasExtractedLicensingInfos）・OSV アドバイザリー SECURITY／advisory・egovframe:* annotations、決定的な namespace の serialNumber UUID）・spdxToCdx（検査用、*_DEPENDENCY_OF を反転・NOASSERTION は不明として扱います）。generate_egovframe_sbom(bomFormat="spdx-json")（既定のパスは sbom/bom.spdx.json、最小要素は SPDX を読み戻して判定）、check_egovframe_sbom は CycloneDX・SPDX 2.x を自動判別（document.format、形式が異なる baseline は purl で比較、SPDX の vex=true は拒否）。CLI sbom --bom-format spdx-json。（3）テスト：新規 test:spdx は43アサーション（ゲート、公式 spdx-spec v2.3 スキーマの固定データ）、test:ci に GitLab 公式 CI スキーマ（gitlab v19.4.1-ee の固定データ、devDependency yaml）・Jenkinsfile の構造・注入拒否を追加、test:sbom-live（CI 統合）で実際の Maven SBOM の SPDX スキーマ・判定の一致を確認し、test:sbom-check の CycloneDX 以外を拒否するアサーションを SPDX 3.0 などに更新。（4）CI：integration job の Maven がリモートリポジトリーの5xx（502など）を3秒間隔で最大5回再試行するようにしました（#53）。（5）generate_egovframe_sbom：cyclonedx-maven-plugin の出力に metadata.timestamp がない場合（CI ランナーで実測）、生成時刻を補完して通知 — v0.40 以降、ときどき発生していた sbom-live の最小要素失敗の原因でした。server.json 0.43.0。
0.42.0 — 閉域網向けオフラインバンドル（ツール数31 → 32種）。（1）新しいツール prepare_egovframe_offline_bundle(outputDir, include=["osv","components","templates","origin"], templates?, dryRun=true, format) を追加：src/offline-bundle.ts・src/offline-bundle-plan.ts — OSV Maven 全件ダンプ（osv-vulnerabilities/Maven/all.zip、レコード数・ソースの更新時刻を記録）、カタログの固定コミットに対応する共通コンポーネントのアーカイブ（sha256・サイズを検証）、テンプレート（既定：固定フィンガープリント付き Initializr zip 12種、リポジトリーテンプレートは指定時に codeload zip）、公式共通コンポーネントの全タグを含む bare ミラー（git fetch --depth 1 +refs/tags/*）を一時ディレクトリーに取得し、bundle-manifest.json（schemaVersion 1、ファイルごとの path・kind・url・sha256・bytes・fetchedAt）とともに新規（または空の）ディレクトリーへ移動します。固定フィンガープリント不一致・失敗時は痕跡を残しません。ツールメタデータは非読み取り・非破壊・openWorld、outputSchema（11種）、英語の説明、AGENTS.md のツール一覧に追加。（2）EGOVFRAME_OFFLINE_BUNDLE：fetchWithTimeout（GET）とカタログアーカイブのダウンロードが、manifest と同じ URL のものをフィンガープリント検証後にバンドルから返します（改ざんを拒否、プロセスごとに1回検証）。defaultOsvQuery はローカルダンプで判定（buildOsvIndex・queryOsvIndex・inOsvRange・compareMavenVersions — Maven ComparableVersion の要点、versions リストまたは ECOSYSTEM 範囲、撤回されたものは除外）、GitOriginSource はバンドルのミラーを使用（for-each-ref でタグ一覧を取得、リモート fetch なし、存在しないタグを案内）。OSV を利用した結果（依存関係チェック・SBOM 生成・SBOM チェック）にスナップショットの基準日を記載し、30日経過時に警告（EGOVFRAME_BUNDLE_MAX_AGE_DAYS）。（3）diagnose_egovframe_network が失敗時にオフラインバンドルの手順（bash・cmd・PowerShell）と使用中であることを表示。CLI bundle（受け取りは --write の場合のみ、--output-dir は現在のディレクトリーを基準）、server.json 環境変数 EGOVFRAME_OFFLINE_BUNDLE（4種）。（4）テスト：新規 test:offline-bundle は30アサーション（ゲート）・test:bundle-live（CI 統合：実際のバンドル、ローカル OSV ＝オンライン、fetch を遮断した状態での生成・組み立て・再組み立て・SBOM の再チェック）、registry 環境変数4種、output-schemas・handshake は32種・11種、cli コマンド10種。設計：docs/design-offline-bundle.md。（5）ランタイム依存関係 handlebars 4.7.9 → 4.7.10（GHSA-xw65-4hp5-5hc7・GHSA-8r5x-fm3f-whwj・GHSA-p8wg-vrv2-v86f、npm audit --omit=dev ゲート）。server.json 0.42.0。
0.41.0 — 移行リハーサル（ツール数30 → 31種）。（1）新しいツール rehearse_egovframe_migration(projectDir, steps=["reassemble","migrate","verify","align-pom"], components?, sourceTag="auto", keepWorkspace=false, timeoutMs=900000, topN=20, format) を追加：src/rehearse.ts — コピー上（EGOVFRAME_CACHE_DIR/rehearsal、ビルド成果物・VCS・バックアップを除外、作業ディレクトリーがプロジェクト内の場合は拒否）で再組み立て → 移行を適用 → コンパイル（Maven は -Dmaven.compiler.fork=true・JDK_JAVAC_OPTIONS=-Xmaxerrs 100000）→ alignPomToReference（公式共通コンポーネントの固定タグの pom を基準に、parent の追加・置換、欠落座標の追加（test は除外）、バージョン・scope の整列、parent が定義するプロパティのプロジェクト側再定義を削除、コメント・dependencyManagement・plugin・profiles は対象外、冪等）→ コンパイル。analyzeErrors（不足パッケージ — 「package X does not exist」・symbol の package・ファイルの import 文から特定した型のパッケージ、連鎖 — 同じファイル・不足パッケージがあるファイルで宣言された型のメンバー・Lombok が生成するメンバー、その他。連鎖はファイル内の最初の不足パッケージに紐付け、候補座標 packageHint、その他のエラーは手動項目・ルールに紐付け、ディレクトリー・ファイルの上位階層も対象）、作業一覧（pom の整列で解消されるエラー数 → 不足パッケージ → ファイル）、pom パッチ（400行上限）、実行前後のフィンガープリント（fingerprintTree）で元ファイルが不変であることを確認、各ステップの失敗を記録して続行、直近の結果を rehearsal/records/<パスのハッシュ>.json に保存。ツールメタデータは非読み取り・非破壊・冪等・openWorld、outputSchema（10種）、英語の説明、AGENTS.md のツール一覧に追加。（2）評価レポートの6節に直近のリハーサル実測値（等級の計算とは別）を追加し、結びの再組み立て案内を reassemble_egovframe_components（移行適用より先に実行）に修正。（3）CLI rehearse（指標 errors・automation・aligned・files・unlinked・failedSteps）。（4）修正：parseBuildErrors が Maven の [WARNING]・javac の lint 警告（[removal] など）の行をエラーとして数えていた問題と、fork 形式の error: 接頭辞、4.x の org.egovframe.rte 座標（バージョン4.*）を5.x 世代に分類していた問題（再組み立て候補タグが5.x だけに絞られる）を修正。runBuild(extraArgs, env)・ResolvedCommand.env、pom にソースエンコーディングがない場合はリハーサルコンパイルに UTF-8 を使用。（5）テスト：新規 test:rehearse は42アサーション（ゲート）・test:rehearse-live（CI 統合：公式 v4.3.2 の全ツリーを対象としたリハーサルの期待値を catalog/migration-corpus.json の rehearsal に追加）、test:output-schemas は54・handshake の outputSchema は10種・test:cli のコマンドは9種。設計：docs/design-migration.md のリハーサル節。server.json 0.41.0。
0.40.0 — SBOM の運用：最小要素・比較・VEX（ツール数29 → 30種）。（1）新しいツール check_egovframe_sbom(projectDir, sbomPath="sbom/bom.cdx.json", baselinePath?, offline=true, vex=false, vexPath="sbom/vex.cdx.json", dryRun=false, format) を追加：src/sbom-check.ts — 最小要素7種（catalog/sbom-rules.json：サプライヤー・コンポーネント名・バージョン・一意識別子・依存関係・作成者・生成日時、出典は NTIA 2021・SW サプライチェーンセキュリティガイドライン1.0）を主 component を含む各 component について数え、ready／needs-work・不足 component（最大20）・ヒントを表示。purl のみで v0.34 分類器による再判定（SBOM の egovframe:status と異なるもの）と OSV の再照会（newIds・goneIds、SBOM に記録がない場合は「未記録」と表示）、baselinePath との比較（groupId:artifactId に基づく追加・削除・バージョン・判定の変化・新規／消失した脆弱性）、vex=true の場合は CycloneDX VEX（analysis.state=in_triage、affects は BOM-Link urn:cdx:<serial>/<version>#<bom-ref>、serial がない場合は bom-ref）を生成 — 既存 VEX の判定・任意フィールドを保持し、in_triage 項目には affects を追加、判定済み ID の新しい影響は別項目として追加、検出されない ID は削除せず notDetected に設定、変更がなければファイルをそのまま維持、破損した VEX は処理を中断します。SBOM は変更せず、VEX のみを transaction で記録します。ツールメタデータは非読み取り・非破壊・openWorld、outputSchema（9種）、英語の説明、AGENTS.md のツール一覧に追加。（2）generate_egovframe_sbom(supplier, author, componentName, componentVersion, fillSuppliers)：metadata.supplier・主 component の supplier・metadata.authors（既定は pom <organization><name>）、metadata.lifecycles（build）、サプライヤーのない component をサプライヤー表で補完（egovframe:supplierBasis=catalog）、応答に minimum の概要を追加。enrichBom の再実行では egovframe:status・basis・baseline のみを更新し、他の egovframe:* は保持するようにしました。（3）評価レポートの5節に最小要素の判定・VEX 項目／状態／最終確認日時を追加。（4）CLI sbom-check（指標 minimum・gaps・changed・vulnerabilities・newVulns・added・removed・versionChanged・diffVulns・triage、--write → VEX、--vex の直接指定を禁止）。（5）テスト：新規 test:sbom-check は54アサーション（ゲート、実際のプラグイン出力の固定データ・CycloneDX 1.6.1 公式スキーマ検証 — devDependencies ajv・ajv-formats）、test:sbom は41・test:cli は36・test:assessment は57・test:output-schemas は53アサーション、handshake の outputSchema は9種、test:sbom-live に実際の SBOM の最小要素・補完・比較・OSV VEX・判定保持を追加。設計：docs/design-dependency-check.md の SBOM 運用節。server.json 0.40.0。
0.39.0 — CLI モード＋CI サプライチェーンゲート（ツール数29種を維持）。（0）upstream が2026-10-07に v5.0.7 タグを 3756ab2 → 7912e13 に移動したため（README・権限グループ・ブックマークメニューコントローラー・メニュー移動 JSP の修正3ファイルが追加）、カタログの固定検証に失敗しました。そこでコンポーネントカタログ（アーカイブ sha256 a1a4b9a7…、46,904,430 bytes、6,604 files）と移行ルールの components.toCommit を新しいコミットに固定し直しました（判定・コーパスの期待値に変化なし）。（1）src/cli.ts：npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate|diagnose|network> [オプション] — 引数なしの場合は従来の stdio サーバー（index.ts の分岐）を起動し、コマンド実行時は同一プロセス内のサーバーに InMemoryTransport で接続したクライアントが tools/call を呼び出します（入力検証・許可 root・outputSchema 検証は同じ）。オプションはツールパラメーター名（kebab-case、tools/list JSON Schema から型に変換）、共通オプション --project・--json（structuredContent）・--out・--step-summary・--fail-on・--write、書き込みオプションをブロック（migrate --apply・sbom --dry-run など）。--fail-on の書式（metric・metric>N・metric>=N・grade:C、コマンドごとの指標）、終了コード0／2／3／64、本文は stdout・1行要約は stderr、--help・--version。（2）generate_egovframe_ci(supplyChain, failOn="supplyChain:D", osv=true)：SBOM → 評価レポート（--step-summary）→ 成果物（if: always()）のゲート job、パッケージバージョンの固定、failOn の形式制限（CI_FAIL_ON_RE、YAML 注入を防止）。（3）@modelcontextprotocol/sdk 1.29 → 1.32.1。（4）テスト：新規 test:cli は32アサーション（ゲート）、test:ci にサプライチェーンゲート・注入拒否を追加。CI 統合に生成ワークフローの actionlint 1.7.7 検査とコーパスツリーの CLI 評価レポート（job サマリー）を追加。設計：docs/design-cli.md。server.json 0.39.0。
0.38.0 — 共通コンポーネントの再組み立てを実行（ツール数28 → 29種）。（1）新しいツール reassemble_egovframe_components(projectDir, components?, sourceTag="auto", database?, dryRun=true, verify=false, timeoutMs, format) を追加：src/component-origin.ts（公式 egovframe-common-components の blob を含まない bare ミラー GitOriginSource — タグごとに --depth 1 --filter=blob:none で fetch・ls-tree・遅延 cat-file、テスト用 MemoryOriginSource、gitBlobId・CRLF 正規化 blobIdsOf、キャッシュ EGOVFRAME_CACHE_DIR）と src/reassemble.ts（対象コンポーネントの選定 — 検出済みコンポーネント・グループ展開・manifest 管理下のコンポーネントを拒否、最長接頭辞による所有判定、座標の世代別候補タグのスコアリング・同点時は高いバージョン・短い名前を優先、8種類の判定と5種類の処理、目標内容の blob 検証、単一 transaction で置換・追加・削除・バックアップ・アセットの参考版・パッチ・SQL・manifest・reassemble-plan.json を処理、verify のコンパイルエラーを作業一覧に紐付け、Markdown・outputSchema）。ツールメタデータは destructive・openWorld（5種）、英語の説明を追加。server.json 環境変数 EGOVFRAME_CACHE_DIR を追加。ProjectFileTransaction.removeFile（rollback 時に復元）、buildComponentSqlPlan を分離（組み立て・再組み立てで共有）。（2）共通コンポーネント v5.0.7：コンポーネントカタログ（generate-catalog.mjs --archive-sha256/--archive-bytes で codeload アーカイブのフィンガープリントを固定、sha256 44a518c1…、46,903,152 bytes、6,604 files）、移行ルールの components.toTag は v5.0.7（削除55・移動4）、migrate_egovframe_project の再組み立て推奨から新しいツールを案内。（3）修正：upgrade_egovframe_project がコンポーネントのアセットファイル（メッセージ・IDGN・Web アセットなど）を upstream との比較対象に含めておらず、すべて「removed」と報告していた不具合、sync_egovframe_catalog の GitHub API 呼び出しが期限切れトークン（401）を受けた場合に未認証で再試行するよう修正。0.37.0 の公開前に main に取り込まれた CI 修正（カタログ検証時の GitHub API 認証、proxy-addr 2.0.8、drift 監視をブロックしない・プローブ再試行）もこのバージョンの記録に含めます。（4）テスト：新規 test:reassemble は46アサーション（ゲート）・test:reassemble-live（CI 統合）、test:migrate-corpus に公式ツリーの再組み立てプレビュー（元ファイル100％・ユーザー変更0）を追加、output-schemas・handshake は29種・outputSchema は8種・destructive は5種、registry 環境変数3種。設計：docs/design-migration.md の再組み立て節。server.json 0.38.0。
0.37.0 — 移行準備度評価レポート＋回帰コーパス（ツール数28種を維持）。（1）generate_egovframe_report(sections=["components"|"assessment"], resolve, resolveScope, resolveTimeoutMs, offline, sbomPath, topN, outputPath, dryRun, format)：assessment は diagnoseProject・migrateProject・checkDependencies（セキュリティチェックを含む）・SBOM ファイルの確認を一括で実行し、（1）概要、（2）移行範囲 — 種類別の表、再組み立てを推奨するコンポーネント、削除された API 参照の数、手動項目を（種類、対象）でまとめた予想手動作業の上位 N 件、（3）依存関係 — 判定の集計、対処一覧（1行の対処説明）、解釈の要約、OSV 脆弱性、ベンダー・基準なしの注記、（4）セキュリティ設定チェック、（5）SBOM の概要、（6）等級と根拠 — 移行難易度（手動項目・再組み立てコンポーネント・削除 API 参照・座標の世代）とサプライチェーンの状態（基準未満・移行／置換・脆弱性・セキュリティ設定の不足・parent／Java）を、要因ごとの区分点の合計で A=0・B≤3・C≤7・D>7 として評価し、計算方法の詳細をレポートに記載します。脆弱性を照会できなかった場合・解釈に失敗した場合は注意として表示します。format=json は outputSchema（structuredContent から Markdown を除外）、outputPath はプロジェクト内の新規 .md ファイルのみ許可します（既存ファイル・..・絶対パス・symlink による逸脱を拒否し、transaction、dryRun を使用）。既定の sections=["components"] は v0.16 レポートと同じ内容です。ツールメタデータ：読み取り専用ヒントを削除（14 → 13種、ファイル生成・ネットワーク通信が可能）、非破壊、ko/en title・英語の説明。新しいモジュール src/assessment.ts（MIGRATION_RUBRIC・SUPPLY_CHAIN_RUBRIC・computeGrade・assessProject・renderAssessmentMarkdown）・src/report.ts（generateProjectReport）、SBOM・レポートで共通の resolveOutputPath。（2）回帰コーパス：catalog/migration-corpus.json（公式 egovframe-common-components v3.10.0 aaebaa5・v4.3.2 bfa2ef5、include は5パス、tolerance は1％）と scripts/corpus-lib.mjs（sparse 部分クローン・コミット検証・キャッシュマーカー・測定・比較）・scripts/generate-migration-corpus.mjs（--check）・test/migrate-corpus.mjs（20アサーション、CI 統合＋actions/cache）。期待値：3.10.0 は項目2,315（自動1,507・手動808、再組み立て159、依存関係66）・4.3.2 は項目1,352（自動635・手動717、再組み立て155、依存関係70）、両世代とも要確認クラス0・基準なし xerces:xercesImpl 1・等級 D/D。コーパスから新たな不具合は見つかりませんでした。（3）リリースの再開：scripts/release-check.mjs が npm への公開状況・npm の gitHead・タグ・GitHub Release・MCP Registry のバージョンを確認して残りの手順だけを選択し（mode=full|resume|none、各手順を出力）、release.yml は各手順に if とサマリーを設定。npm の反映待ちを2分から10分に延長し、警告のみとしました（v0.36.1 Release #3 で反映遅延によりタグ・Release・Registry の公開がスキップされ、再実行も停止した不具合への対応）。test:release は33 → 44アサーション。（4）テスト：新規 test:assessment は55アサーション（ゲート）、test:output-schemas は42 → 47（レポートスキーマ・未宣言キー）、handshake は outputSchema 7種・readOnly 13種、test:dependencies-live に公式5.x テンプレートの移行判定が A となるアサーションを追加。設計：docs/design-assessment-report.md。server.json 0.37.0。
0.36.1 — 初回の自動デプロイ（Release #2）が npm 公開手順の prepublishOnly 内で test:release により停止した不具合を修正（0.36.0 は npm に公開されていないためスキップ）しました。原因は、ワークフローが npm@latest をインストールして npm 12 が導入され、npm 12 の npm pack --json が配列ではなくパッケージ名をキーとするオブジェクトを返したため、tarball 検査が undefined を読み込んでいたことです。test/release.mjs は両方の形式（および先行する警告行）を読み取り（parsePackJson）、ネストされた npm 呼び出しには親の npm_config_*・lifecycle 環境を渡さず、失敗時には終了コードと出力の先頭300文字を報告します（npm 10・12 で検証）。release.yml で npm を11に固定（trusted publishing の要件である ≥ 11.5.1 を満たし、メジャーバージョンの変更を防止）、CI の setup-java を v5 に変更しました。機能の変更はありません。
0.36.0 — 解決済み依存関係ツリー＋SBOM（ツール数27 → 28種、既存パラメーターとの互換性を維持）。（1）src/dependency-tree.ts：Maven org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputType=text -DoutputFile … -DappendOutput=true（pom の変更なし、マルチモジュールの場合はルートごとに連結、runtime の場合は -Dscope=runtime）と Gradle dependencies --configuration runtimeClasspath|testRuntimeClasspath -q --console=plain の出力を解析し、artifact ごとの深さ・ツリーパス（via）・scope・要求バージョンと解決バージョン（a:b:1.0 -> 1.2）を取得して、同じ座標は最も浅いパス1つに絞ります（project :x・(c)・(n)・ルート座標は除外）。実行には build_egovframe_project の Runner（タイムアウト・プロセスツリーの終了・mvnw／gradlew ラッパーの検出）をそのまま使います。（2）check_egovframe_dependencies(resolve, resolveScope, resolveTimeoutMs)：宣言にない artifact は origin: "transitive" の項目（ビルドファイル・行番号は0・via・depth）として追加し、v0.34 の分類器で判定します。宣言座標には treeVersion と resolution.differs（最も近い宣言が優先された結果）を記録し、parent が管理する座標が基準未満のバージョンに解決された場合は注記で案内します。resolution の概要（artifact・直接・推移・判定の集計・コマンド・所要時間）、OSV 照会には推移依存関係も含め、解決失敗・タイムアウト時は宣言ベースの結果に理由を付けます。Markdown に解決の概要・差分・推移パスの列を追加し、outputSchema を拡張。（3）新しいツール generate_egovframe_sbom(projectDir, outputPath="sbom/bom.cdx.json", bomFormat="cyclonedx-json", scope, enrich=true, offline=true, overwrite=false, dryRun=true, timeoutMs) を追加：Maven は org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom（JSON・schema 1.6・includeTestScope/ProvidedScope は scope に応じて）を一時ディレクトリーに出力してハッシュ・ライセンスを保持します。Gradle は解決済みツリーからこのサーバーが CycloneDX 1.6 文書（purl=bom-ref、ルート座標は settings.gradle・build.gradle、依存関係グラフ dependencies[]）を構成します。enrich は component ごとの egovframe:status・egovframe:basis・egovframe:baseline プロパティ（再実行時に更新し、他のプロパティは保持）、offline=false は OSV の結果を vulnerabilities[]（ID 順に並べ、同じ ID は affects にまとめ、source は OSV）に追加し、失敗は osvError としてのみ記録します。出力はプロジェクト内の相対パスのみ許可（..・絶対パス・ドライブ・symlink による逸脱を拒否）、既存ファイルは overwrite=true でない限り拒否し、transaction で記録。dryRun は実行せずコマンド・パスのみを返します。ツールメタデータ（ko/en title、非破壊・openWorld、outputSchema＋structuredContent — 文書本文はファイルにあるため除外）、英語の説明。（4）ルールの遡及適用：vendorCoordinates に project（system scope のローカル jar）・com.goldilocks、Jakarta artifact に javax.faces:javax.faces-api → jakarta.faces:jakarta.faces-api:4.1.2 を追加。共通コンポーネント4.3.2の pom で基準なしは11 → 1。（5）ワークフローの actions/checkout・setup-node を v5 に変更（Node 20 の非推奨警告を解消）。テスト：test:dependencies は104 → 129アサーション（パーサー・コマンド・偽 runner による resolve・失敗・タイムアウト・Gradle）、新規 test:sbom は37アサーション（ゲート）・test:sbom-live（CI 統合：公式 web テンプレートの実際の Maven 解決 ≥60・SBOM の component ≥60・OSV 脆弱性・Gradle サンプル）、test:output-schemas・handshake に28種・6種を反映、test:migration-rules は632。設計：docs/design-dependency-check.md の解決・SBOM 節。server.json 0.36.0。
0.35.0 — リリース自動化（デプロイのサプライチェーン、ツール数27種を維持、サーバーの動作に変更なし）。（1）.github/workflows/release.yml：main で CI ワークフローが成功した後（workflow_run、手動の workflow_dispatch も可能）、scripts/release-check.mjs が package.json のバージョンに基づき、次の4条件を確認します — server.json の2つの version が一致、README の変更履歴に該当項目が存在、リモートタグ vX.Y.Z がない、npm にそのバージョンがない — すべて満たす場合のみデプロイします（満たさない場合は理由を記載して成功終了）。デプロイは mcp-publisher validate → npm publish --access public（npm trusted publishing：OIDC・トークンなし・公開パッケージのため provenance は自動、Node 22・最新 npm）→ npm への反映確認（再試行）→ 検証済みの main コミットに注釈付きタグを作成・プッシュ → scripts/release-notes.mjs が変更履歴の項目から生成した本文（番号付き段落・インストールスニペット・検証案内）で GitHub Release を作成 → mcp-publisher login github-oidc && mcp-publisher publish（失敗してもリリースを維持し、警告）の順です。事前に npmjs.com で trusted publisher を1回登録する必要があります（release.yml）。（2）server.json の description が MCP Registry の上限（100文字）を超えて初回登録に失敗する状態だったことを mcp-publisher validate で発見して98文字に短縮し、test:registry が100文字以下であることを検証します。CI 統合 job に mcp-publisher validate のステップを追加。（3）新規 test:release（ゲート、32アサーション）：判定関数（条件ごとの拒否・理由の累積）、変更履歴の項目抽出・リリースノートのレンダリング、現行バージョンの項目の存在、npm pack --dry-run の tarball 内容（dist・catalog・設定テンプレート・README・LICENSE を含み、test・scripts・src・.github・ソースマップを除外、圧縮時600KB・展開時2MBの上限）。スクリプト release:check・release:notes。README のリリース手順を「PR のマージまでが人の作業」とし、手動手順は緊急時用に残しました。server.json 0.35.0。
0.34.0 — 依存関係の基準を完成＋ルール・基準の drift 監視（ツール数27種を維持、既存パラメーターとの互換性を維持）。（1）catalog/dependency-baseline.json schemaVersion 2：生成スクリプトが Boot parent の親と同じバージョンの spring-boot-dependencies（Maven Central）を取得し、直接項目と BOM import 44種を1段階展開して boot.managed（1,473座標、Maven の解決順で直接項目を優先）に記録。egovframe-runtime モジュールの pom 18種（＋root）について、test・optional を除いた依存関係を rteTransitive.managed（58座標、バージョン・scope・依存を導入するモジュール）に記録します。すべての pom は URL・sha256 を固定し、--cache／--offline で再現可能、ファイルは150KB。基準 parent を5.0.2に更新しました（5.0.1 との差は RTE バージョン）。（2）check_egovframe_dependencies：照合順序は parent 直接 → 系列 →（Boot parent の場合）Boot BOM → RTE 推移／（その他）RTE 推移 → Boot BOM。各項目に basis（parent・family・boot-bom・rte-transitive・migration-rules）を表示し、Markdown に出典の集計・出典列を追加。RTE 推移バージョンより低いバージョンを明示した場合は、競合の可能性を理由として基準未満に分類します。Boot parent のプロジェクトでバージョンを指定していない依存関係には、Boot BOM の基準バージョンも表示します。新しい分類 vendor（国内 DBMS・GPKI・mGov などベンダー・機関が配布する座標、catalog/migration-mapping.json の vendorCoordinates、理由を表示）を追加。系列ルールを groupId の完全一致（jackson のみサブ groupId を含む）に絞り、org.springframework.social などの別プロジェクトを Spring 系列と誤判定する問題を修正。カレンダー形式のリリーストレイン（spring-cloud-dependencies 2025.0.0）は系列から除外し、releaseTrains に記録します。（3）移行ルールの libraries に EOL・旧座標の置換ルール8件を追加 — mysql:mysql-connector-java→com.mysql:mysql-connector-j、ojdbc:ojdbc→com.oracle.database.jdbc:ojdbc11、org.codehaus.jackson:*（Jackson 1）、xmlbeans:xbean、net.sf.ehcache:ehcache*（Spring 6 で EhCache 2 のサポートを削除）、org.apache.httpcomponents:httpclient（Spring 6 は HttpClient 5）、org.antlr:antlr（削除された spring-modules-validation の推移依存関係）、org.springframework.social:*。migrate_egovframe_project の診断にも手動項目として表示します。公式共通コンポーネント v3.10.0 の pom で「基準なし」は17 → 1（xerces:xercesImpl）、公式 egovframe-boot-web・egovframe-web テンプレートの pom では0。（4）sync_egovframe_templates に catalogs 節（src/catalog-drift.ts）を追加：egovframe-runtime・egovframe-common-components のタグ一覧（GitHub API → 失敗時はタグページ HTML、GITHUB_TOKEN は任意）から、ルールの toTag より新しいタグ、公式 parent 2種の次の patch 3つ・minor・major 候補の HEAD プローブ（リポジトリーが maven-metadata.xml・一覧をブロック）、parent pom・Boot BOM pom の sha256 変化を報告し、変化がある場合は更新手順を添えます。取得失敗は項目ごとのエラーとして記録し、drift として扱わず、ファイルも変更しません。英語のツール説明・リソース説明を更新。テスト：test:dependencies は68 → 104アサーション、test:migration-rules は613 → 628、新規 test:catalog-drift は26アサーション（ゲート）・test:catalog-drift-live（CI 統合、GITHUB_TOKEN を渡す）、test:dependencies-live に公式テンプレート・3.10 pom の基準に関するアサーション4件。設計：docs/design-dependency-check.md。server.json 0.34.0。
0.33.1 — Windows のビルドエラーパスを修正。Maven・Gradle のコンパイルエラーパーサーが : をファイル名の区切りとみなして C:\work\A.java を :\work\A.java に切り詰めていた問題を修正しました（ドライブ文字をパスの一部として認識）。このため Windows で build_egovframe_project・test_egovframe_project のエラーファイルパスが壊れ、migrate_egovframe_project(verify=true) がエラーを手動項目に紐付けられず、リリースゲートの test:migrate が Windows で失敗していました（v0.33.0 の CI Windows ゲート3件失敗の原因）。test:migrate に Windows ドライブパスのアサーション3件を追加（162 → 165）。機能の変更はありません。
0.33.0 — 5.x 移行の3段階目（検証）＋共通コンポーネント対応表（ツール数27種を維持）。（1）migrate_egovframe_project(verify=true)：診断後に compile を実行し、コンパイルエラーを診断項目に紐付けます — 同じファイル内のシンボル一致（cannot find symbol … class Mapper ↔ class-removed Mapper、package X does not exist ↔ 接頭辞の一致、手動項目を優先）→ 同じファイル・行 ±3 の手動項目 → ルールカタログにある削除クラス・egovframework.rte／javax パッケージの不足（適用未完了の案内）→ 未分類。手動項目ごとに「解決されるエラー数」の降順で作業一覧を作り、エラーと無関係な手動項目も0件として追加して漏れを防止します。parseBuildErrors は javac の後続行 symbol:・location: を BuildError.symbol/location に追加します（Maven・Gradle）。ビルドファイルがない場合は検証をスキップし、理由を記載します。（2）ルールカタログ schemaVersion 2：生成スクリプトが egovframe-common-components v3.10.0 ↔ v5.0.6 のソースツリーを第2の根拠として比較し、packages.components（削除54・移動4・追加52、commit を固定）に記録します。診断では egovframework.com.* 参照のうち、対応表にある削除クラスを component-class-removed（manual、代替 EgovMybaitsUtil→EgovMybatisUtil はキュレーション）、移動クラスを component-class-moved（auto）として報告します。対応表にないクラスはユーザーコードの可能性があるため報告しません。（3）再組み立ての推奨：検出された共通コンポーネントのディレクトリーに3.x 移行項目がある場合、コンポーネントごとに component-reassemble（manual）を1件出力し、skipComponents=true の場合はそのディレクトリーの自動項目を手動に変更して置換対象から除外します。構造化出力スキーマに verify フィールドを追加し、英語のツール説明を更新。テスト：test:migrate は132 → 162アサーション、test:migration-rules は605アサーション、test:migrate-integration に実際のコンパイルエラーとの紐付けを3件追加。設計：docs/design-migration.md の3段階目の節。server.json 0.33.0。
0.32.0 — MCP プロトコルの最新化（ツール数27種を維持、応答本文に変更なし）。（1）SDK 1.29 で非推奨になった server.tool() 27箇所を registerTool() に置き換え、src/tool-meta.ts の ko/en title と annotations を tools/list に公開します — readOnlyHint 14種（一覧・検索・詳細・ガイド・ドキュメント検索・診断・検証・レポート・依存関係チェック・ネットワーク診断・upstream との比較2種）、destructiveHint 4種（remove_egovframe_components・upgrade_egovframe_project・migrate_egovframe_project・generate_agents_md — 引数によって性質が変わるツールは保守的に表示）、idempotentHint（読み取り専用・ビルド・テスト）、openWorldHint（ダウンロード・OSV・ネットワークプローブ・ビルド）。MCP クライアントが読み取り専用のツールを承認なしで実行したり、破壊的なツールに確認を求めたりする際の根拠となります。（2）format=json を提供していた5種（diagnose_egovframe_project・validate_egovframe_project・migrate_egovframe_project・check_egovframe_dependencies・diagnose_egovframe_network）に src/output-schemas.ts の zod outputSchema を宣言し、structuredContent も返します（text は維持、移行結果の内部編集オフセット edits は構造化出力から除外）。SDK が呼び出し時に結果をスキーマで検証するため、結果のインターフェースに不整合があればすぐに判明します。（3）テスト移植性のガード — v0.30・v0.31 で Windows のゲートだけが2回失敗した原因（テストにおける POSIX の前提）を scripts/check-test-portability.mjs（正規化なしの path.relative 比較、./mvnw リテラル、POSIX 絶対パス）で検出し、prepublishOnly に追加しました。また、collectAgentsFacts に platform 注入を追加して linux・win32 の両方を検証します。潜在していた同種の問題1件（test/dependencies.mjs）も修正しました。buildServer({ lang }) は title にも適用されます。テスト：test:output-schemas は41アサーション、handshake を拡張、check:portability を追加。server.json 0.32.0。
0.31.0 — 運用性の向上：ツール数25 → 27種。（1）diagnose_egovframe_network — ツールがダウンロードする7種のホストに DNS 照会と HEAD リクエストを実際に送り、到達可否・所要時間・失敗の種類（DNS・タイムアウト・TLS・プロキシ認証・拒否・リセット・到達不可・HTTP 5xx）を報告します。環境変数（HTTPS_PROXY・NO_PROXY・NODE_USE_ENV_PROXY・NODE_OPTIONS・NODE_EXTRA_CA_CERTS、認証情報はマスク）と Node の --use-env-proxy サポート状況も表示し、状況に応じた対処（プロキシの使用・IPv4 優先・社内 CA・プロキシ認証・DNS 許可リスト）を bash/cmd/PowerShell コマンドで案内します。NODE_TLS_REJECT_UNAUTHORIZED=0 は警告します。すべてのダウンロード経路（fetchWithTimeout）が失敗した場合も、同じ分類と1行の対処をエラーメッセージに追加します（2026-09-21 に新しいノート PC で発生した codeload のタイムアウトがきっかけ）。（2）generate_agents_md — 診断結果（ビルドツール・ラッパー・RTE・5.x 移行状況・DbType・基本パッケージ・設定ディレクトリー・インストール済みコンポーネントと manifest の有無・バックアップディレクトリー）をもとに、AI コーディングツール用の AGENTS.md を作成します。ルール節はこのサーバーのツールが守る原則（座標体系・バックアップディレクトリーをコミットしない・秘密情報・parent が管理する座標）を反映し、dryRun・overwrite・fileName（CLAUDE.md など）・lang（ko/en）に対応し、transaction で書き込みます。（3）英語対応 — README.en.md と EGOVFRAME_LANG=en（ツールの説明27種は英語、応答は韓国語）。（4）MCP Registry — server.json（io.github.EricSeokgon/egovframe-scaffold-mcp、npm パッケージ・stdio・環境変数2種を文書化）と package.json の mcpName、整合性テスト test:registry を追加。SERVER_VERSION を src/version.ts に分離（循環 import を防止）、buildServer({lang}) オプションを追加。テスト：test:network は33アサーション・test:agents-md は22アサーション・test:registry、handshake に英語の説明の検証を追加、CI 統合 job に test:network-live を追加。既存25ツールとの後方互換性を維持。
0.30.0 — 5.x 移行の適用（第2段階）＋依存関係チェック：ツール数24 → 25種。（1）migrate_egovframe_project に apply・dryRun パラメーターを追加し、第1段階の診断で auto と表示された項目を実際に置換します。診断では項目ごとに元テキストのオフセットに基づく編集（edits）を付け、適用時はファイルごとに後ろから反映するため、プレビューと実際の適用で同じ根拠を使います — RTE 座標（groupId/artifactId/version のテキスト）、RTE バージョンプロパティの名前・値（<org.egovframe.rte.version>5.0.2）と ${プロパティ} 参照、パッケージ接頭辞・名前の変更・移動、javax→jakarta パッケージと依存関係座標（JSTL は glassfish 実装が置換後に存在しない場合のみ挿入）、リポジトリー URL、Java 17、web.xml の開始タグ（xmlns・version・schemaLocation）、gradle 文字列。要素名・インデント・コメントを維持し、manual 項目には触れません。既定の dryRun はファイルごとの変更行プレビューのみを返し、適用時は withFileTransaction で元ファイルを migration-backup/<時刻>-<id>/ に保存してから置換し、migration-plan.json を記録します。途中で失敗した場合は作業前の状態に戻します（書き込み前に診断時点の内容と再照合）。適用後の再診断の概要（remaining、auto は0を期待）と build_egovframe_project(goal="compile") の案内を追加します。その後のスキャンではバックアップディレクトリーを除外します。<source>${java.version}</source> のようなプロパティ参照は、プロパティ項目が処理するように診断を調整しました。（2）check_egovframe_dependencies — 公式5.x parent 2種（egovframe-web-config-parent・egovframe-boot-starter-parent 5.0.1）の pom を標準フレームワークリポジトリーからダウンロードし、catalog/dependency-baseline.json（管理座標139種、BOM import・バージョンプロパティから導出した系列基準7種、sha256 を記録）を生成します（scripts/generate-dependency-baseline.mjs）。プロジェクトの依存関係を基準充足／基準未満／parent 管理／移行対象（3.x・4.x RTE・javax 座標）／置換が必要（移行ルールのライブラリー一覧）／基準なし／バージョンなしに分類します。5.x parent の使用状況・バージョン、Java バージョン（parent による管理を認識）、セキュリティ設定の有無を5種（sec.security コンポーネント・CSRF・XSS フィルター・セキュリティ応答ヘッダー・HTTPS リポジトリー、ファイル・行番号の根拠）まとめて報告します。offline=false の場合は OSV querybatch でバージョンが確定した依存関係の既知の脆弱性を追加します（失敗は osvError としてのみ記録）。リソース egovframe://catalog/dependency-baseline を追加。Jakarta 移行ルールの移行先バージョンを parent の基準以上に調整し（test:migration-rules で検査）、fetchWithTimeout がリクエストオプションを受け取るようにしました。テスト：test:migrate は87 → 132アサーション、test:dependencies は68、test:migration-rules は597アサーション。CI 統合 job に test:migrate-integration（適用後に JDK 17 で mvn compile）・test:dependencies-live（OSV）を追加。設計：docs/design-migration.md（第2段階の節）、docs/design-dependency-check.md。既存24ツールとの後方互換性を維持。
0.29.0 — 5.x 移行診断（第1段階）：migrate_egovframe_project を追加（ツール数23 → 24）。標準フレームワーク3.x／4.x プロジェクトを5.x（Jakarta EE 9+、Spring 6、Java 17）に移行する際に変更が必要な箇所を、ファイル・行単位で報告します — RTE Maven 座標（egovframework.rte:egovframework.rte.<module>・4.x の org.egovframe.rte:org.egovframe.rte.<module> → org.egovframe.rte:egovframe-rte-<module>、18モジュール）、RTE バージョンプロパティ・リポジトリー URL（http → https）・5.x parent の推奨、Java 17 未満のコンパイル設定、Spring 6 未満のプロパティ、パッケージ接頭辞（egovframework.rte.* → org.egovframe.rte.*）と5.x で名称が変更されたパッケージ4件（fdl.cryptography→fdl.crypto、security.securedobject→security.secureobject、security.config.internal／security.intercept→security.bean）、削除されたクラス38種（@Mapper→@EgovMapper、AbstractServiceImpl→EgovAbstractServiceImpl、@CommandMap・SimpleUrlAnnotationHandlerMapping・RteFieldChecks の削除など — 代替と理由を併記）、削除された RTE モジュール spring-modules-validation、javax→jakarta パッケージ28種（JDK 内蔵の javax.sql・javax.xml.*・javax.crypto などは除外）と依存関係座標26種、web.xml スキーマ、5.x で削除された egov-security/egov-access/egov-crypto XML namespace、置換が必要なライブラリー（DBCP 1.x・Log4j 1.x・commons-fileupload・Tiles・JUnit 4・旧バージョンの Hibernate Validator など）。各項目に auto（第2段階で機械的に置換）・manual（コードの修正が必要）を表示し、markdown/json で返します。ファイルは書き込みません。ルールはコードではなく catalog/migration-rules.json（schemaVersion 1）に置き、生成スクリプト scripts/generate-migration-rules.mjs が egovframe-runtime の v3.10.0・v4.3.0-Final・v5.0.2-Final タグのソースツリーを比較して座標・パッケージの移動・削除を導出します。削除クラスにキュレーション済みの理由（catalog/migration-mapping.json）がない場合は失敗します。リソース egovframe://catalog/migration-rules を追加。オフラインの test:migrate は87アサーション（3.10 フィクスチャ・5.x フィクスチャ0件・読み取り専用）、test:migration-rules は579アサーション。CI 統合 job の test:migration-rules-live で移行先座標61件が実際のリポジトリーに存在することを確認します。公式5.x テンプレート2種で誤検出0件、公式共通コンポーネント v3.10.0 のアセットで57件の検出を確認しました（設計：docs/design-migration.md）。既存23ツールとの後方互換性を維持。
0.28.1 — Windows チェックアウトへの対応（npm インストール版の動作に変更なし）：core.autocrlf が有効な Git クローンで、同梱の設定テンプレート（catalog/config-templates/*.hbs）が CRLF でチェックアウトされ、レンダリング前のフィンガープリント照合に失敗して generate_egovframe_config・test:config・test:template-catalog が壊れる問題を修正しました（PR #28）。フィンガープリントを改行 LF 正規化後の内容に基づいて計算するよう変更し（templateSha256、生成スクリプト・レンダラー・sync・テストで共通）、この基準でカタログのフィンガープリントを再生成しました（テンプレートの内容は不変）。.gitattributes で対象パスの改行変換を抑止しました。test:config に CRLF チェックアウトのシミュレーションのアサーションを追加（506アサーション）。npm からインストールした0.28.0は tarball が LF を維持しているため影響ありませんでした。
0.28.0 — 設定ファイルの生成：generate_egovframe_config を追加（ツール数22 → 23）。公式 eGovFrame VSCode Initializr の設定ウィザードテンプレート21種（templates/config、Handlebars、Apache-2.0）を catalog/config-templates/ にコミットし、ファイルごとに sha256 を固定して同梱することで、ネットワークなしで Spring 設定ファイルを作成します — datasource（DBCP/C3P0/JDBC・JNDI）、transaction（datasource/JPA/JTA）、cache（Ehcache 定義・Spring キャッシュ）、logging（log4j2 console/file/rolling/time-rolling/jdbc）、scheduling（Quartz bean job/method job/simple・cron trigger/scheduler）、idGeneration（sequence/table/uuid）、property。形式は xml（すべてのテンプレート）・javaConfig（@Configuration）・yaml・properties（logging）です。フィールド名と既定値は Initializr Web ビューのフォームと同じで、フィールドを省略すると IDE と同じ結果になります。テンプレートにないフィールド・選択肢外の値・無効なファイル名／クラス名／パッケージは拒否し、出力パスはプロジェクト内に限定（..・絶対パス・symlink による逸脱を拒否）、既存ファイルは上書きしません。応答コンテキストのパスワードフィールドはマスクします。レンダリング前に同梱ファイルのフィンガープリントを照合し（改行を LF に正規化して Windows の autocrlf チェックアウトでも同じ判定、.gitattributes を追加）、sync_egovframe_templates が upstream の同じファイルと照合して configTemplates.drift を報告します。リソース egovframe://catalog/config-templates からテンプレートごとの形式・フィールド・既定値・選択肢を確認できます。upstream で見つかった問題3件（存在しない timeBasedRollingFile-java.hbs、XML 内容の jdbc-properties.hbs、フォームの txtPasswrd という誤字）はキュレーションで除外・修正し、設計文書に記録しました。ランタイム依存関係に handlebars を追加（npm audit 0件）。オフラインで457アサーション（npm run test:config）、49件の出力を XML・YAML で解析し、JavaConfig 2種を mvn compile で確認。既存22ツールとの後方互換性を維持。ロードマップの候補番号を1つずつ後ろに移しました。
0.27.0 — 公式テンプレートの対応範囲を拡大（10 → 22種、Initializr 22種に対する対応は9 → 21種）：v0.26.0 の統合カタログが算出した未対応13種のうち、単独 GitHub リポジトリーがなく Initializr リポジトリーの zip（Git LFS、templates/projects/examples/）のみで配布される12種を追加しました — web・boot-web（空のひな型）、batch-file-scheduler・batch-file-commandline・batch-file-web・batch-db-scheduler・batch-db-commandline・batch-db-web、mobile-web・mobile-common-components、msa-portal-backend・msa-portal-frontend（マルチプロジェクト）。ブランチは変わるため Initializr の commit でダウンロード URL を固定し、LFS ポインターの sha256・サイズでダウンロードしたバイト列を検証します。不一致の場合は何も書き込まず拒否します（ref を直接指定した場合は検証を省略し、結果に archiveVerified: false と警告を残します）。zip は codeload アーカイブと異なりトップレベルのフォルダーがないため、ルートを切り詰めず、pom.xml の ###GROUP_ID###・###ARTIFACT_ID###・###NAME###・###VERSION###・###URL### のプレースホルダーを置換した後、既存の座標適用処理に渡します。Globals.DbType はテンプレートごとに異なる globals.properties のパス（バッチは egovframework/batch/properties/）を見つけて適用します。sync_egovframe_templates は zip 本文ではなく LFS ポインターを読み取って固定フィンガープリントと照合し、archivesChecked・archiveDrift を報告します。統合カタログの mcp.archive にもフィンガープリントを記載します。23MB のオールインワン egov-template-common-components は「共通コンポーネントは add_egovframe_components で選択して組み立てる」という従来のキュレーション方針に従い除外しました。12種すべてを実際に生成し、プレースホルダーが0件であることを確認しました。batch-db-commandline・boot-web・mobile-web は mvn compile に成功。zip 本文の取得には media.githubusercontent.com へのアクセスも必要です。既存10種・全ツールとの後方互換性を維持。ロードマップの候補番号を1つずつ後ろに移しました（namespace 移行は v0.27 → v0.28 など）。
0.26.0 — 公式テンプレートカタログを統合：sync_egovframe_templates を追加（ツール数21 → 22）。これまで同じ情報が3箇所に分かれて記載されていました — Initializr は templates/templates-projects.json にプロジェクト22種を zip・pom のスナップショットとともに、MCP は TEMPLATES（現在の src/project.ts）に公式リポジトリーの取得方法とともに10種を、Development は eGovFrameTemplates/wizards.xml に設定スニペットウィザード8カテゴリを記載していました。v0.24.0 の対応範囲拡大も、この2つを人が目で比較して進めました。今回は schemaVersion: 1 の catalog/templates.json 1つに統合し、プロジェクトごとに Initializr 側の zip・pom と MCP 側のリポジトリー・ブランチ・マルチプロジェクトの有無を並べ、対応範囲（22種中、対応9種・未対応13種・MCP 独自2種）を計算値として記録します。マッピングは catalog/template-mapping.json でキュレーションし、自動推定はしません — たとえば Initializr の egov-web（空の Web ひな型）と MCP の web-sample（掲示板サンプル）は名前が似ていても異なる成果物のため、対応付けず、根拠を note に記録しました。生成スクリプト scripts/generate-template-catalog.mjs はマッピングにない upstream 項目を見つけると失敗し、見落としを防ぎます。sync_egovframe_templates は upstream をダウンロードし、追加・削除・変更（フィールド単位）と sha256 を照合して報告しますが、ファイルは変更しません。list_egovframe_templates の応答にも対応範囲の概要を追加します（カタログがない場合は従来の動作を維持）。オフラインで148アサーション（npm run test:template-catalog）、既存21ツールとの後方互換性を維持。生成スクリプトが Windows でも動作するよう、dist/index.js の読み込みと直接実行の判定を file URL・realpath に基づいて処理します。
0.25.3 — 起動時の不具合修正＋CI 拡張（ツールインターフェースとの後方互換性を維持）。
- npx の起動失敗を修正（Linux・macOS）：エントリーポイントの判定で process.argv[1] のファイル名末尾と import.meta.url を比較していたため、npm が POSIX 上で bin を symlink（node_modules/.bin/egovframe-scaffold-mcp → dist/index.js）としてインストールすると、エントリーポイントではないと判定されてサーバーを起動せず、エラーなしで終了していました。README で案内している npx -y egovframe-scaffold-mcp の設定が Linux・macOS で動作しなかった原因です（Windows は .cmd shim が dist/index.js を直接実行するため影響なし、node dist/index.js の直接実行も影響なし）。両方のパスを realpath に解決して比較するように変更し、symlink 経由の起動を回帰テストに追加しました（npm run test:handshake）。
- CI：リリースゲートを ubuntu・windows × Node 18・20・22 のマトリックスで実行し、公式リポジトリーをダウンロードする統合テストを別の job（ubuntu／Node 20）に分離しました。bash パイプラインだったハンドシェイク確認を、プラットフォームに依存しないテスト（test:handshake）に置き換えて prepublishOnly に含め、ランタイム依存関係の npm audit（high 以上）のステップを追加しました。
- テスト：タイムアウト時にプロセスツリーを終了する回帰テストを、node の孫プロセスを使う形式に変更し、Windows（taskkill /T /F の経路）でも実行できるようにしました。
- 文書：公開時期によって不整合になる「デプロイ状況」の文言を、npm バッジを唯一の情報源とする形に整理しました。
0.25.2 — セキュリティ・安定性の強化（ツールインターフェースとの後方互換性を維持）。
- generate_egovframe_ci：jdk の値が生成されるワークフロー YAML に検証なしで挿入され、引用符・改行によって任意の step を挿入できる問題を修正しました。数字・ドット形式（17、21、1.8、17.0.9）のみを許可し、ツールスキーマと関数の両方で拒否します。違反時はファイルを作成しません。
- build_egovframe_project・test_egovframe_project：タイムアウト時に直接の子プロセスだけを終了していたため、mvnw／gradlew が起動した JVM が出力パイプを保持して生き残ると、タイムアウト後も呼び出しが終了しない問題を修正しました（再現条件：timeoutMs を1秒に設定しても30秒後に返る）。POSIX ではプロセスグループ単位で SIGKILL、Windows では taskkill /T /F でツリーを終了し、それでもパイプが閉じない場合は2秒間待ってから結果を返します。実際にプロセスを起動する回帰テストを追加しました（npm run test:build）。
- MCP handshake のサーバーバージョンが 0.23.0 に固定されていた問題を修正し、package.json のバージョンを読み込むようにしました。
- 依存関係：adm-zip 0.6.1（0.6.0 以下を対象とした symlink の追従・宣言サイズに基づくメモリー割り当ての勧告を解消）と MCP SDK の推移依存関係（hono・fast-uri・ip-address・qs）を更新し、npm audit 0件。
- 文書：create_egovframe_project のテンプレート一覧を実際の10種に修正しました。
0.25.1 — 文書の修正（コード変更なし）：v0.25.0 時点まで README に残っていた「npm は v0.23.0 まで公開」という記載を、実際の公開状況に更新しました。npm パッケージページには公開済み tarball の README が表示されるため、記載を反映するには新しいバージョンの公開が必要となり、パッチバージョンを上げました。
0.25.0 — テスト実行・レポートの構造化：test_egovframe_project を追加。build_egovframe_project(goal=test) が終了コードとログのみを返していた制約を補い、ビルドツールが出力する JUnit XML レポート（maven-surefire target/surefire-reports、gradle build/test-results/test）を一次情報として読み取ります。スイートごとの成功・失敗・エラー・スキップ数と、失敗ケースのメッセージ・例外型・スタックトレース内のテストクラスのフレーム（ファイル:行）を返します。testFilter はビルドツールと同じ構文でそのまま渡します（-Dtest=… -Dsurefire.failIfNoSpecifiedTests=false／--tests …）が、引数の解析を壊す文字は拒否します。今回の実行より前のレポートは mtime で除外し、終了コードが0でもレポートに失敗があれば（testFailureIgnore）失敗と判定します。レポートがない場合はコンパイルエラー（ログ解析）と原因候補を案内します。タイムアウト・ログ上限・許可 root・dryRun は build ツールと同じです。オフラインで54アサーション（npm run test:test）、外部依存関係なし。既存20ツールとの後方互換性を維持。
0.24.0 — 公式テンプレートの対応範囲を拡大（7 → 10種）：eGovFrame VSCode Initializr カタログ（22項目）と照合して MCP が扱っていなかった公式アセットを特定し、GitHub 公開リポジトリーで提供される msa-common-components（MSA 共通コンポーネント、KRDS）・mobile-device-api（デバイス API）・ai-rag（Spring AI・LangChain4j の RAG サンプル）を追加しました。3つのテンプレートはいずれも下位モジュールを持つマルチプロジェクトのため、multiProject として扱って座標・DB の自動書き換えをスキップし、下位モジュールへの参照を保護します。生成結果には座標／DB の自動適用がないことを明記します。npm run test:templates に登録・表示・公式リポジトリーパスの検証と、実際のアーカイブをダウンロードする dryRun 統合検証を追加しました。既存7種・全ツールとの後方互換性を維持。
0.21.1（完了、v0.22.0 に統合） — ユーザープロジェクトを損傷しないための失敗・復旧の境界を優先して強化しました。
- PR #9：インストール時の SHA-256 と現在のファイルを比較して unchanged/modified/unverified/missing に分類し、ユーザーによる変更や基準線が未確認のファイルは既定で保持します。force=true は既存ファイルと削除計画を remove-backup/ に保存してから削除し、途中で失敗した場合はファイル・POM・manifest を作業前の状態にロールバックします。
- PR #10：再利用可能な ProjectFileTransaction を導入し、AI ファイル・POM のバックアップ／更新・manifest を1つの transaction として commit します。
- PR #11：プロジェクトを sibling staging で解凍・カスタマイズした後に atomic rename し、失敗・出力先の競合時に部分的なプロジェクトを公開しません。
- PR #12：プロジェクト生成→共通コンポーネント→任意の AI 組み立てを1つのディレクトリー transaction として実行し、すべての手順が成功した後にのみ最終パスを公開します。公式テンプレート・コンポーネントの rollback 統合テストと CI gate を含みます。
- PR #13：共通コンポーネントの直接組み立てで、ファイル・SQL・manifest を共通の file transaction で commit し、途中で失敗した場合や上位 symlink の境界を逸脱した場合は作業前の状態に復元します。
- PR #14：コンポーネントアップグレードの対象 hash を適用直前に再検証し、ファイル・一意のバックアップ・upgrade-plan.json・manifest を共通 transaction で反映します。途中で失敗した場合や上位 symlink の境界を逸脱した場合は作業前の状態に復元します。
- PR #15：公式テンプレートにすでに含まれる cmm を providedComponents として確認・保持し、recipe が追加する bbs/login のみをインストールします。既存38ファイルを上書きしたり、ツール所有として記録したりしません。正常な組み立て・検証と後半の rollback の両方を統合テストします。
- PR #16：EGOVFRAME_ALLOWED_ROOTS をすべてのツールのエントリーポイントに適用し、realpath に基づいて symlink/junction による迂回を防止します。transaction が失敗した場合は RollbackReport（filesAttempted・restoredFiles・removedNewFiles・cleanedDirs・failures・ok）を提供します。
- 詳細な分析・検証・失敗／復旧の履歴は、egovframe-contribution-notes/작업이력.md を唯一の台帳として使用します。
0.22.0 — 安全性基盤を完成：すべての書き込みツールをロールバック可能な transaction に統一し（プロジェクト生成・レシピ・直接組み立て・AI 組み立て・アップグレード）、回帰が発生した場合はテストが失敗するよう判定を強制し、コンポーネント削除時にユーザーファイルを保護します。新規 EGOVFRAME_ALLOWED_ROOTS ですべてのツールに共通の許可 rootを強制（realpath ベース、symlink による迂回を禁止、未設定時は従来どおり無制限）。transaction が失敗した場合は、ユーザー向けの説明とともに機械可読な rollback-report: {json}（復元・削除・クリーンアップの件数、失敗一覧）を返します。レシピでテンプレートのコンポーネントを保持する修正を含みます。（#8–#16）
0.21.0 — 検証済み共通コンポーネントの完全な組み立て：sync_egovframe_catalog を追加し、common-components の公式 v5.0.6 タグ・commit（23d01889…）・archive SHA-256／サイズ／ファイル数を固定しました。カタログを schema v2、190項目（リーフ176＋グループ14）で再生成し、message bundle 278件、IDGN context 91件、scheduling context 18件、Web アセット662件、Spring／Web fragment 26件と Maven 座標を関連付けました。add_egovframe_components はこれらのアセットもコピーし、同一ファイルの再利用、内容が異なる場合は全体を拒否、書き込み失敗時のロールバック、DB を使用しないコンポーネントに対する SQL フォールバックの防止を実装します。sec.security の新しいセキュリティパッケージとマッピングされていない upstream パスを CI で検証し、manifest schema v3 に source の固定情報を記録します。既存のカタログ schema v1・manifest v1/v2 との後方互換性を維持。
0.20.0 — CRUD 코드 생성: generate_egovframe_crud 추가. eGovFrame Development의 공식 wizard.xml 입력 그룹(author/createDate, DataAccess·Service·Web, mapper/VO/service/controller/JSP 경로)에 맞춰 VO·DefaultVO·EgovMapper 인터페이스·MyBatis XML·Service·ServiceImpl·Controller를 생성합니다. Classic은 MVC+JSP 2종, Boot는 REST Controller를 생성하고 withTest로 JUnit 5 계약 테스트를 추가합니다. PK 필수, SQL/Java 식별자·상대경로 검증, dryRun, 전체 충돌 사전 검사, 쓰기 실패 롤백을 적용했습니다. 오프라인 테스트(npm run test:crud)와 공식 simple-backend/Boot·web-sample/Classic Maven compile 통합 테스트를 추가했습니다. 프로젝트 직접 Maven 좌표만 변경해 parent·dependency를 보존하고, lockfile·npm 패키지 설계 문서·CI 전체 릴리스 게이트를 추가했으며 adm-zip 0.6.0으로 고위험 ZIP 취약점을 해소했습니다. 기존 17개 도구 하위 호환.
0.19.0 — CI 생성 + 문서 검색 deep: generate_egovframe_ci 추가(프로젝트에 GitHub Actions 빌드·테스트 워크플로 생성, maven/gradle 자동 감지·dryRun·기존 파일 거부). search_egovframe_docs에 fetchTop 옵션 추가 — 상위 결과 문서 본문을 내려받아 스니펫 제공(기본 0=오프라인). 테스트(npm run test:ci) 추가. 기존 도구 하위 호환.
0.18.0 — 컴포넌트 설명 + 리소스/프롬프트 확장: explain_egovframe_component 추가 — 컴포넌트 하나의 설명·직접/전이 의존성·이 컴포넌트에 의존하는 컴포넌트·참조 테이블·가이드 링크·설치 명령을 한 번에 반환(읽기 전용). 리소스 egovframe://catalog/ai-components 추가, 프롬프트 scaffold_portal·maintain_existing(진단→리포트→업그레이드) 추가. 테스트(npm run test:explain) 추가. 기존 도구 불변(완전 하위 호환).
0.17.0 — 컴포넌트 업그레이드: upgrade_egovframe_project 추가 — 매니페스트 설치 컴포넌트를 upstream 최신본과 3-way 비교(설치 기준선 해시·현재 디스크·upstream)해 갱신합니다. 사용자가 수정한 파일은 force 없이 보존, dryRun 기본(계획 미리보기), 덮어쓰기 전 upgrade-backup/에 백업, 하드 충돌 시 아무것도 쓰지 않고 거부. 매니페스트 스키마 v2(파일별 해시 기준선) — add_egovframe_components가 이후 설치본에 해시 기록. 오프라인 판정 테스트(npm run test:upgrade) 추가. 기존 도구·기존 매니페스트(v1) 하위 호환(해시 없으면 보수 모드).
0.16.0 — 프로젝트 리포트: generate_egovframe_report 추가 — 프로젝트를 스캔해 설치 공통컴포넌트·참조 테이블·가이드 문서 링크·이슈를 Markdown 리포트로 생성합니다(읽기 전용, diagnose+카탈로그+가이드 매핑 재사용). 조립 결과 문서화/README 첨부용. 테스트(npm run test:report) 추가. 기존 도구 불변(완전 하위 호환).
0.15.0 — 가이드 문서 검색: search_egovframe_docs 추가 — 카탈로그 가이드 매핑(제목·경로·연계 컴포넌트·카테고리)을 키워드로 점수순 검색하고 문서 URL과 조립용 컴포넌트 id를 반환합니다. 오프라인 동작(네트워크 불필요). 테스트(npm run test:docs) 추가. 기존 도구 불변(완전 하위 호환).
0.14.0 — 프로젝트 진단 도구: diagnose_egovframe_project 추가 — 기존(스캐폴딩 도구로 만들지 않은 것 포함) 프로젝트를 읽기 전용으로 스캔해 빌드시스템(maven/gradle)·eGovFrame RTE 버전·Globals.DbType·설치된 공통컴포넌트(카탈로그 pathPrefixes 지문 매칭)·AI 계층·매니페스트 유무를 파악하고, 의존성 누락·DbType 미설정 등 이슈와 다음 단계 제안을 리포트합니다. 픽스처 테스트(npm run test:diagnose) 추가. 기존 도구 불변(완전 하위 호환).
0.13.0 — MCP 리소스·프롬프트 + 레시피: tools 외에 resources(카탈로그·템플릿·가이드 읽기 전용 노출, 단일 컴포넌트는 resource template)와 prompts(scaffold_board_login·scaffold_ai_chatbot)를 지원해 MCP 3대 프리미티브를 완비. 레시피(catalog/recipes.json)와 list_egovframe_recipes·apply_egovframe_recipe 도구 추가 — 생성→컴포넌트→AI 계층 조립을 한 번에 오케스트레이션(각 단계 dryRun 전파·원자적 거부 계승). 정합성 테스트(npm run test:recipes) 추가. 기존 도구·카탈로그 불변(완전 하위 호환).
0.12.0 — 카탈로그 커버리지 확대(68 → 188항목): 컴포넌트 단위를 2단계 패키지에서 리프 패키지(서비스 단위, 최대 4단계) 로 세분화해 리프 174종을 개별 선택 설치할 수 있습니다. 기존 2단계 id는 children을 가진 그룹으로 유지되어 하위 호환됩니다(그룹 요청 시 리프로 확장 설치, 그룹+리프 동시 요청 중복 제거). 리프 한글명은 Service 인터페이스 Javadoc에서 자동 추출(96종), 가이드 문서 매핑은 리프 우선으로 재계산(151종).
0.11.0 — 템플릿 확장: 공식 템플릿 2종 → 7종 (simple-homepage·portal-site·enterprise-business·web-sample·msa-edu 추가). 레거시 템플릿은 egovProps/globals.properties의 Globals.DbType 적용을 새로 지원, 멀티 프로젝트(msa-edu)는 좌표/DB 재작성을 건너뛰어 하위 모듈 참조를 보호. 템플릿별 빌드 안내(nextSteps) 분기, 통합 테스트(npm run test:templates) 추가.
0.10.0 — AI 컴포넌트 조립 M3: langchain4j 스택 실조립·제거 사이클 통합 검증(init-scripts/ai/·JPA 의존성·pom 원복), validate_egovframe_project에 AI 실행 전제 진단(aiChecks) 추가 — application-ai.yml의 ONNX 모델/토크나이저·임베딩 설정 경로를 ${user.home}·환경변수 플레이스홀더까지 해석해 존재 확인, docker compose 기동 안내 (경고와 분리되어 ok 판정에 영향 없음).
0.9.0 — AI 컴포넌트 조립 M2(실조립): add_ai_components가 실제로 조립합니다 — 소스(com.example.chat)·설정(application-ai.yml 프로필, 기존 설정 불변)·UI·인프라(docker-compose.ai.yml·Dockerfile.ai·k8s/ai/) 복사(전체 사전 충돌 검사·원자적 거부), pom에 누락 좌표만 마커 주석 구간으로 삽입(exclusions 보존, pom.xml.bak-ai 백업), 매니페스트 기록으로 remove_egovframe_components가 파일·pom 삽입분을 함께 원복(바이트 단위 복원 검증), validate_egovframe_project에 pom 마커 진단 추가, 통합 테스트(npm run test:ai-assembly) 추가.
0.8.0 — AI 컴포넌트 조립 M1: add_ai_components dryRun 미리보기(파일 복사 계획·pom 의존성 diff·부모 POM 호환성 게이트·스택 상호 배타 검사), AI 카탈로그(catalog/ai-components.json, egovframe-ai-rag 모듈 스캔 자동 생성 npm run generate:ai-catalog), list_egovframe_components에 AI 컴포넌트 노출, 오프라인 테스트(npm run test:ai) 추가.
0.7.0 — get_egovframe_guide: 컴포넌트 id로 표준프레임워크 공식 가이드 문서(egovframe-docs)를 조회. 카탈로그에 문서 매핑 자동 생성(--docs, 지배적 패키지 참조 기준 45종) 추가. 한글명 큐레이션 12→27종.
0.6.0 — 컴포넌트별 테이블 선별 DDL(M4): 카탈로그에 매퍼 기반 참조 테이블 자동 추출(48/68종), database 지정 시 통합 스크립트에서 해당 컴포넌트 구문만 추출해 ddl|dml/<컴포넌트id>.sql 생성(테이블 미상 컴포넌트는 통합본 폴백), 매니페스트에 컴포넌트별 스크립트 귀속(제거 시 함께 정리).
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 — 최초 PoC: create_egovframe_project, list_egovframe_templates.

라이선스

Apache License 2.0

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

egovframe-scaffold-mcp

egovframe-scaffold-mcp について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

egovframe-scaffold-mcp

진행 현황 (2026-10-11)

제공 도구

create_egovframe_project パラメーター

generate_egovframe_crud の主要パラメーター

generate_egovframe_config の主要パラメーター

migrate_egovframe_project 파라미터

check_egovframe_dependencies 파라미터

generate_egovframe_sbom 파라미터

check_egovframe_sbom 파라미터 (SBOM 점검)

SBOM 제출 준비

generate_egovframe_report 파라미터 (전환 준비도 평가서)

reassemble_egovframe_components 파라미터 (공통컴포넌트 재조립)

rehearse_egovframe_migration 파라미터 (전환 리허설)

diagnose_egovframe_network / generate_agents_md

sync_egovframe_catalog / 컴포넌트 조립

설치·사용

CI 에서 쓰기 (CLI 모드)

CI 설정 생성: GitHub Actions · GitLab CI · Jenkins

폐쇄망에서 쓰기 (오프라인 번들)

리소스·프롬프트 (MCP Resources/Prompts)

MCP Registry

보안 설정 — 허용 root (선택)

검증

현재 지원 범위와 알려진 제약

로드맵

다음 버전 기획 (v0.41–v0.43)

v0.41.0 — 전환 리허설 (rehearse_egovframe_migration)

v0.42.0 — 폐쇄망(망분리) 운영: 오프라인 번들

v0.43.0 — CI・提出形式の多様化：Jenkins・GitLab、SPDX

保留・運用項目

事前調査結果（2026-10-07）

以前の計画（v0.38–v0.40、完了）

v0.38.0 — 공통컴포넌트 재조립 실행 (reassemble_egovframe_components)

v0.39.0 — CLI 모드 + CI 공급망 게이트

v0.40.0 — SBOM 運用：最小要素・比較・VEX

保留・運用項目（当時）

선행 조사 결과 (2026-10-05)

이전 기획 (v0.35–v0.37, 완료)

v0.35.0 — 릴리스 자동화 (배포 공급망)

v0.36.0 — 해석된 의존성 트리 + SBOM

v0.37.0 — 移行準備度評価書 + 回帰コーパス

以前の計画（v0.32–v0.34、完了）

v0.32.0 — MCP 프로토콜 현대화 + 테스트 플랫폼 중립 가드

v0.33.0 — migrate_egovframe_project 3단계: 검증 + 공통컴포넌트 대응표

v0.34.0 — 의존성 기준 완성 + 규칙 drift 감시

이전 기획 (v0.29–v0.31, 완료)

v0.29.0 — migrate_egovframe_project 第1段階：移行診断（読み取り専用）— 完了

v0.30.0 — 移行の適用＋依存関係の確認

v0.31.0 — 運用の利便性

リリース手順（v0.35以降、すべてのバージョンで共通）

事前調査の結果（2026-10-04）

事前調査結果（2026-10-02）

事前調査結果（2026-09-26）

変更履歴

라이선스

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？

v0.41.0 — 전환 리허설 (`rehearse_egovframe_migration`)

v0.38.0 — 공통컴포넌트 재조립 실행 (`reassemble_egovframe_components`)

v0.33.0 — `migrate_egovframe_project` 3단계: 검증 + 공통컴포넌트 대응표

v0.29.0 — `migrate_egovframe_project` 第1段階：移行診断（読み取り専用）— 完了