@axboot-mcp/mcp-server 1.0.0

package/src/docs/quick-start.md

@@ -0,0 +1,257 @@
+# MCP-AXBoot 빠른 시작 가이드
+
+> MCP-AXBoot를 처음 사용하는 분들을 위한 빠른 시작 가이드입니다.
+
+## 목차
+
+1. [설치 및 설정](#1-설치-및-설정)
+2. [기본 사용법](#2-기본-사용법)
+3. [5분 만에 Store 만들기](#3-5분-만에-store-만들기)
+4. [자주 묻는 질문](#4-자주-묻는-질문)
+
+---
+
+## 1. 설치 및 설정
+
+### 1.1 프로젝트 클론
+
+```bash
+cd /path/to/your/workspace
+git clone <mcp-axboot-repo-url>
+cd mcp-axboot
+npm install
+npm run build
+```
+
+### 1.2 Claude Desktop 설정
+
+Claude Desktop의 설정 파일에 MCP 서버를 등록합니다:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "mcp-axboot": {
+      "command": "node",
+      "args": ["/Users/kyle/work/mcp-axboot/dist/index.js"]
+    }
+  }
+}
+```
+
+경로를 실제 프로젝트 경로로 수정하세요.
+
+### 1.3 Claude Desktop 재시작
+
+설정을 저장한 후 Claude Desktop을 재시작합니다.
+
+---
+
+## 2. 기본 사용법
+
+### 2.1 사용 가능한 도구
+
+MCP-AXBoot는 다음 도구들을 제공합니다:
+
+| 도구 이름 | 설명 |
+|---------|------|
+| `analyze_interface` | Repository 인터페이스 파일 분석 |
+| `generate_store` | Store 파일 생성 (타입 지정) |
+| `generate_store_from_requirements` | 자연어 요구사항으로 Store 생성 |
+| `analyze_requirements` | 요구사항 분석 및 타입 추천 |
+| `generate_multi_stores` | 다중 리스트 Store 생성 |
+| `list_templates` | 사용 가능한 템플릿 목록 |
+| `suggest_layout` | Repository에 적합한 레이아웃 추천 |
+| `generate_requirements_from_layout` | 레이아웃으로 요구사항 생성 |
+
+### 2.2 Claude에서의 사용 예시
+
+#### Repository 분석
+
+```
+분석해줘: /path/to/MemberRepository.ts
+```
+
+#### Store 생성 (기본)
+
+```
+MemberRepository.ts를 분석해서 useMemberListStore를 생성해줘.
+출력 경로는 /path/to/stores/useMemberListStore.ts로 해줘.
+```
+
+#### Store 생성 (타입 지정)
+
+```
+ProductRepository.ts를 분석해서 Type 7 스타일의 Store를 만들어줘.
+대시보드 형태가 필요해.
+```
+
+#### 자연어 요구사항으로 Store 생성
+
+```
+"상품 목록을 보여주고, 선택한 상품을 모달에서 수정할 수 있는 Store"를 만들어줘.
+```
+
+---
+
+## 3. 5분 만에 Store 만들기
+
+### 시나리오: 회원 목록 Store 만들기
+
+#### Step 1: Repository 파일 확인
+
+```typescript
+// services/MemberRepository.ts
+export interface MemberRepository {
+  postMemberListMember(request: PostMemberListMemberRequest): Promise<MemberListResponse>;
+  postMemberSaveMember(request: PostMemberSaveMemberRequest): Promise<MemberSaveResponse>;
+  postMemberDeleteMember(request: PostMemberDeleteMemberRequest): Promise<void>;
+}
+```
+
+#### Step 2: Claude에 요청
+
+```
+다음 조건으로 Store를 생성해줘:
+- Repository: /path/to/services/MemberRepository.ts
+- 출력: /path/to/stores/useMemberListStore.ts
+- 타입: CRUD 가능한 전체 기능 (저장, 삭제 포함)
+```
+
+#### Step 3: 생성된 Store 확인
+
+```typescript
+// stores/useMemberListStore.ts
+import { AXDGDataItem, AXDGPage, AXDGSortParam } from "@axboot/datagrid";
+import { pageStoreActions } from "@core/stores/pageStoreActions";
+// ... imports
+
+interface ListRequest extends PostMemberListMemberRequest {}
+interface DtoItem extends MemberRes {}
+interface SaveRequest extends PostMemberSaveMemberRequest {}
+
+interface MetaData {
+  programFn?: ProgramFn;
+  listRequestValue: ListRequest;
+  listColWidths: number[];
+  listSortParams: AXDGSortParam[];
+  listSelectedRowKey?: React.Key;
+  saveRequestValue: SaveRequest;
+  // ... 필드들
+}
+
+export const useMemberListStore = create(
+  subscribeWithSelector<memberListStore>((set, get) => ({
+    ...createState,
+    ...createActions(set, get),
+  }))
+);
+```
+
+#### Step 4: 컴포넌트에서 사용
+
+```tsx
+import { useMemberListStore } from './stores/useMemberListStore';
+
+function MemberListPage() {
+  const {
+    listData,
+    listPage,
+    listSpinning,
+    callListApi,
+    changeListPage,
+    setListSelectedRowKey,
+    callSaveApi,
+    callDeleteApi,
+  } = useMemberListStore();
+
+  useEffect(() => {
+    callListApi();
+  }, []);
+
+  return (
+    // ... UI 구현
+  );
+}
+```
+
+---
+
+## 4. 자주 묻는 질문
+
+### Q1: 어떤 Store 타입을 선택해야 하나요?
+
+**A**: 기능별로 추천 타입:
+
+| 필요한 기능 | 추천 타입 |
+|-----------|---------|
+| 단순 조회만 | Type 1 (Basic List) |
+| 조회 + 엑셀 다운로드 | Type 2 |
+| 조회 + 상세 보기/편집 | Type 3 |
+| 마스터-디테일 (선택 시 상세 표시) | Type 4 |
+| 전체 CRUD | Type 5 |
+| 트리 구조 | Type 6 |
+| 대시보드 (여러 데이터) | Type 7 |
+| 모달 기반 작업 | Type 8 |
+| 체크박스 다중 선택 후 일괄 처리 | Type 9 |
+
+### Q2: 생성된 Store를 수정해야 하나요?
+
+**A**: 네, 생성 후 다음을 확인하세요:
+
+1. **초기 검색조건**: `createState.listRequestValue`에 필요한 검색조건 추가
+2. **API 파라미터**: `callListApi`에서 필요한 파라미터 변환 로직 확인
+3. **타입 정의**: Request/Response 타입이 실제 API와 일치하는지 확인
+4. **Service 메서드명**: 실제 Service 메서드명과 일치하는지 확인
+
+### Q3: 다중 리스트는 어떻게 만드나요?
+
+**A**: 두 가지 방법:
+
+**방법 1**: `generate_multi_stores` 도구 사용
+```
+왼쪽 목록, 상단 디테일 목록, 하단 디테일 목록이 있는 Store를 만들어줘.
+각 목록은 검색과 엑셀 다운로드가 필요해.
+```
+
+**방법 2**: Type 7 (Dashboard) 템플릿 사용
+```
+요약 데이터와 2개의 리스트가 있는 대시보드 Store를 만들어줘.
+```
+
+### Q4: 생성 후 컴파일 오류가 발생해요
+
+**A**: 일반적인 해결 방법:
+
+1. **imports 확인**: Service, 타입 import 경로가 올바른지 확인
+2. **타입 오류**: Repository의 Request/Response 타입과 일치하는지 확인
+3. **누락된 메서드**: TODO 주석으로 표시된 메서드 구현
+
+```typescript
+// TODO: 저장 API 호출 구현 필요
+// await MemberService.saveMember(apiParam);
+// → 실제 Service 메서드로 변경
+await MemberService.postMemberSave(apiParam);
+```
+
+### Q5: Store 패턴을 커스텀할 수 있나요?
+
+**A**: 네, 두 가지 방법:
+
+1. **생성 후 수정**: 생성된 Store를 직접 수정
+2. **템플릿 확장**: `src/templates/` 폴더에 새 템플릿 추가
+
+### Q6: 기존 Store와 호환되나요?
+
+**A**: 네, NH-FE-B 프로젝트의 Store 패턴을 따르므로 기존 Store와 호환됩니다.
+
+---
+
+## 5. 다음 단계
+
+- [상세 가이드](./store-patterns-usage-guide.md) - Store 패턴별 상세 가이드
+- [요구사항 분석 가이드](./requirements-analysis-guide.md) - 자연어 요구사항 분석 방법
+- [실전 예제](./practical-examples.md) - 실제 프로젝트 예제
+- [문제 해결](./troubleshooting.md) - 흔한 문제와 해결 방법

package/src/docs/requirements-analysis-guide.md

@@ -0,0 +1,364 @@
+# 요구사항 분석 가이드
+
+> 자연어 요구사항을 정확하게 분석하여 최적의 Store를 생성하는 방법을 안내합니다.
+
+## 목차
+
+1. [분석 원리](#1-분석-원리)
+2. [키워드 매칭](#2-키워드-매칭)
+3. [효과적인 요구사항 작성법](#3-효과적인-요구사항-작성법)
+4. [시나리오별 예제](#4-시나리오별-예제)
+5. [분석 결과 해석](#5-분석-결과-해석)
+
+---
+
+## 1. 분석 원리
+
+MCP-AXBoot는 요구사항을 다음 단계로 분석합니다:
+
+```
+요구사항 입력
+    ↓
+키워드 추출 (리스트, 검색, 저장, 삭제 등)
+    ↓
+Store 타입별 매칭 (12가지 타입)
+    ↓
+매칭 점수 계산
+    ↓
+최적 타입 추천
+```
+
+### 1.1 docs/patterns.json 활용
+
+`analyze_requirements` 도구는 `docs/patterns.json`에 정의된 패턴을 기반으로 분석합니다:
+
+- **MetaData 필드**: Store 타입별 필수/선택 필드
+- **States 필드**: 상태 관리 필드
+- **Actions 필드**: 액션 메서드
+- **초기값 패턴**: 타입별 초기값
+
+---
+
+## 2. 키워드 매칭
+
+### 2.1 기본 키워드
+
+| 키워드 | 대응 기능 | Store 타입 영향 |
+|--------|----------|-----------------|
+| 리스트, 목록, 조회 | LIST | 모든 타입 |
+| 검색, 찾기, 서치 | SEARCH | 모든 타입 |
+| 상세, 디테일 | DETAIL_PANEL | Type 3, 5 |
+| 모달, 팝업, 다이얼로그 | MODAL | Type 8 |
+| 저장, 수정, 등록, 추가 | SAVE | Type 3, 5, 6 |
+| 삭제, 제거 | DELETE | Type 5, 9 |
+| 엑셀, excel, 다운로드 | EXCEL_DOWNLOAD | Type 2, 7, 8, 10 |
+| 체크, checkbox, 선택 | CHECKBOX | Type 4, 5, 9 |
+| 트리, 카테고리, 계층 | TREE | Type 6 |
+| 대시보드, dashboard, 요약 | DASHBOARD | Type 7 |
+| 정렬, 재배열, 순서 | REORDER | Type 7 (원래 6) |
+
+### 2.2 조합 키워드
+
+키워드 조합에 따라 더 정확한 타입 추천:
+
+| 조합 | 추천 타입 | 설명 |
+|-----|----------|------|
+| 리스트 + 저장 + 삭제 | Type 5 (CRUD) | 전체 기능 |
+| 리스트 + 모달 + 저장 | Type 8 (Modal Based) | 모달 기반 작업 |
+| 리스트 + 체크박스 + 삭제 | Type 9 (Status Change) | 다중 선택 후 일괄 처리 |
+| 리스트 + 트리 | Type 6 (Tree) | 트리 구조 |
+| 리스트 + 상세 + 저장 | Type 3 (List + Detail) | 조회 + 상세 편집 |
+| 리스트 + 엑셀 | Type 2 (List + Excel) | 엑셀 다운로드 |
+
+---
+
+## 3. 효과적인 요구사항 작성법
+
+### 3.1 좋은 요구사항의 특징
+
+1. **구체적**: 원하는 기능을 명확히 설명
+2. **키워드 포함**: 위 표의 키워드 활용
+3. **UI 패턴 언급**: 마스터-디테일, 모달, 트리 등
+4. **데이터 구조 언급**: 단일 리스트, 다중 리스트, 대시보드 등
+
+### 3.2 요구사항 작성 템플릿
+
+#### 템플릿 1: 기본형
+
+```
+[데이터 이름] 목록을 보여주는 Store.
+- 검색조건: [검색필드들]
+- 필요한 기능: [기능들]
+```
+
+#### 템플릿 2: UI 패턴 명시
+
+```
+[UI 패턴] 형태의 [데이터 이름] Store.
+- 왼쪽: [목록/트리]
+- 오른쪽: [상세/폼]
+- 기능: [기능들]
+```
+
+#### 템플릿 3: 사용자 시나리오
+
+```
+사용자가 [작업]을 할 수 있는 [데이터 이름] Store.
+1. [단계1]
+2. [단계2]
+3. [단계3]
+```
+
+### 3.3 예시 비교
+
+| ❌ 부족한 요구사항 | ✅ 좋은 요구사항 |
+|------------------|----------------|
+| 회원 목록 | 회원 목록을 보여주고 검색할 수 있는 Store |
+| 상품 관리 | 상품 목록에서 체크박스로 다중 선택 후 일괄 삭제하는 Store |
+| 카테고리 | 트리 형태의 카테고리 목록과 선택된 카테고리의 편집 폼 |
+
+---
+
+## 4. 시나리오별 예제
+
+### 시나리오 1: 단순 조회 페이지
+
+**요구사항**:
+```
+부서 목록을 보여주는 페이지. 검색조건으로 부서명으로 검색할 수 있어야 함.
+```
+
+**분석 결과**:
+```json
+{
+  "extractedFeatures": ["LIST", "SEARCH"],
+  "recommendedType": {
+    "type": 1,
+    "name": "Basic List",
+    "confidence": 0.85
+  }
+}
+```
+
+### 시나리오 2: 마스터-디테일 + CRUD
+
+**요구사항**:
+```
+회원 목록에서 회원을 선택하면 상세 정보가 표시되고,
+상세 정보에서 수정과 삭제가 가능한 Store. 모달로 처리.
+```
+
+**분석 결과**:
+```json
+{
+  "extractedFeatures": ["LIST", "DETAIL_PANEL", "MODAL", "SAVE", "DELETE"],
+  "recommendedType": {
+    "type": 8,
+    "name": "Modal Based",
+    "confidence": 0.92
+  }
+}
+```
+
+### 시나리오 3: 트리 + 폼
+
+**요구사항**:
+```
+상품 카테고리를 트리 형태로 표시하고,
+선택된 카테고리의 정보를 오른쪽 폼에서 편집할 수 있는 Store.
+```
+
+**분석 결과**:
+```json
+{
+  "extractedFeatures": ["LIST", "TREE", "DETAIL_PANEL", "SAVE"],
+  "recommendedType": {
+    "type": 6,
+    "name": "Tree + Form",
+    "confidence": 0.95
+  }
+}
+```
+
+### 시나리오 4: 대시보드
+
+**요구사항**:
+```
+회원 대시보드. 상단에 회원 통계 요약이 표시되고,
+하단에 탭으로 구분된 가입 회원 목록과 탈퇴 회원 목록이 표시됨.
+각 목록은 엑셀 다운로드 가능.
+```
+
+**분석 결과**:
+```json
+{
+  "extractedFeatures": ["LIST", "DASHBOARD", "EXCEL_DOWNLOAD"],
+  "recommendedType": {
+    "type": 7,
+    "name": "Dashboard",
+    "confidence": 0.98
+  }
+}
+```
+
+### 시나리오 5: 체크박스 일괄 처리
+
+**요구사항**:
+```
+상품 목록에서 체크박스로 여러 상품을 선택하고,
+선택된 상품들을 일괄적으로 전시/비전시 상태를 변경하는 Store.
+```
+
+**분석 결과**:
+```json
+{
+  "extractedFeatures": ["LIST", "CHECKBOX", "DELETE"],
+  "recommendedType": {
+    "type": 9,
+    "name": "Status Change",
+    "confidence": 0.90
+  }
+}
+```
+
+---
+
+## 5. 분석 결과 해석
+
+### 5.1 analyze_requirements 응답 구조
+
+```json
+{
+  "success": true,
+  "requirements": "원본 요구사항",
+  "extractedFeatures": ["LIST", "SEARCH", "SAVE"],
+  "matchedTypes": [
+    {
+      "type": 3,
+      "name": "List + Detail/Form",
+      "description": "조회 + 상세보기/편집",
+      "matchScore": 0.92,
+      "matchedFeatures": ["LIST", "SEARCH", "SAVE"],
+      "missingFeatures": [],
+      "extraFeatures": ["DETAIL_PANEL"]
+    }
+  ],
+  "recommendedType": { /* ... */ },
+  "canUseExistingType": true
+}
+```
+
+### 5.2 필드 설명
+
+| 필드 | 설명 |
+|-----|------|
+| `extractedFeatures` | 요구사항에서 추출된 기능 키워드 |
+| `matchedTypes` | 매칭된 모든 Store 타입 (점수순 정렬) |
+| `matchScore` | 매칭 점수 (0~1, 높을수록 적합) |
+| `matchedFeatures` | 타입과 일치하는 기능 |
+| `missingFeatures` | 요구사항에는 있는데 타입에는 없는 기능 |
+| `extraFeatures` | 타입에는 있는데 요구사항에는 없는 기능 |
+| `canUseExistingType` | 기존 타입으로 충분한지 (0.8 이상이면 충분) |
+
+### 5.3 해석 예시
+
+#### Case 1: 높은 매칭 점수 (0.8+)
+
+```json
+{
+  "matchScore": 0.92,
+  "canUseExistingType": true
+}
+```
+
+→ **해석**: 기존 타입을 그대로 사용해도 됨
+
+#### Case 2: 낮은 매칭 점수 (0.5~0.7)
+
+```json
+{
+  "matchScore": 0.65,
+  "missingFeatures": ["EXCEL_DOWNLOAD"],
+  "extraFeatures": ["MODAL"]
+}
+```
+
+→ **해석**: 기존 타입에 일부 기능 추가/제거 필요
+- 엑셀 다운로드 기능 추가
+- 모달 기능 제거 또는 무시
+
+#### Case 3: 매우 낮은 매칭 점수 (0.5 미만)
+
+```json
+{
+  "matchScore": 0.42,
+  "missingFeatures": ["TREE", "DETAIL_PANEL"]
+}
+```
+
+→ **해석**: 커스텀 Store 생성 권장
+- `generate_multi_stores` 사용
+- 또는 생성 후 직접 수정
+
+---
+
+## 6. 실전 팁
+
+### Tip 1: 단계적으로 요구사항 작성
+
+처음에는 단순하게 시작하고, 점차 구체화하세요:
+
+```
+1단계: "회원 목록 Store"
+2단계: "회원 목록에 검색 추가된 Store"
+3단계: "회원 목록에서 선택하여 상세 보고 수정/삭제하는 Store"
+```
+
+### Tip 2: UI 레이아웃 언급
+
+UI 구조를 명시하면 더 정확한 추천:
+
+```
+"왼쪽에 목록, 오른쪽에 상세 폼"
+```
+
+### Tip 3: 사용자 플로우 설명
+
+사용자가 수행하는 작업을 순서대로 설명:
+
+```
+"사용자가 카테고리를 선택하고 → 선택된 카테고리의 하위 항목을 표시하고 → 항목을 더블클릭하여 편집"
+```
+
+### Tip 4: 기존 Store 참조
+
+이미 존재하는 유사한 Store를 언급:
+
+```
+"useProductCategoryStore와 비슷하지만 검색 기능이 추가된 형태"
+```
+
+---
+
+## 7. Claude에서의 사용 예시
+
+### 예시 1: 요구사항 분석
+
+```
+다음 요구사항을 분석해줘:
+"주문 목록을 보여주고, 체크박스로 여러 주문을 선택하여 일괄 배송처를 변경할 수 있는 Store"
+```
+
+### 예시 2: 분석 후 Store 생성
+
+```
+분석 결과를 바탕으로 Store를 생성해줘.
+Repository: /path/to/OrderRepository.ts
+출력: /path/to/stores/useOrderStore.ts
+```
+
+### 예시 3: 요구사항으로 바로 생성
+
+```
+"게시판 목록과 상세 보기, 그리고 엑셀 다운로드가 있는 Store"를 만들어줘.
+```