JHipster MCP 서버 구축하기: AI 에이전트가 아키텍처를 스캐폴딩하고 진화시키도록 하기

AI 에이전트(AI agents)는 코드 스니펫을 작성하는 데는 뛰어나지만, 풀스택 아키텍처(full-stack architecture)를 다루는 데는 대개 어려움을 겪습니다. 이들은 설정을 환각(hallucinate)하거나, 보일러플레이트(boilerplate)를 망가뜨리고, 프로젝트의 일관성을 깨뜨리곤 합니다.

이를 해결하기 위해, 저는 자연어를 사용하여 호환 가능한 모든 AI 에이전트(예: Claude)가 JHipster 애플리케이션을 안전하게 스캐폴딩(scaffold)하고 진화시킬 수 있도록 지원하는 오픈 소스 Model Context Protocol (MCP) 서버인 **jhipster-mcp**를 구축했습니다.

에이전트가 가공되지 않은 파일을 직접 작성하는 대신, **JDL (JHipster Domain Language)**을 작성하고 공식 생성기(generator)를 대신 구동하게 됩니다.

이것이 어떻게 작동하는지, 그리고 최신 v0.0.4 릴리스에 무엇이 포함되었는지 자세히 살펴보겠습니다.

npx -y jhipster-mcp

아키텍처: 왜 JDL 우선인가?

LLM(Large Language Model)에게 Java, TypeScript, Spring Boot 설정을 직접 작성할 수 있는 권한을 주는 것은 재앙을 초래하는 레시피와 같습니다.

jhipster-mcp는 **JDL 우선 접근 방식(JDL-first approach)**을 취합니다. JDL은 매우 구조화되고 엄격한 도메인 언어(domain language)입니다. LLM이 JDL로 추론하도록 학습시킴으로써 우리는 두 가지 거대한 이점을 얻을 수 있습니다:

1. 컨텍스트 압축 (Compacting Context): 단 20줄의 JDL 블록으로 수백 개의 프로덕션 준비 완료(production-ready) 파일을 생성할 수 있습니다.
2. 검증 (Validation): 생성기를 실행하기 _전(before)_에 스키마(schema)를 검증할 수 있습니다.

🔒 설계 단계부터 안전하게 (Safe by Design)

AI 에이전트로부터 로컬 CLI 생성기를 실행하는 것은 프롬프트 인젝션(prompt injection) 위험을 초래할 수 있습니다. jhipster-mcp는 안전 경계(safety boundaries)를 강제합니다:

• 원시 셸 실행 금지 (No Raw Shell Execution): 서버는 내부 API와 엄격하게 제한된 실행 경로를 사용합니다.
• 명령어 화이트리스트 (Command Allowlisting): 에이전트는 검증된 특정 JHipster 하위 명령(sub-commands)만 호출할 수 있습니다.
• 비대화형 실행 (Non-Interactive Runs): 에이전트가 CLI 프롬프트에서 멈추는 것을 방지하기 위해 모든 생성기 호출은 비대화형 모드로 강제됩니다.

기술적 심층 분석: v0.0.4의 새로운 기능 🚀

JHipster와 같은 무거운 개발 도구를 LLM을 통해 상호작용하는 것은 특정한 UX 및 엔지니어링 과제를 야기합니다. v0.0.4가 이를 어떻게 해결했는지 소개합니다.

1. 실시간 진행 상황 스트리밍 (MCP Progress API)

JHipster 생성은 시간이 소요됩니다 (애플리케이션 크기에 따라 일반적으로 30초에서 90초 사이). 표준 MCP 요청/응답 (request/response) 사이클에서는 이 시간 동안 에이전트가 멈춘 것처럼 보여 타임아웃이 발생하거나 사용자의 불안을 유발할 수 있습니다.

우리는 **MCP 진행 상황 알림 (MCP Progress Notifications)**을 구현했습니다. 이제 서버가 생성기(generator)의 표준 출력(stdout)을 가로채어 클라이언트에 실시간으로 스트리밍합니다.

// 내부 구현 스니펫
const process = execa('jhipster', ['jdl', ...]);
process.stdout?.on('data', (data) => {
...
```

### 2. 격리된 드라이 런 샌드박싱 (Isolated Dry-Run Sandboxing)
LLM이 잘못된 JDL을 생성하거나 생성 과정이 중간에 실패하면 어떻게 될까요? 우리는 사용자의 작업 디렉토리가 손상되는 것을 원하지 않습니다.

v0.0.4는 **일회용 복사본 워크플로 (throwaway copy workflow)**를 도입합니다:
1. 서버가 로컬에서 JDL을 린트(lint)합니다.
2. 현재 프로젝트 상태를 격리된 임시 시스템 폴더로 복제(clone)합니다.
3. 해당 샌드박스(sandbox) 내부에서 생성기를 실행합니다.
4. 성공하면 프로젝트에 차이점(diff)을 다시 적용합니다. 실패하면 샌드박스는 폐기되며 소스 코드는 그대로 유지됩니다.

### 3. 에이전트 추론을 위한 구조화된 JSON 출력 (Structured JSON Outputs for Agent Reasoning)
LLM은 가공되지 않은 CLI 로그를 파싱하는 데 매우 서툽니다. 명령어가 방대한 텍스트 뭉치를 반환하면, 에이전트가 미세한 경고를 놓칠 수 있습니다.

`jhipster-mcp`의 모든 도구는 이제 엄격하고 기계가 읽을 수 있는 JSON 객체를 반환합니다:

```json
{
  "success": true,
  "entities": ["Product", "Order"],
...
```

출력이 구조화되어 있기 때문에, 에이전트는 자신의 작업 결과에 대해 프로그래밍 방식으로 추론하고 스스로의 실수를 자율적으로 수정할 수 있습니다.

## 기술 스택 및 품질 (Tech Stack & Quality)

-   **런타임 (Runtime):** Node.js (v22 및 v24에서 검증됨)
-   **언어 (Language):** TypeScript
-   **SDK:** 공식 `@modelcontextprotocol/sdk`
-   **신뢰성 (Reliability):** 70개 이상의 통합 및 단위 테스트, OIDC 신뢰할 수 있는 게시(OIDC Trusted Publishing)를 통한 GitHub Actions 자동화.

## 다음 단계는? (What's Next?)

로드맵은 흥미로운 기능들로 가득 차 있습니다:

- **프로젝트 상태 리소스 (Project-State Resources):** 현재 프로젝트 아키텍처를 MCP 리소스로 노출하여 에이전트가 항상 동기화된 상태를 유지하도록 합니다.
- **Git 롤백을 포함한 안전한 적용 (Safe-Apply with Git Rollback):** 대규모 변경 사항을 적용하기 전 자동으로 Git 브랜치를 생성합니다.
- **전체 Docker 샌드박싱 (Full Docker Sandboxing).**

## 🤝 오픈 소스 및 기여 (Open Source & Contributions)

이 프로젝트는 완전히 오픈 소스입니다. 직접 사용해 보고, 오류를 찾아내며, 더 나은 프로젝트를 만들 수 있도록 도와주세요!

- 📦 **NPM 패키지:** [npmjs.com/package/jhipster-mcp](https://www.npmjs.com/package/jhipster-mcp)
- 💬 댓글로 알려주세요: AI 기반 JHipster 워크플로우에서 다음에 어떤 도구나 안전 장치(safeguards)를 보고 싶으신가요?