@axboot-mcp/mcp-server 1.0.0

package/SEARCH_PARAMS_PLAN.md

@@ -0,0 +1,2570 @@
+# SearchParams 대화형 생성 툴 계획
+
+> **⚠️ MCP 구현 시 필독**
+>
+> 이 문서는 **SearchParams 대화형 생성 MCP**를 구현하기 위한 설계서입니다.
+>
+> **핵심 컨셉**: 이 MD는 AI를 위한 "매뉴얼 + 설계서"입니다.
+> - 사용자가 어떤 입력을 하면
+> - AI가 어떤 질문을 해야 하고
+> - 그 답변을 어떻게 코드로 변환할지가 정의되어 있어야 합니다.
+>
+> **목표**: 자연어로 대화하면서 사용자 의도에 최대한 맞는 코드가 나오도록 설계
+
+## 개요
+
+검색 폼(SearchParams)을 대화형으로 생성합니다.
+
+## 입력
+
+- `repositoryPath`: Repository 파일 경로 (절대 경로)
+- `dtoPath`: DTO 파일 경로 (선택, 없으면 자동 검색)
+
+## 처리 흐름
+
+```
+1. Repository의 List API 메서드 찾기
+2. Request 타입 분석 → 필드 목록 추출
+3. 연동 설정 (선택)
+4. 필드별로 패턴 선택 (대화형)
+5. 그룹핑 설정
+6. 기본값 설정
+7. SearchParams JSX 코드 생성
+```
+
+---
+
+## 필드별 패턴 선택
+
+### 패턴 카탈로그 (NH 프로젝트 실사용 패턴 기반)
+
+```
+[MCP] usrNm (회원명) 필드를 발견했습니다.
+      어떤 검색 컴포넌트를 사용할까요?
+
+┌─────────────────────────────────────────────────────────────────────┐
+│ 1. 🤖 AI에게 맡기기 (자연어로 설명)                                │
+├─────────────────────────────────────────────────────────────────────┤
+│ 2. 📝 일반 텍스트 입력 (INPUT)                                      │
+│    예: 회원명, 이메일, 전화번호 검색                                │
+├─────────────────────────────────────────────────────────────────────┤
+│ 3. 🔍 검색구분 + 텍스트 (GROUP)                                    │
+│    예: 제목/내용 검색, 이름/ID 검색                                 │
+├─────────────────────────────────────────────────────────────────────┤
+│ 4. 📋 드롭다운 선택 (SELECT)                                       │
+│    예: 상태코드, 카테고리, 주문유형                                 │
+├─────────────────────────────────────────────────────────────────────┤
+│ 5. ✓ 체크박스 다중 선택 (CHECKBOX)                                 │
+│    예: 회원가입채널, 관심사                                         │
+├─────────────────────────────────────────────────────────────────────┤
+│ 6. ☐ 멀티 셀렉트 (SELECT_MULTI)                                   │
+│    예: 주문상태, 배송상태 (체크박스 대용)                           │
+├─────────────────────────────────────────────────────────────────────┤
+│ 7. ○ 라디오 버튼 (RADIO)                                           │
+│    예: 사용여부(Y/N), 이메일수신동의, 답변상태                       │
+├─────────────────────────────────────────────────────────────────────┤
+│ 8. 📅 단일 날짜 (DTPICKER_DATE)                                    │
+│    예: 등록일, 수정일                                              │
+├─────────────────────────────────────────────────────────────────────┤
+│ 9. 📆 날짜 범위 (DTPICKER_DATE_RANGE)                              │
+│    예: 가입기간, 주문기간, 기간검색                                 │
+├─────────────────────────────────────────────────────────────────────┤
+│ 10. 🔢 숫자 범위 (NUMBER_RANGE)                                    │
+│     예: 방문회수, 구매금액, 나이                                     │
+├─────────────────────────────────────────────────────────────────────┤
+│ 11. ⏭️ 스킵 (SKIP)                                                 │
+│     이 필드는 SearchParams에 포함하지 않음                          │
+├─────────────────────────────────────────────────────────────────────┤
+│ 12. 👁️ 숨김 (HIDDEN)                                              │
+│     필드는 존재하지만 UI에는 표시하지 않음                          │
+├─────────────────────────────────────────────────────────────────────┤
+│ 13. 🔀 조건부 필드 (CONDITIONAL)                                   │
+│     특정 필드값에 따라 동적으로 표시되는 필드                        │
+│     예: 리뷰유형이 '포토'일 때만 상세옵션 표시                     │
+├─────────────────────────────────────────────────────────────────────┤
+│ 14. 🔍 자동완성 (AUTOCOMPLETE)                                     │
+│     키워드 입력 시 실시간 API 호출로 검색                          │
+│     예: 고객사 검색, 제품 검색                                     │
+├─────────────────────────────────────────────────────────────────────┤
+│ 15. 🌊 계층 선택 (CASCADE)                                        │
+│     계층적 구조에서 단계별 선택 (조직 > 팀 > 파트)                │
+│     예: 조직도, 카테고리 > 하위카테고리                           │
+├─────────────────────────────────────────────────────────────────────┤
+│ 16. 🪟 모달 검색 (MODAL)                                          │
+│     버튼 클릭 시 모달 오픈하여 선택                               │
+│     예: 고객사 검색, 영업사원 검색                                 │
+└─────────────────────────────────────────────────────────────────────┘
+
+번호를 입력하세요:
+```
+
+---
+
+### 13번 조건부 필드 (CONDITIONAL) 상세
+
+다른 필드의 값에 따라 동적으로 표시되는 필드입니다.
+
+```tsx
+// product.review/App.tsx 예시
+params={[
+  {
+    label: t("리뷰유형"),
+    type: SearchParamType.SELECT,
+    name: "prdBbsRvwTpcd",
+    options: [{ label: t("전체"), value: "" }, ...(PRD_BBS_RVW_TPCD?.options ?? [])],
+  },
+  // prdBbsRvwTpcd가 "1"일 때만 표시
+  ...(listRequestValue.prdBbsRvwTpcd === "1"
+    ? [
+        {
+          label: t(" "),
+          name: "prdBbsRvwDtlTpcdArray",
+          type: SearchParamType.CHECKBOX,
+          width: 120,
+          options: PRD_BBS_RVW_DTL_TPCD?.options,
+        },
+      ]
+    : []),
+]}
+```
+
+#### 대화형 설정 흐름
+
+```
+[MCP] CONDITIONAL을 선택했습니다.
+      이 필드는 조건부로 표시됩니다.
+
+1️⃣ 조건 필드 선택
+   어느 필드의 값에 따라 표시할까요?
+   (이미 정의된 필드 목록에서 선택)
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. usrNm (회원명)                           │
+   │ 2. prdBbsRvwTpcd (리뷰유형)                │
+   │ 3. useYn (사용여부)                         │
+   │ 4. statusCd (상태)                          │
+   └─────────────────────────────────────────────┘
+
+사용자: 2
+
+[MCP] 'prdBbsRvwTpcd' 필드를 조건 필드로 선택했습니다.
+
+2️⃣ 이 필드의 실제 타입 선택
+   이 필드의 실제 타입을 선택하세요:
+
+   ┌─────────────────────────────────────────────┐
+   │ 2. INPUT    3. GROUP    4. SELECT           │
+   │ 5. CHECKBOX 6. MULTI    7. RADIO            │
+   │ 8. DATE     9. DATE_RANGE 10. NUMBER_RANGE  │
+   └─────────────────────────────────────────────┘
+
+사용자: 5
+
+[MCP] CHECKBOX를 선택했습니다.
+      prdBbsRvwDtlTpcdArray (상세옵션) 필드에 대해 추가 설정을 진행합니다.
+
+[CHECKBOX 타입의 일반 설정 진행...]
+- 옵션 소스 선택 (Code Store / 직접 입력)
+- 코드 변수명 입력
+- 전체 옵션 포함 여부
+- 기본값 설정
+
+3️⃣ 조건을 자연어로 입력
+   조건을 자연어로 설명해주세요.
+   AI가 조건식을 생성합니다.
+
+사용자: prdBbsRvwTpcd가 1일 때만 표시해줘
+
+[MCP] 다음 조건식으로 생성합니다:
+
+...(listRequestValue.prdBbsRvwTpcd === "1" ? [{
+  label: t('상세옵션'),
+  name: 'prdBbsRvwDtlTpcdArray',
+  type: SearchParamType.CHECKBOX,
+  width: 120,
+  options: PRD_BBS_RVW_DTL_TPCD?.options ?? [],
+  checkAllItem: true,
+}] : [])
+
+확인되나요? (Y/n)
+```
+
+#### 자연어 조건 예시
+
+```
+// 단일 값 조건
+"prdBbsRvwTpcd가 1일 때만 표시"
+→ listRequestValue.prdBbsRvwTpcd === "1"
+
+// 다중 값 조건
+"prdBbsRvwTpcd가 1 또는 2일 때 표시"
+→ ["1", "2"].includes(listRequestValue.prdBbsRvwTpcd)
+
+// 참/거짓 조건
+"useYn이 Y일 때만 표시"
+→ listRequestValue.useYn === "Y"
+
+// 복합 조건
+"prdBbsRvwTpcd가 1이고 useYn이 Y일 때만 표시"
+→ listRequestValue.prdBbsRvwTpcd === "1" && listRequestValue.useYn === "Y"
+
+// 존재 여부
+"searchText가 있을 때만 표시"
+→ !!listRequestValue.searchText
+```
+
+---
+
+### 14번 자동완성 (AUTOCOMPLETE) 상세
+
+키워드 입력 시 실시간으로 API를 호출하여 검색 결과를 표시하는 컴포넌트입니다.
+
+```tsx
+// /wefor-sales-server/front/src/pages/sales/pipeline/App.tsx 예시
+{
+  placeholder: t("고객사"),
+  name: "custDto",
+  type: SearchParamType.AUTOCOMPLETE,
+  onSearch: async (filter?: string) => {
+    const { ds } = await CustomerService.getCustomerList({
+      filter,              // ← 입력한 키워드
+      filterCond: "CONTAINS",
+      pageSize: 100,
+    });
+    return ds.map((n) => ({
+      key: n.id ?? "",
+      value: { custId: n.id, custNm: n.custNm, inputValue: n.custNm },
+      label: n.custNm + ` (${bizNumFormatter(bizNumParser(n.bizNum))})`,
+    }));
+  },
+}
+```
+
+#### 특징
+
+| 항목 | 설명 |
+|------|------|
+| **onSearch** | 키워드 입력 시 호출되는 함수 |
+| **filter** | 사용자가 입력한 키워드 |
+| **반환값** | `{ key, value, label }` 형태의 배열 |
+| **value** | 객체 저장 가능 (예: `{ custId, custNm }`) |
+
+#### 대화형 설정 흐름
+
+```
+[MCP] AUTOCOMPLETE를 선택했습니다.
+      키워드 입력 시 실시간 검색을 수행합니다.
+
+1️⃣ 검색 API 서비스 선택
+   검색에 사용할 API 서비스를 입력하세요:
+
+사용자: CustomerService.getCustomerList
+
+2️⃣ 검색 필드 설정
+   검색할 필드명을 입력하세요 (엔터: filter):
+
+사용자: custNm
+
+3️⃣ 필터 조건 설정 (선택)
+   필터 조건을 선택하세요:
+   1. CONTAINS (포함)
+   2. STARTS_WITH (시작)
+   3. ENDS_WITH (종료)
+   4. EQUAL (일치)
+
+사용자: 1
+
+4️⃣ 표시 라벨 설정
+   결과에 표시할 라벨 형식을 입력하세요.
+   변수: {custNm}, {bizNum}, {custOwner} 등
+
+사용자: {custNm} ({bizNum})
+
+5️⃣ 저장 값 설정
+   결과 값으로 저장할 필드를 선택하세요:
+   1. id만 저장
+   2. 전체 객체 저장
+
+사용자: 2
+
+생성될 코드:
+{
+  placeholder: t('고객사'),
+  name: 'custDto',
+  type: SearchParamType.AUTOCOMPLETE,
+  onSearch: async (filter?: string) => {
+    const { ds } = await CustomerService.getCustomerList({
+      filter,
+      filterCond: 'CONTAINS',
+      pageSize: 100,
+    });
+    return ds.map((n) => ({
+      key: n.id ?? '',
+      value: n,  // 전체 객체 저장
+      label: `${n.custNm} (${bizNumFormatter(n.bizNum)})`,
+    }));
+  },
+}
+```
+
+---
+
+### 15번 계층 선택 (CASCADE) 상세
+
+계층적 구조에서 단계별로 선택하는 컴포넌트입니다. (예: 조직 > 팀 > 파트)
+
+```tsx
+// /wefor-sales-server/front/src/pages/sales/pipeline/App.tsx 예시
+const { list: organizationOption } = useOrganizationCascadeData();
+
+{
+  placeholder: t("조직"),
+  name: "_orgCd",
+  width: 200,
+  type: SearchParamType.CASCADE,
+  options: organizationOption as SearchParamOption[],
+  displayRender: (labels: string[]) => labels[labels.length - 1],  // 마지막 레벨만 표시
+  onSelect: (option) => {
+    setUserComboParams({ ...option });  // 선택 시 다른 필드 업데이트
+  },
+}
+```
+
+#### 특징
+
+| 항목 | 설명 |
+|------|------|
+| **options** | 계층적 구조의 옵션 (children 포함) |
+| **displayRender** | 표시할 라벨 커스터마이징 |
+| **onSelect** | 선택 시 콜백 (다른 필드 연동) |
+
+#### 계층 옵션 구조
+
+```tsx
+// useOrganizationCascadeData 훅이 반환하는 옵션 구조
+[
+  {
+    value: "ORG001",
+    label: "본사",
+    children: [
+      {
+        value: "TEAM001",
+        label: "영업팀",
+        children: [
+          { value: "PART001", label: "1파트" },
+          { value: "PART002", label: "2파트" },
+        ],
+      },
+    ],
+  },
+]
+```
+
+#### 대화형 설정 흐름
+
+```
+[MCP] CASCADE를 선택했습니다.
+      계층적 선택 컴포넌트를 생성합니다.
+
+1️⃣ 계층 데이터 훅 선택
+   계층 데이터를 가져올 훅을 입력하세요:
+
+사용자: useOrganizationCascadeData
+
+2️⃣ 표시 레벨 설정
+   선택된 경로 중 어떤 레벨을 표시할까요?
+   1. 전체 경로 (본사 > 영업팀 > 1파트)
+   2. 마지막 레벨만 (1파트)
+   3. 첫 번째 레벨만 (본사)
+
+사용자: 2
+
+3️⃣ 연동 필드 설정 (선택)
+   선택 시 다른 필드를 업데이트할까요?
+   (이미 정의된 필드 목록, 엔터: 없음)
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. salesUserCd (영업사원)                   │
+   │ 2. someOtherField                          │
+   └─────────────────────────────────────────────┘
+
+사용자: 1
+
+[MCP] 조직 선택 시 salesUserCd 필드를 업데이트합니다.
+
+생성될 코드:
+// API 훅
+const { list: organizationOption } = useOrganizationCascadeData();
+const [userComboParams, setUserComboParams] = useState({});
+
+// SearchParams
+{
+  placeholder: t('조직'),
+  name: '_orgCd',
+  width: 200,
+  type: SearchParamType.CASCADE,
+  options: organizationOption,
+  displayRender: (labels: string[]) => labels[labels.length - 1],
+  onSelect: (option) => {
+    setUserComboParams({ ...option });
+  },
+}
+
+// 연동 필드
+{
+  placeholder: t('영업사원'),
+  name: 'salesUserCd',
+  type: SearchParamType.SELECT,
+  options: userComboList,  // onSelect로 업데이트됨
+}
+```
+
+#### 계층 데이터 전송
+
+```tsx
+// API 호출 시 계층 값을 처리하는 유틸리티
+import { collectCascadeValue } from 'utils/collectOptions';
+
+const apiParams = {
+  ...
+  orgCd: collectCascadeValue(listRequestValue._orgCd),
+  // _orgCd: ["ORG001", "TEAM001", "PART001"]
+  // → orgCd: "PART001" (마지막 값만 전송)
+  // 또는 "ORG001>TEAM001>PART001" (전체 경로)
+};
+```
+
+---
+
+### 16번 모달 검색 (MODAL) 상세
+
+버튼 클릭 시 모달을 열어서 선택하는 컴포넌트입니다.
+
+```tsx
+// /wefor-sales-server/front/src/pages/sales/estimate/App.tsx 예시
+import { openCustomerModal } from "modals/customer/CustomerModal";
+import { openEmployeeModal } from "modals/employee/EmployeeModal";
+
+// 고객사 선택 (단일)
+{
+  placeholder: t("고객사코드"),
+  name: "custId",
+  type: SearchParamType.MODAL,
+  onSearch: async () => {
+    const data = await openCustomerModal();
+    return [{
+      label: data.customer?.custNm,
+      value: JSON.stringify({
+        custId: data.customer?.id,
+        custNm: data.customer?.custNm,
+      }),
+    }];
+  },
+  config: {
+    single: true,  // 단일 선택
+  },
+}
+
+// 영업사원 선택 (단일)
+{
+  placeholder: t("영업사원"),
+  name: "salesUserCd",
+  type: SearchParamType.MODAL,
+  onSearch: async () => {
+    const data = await openEmployeeModal();
+    return [{
+      label: data.user?.userNm,
+      value: JSON.stringify({
+        salesUserCd: data.user?.userCd,
+        salesUserNm: data.user?.userNm,
+      }),
+    }];
+  },
+  config: {
+    single: true,
+  },
+  width: 150,
+}
+```
+
+#### 특징
+
+| 항목 | 설명 |
+|------|------|
+| **onSearch** | 버튼 클릭 시 호출되는 함수 (모달 오픈) |
+| **modal 함수** | `openXxxModal()` 형태의 함수 |
+| **반환값** | `[{ label, value }]` 형태의 배열 |
+| **value** | JSON 문자열로 객체 저장 |
+| **config.single** | 단일 선택 여부 (`true`: 단일, `false`/없음: 다중) |
+
+#### 대화형 설정 흐름
+
+```
+[MCP] MODAL(모달형 검색)을 선택했습니다.
+      버튼 클릭 시 모달을 열어서 선택합니다.
+
+1️⃣ 모달 함수 선택
+   사용할 모달 오픈 함수를 입력하세요:
+   예: openCustomerModal, openEmployeeModal, openProductModal
+
+사용자: openCustomerModal
+
+2️⃣ 표시 라벨 설정
+   모달에서 선택한 결과를 어떻게 표시할까요?
+   사용 가능 변수: 모달이 반환하는 데이터의 필드들
+   예: {custNm}, {bizNum}, {custOwner} 등
+
+   형식: {필드명} 또는 조합 가능
+   예: {custNm} ({bizNum})
+
+사용자: {custNm}
+
+3️⃣ 저장 값 설정
+   어떤 값을 저장할까요?
+   1. id만 저장 (단일 값)
+   2. 전체 객체를 JSON으로 저장
+
+사용자: 2
+
+[MCP] 저장할 필드를 선택하세요:
+   쉼표로 구분하여 입력하세요.
+   예: custId, custNm, bizNum
+
+사용자: custId, custNm
+
+4️⃣ 단일/다중 선택
+   단일 선택인가요? (Y/n):
+
+사용자: y
+
+5️⃣ 너비 설정 (선택)
+   너비를 입력하세요 (엔터: 기본값 200):
+
+사용자: 150
+
+생성될 코드:
+{
+  placeholder: t('고객사코드'),
+  name: 'custId',
+  type: SearchParamType.MODAL,
+  onSearch: async () => {
+    const data = await openCustomerModal();
+    return [{
+      label: data.customer?.custNm,
+      value: JSON.stringify({
+        custId: data.customer?.id,
+        custNm: data.customer?.custNm,
+      }),
+    }];
+  },
+  config: {
+    single: true,
+  },
+  width: 150,
+}
+```
+
+#### 다중 선택 예시
+
+```
+사용자: n (다중 선택)
+
+[MCP] config.single을 설정하지 않습니다 (다중 선택).
+
+생성될 코드:
+{
+  placeholder: t('고객사'),
+  name: 'custId',
+  type: SearchParamType.MODAL,
+  onSearch: async () => {
+    const data = await openCustomerModal();
+    return data.customers.map((c) => ({
+      label: c.custNm,
+      value: JSON.stringify({
+        custId: c.id,
+        custNm: c.custNm,
+      }),
+    }));
+  },
+  // config: { single: true } 없음 → 다중 선택
+}
+```
+
+#### 저장 값 처리
+
+```tsx
+// API 호출 시 JSON 문자열을 파싱
+const custId = listRequestValue.custId;
+
+// 단일 선택
+if (custId) {
+  const parsed = JSON.parse(custId);
+  // parsed: { custId: 123, custNm: "ABC고객사" }
+  apiParams.custId = parsed.custId;
+}
+
+// 다중 선택
+if (custId && Array.isArray(custId)) {
+  const parsedList = custId.map((c) => JSON.parse(c));
+  // parsedList: [{ custId: 123, custNm: "A" }, { custId: 456, custNm: "B" }]
+  apiParams.custIds = parsedList.map((p) => p.custId);
+}
+```
+
+---
+
+### 1번 선택 시 (AI에게 맡기기)
+
+```
+사용자: "이름으로 검색하는데, placeholder는 '이름을 입력하세요'로 해주고"
+
+[MCP] "알겠습니다. 검색어 INPUT으로 생성합니다.
+      placeholder는 '이름을 입력하세요'로 설정합니다.
+
+      다음과 같이 생성됩니다:
+
+{
+  label: t('회원명'),
+  name: 'usrNm',
+  type: SearchParamType.INPUT,
+  placeholder: t('이름을 입력하세요'),
+}
+
+확인되나요? (y/n)"
+```
+
+### 자연어 설명 예시
+
+```
+사용자: "이메일로 검색하고, 이메일 형식 검증도 추가해줘"
+
+[MCP] "검색어 INPUT으로 생성합니다.
+      이메일 형식 검증 rules를 추가합니다.
+
+{
+  label: t('이메일'),
+  name: 'usrEmailAddr',
+  type: SearchParamType.INPUT,
+  inputType: 'email',
+  rules: [{ type: 'email', message: t('이메일 형식이 아닙니다.') }],
+}"
+```
+
+```
+사용자: "사용여부는 드롭다운으로, 기본값은 Y로"
+
+[MCP] "SELECT으로 생성합니다.
+      기본값을 'Y'로 설정합니다.
+
+{
+  label: t('사용여부'),
+  name: 'useYn',
+  type: SearchParamType.SELECT,
+  codeVar: 'USE_YN',
+  initialValue: 'Y',
+}"
+```
+
+```
+사용자: "가입일은 날짜 범위 picker로, 기본값은 최근 30일로"
+
+[MCP] "DATE_RANGE로 생성합니다.
+      기본값을 최근 30일로 설정합니다.
+
+{
+  label: t('가입일'),
+  name: 'joinDt',
+  type: SearchParamType.DATE_RANGE,
+  defaultValue: [dayjs().subtract(30, 'day'), dayjs()],
+}"
+```
+
+### 자연어 처리 규칙
+
+| 키워드 | 컴포넌트 | 예시 |
+|--------|----------|------|
+| 검색어, 텍스트, 입력 | INPUT | "이름으로 검색" |
+| 드롭다운, 셀렉트, 선택 | SELECT | "드롭다운으로" |
+| 체크박스, 다중 선택 | CHECKBOX | "여러 개 선택 가능" |
+| 멀티 셀렉트 | SELECT_MULTI | "여러 상태 선택" |
+| 라디오, Y/N | RADIO | "사용여부 Y/N" |
+| 날짜, 일자 | DTPICKER_DATE | "가입일자" |
+| 기간, 범위, ~부터 ~까지 | DTPICKER_DATE_RANGE | "가입기간" |
+| 숫자 범위, 최소 최대 | NUMBER_RANGE | "방문회수 범위" |
+| 검색구분 + 텍스트 | GROUP | "제목/내용 검색" |
+| 코드, 분류 | SELECT + codeVar | "상태코드" |
+| 필수, 필수입력 | required: true | "필수 입력" |
+| placeholder ~ | placeholder: "~" | "placeholder는 '검색어'" |
+
+---
+
+### 타입별 대화형 설정 (타입 선택 후 추가 질문)
+
+타입을 선택하면 해당 타입에 맞는 추가 설정을 대화형으로 진행합니다.
+
+#### 2번 INPUT 선택 시
+
+```
+[MCP] INPUT을 선택했습니다.
+      usrNm (회원명) 필드에 대해 추가 설정을 진행합니다.
+
+1️⃣ placeholder 설정 (선택)
+   placeholder를 입력하세요 (엔터: 설정 안함):
+
+사용자: [엔터]
+
+[MCP] placeholder를 설정하지 않습니다.
+
+2️⃣ 너비 설정 (선택)
+   너비를 입력하세요 (엔터: 기본값 200):
+
+사용자: 250
+
+[MCP] width: 250으로 설정되었습니다.
+
+3️⃣ 기본값 설정 (선택)
+   기본값을 입력하세요 (엔터: 설정 안함):
+
+사용자: [엔터]
+
+[MCP] 기본값을 설정하지 않습니다.
+
+생성될 코드:
+{
+  label: t('회원명'),
+  name: 'usrNm',
+  type: SearchParamType.INPUT,
+  width: 250,
+}
+
+확인되나요? (Y/n)
+```
+
+#### 4번 SELECT 선택 시
+
+```
+[MCP] SELECT를 선택했습니다.
+      statusCd (상태코드) 필드에 대해 추가 설정을 진행합니다.
+
+1️⃣ 옵션 소스 선택
+   옵션을 어떻게 제공할까요?
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. 📦 Code Store 사용 (codeVar)             │
+   │ 2. ✏️ 직접 옵션 입력 (options 배열)         │
+   └─────────────────────────────────────────────┘
+
+사용자: 1
+
+2️⃣ 코드 변수명
+   코드 변수명을 입력하세요 (예: STATUS_CD):
+
+사용자: STATUS_CD
+
+[MCP] codeVar: 'STATUS_CD'로 설정되었습니다.
+
+3️⃣ 너비 설정 (엔터: 기본값 150):
+
+사용자: [엔터]
+
+4️⃣ 다중 선택 여부
+   다중 선택을 지원할까요? (y/N):
+
+사용자: n
+
+5️⃣ 기본값 설정 (선택)
+   기본값을 입력하세요 (엔터: 설정 안함):
+   코드 값으로 입력 (예: 01, Y):
+
+사용자: 01
+
+[MCP] 기본값 '01'로 설정되었습니다.
+
+생성될 코드:
+{
+  label: t('상태'),
+  name: 'statusCd',
+  type: SearchParamType.SELECT,
+  width: 150,
+  options: [
+    { label: t('전체'), value: '' },
+    ...(STATUS_CD?.options ?? [])
+  ],
+  initialValue: '01',
+}
+
+확인되나요? (Y/n)
+```
+
+#### 7번 RADIO 선택 시
+
+```
+[MCP] RADIO를 선택했습니다.
+      useYn (사용여부) 필드에 대해 추가 설정을 진행합니다.
+
+1️⃣ 옵션 패턴 선택
+   어떤 옵션 패턴을 사용할까요?
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. Y/N 패턴 (전체/Y/N)                      │
+   │ 2. 직접 옵션 입력                           │
+   └─────────────────────────────────────────────┘
+
+사용자: 1
+
+[MCP] Y/N 패턴을 사용합니다.
+
+2️⃣ 기본값 설정 (선택)
+   기본값을 선택하세요:
+   1. 전체 (빈값)
+   2. Y
+   3. N
+
+사용자: 2
+
+[MCP] 기본값 'Y'로 설정되었습니다.
+
+생성될 코드:
+{
+  label: t('사용여부'),
+  name: 'useYn',
+  type: SearchParamType.RADIO,
+  options: [
+    { label: t('전체'), value: '' },
+    { label: t('Y'), value: 'Y' },
+    { label: t('N'), value: 'N' },
+  ],
+  initialValue: 'Y',
+}
+
+확인되나요? (Y/n)
+```
+
+#### 9번 DTPICKER_DATE_RANGE 선택 시
+
+```
+[MCP] DATE_RANGE를 선택했습니다.
+      dateRange (등록일) 필드에 대해 추가 설정을 진행합니다.
+
+1️⃣ 프리셋 타입
+   프리셋 타입을 선택하세요:
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. all (전체: 오늘, 7일, 30일, 90일, 1년)  │
+   │ 2. default (기본: 오늘, 7일, 30일)         │
+   │ 3. 없음                                    │
+   └─────────────────────────────────────────────┘
+
+사용자: 1
+
+2️⃣ 날짜 포맷 선택
+   날짜 포맷을 선택하세요:
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. DATE (년월일)                           │
+   │    예: 2024-01-15                           │
+   ├─────────────────────────────────────────────┤
+   │ 2. DATETIME (년월일시분초)                 │
+   │    예: 2024-01-15 14:30:00                  │
+   ├─────────────────────────────────────────────┤
+   │ 3. DATETIME_HHMM (년월일시분)              │
+   │    예: 2024-01-15 14:30                     │
+   └─────────────────────────────────────────────┘
+
+사용자: 1
+
+[MCP] format: DT_FORMAT.DATE, isTimeSelector: false로 설정합니다.
+
+3️⃣ 기간구분 포함 여부
+   기간구분(예: 가입일/수정일)을 포함할까요? (y/N):
+
+사용자: n
+
+4️⃣ 기본 날짜 범위 설정 (선택)
+   기본 날짜 범위를 선택하세요:
+   1. 설정 안함
+   2. 오늘
+   3. 최근 7일
+   4. 최근 30일
+   5. 최근 90일
+   6. 최근 1년
+
+사용자: 4
+
+[MCP] 기본값을 최근 30일로 설정합니다.
+
+생성될 코드:
+{
+  label: t('등록일'),
+  placeholder: [t('년월일'), t('년월일')],
+  name: 'dateRange',
+  type: SearchParamType.DTPICKER_DATE_RANGE,
+  format: DT_FORMAT.DATE,
+  isTimeSelector: false,
+  presetRender: DtPickerPresetRender({ type: 'all' }),
+  defaultValue: [dayjs().subtract(30, 'day'), dayjs()],
+}
+
+확인되나요? (Y/n)
+```
+
+#### DATETIME_HHMM 선택 시 예시
+
+```
+사용자: 3 (DATETIME_HHMM 선택)
+
+[MCP] format: DT_FORMAT.DATETIME_HHMM, isTimeSelector: true로 설정합니다.
+      placeholder는 '년월일시분'으로 설정됩니다.
+
+생성될 코드:
+{
+  label: t('작성기간'),
+  placeholder: [t('년월일시분'), t('년월일시분')],
+  name: 'dateRange',
+  type: SearchParamType.DTPICKER_DATE_RANGE,
+  format: DT_FORMAT.DATETIME_HHMM,
+  isTimeSelector: true,
+  presetRender: DtPickerPresetRender({ type: 'all' }),
+}
+```
+
+#### 10번 NUMBER_RANGE 선택 시
+
+```
+[MCP] NUMBER_RANGE를 선택했습니다.
+      visitCount (방문회수) 필드에 대해 추가 설정을 진행합니다.
+
+1️⃣ MIN placeholder 설정 (선택)
+   MIN placeholder를 입력하세요 (엔터: 'MIN'):
+
+사용자: [엔터]
+
+2️⃣ MAX placeholder 설정 (선택)
+   MAX placeholder를 입력하세요 (엔터: 'MAX'):
+
+사용자: [엔터]
+
+3️⃣ 기본값 설정 (선택)
+   MIN 기본값을 입력하세요 (엔터: 설정 안함):
+
+사용자: 10
+
+4️⃣ 기본값 설정 (선택)
+   MAX 기본값을 입력하세요 (엔터: 설정 안함):
+
+사용자: 100
+
+[MCP] 기본값을 MIN: 10, MAX: 100으로 설정합니다.
+
+생성될 코드:
+{
+  label: t('방문회수'),
+  placeholder: [t('MIN'), t('MAX')],
+  name: 'visitCount',
+  type: SearchParamType.NUMBER_RANGE,
+  defaultValue: [10, 100],
+}
+
+확인되나요? (Y/n)
+```
+
+#### 11번 SKIP 선택 시
+
+```
+[MCP] SKIP을 선택했습니다.
+      usrNm (회원명) 필드는 SearchParams에 포함하지 않습니다.
+
+다음 필드로 넘어갑니다...
+```
+
+#### 12번 HIDDEN 선택 시
+
+```
+[MCP] HIDDEN을 선택했습니다.
+      usrNm (회원명) 필드는 UI에 표시하지 않지만,
+      listRequestValue에는 유지됩니다.
+
+⚠️ HIDDEN 필드는 별도로 초기값 설정이 필요할 수 있습니다.
+
+다음 필드로 넘어갈까요? (Y/n)
+```
+
+#### 5번 CHECKBOX 선택 시
+
+```
+[MCP] CHECKBOX를 선택했습니다.
+      sbscrbPathClcdArr (회원가입채널) 필드에 대해 추가 설정을 진행합니다.
+
+1️⃣ 옵션 소스 선택
+   옵션을 어떻게 제공할까요?
+
+   ┌─────────────────────────────────────────────┐
+   │ 1. 📦 Code Store 사용 (codeVar)             │
+   │ 2. ✏️ 직접 옵션 입력 (options 배열)         │
+   └─────────────────────────────────────────────┘
+
+사용자: 1
+
+2️⃣ 코드 변수명
+   코드 변수명을 입력하세요 (예: SBSCRB_PATH_CLCD):
+
+사용자: SBSCRB_PATH_CLCD
+
+[MCP] codeVar: 'SBSCRB_PATH_CLCD'로 설정되었습니다.
+
+3️⃣ 전체 옵션 포함 여부
+   "전체" 옵션을 포함할까요? (Y/n):
+
+사용자: y
+
+[MCP] checkAllItem: true로 설정되었습니다.
+
+4️⃣ 기본값 설정 (선택)
+   기본으로 체크할 옵션을 입력하세요.
+   형식: 값,값 (쉼표로 구분, 엔터: 설정 안함):
+
+사용자: Y,02
+
+[MCP] 기본값 ['Y', '02']로 설정되었습니다.
+
+생성될 코드:
+{
+  label: t('회원가입채널'),
+  name: 'sbscrbPathClcdArr',
+  type: SearchParamType.CHECKBOX,
+  options: SBSCRB_PATH_CLCD?.options ?? [],
+  checkAllItem: true,
+  defaultValue: ['Y', '02'],
+}
+
+확인되나요? (Y/n)
+```
+
+---
+
+### 각 패턴별 코드 예시 (NH 프로젝트 실사용)
+
+#### 2. 📝 일반 텍스트 입력 (INPUT)
+
+```tsx
+// 기본 텍스트 입력
+{
+  label: t("검색어"),
+  placeholder: t("검색어"),
+  name: "searchText",
+  type: SearchParamType.INPUT,
+}
+
+// 너비 지정
+{
+  label: t("회원명"),
+  placeholder: t("회원명을 입력하세요"),
+  name: "usrNm",
+  type: SearchParamType.INPUT,
+  width: 200,
+}
+```
+
+#### 3. 🔍 검색구분 + 텍스트 (GROUP)
+
+```tsx
+// 검색어 구분 + 텍스트 입력
+{
+  type: SearchParamType.GROUP,
+  children: [
+    {
+      label: t("검색어구분"),
+      name: "searchType",
+      type: SearchParamType.SELECT,
+      options: [
+        { label: t("제목"), value: "TITLE" },
+        { label: t("내용"), value: "CONTENT" },
+        { label: t("작성자"), value: "WRITER" },
+      ],
+      width: 120,
+    },
+    {
+      label: t("검색어"),
+      name: "searchText",
+      type: SearchParamType.INPUT,
+      placeholder: t("검색어를 입력하세요"),
+    },
+  ],
+}
+```
+
+#### 4. 📋 드롭다운 선택 (SELECT)
+
+```tsx
+// Code Store 사용
+{
+  label: t("주문상태"),
+  name: "ordSttusTpcd",
+  type: SearchParamType.SELECT,
+  width: 200,
+  options: ORD_STTUS_TPCD?.options ?? [],
+  showSearch: true,
+  allowClear: true,
+}
+
+// 직접 옵션 입력
+{
+  label: t("정렬"),
+  name: "sortType",
+  type: SearchParamType.SELECT,
+  width: 150,
+  options: [
+    { label: t("최신순"), value: "latest" },
+    { label: t("이름순"), value: "name" },
+    { label: t("가나다순"), value: "abc" },
+  ],
+}
+
+// API 로딩 상태
+{
+  label: t("제품군"),
+  name: "ctgrNo",
+  type: SearchParamType.SELECT,
+  width: 250,
+  options: [...prodgrpNo],
+  showSearch: false,
+  allowClear: true,
+  loading: prodgrpSpinning,
+}
+```
+
+#### 5. ✓ 체크박스 다중 선택 (CHECKBOX)
+
+```tsx
+// 코드 기반 체크박스
+{
+  label: t("회원가입채널"),
+  name: "sbscrbPathClcdArr",
+  type: SearchParamType.CHECKBOX,
+  options: SBSCRB_PATH_CLCD?.options ?? [],
+  checkAllItem: true, // "전체" 옵션 추가
+}
+
+// 직접 옵션 입력
+{
+  label: t("통합회원여부"),
+  name: "unityMberYnArr",
+  type: SearchParamType.CHECKBOX,
+  options: [
+    { label: t("통합회원"), value: "Y" },
+    { label: t("임직원"), value: "02" },
+    { label: t("미전환"), value: "N" },
+  ],
+  checkAllItem: true,
+}
+```
+
+#### 6. ☐ 멀티 셀렉트 (SELECT_MULTI)
+
+```tsx
+// 상태 다중 선택
+{
+  label: t("주문상태"),
+  name: "ordSttusTpcds",
+  type: SearchParamType.SELECT_MULTI,
+  width: 200,
+  options: ORD_STTUS_TPCD?.options ?? [],
+  checkAllItem: true,
+}
+
+// 동적 옵션 생성
+{
+  label: t("년도"),
+  name: "bbscttMgmtYys",
+  type: SearchParamType.SELECT_MULTI,
+  options: Array.from({ length: dayjs().year() - 2010 + 1 })
+    .map((_, i) => ({
+      label: `${i + 2010}년`,
+      value: `${i + 2010}`,
+    })),
+}
+```
+
+#### 7. ○ 라디오 버튼 (RADIO)
+
+```tsx
+// Y/N 선택 (가장 일반적)
+{
+  label: t("사용여부"),
+  name: "useYn",
+  type: SearchParamType.RADIO,
+  options: [
+    { label: t("전체"), value: "" },
+    { label: t("Y"), value: "Y" },
+    { label: t("N"), value: "N" },
+  ],
+}
+
+// 이메일 수신 동의
+{
+  label: t("이메일수신동의"),
+  name: "emailRecptnYn",
+  type: SearchParamType.RADIO,
+  options: [
+    { label: t("전체"), value: "" },
+    { label: t("동의"), value: "Y" },
+    { label: t("미동의"), value: "N" },
+  ],
+}
+
+// 답변 상태
+{
+  label: t("답변상태"),
+  name: "answerSttusYn",
+  type: SearchParamType.RADIO,
+  options: [
+    { label: t("전체"), value: "" },
+    { label: t("답변대기"), value: "N" },
+    { label: t("답변완료"), value: "Y" },
+  ],
+}
+```
+
+#### 8. 📅 단일 날짜 (DTPICKER_DATE)
+
+```tsx
+{
+  label: t("등록일"),
+  name: "regDt",
+  type: SearchParamType.DTPICKER_DATE,
+  format: DT_FORMAT.DATE,
+}
+```
+
+#### 9. 📆 날짜 범위 (DTPICKER_DATE_RANGE)
+
+```tsx
+// 기본 날짜 범위
+{
+  label: t("등록일"),
+  placeholder: [t("년월일"), t("년월일")],
+  name: "dateRange",
+  type: SearchParamType.DTPICKER_DATE_RANGE,
+  format: DT_FORMAT.DATE,
+  isTimeSelector: false,
+  presetRender: DtPickerPresetRender({ type: "all" }),
+}
+
+// 기간구분 + 날짜 범위 (단일 달력으로 처리)
+{
+  type: SearchParamType.GROUP,
+  children: [
+    {
+      label: t("기간구분"),
+      name: "periodType",
+      type: SearchParamType.SELECT,
+      options: [
+        { label: t("주문일"), value: "01" },
+        { label: t("결제일"), value: "02" },
+        { label: t("배송일"), value: "03" },
+      ],
+      width: 120,
+    },
+    {
+      label: t("기간"),
+      name: "dateRange",
+      type: SearchParamType.DTPICKER_DATE_RANGE,
+      format: DT_FORMAT.DATE,
+      presetRender: DtPickerPresetRender({ type: "all" }),
+    },
+  ],
+}
+
+// 날짜 범위 (시간 포함)
+{
+  label: t("작성일시"),
+  name: "datetimeRange",
+  type: SearchParamType.DTPICKER_DATE_RANGE,
+  format: DT_FORMAT.DATETIME,
+  isTimeSelector: true,
+  presetRender: DtPickerPresetRender({ type: "all" }),
+}
+```
+
+#### 10. 🔢 숫자 범위 (NUMBER_RANGE)
+
+```tsx
+// 방문회수 범위
+{
+  label: t("방문회수"),
+  placeholder: [t("MIN"), t("MAX")],
+  name: "visitCount",
+  type: SearchParamType.NUMBER_RANGE,
+}
+
+// 구매금액 범위
+{
+  label: t("구매금액"),
+  placeholder: [t("최소금액"), t("최대금액")],
+  name: "purchaseAmount",
+  type: SearchParamType.NUMBER_RANGE,
+}
+```
+
+---
+
+### 추가 레이아웃 요소
+
+#### 줄바꿈 (LINE_BREAK)
+
+```tsx
+// 줄바꿈으로 섹션 분리
+{ type: SearchParamType.LINE_BREAK }
+```
+
+#### 간격 조절 (GAP)
+
+```tsx
+// 필드 간 간격 조절
+{ type: SearchParamType.GAP }
+```
+
+---
+
+### Code Store vs 직접 옵션
+
+```
+[MCP] statusCd (상태코드) 필드입니다.
+      어떤 방식으로 옵션을 제공할까요?
+
+┌─────────────────────────────────────────────┐
+│ 1. 📦 Code Store 사용 (codeVar)             │
+│    → USE_YN, STATUS_CD 등                   │
+├─────────────────────────────────────────────┤
+│ 2. ✏️ 직접 옵션 입력 (options 배열)         │
+│    → [{ label: '이름', value: 'name' }]     │
+└─────────────────────────────────────────────┘
+
+번호를 입력하세요:
+```
+
+#### 1번 선택 시 (Code Store)
+```
+[MCP] "코드 변수명을 입력하세요:"
+사용자: "STATUS_CD"
+
+[MCP] "자동 추론: STATUS_CD (확인되었습니다)"
+```
+
+#### 2번 선택 시 (직접 옵션)
+```
+[MCP] "옵션을 입력하세요.
+       형식: label,value (줄바리로 구분)"
+
+사용자:
+활성,active
+비활성,inactive
+대기,pending
+
+[MCP] "다음과 같이 변환됩니다:
+[
+  { label: '활성', value: 'active' },
+  { label: '비활성', value: 'inactive' },
+  { label: '대기', value: 'pending' },
+]
+
+확인되나요? (y/n)"
+```
+
+---
+
+## 그룹핑 설정
+
+### 그룹핑 방식
+
+| 방식 | 설명 | 코드 예시 |
+|------|------|---------|
+| 한 줄 | 기본, 한 줄에 표시 | `<Params.Input />` |
+| 그룹 | 여러 필드를 같은 줄 | `<Params.Group>...</Params.Group>` |
+| 독립 줄 | 그룹 없이 독립 | `lineBreak: true` |
+
+### 대화형 흐름
+
+```
+[MCP] "필드 그룹핑을 설정합니다.
+
+      형식 1 (줄바꿈):
+      - 필드명 (독립 줄)
+
+      형식 2 (그룹):
+      - 필드1, 필드2 (한 줄)
+
+      예시:
+      - usrNm, usrEmailAddr
+      - useYn, statusCd
+      - joinDt (줄바꿈)"
+```
+
+### 생성 코드 예시 (그룹핑)
+
+```tsx
+<SearchParams
+  form={searchForm}
+  params={[
+    // 그룹 1: 한 줄에 2개
+    { label: '이름', name: 'usrNm', type: SearchParamType.INPUT },
+    { label: '이메일', name: 'usrEmailAddr', type: SearchParamType.INPUT },
+
+    // 줄바꿈
+    null,
+
+    // 그룹 2: 한 줄에 2개
+    { label: '사용여부', name: 'useYn', type: SearchParamType.SELECT, codeVar: 'USE_YN' },
+    { label: '상태', name: 'statusCd', type: SearchParamType.SELECT, codeVar: 'STATUS_CD' },
+
+    // 줄바꿈
+    null,
+
+    // 독립 필드
+    { label: '가입일', name: 'joinDt', type: SearchParamType.DATE_PICKER },
+  ]}
+  paramsValue={listRequestValue}
+  onChangeParamsValue={setListRequestValue}
+  onSearch={handleSearch}
+  spinning={listSpinning}
+/>
+```
+
+---
+
+## 기본값 처리
+
+### 기본값 설정 방식
+
+| 방식 | 설명 | 예시 |
+|------|------|------|
+| 고정값 | 항상 같은 값 | `useYn: 'Y'` |
+| 동적값 | 실행 시 계산 | `joinDt: dayjs()` |
+| 코드 첫번째 | 코드 옵션의 첫 값 | `statusCd: CODE.options[0]?.value` |
+| 빈값 | 초기에 비워둠 | `searchText: ''` |
+
+### 대화형 흐름
+
+```
+[MCP] "각 필드의 기본값을 설정합니다.
+      기본값이 필요한 필드를 말씀해주세요:"
+
+사용자:
+- useYn: 'Y'
+- joinDt: 오늘날짜
+- statusCd: 첫번째코드
+
+[MCP] "다음과 같이 설정합니다:
+
+const initialSearchValues = {
+  useYn: 'Y',
+  joinDt: dayjs(),
+  statusCd: STATUS_CD?.options[0]?.value,
+};
+
+확인되나요? (y/n)"
+```
+
+### 기본값 입력 형식
+
+```
+필드명: 값
+
+예시:
+- useYn: 'Y'           // 문자열
+- pageNumber: 1       // 숫자
+- joinDt: 오늘날짜     // 동적 값
+- statusCd: 첫번째코드 // 코드 첫 값
+- searchText: ''       // 빈값 (명시)
+```
+
+---
+
+## 연동 선택박스 설정 (Cascading Select)
+
+### 연동 그룹 종류
+
+| 구분 | 설명 | 예시 |
+|------|------|------|
+| 2단계 연동 | 부모 → 자식 | 배송사 → 배송비 방식 |
+| 3단계 연동 | 부모 → 자식 → 손자 | 대분류 → 중분류 → 소분류 |
+
+### 연동 그룹 설정 프롬프트
+
+```
+연동 그룹 1:
+- 단계: 2단계
+- 필드: dlvyClTpcd → dlcstMthdCd
+- 훅: useCodeStore
+- 코드: DLCMPY_TPCD
+- 필터: uprDtlCd
+```
+
+### 대화형 흐름
+
+#### 1단계: 연동 설정 질문
+```
+[MCP] 모든 필드 설정이 완료되었습니다.
+      연동된 선택박스가 있나요?
+
+┌─────────────────────────────────────────────┐
+│ 1. 🔗 연동 설정이 있다                       │
+├─────────────────────────────────────────────┤
+│ 2. ✅ 연동 없음, 다음 단계로                 │
+└─────────────────────────────────────────────┘
+```
+
+#### 2단계: 연동 그룹 입력
+```
+[MCP] "연동 그룹을 입력해주세요.
+      형식:
+
+      연동 그룹 N:
+      - 단계: 2단계 또는 3단계
+      - 필드: 부모 → 자식 (→ 손자)
+      - 훅: useCodeStore
+      - 코드: CODE_NAME
+      - 필터: 필터링 필드명"
+
+사용자:
+연동 그룹 1:
+- 단계: 2단계
+- 필드: dlvyClTpcd → dlcstMthdCd
+- 훅: useCodeStore
+- 코드: DLCMPY_TPCD
+- 필터: uprDtlCd
+```
+
+#### 3단계: 코드 미리보기
+```
+[MCP] "다음과 같이 연동 코드를 생성합니다:
+
+const DLCMPY_TPCD = useCodeStore((s) => s.DLCMPY_TPCD);
+
+const DLCMPY_TPCD_OPTS = useMemo(() => {
+  const selected = form.getFieldValue('dlvyClTpcd');
+  return DLCMPY_TPCD?.options.filter(
+    (o) => o.uprDtlCd === selected
+  );
+}, [form.getFieldValue('dlvyClTpcd')]);
+
+확인되나요? (y/n)"
+```
+
+---
+
+## 대화형 생성 절차 (전체)
+
+### 1단계: 필드 분석
+```
+[MCP] "N개의 필드를 발견했습니다.
+       하나씩 어떻게 처리할지 물어볼게요."
+```
+
+### 2단계: 연동 설정 (선택)
+```
+[MCP] "연동된 선택박스가 있나요?
+      연동 그룹을 입력해주세요.
+
+      형식:
+      연동 그룹 N:
+      - 단계: 2단계 또는 3단계
+      - 필드: 부모 → 자식 (→ 손자)
+      - 훅: useCodeStore
+      - 코드: CODE_NAME
+      - 필터: 필터링 필드명"
+```
+
+### 3단계: 필드별 패턴 선택
+```
+[MCP] "fieldName (한글명) 필드입니다.
+      다음 중 선택해주세요:"
+
+[패턴 카탈로그 표시]
+
+사용자: "1"
+```
+
+### 4단계: 추가 질문 (필요시)
+```
+[MCP] "코드 변수명이 필요합니다.
+      USE_YN, STATUS_CD 등:"
+```
+
+### 5단계: 그룹핑 설정
+```
+[MCP] "필드 그룹핑을 설정합니다.
+      같은 줄에 표시할 필드들을 콤마로 구분해주세요:"
+
+사용자:
+- usrNm, usrEmailAddr
+- useYn, statusCd
+- joinDt
+```
+
+### 6단계: 기본값 설정
+```
+[MCP] "기본값이 필요한 필드가 있나요?
+      형식: 필드명: 값"
+
+사용자:
+- useYn: 'Y'
+- joinDt: 오늘날짜
+```
+
+### 7단계: 확인 및 생성
+```
+[MCP] "모든 설정 완료!
+       다음과 같이 생성합니다:"
+
+[요약 표시]
+
+생성할까요? (y/n)"
+```
+
+---
+
+## SearchParams 컴포넌트 패턴 (NH 프로젝트 기반)
+
+| # | 패턴 | SearchParamType | 주요 용도 | 빈도 |
+|---|------|-----------------|----------|------|
+| 1 | 🤖 AI 추론 | - | 자연어로 설명 | - |
+| 2 | 📝 텍스트 입력 | INPUT | 회원명, 이메일, 전화번호 | 115회 |
+| 3 | 🔍 검색구분+텍스트 | GROUP | 제목/내용, 이름/ID 검색 | 110회 |
+| 4 | 📋 드롭다운 | SELECT | 상태코드, 카테고리 | 191회 |
+| 5 | ✓ 체크박스 | CHECKBOX | 회원가입채널, 관심사 | 14회 |
+| 6 | ☐ 멀티 셀렉트 | SELECT_MULTI | 주문상태, 배송상태 | 38회 |
+| 7 | ○ 라디오 | RADIO | 사용여부, 이메일수신동의 | 127회 |
+| 8 | 📅 단일 날짜 | DTPICKER_DATE | 등록일, 수정일 | 1회 |
+| 9 | 📆 날짜 범위 | DTPICKER_DATE_RANGE | 가입기간, 주문기간 | 100회 |
+| 10 | 🔢 숫자 범위 | NUMBER_RANGE | 방문회수, 구매금액 | 1회 |
+| - | 줄바꿈 | LINE_BREAK | 섹션 분리 | 15회 |
+| - | 간격 조절 | GAP | 필드 간 간격 | 2회 |
+
+---
+
+## 출력 코드 구조
+
+### 기본 예시
+
+```tsx
+// App.tsx에 추가할 SearchParams JSX
+
+import { SearchParams, SearchParamType } from "@core/components/search";
+import { useI18n } from "hooks";
+
+function App() {
+  const { t } = useI18n("_screenName"); // 다국어 지원
+
+  // 필수 검증이 있는 경우
+  const requiredFields = ['usrNm', 'usrEmailAddr'];
+
+  <SearchParams
+    form={searchForm}
+    params={[
+      // 그룹 1: 텍스트 입력 2개
+      { label: t("이름"), name: 'usrNm', type: SearchParamType.INPUT },
+      { label: t("이메일"), name: 'usrEmailAddr', type: SearchParamType.INPUT },
+
+      // 줄바꿈
+      null,
+
+      // 그룹 2: 라디오 + 셀렉트
+      { label: t("사용여부"), name: 'useYn', type: SearchParamType.RADIO,
+        options: [{ label: t("전체"), value: "" }, { label: t("Y"), value: "Y" }, { label: t("N"), value: "N" }] },
+      { label: t("상태"), name: 'statusCd', type: SearchParamType.SELECT, codeVar: 'STATUS_CD' },
+
+      // 줄바꿈
+      null,
+
+      // 독립 필드: 날짜 범위
+      { label: t("가입일"), name: 'dateRange', type: SearchParamType.DTPICKER_DATE_RANGE,
+        format: DT_FORMAT.DATE, presetRender: DtPickerPresetRender({ type: "all" }) },
+    ]}
+    requiredFields={requiredFields}
+    paramsValue={listRequestValue}
+    onChangeParamsValue={setListRequestValue}
+    onSearch={handleSearch}
+    spinning={listSpinning}
+  />
+}
+```
+
+### 복합 예시 (NH 프로젝트 실사용 패턴)
+
+```tsx
+import { SearchParams, SearchParamType } from "@core/components/search";
+import { useI18n } from "hooks";
+import { DtPickerPresetRender, DT_FORMAT } from "@core/components/datetime";
+
+function OrderList() {
+  const { t } = useI18n("_orderList");
+  const ORD_STTUS_TPCD = useCodeStore((s) => s.ORD_STTUS_TPCD);
+
+  <SearchParams
+    form={searchForm}
+    params={[
+      // 검색구분 + 검색어 그룹
+      {
+        type: SearchParamType.GROUP,
+        children: [
+          {
+            label: t("검색구분"),
+            name: "searchType",
+            type: SearchParamType.SELECT,
+            options: [
+              { label: t("주문번호"), value: "ORD_NO" },
+              { label: t("상품명"), value: "PRD_NM" },
+              { label: t("구매자명"), value: "BUYER_NM" },
+            ],
+            width: 120,
+          },
+          {
+            label: t("검색어"),
+            name: "searchText",
+            type: SearchParamType.INPUT,
+            placeholder: t("검색어를 입력하세요"),
+          },
+        ],
+      },
+
+      // 줄바꿈
+      null,
+
+      // 상태 다중 선택 + 사용여부
+      {
+        label: t("주문상태"),
+        name: "ordSttusTpcds",
+        type: SearchParamType.SELECT_MULTI,
+        width: 200,
+        options: ORD_STTUS_TPCD?.options ?? [],
+        checkAllItem: true,
+      },
+      {
+        label: t("사용여부"),
+        name: "useYn",
+        type: SearchParamType.RADIO,
+        options: [
+          { label: t("전체"), value: "" },
+          { label: t("Y"), value: "Y" },
+          { label: t("N"), value: "N" },
+        ],
+      },
+
+      // 줄바꿈
+      null,
+
+      // 기간구분 + 날짜 범위 (단일 달력)
+      {
+        type: SearchParamType.GROUP,
+        children: [
+          {
+            label: t("기간구분"),
+            name: "periodType",
+            type: SearchParamType.SELECT,
+            options: [
+              { label: t("주문일"), value: "01" },
+              { label: t("결제일"), value: "02" },
+            ],
+            width: 120,
+          },
+          {
+            label: t("기간"),
+            name: "dateRange",
+            type: SearchParamType.DTPICKER_DATE_RANGE,
+            format: DT_FORMAT.DATE,
+            presetRender: DtPickerPresetRender({ type: "all" }),
+          },
+        ],
+      },
+
+      // 줄바꿈
+      null,
+
+      // 숫자 범위
+      {
+        label: t("구매금액"),
+        placeholder: [t("최소금액"), t("최대금액")],
+        name: "purchaseAmount",
+        type: SearchParamType.NUMBER_RANGE,
+      },
+    ]}
+    paramsValue={listRequestValue}
+    onChangeParamsValue={setListRequestValue}
+    onSearch={handleSearch}
+    spinning={listSpinning}
+  />
+}
+```
+
+---
+
+## 다국어 지원 (i18n)
+
+모든 라벨은 `t()` 함수로 감싸서 다국어를 지원해야 합니다.
+
+### 라벨 형식
+
+```tsx
+// 기본 형식
+label: t("라벨 텍스트")
+
+// 예시
+{ label: t("회원명"), name: 'usrNm' }
+{ label: t("사용여부"), name: 'useYn' }
+{ label: t("가입일자"), name: 'joinDt' }
+```
+
+### useI18n 훅
+
+```tsx
+import { useI18n } from "hooks";
+
+function App() {
+  // 화면별 네임스페이스
+  const { t } = useI18n("_memberList");
+  // 또는
+  const { t } = useI18n("_productCategory");
+}
+```
+
+### 네임스페이스 규칙
+
+| 화면 | 네임스페이스 | 예시 |
+|------|-------------|------|
+| 회원 관리 | `_memberList` | `t("회원명")` |
+| 상품 관리 | `_productList` | `t("상품명")` |
+| 주문 관리 | `_orderList` | `t("주문번호")` |
+
+---
+
+## 줄바꿈 방식
+
+| 방식 | 설명 | 코드 |
+|------|------|------|
+| `null` | 줄바꿈 | params 배열에 `null` 추가 |
+| `lineBreak: true` | 명시적 줄바꿈 | params 옵션에 설정 |
+
+---
+
+## 개선 계획 (v2)
+
+### 변경 사항
+
+1. **`outPath` 필수화**: 출력 파일 경로를 입력으로 추가
+2. **Repository 분석 제거**: `dtoPath`와 `outPath`를 필수로 처리
+3. **처리 흐름 간소화**: 1,2단계를 DTO 직접 분석으로 대체
+
+### 변경된 입력
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `dtoPath` | string | ✅ | Request DTO 파일 경로 (절대 경로) |
+| `outPath` | string | ✅ | 출력 SearchParams 파일 경로 (절대 경로) |
+
+### 변경된 처리 흐름
+
+```
+[기존]                        [변경 후]
+─────────────                 ─────────────
+1. Repository의 List API
+   메서드 찾기           →     (제거)
+2. Request 타입 분석     →     1. DTO 파일 분석 → 필드 목록 추출
+   → 필드 목록 추출
+3. 연동 설정 (선택)      →     2. 연동 설정 (선택)
+4. 필드별 패턴 선택      →     3. 필드별 패턴 선택 (대화형)
+   (대화형)
+5. 그룹핑 설정          →     4. 그룹핑 설정
+6. 기본값 설정          →     5. 기본값 설정
+7. 코드 생성            →     6. SearchParams JSX 코드를 outPath로 파일 생성
+```
+
+### 구현 포인트
+
+1. **DTO 파일 분석**
+   - `analyze.ts`의 `extractRequestFields()` 함수 재사용
+   - DTO 파일을 직접 읽어서 필드 목록 추출
+
+2. **출력 파일 생성**
+   - `outPath` 경로로 JSX 코드를 파일로 직접 생성
+   - 기존 `generate-search-params.ts`의 코드 생성 로직 활용
+
+3. **MCP 도구 스키마 변경**
+   ```typescript
+   {
+     name: 'generate_search_params_interactive',
+     description: 'DTO를 기반으로 SearchParams를 대화형으로 생성',
+     inputSchema: {
+       type: 'object',
+       properties: {
+         dtoPath: {
+           type: 'string',
+           description: 'Request DTO 파일 경로 (절대 경로)',
+         },
+         outPath: {
+           type: 'string',
+           description: '출력 SearchParams 파일 경로 (절대 경로)',
+         },
+       },
+       required: ['dtoPath', 'outPath'],
+     },
+   }
+   ```
+
+### 핸들러 파일 구조
+
+```typescript
+// src/handlers/generate-search-params-interactive.ts
+
+export interface GenerateSearchParamsInteractiveParams {
+  dtoPath: string;      // Request DTO 파일 경로
+  outPath: string;      // 출력 파일 경로
+}
+
+export async function generateSearchParamsInteractive(
+  params: GenerateSearchParamsInteractiveParams
+): Promise<{ content: Array<{ type: string; text: string }> }> {
+  // 1. DTO 파일 읽기 및 필드 분석
+  const fields = await extractRequestFieldsFromDto(params.dtoPath);
+
+  // 2. 대화형으로 필드별 패턴 선택 (현재는 JSON 응답, 향후 true 대화형)
+  const selections = await promptFieldSelections(fields);
+
+  // 3. SearchParams JSX 코드 생성
+  const jsxCodes = generateSearchParamsJsx(selections);
+
+  // 4. outPath로 파일 쓰기
+  await fs.writeFile(params.outPath, jsxCodes, 'utf-8');
+
+  return { content: [{ type: 'text', text: '생성 완료' }] };
+}
+```
+
+### 활용 예시
+
+```typescript
+// MCP 호출 예시
+mcpAxboot.generateSearchParamsInteractive({
+  dtoPath: '/path/to/dto/MemberListReq.ts',
+  outPath: '/path/to/src/pages/resources/NH/member.list/App.tsx',
+});
+```
+
+### App.tsx 파일 삽입 위치
+
+검색 영역 코드는 `<PageSearchBar>` 컴포넌트 내부에 삽입됩니다.
+
+#### NH 프로젝트 App.tsx 구조
+
+```tsx
+<Container stretch role={"page-container"}>
+  <Header>
+    <ProgramTitle>...</ProgramTitle>
+
+    {/* 검색 버튼 영역 */}
+    <Flex align={"center"} gap={6}>
+      <Button onClick={handleSearch}>{t("btn.검색")}</Button>
+    </Flex>
+
+    {/* 👇 SearchParams 삽입 위치 (PageSearchBar 내부) */}
+    <PageSearchBar>
+      <SearchParams
+        form={searchForm}
+        params={[/* 생성된 params 배열 */}
+        ]}
+        paramsValue={listRequestValue}
+        onChangeParamsValue={(value, changedValues) => setListRequestValue(value, changedValues)}
+        onSearch={handleSearch}
+        spinning={listSpinning}
+      />
+    </PageSearchBar>
+  </Header>
+
+  <Body ref={resizerContainerRef}>
+    <Frame>
+      <ListDataGrid />
+    </Frame>
+  </Body>
+</Container>
+```
+
+#### 파일 처리 로직
+
+1. **파일 존재 시**
+   - `<PageSearchBar>` 태그를 찾아 내부에 SearchParams를 삽입
+   - 기존 SearchParams가 있으면 교체
+
+2. **파일 없는 경우**
+   - 기본 App.tsx 템플릿으로 파일 생성
+   - `<PageSearchBar>` 내부에 SearchParams 포함
+
+#### 삽입 예시
+
+```tsx
+// 기존 파일에서 PageSearchBar를 찾아 내부에 삽입
+<PageSearchBar>
+  <SearchParams
+    form={searchForm}
+    params={[
+      // DTO에서 추출한 필드 기반으로 생성된 params
+      { label: t("회원명"), name: "usrNm", type: SearchParamType.INPUT },
+      { label: t("사용여부"), name: "useYn", type: SearchParamType.RADIO, ... },
+      // ...
+    ]}
+    paramsValue={listRequestValue}
+    onChangeParamsValue={(value, changedValues) => setListRequestValue(value, changedValues)}
+    onSearch={handleSearch}
+    spinning={listSpinning}
+  />
+</PageSearchBar>
+```
+
+#### 필요한 styled 컴포넌트
+
+파일 생성 시 필요한 styled 컴포넌트:
+
+```tsx
+const Container = styled(PageLayout)``;
+const Header = styled(PageLayout.Header)``;
+const PageSearchBar = styled(PageLayout.PageSearchBar)``; // 필수
+const Body = styled(PageLayout.FrameRow)``;
+const Frame = styled(PageLayout.FrameColumn)``;
+```
+
+---
+
+## 사전 수집 MCP 툴 계획
+
+SearchParams 생성 전, 프로젝트의 메타데이터를 수집하는 별도 MCP 툴을 제공합니다.
+
+### 개요
+
+| 툴 | 목적 |
+|-----|------|
+| **SCAN 툴** | 프로젝트 메타데이터 수집 (DTO, Repository API, 모달 함수, 서비스, 훅, 코드) |
+| **GENERATE 툴** | 수집된 메타데이터 기반으로 SearchParams 대화형 생성 |
+
+### SCAN 툴: 메타데이터 수집
+
+#### 수집 항목
+
+| 항목 | 설명 | 사용처 |
+|------|------|--------|
+| **DTO 필드** | Request/Response DTO의 모든 필드 | 필드 목록 자동 완성 |
+| **Repository API** | Repository 인터페이스의 메서드 시그니처 | API 연동 패턴 |
+| **모달 함수** | `openXxxModal()` 형태의 함수 | MODAL 타입 검색 |
+| **서비스** | API 서비스 메서드 | AUTOCOMPLETE 타입 |
+| **훅** | 계층 데이터 훅 | CASCADE 타입 |
+| **코드** | Code Store의 코드 변수명 | SELECT, CHECKBOX 옵션 |
+
+#### 수집 경로 (고정 패턴)
+
+```typescript
+const SCAN_PATTERNS = {
+  // DTO (1순위)
+  dto: [
+    'src/services/@interface/dto/**/*.ts',        // DTO 전용 폴더
+    'src/services/**/dto/**/*.ts',               // 서비스 하위 DTO
+    'src/types/**/*Dto*.ts',                     // Types 폴더 DTO
+    'src/interfaces/**/*Request*.ts',            // Request 인터페이스
+    'src/interfaces/**/*Response*.ts',           // Response 인터페이스
+  ],
+
+  // Repository
+  repository: [
+    'src/services/**/*Repository.ts',
+    'src/services/**/repository/*.ts',
+  ],
+
+  // 모달
+  modal: [
+    'src/modals/**/*Modal.ts',
+    'src/components/**/*Modal.ts',
+  ],
+
+  // 서비스
+  service: [
+    'src/services/**/*.ts',
+  ],
+
+  // 훅
+  hook: [
+    'src/hooks/**/*.ts',
+    'src/hooks/**/*Cascade*.ts',                 // 계층 데이터 훅
+  ],
+};
+```
+
+#### DTO 스캔: 경로 패턴 기반 전체 스캔
+
+**DTO 파일이 여기저기 산재해 있어도, 전체를 스캔하여 인덱싱합니다.**
+
+##### 스캔 경로 패턴 (고정)
+
+```typescript
+const DTO_PATTERNS = [
+  'src/services/@interface/dto/**/*.ts',        // 1순위: DTO 전용 폴더
+  'src/services/**/dto/**/*.ts',               // 2순위: 서비스 하위 DTO
+  'src/types/**/*Dto*.ts',                     // 3순위: Types 폴더
+  'src/interfaces/**/*Request*.ts',            // 4순위: Request 인터페이스
+  'src/interfaces/**/*Response*.ts',           // 5순위: Response 인터페이스
+];
+```
+
+##### 추출 정보
+
+```typescript
+interface DtoIndex {
+  // 인터페이스 기본 정보
+  name: string;              // 인터페이스 명 (예: MemberListRequest)
+  filePath: string;          // 파일 경로 (절대 경로)
+  isExport: boolean;         // export 여부
+
+  // 상속 정보 (체인 추적 지원)
+  extends?: string[];        // 상속받은 인터페이스 배열 (순서 중요!)
+                            // 예: ["DefaultDto", "MemberSearch"]
+
+  // 필드 목록 (extends 체인을 모두 포함한 필드)
+  fields: DtoField[];
+}
+
+interface DtoField {
+  name: string;              // 필드명 (예: usrNm)
+  type: string;              // 타입 (예: string, number, boolean)
+  isOptional: boolean;       // 선택적 여부 (?:)
+  comment?: string;          // 주석 (있는 경우)
+  source?: string;           // 필드가 정의된 위치 (예: "MemberSearch", "DefaultDto")
+}
+```
+
+##### extends 체인 추적 (중요!)
+
+**실제 프로젝트에서는 Repository 인터페이스에서 정의한 Request/Response 타입이 실제 DTO를 `extends` 합니다.**
+
+> **이미 구현됨**: `analyze_interface` MCP 툴(`src/handlers/analyze.ts`)에서 `extractRequestFields()` 함수가 이미 extends 체인 추적을 구현하고 있습니다. SearchParams 생성 시 이 기능을 활용하면 됩니다.
+
+```typescript
+// 예시: MemberInterface.ts
+export interface PostMemberListMemberRequest extends MemberSearch {
+  pageNumber?: number;
+  pageSize?: number;
+}
+
+// 예시: MemberSearch.ts (DTO)
+export interface MemberSearch extends DefaultDto {
+  usrNm?: string;
+  usrTpcd?: string;
+  // ...
+}
+
+// 예시: types/index.ts
+export interface DefaultDto {
+  __status__?: DtoItemStatus;
+  rowId?: string;
+  crtrId?: string;
+  crtrNm?: string;
+  creatDtm?: string;
+  upusrId?: string;
+  upusrNm?: string;
+  upddeDtm?: string;
+}
+```
+
+**체인 추적 알고리즘:**
+
+```typescript
+/**
+ * extends 체인을 추적하여 모든 필드를 수집합니다.
+ *
+ * 1. 인터페이스 파싱 시 extends 정보 수집
+ * 2. 재귀적으로 extends 체인을 탐색
+ * 3. 순환 참조 방지 (방문 기록)
+ * 4. 필드 중복 시 하위 클래스가 우선 (override)
+ */
+async function resolveExtendsChain(
+  interfaceName: string,
+  cache: MetadataCache,
+  visited = new Set<string>()
+): Promise<DtoIndex> {
+  // 순환 참조 방지
+  if (visited.has(interfaceName)) {
+    console.warn(`[MCP] 순환 참조 감지: ${interfaceName}`);
+    return { name: interfaceName, fields: [] };
+  }
+  visited.add(interfaceName);
+
+  // 캐시에서 현재 인터페이스查找
+  const current = cache.dtos[interfaceName];
+  if (!current) {
+    console.warn(`[MCP] 인터페이스를 찾을 수 없음: ${interfaceName}`);
+    return { name: interfaceName, fields: [] };
+  }
+
+  // 자체 필드 수집 (extends 제외)
+  const ownFields = current.fields.filter(f =>
+    !f.source?.includes('extends')
+  );
+
+  // extends 체인 처리
+  const allFields = [...ownFields];
+  const extendsChain: string[] = [];
+
+  if (current.extends && current.extends.length > 0) {
+    for (const parent of current.extends) {
+      extendsChain.push(parent);
+
+      // 재귀적으로 부모 인터페이스 처리
+      const parentDto = await resolveExtendsChain(parent, cache, visited);
+      allFields.push(...parentDto.fields);
+
+      // 부모의 extends 체인도 병합
+      if (parentDto.extends) {
+        extendsChain.push(...parentDto.extends);
+      }
+    }
+  }
+
+  // 필드 중복 제거 (하위 클래스가 우선)
+  const uniqueFields = Array.from(
+    new Map(allFields.map(f => [f.name, f])).values()
+  );
+
+  return {
+    ...current,
+    extends: [...new Set(extendsChain)], // 중복 제거
+    fields: uniqueFields,
+  };
+}
+```
+
+**스캔 시 extends 정보 수집:**
+
+```typescript
+// 인터페이스 파싱 시 extends 추출
+function parseInterfaceFile(sourceCode: string): DtoIndex[] {
+  const results: DtoIndex[] = [];
+
+  // 정규식으로 인터페이스 선언 추출
+  const interfaceRegex = /export\s+interface\s+(\w+)\s+(?:extends\s+([^{]+))?/g;
+
+  let match;
+  while ((match = interfaceRegex.exec(sourceCode)) !== null) {
+    const [, name, extendsClause] = match;
+
+    const extendsList: string[] = [];
+    if (extendsClause) {
+      // extends A, B, C → ["A", "B", "C"]
+      extendsList.push(
+        ...extendsClause.split(',').map(e => e.trim())
+      );
+    }
+
+    results.push({
+      name,
+      extends: extendsList.length > 0 ? extendsList : undefined,
+      filePath: currentFile,
+      isExport: true,
+      fields: parseFields(sourceCode, name),
+    });
+  }
+
+  return results;
+}
+```
+
+**캐시에 해결된 필드 저장:**
+
+```json
+{
+  "dtos": {
+    "PostMemberListMemberRequest": {
+      "name": "PostMemberListMemberRequest",
+      "filePath": "/Users/kyle/Desktop/nh-fe-bo/src/services/@interface/interface/MemberInterface.ts",
+      "extends": ["MemberSearch", "DefaultDto"],
+      "fields": [
+        { "name": "__status__", "type": "DtoItemStatus", "isOptional": true, "source": "DefaultDto" },
+        { "name": "rowId", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "crtrId", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "crtrNm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "creatDtm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "upusrId", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "upusrNm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "upddeDtm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "usrNm", "type": "string", "isOptional": true, "comment": "사용자명", "source": "MemberSearch" },
+        { "name": "usrTpcd", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrNo", "type": "number", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrHpNo", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrLoginId", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrSttusTpcd", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "pageNumber", "type": "number", "isOptional": true, "source": "PostMemberListMemberRequest" },
+        { "name": "pageSize", "type": "number", "isOptional": true, "source": "PostMemberListMemberRequest" }
+      ]
+    },
+    "MemberSearch": {
+      "name": "MemberSearch",
+      "filePath": "/Users/kyle/Desktop/nh-fe-bo/src/services/@interface/dto/MemberSearch.ts",
+      "extends": ["DefaultDto"],
+      "fields": [
+        { "name": "usrNm", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrTpcd", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrNo", "type": "number", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrHpNo", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrLoginId", "type": "string", "isOptional": true, "source": "MemberSearch" },
+        { "name": "usrSttusTpcd", "type": "string", "isOptional": true, "source": "MemberSearch" }
+      ]
+    },
+    "DefaultDto": {
+      "name": "DefaultDto",
+      "filePath": "/Users/kyle/Desktop/nh-fe-bo/src/services/@interface/types/index.ts",
+      "extends": undefined,
+      "fields": [
+        { "name": "__status__", "type": "DtoItemStatus", "isOptional": true, "source": "DefaultDto" },
+        { "name": "rowId", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "crtrId", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "crtrNm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "creatDtm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "upusrId", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "upusrNm", "type": "string", "isOptional": true, "source": "DefaultDto" },
+        { "name": "upddeDtm", "type": "string", "isOptional": true, "source": "DefaultDto" }
+      ]
+    }
+  }
+}
+```
+
+##### Repository와 DTO 자동 매칭
+
+```typescript
+// Repository 메서드의 Request 타입 → DTO 인덱스에서 찾기
+interface RepositoryMethod {
+  name: string;
+  requestType: string;      // 예: "PostMemberListMemberRequest"
+  responseType: string;
+}
+
+// Request 타입명으로 DTO 인덱스 검색
+// (이미 extends 체인이 해결되어 모든 필드가 포함됨)
+function findDtoByRequestType(requestType: string): DtoIndex | undefined {
+  return cache.dtos[requestType];
+}
+
+// 예: MemberRepository.postMemberListMember(PostMemberListMemberRequest)
+// ↓
+// cache.dtos["PostMemberListMemberRequest"] → extends 체인이 해결된 필드 목록 제공
+// ↓
+// fields: [__status__, rowId, ..., usrNm, usrTpcd, ..., pageNumber, pageSize]
+//       (DefaultDto 포함)   (MemberSearch 포함)   (자체 필드)
+```
+
+**Repository 스캔 시 Request 타입 추출:**
+
+```typescript
+// Repository 파일 파싱
+function parseRepositoryFile(sourceCode: string): RepositoryInfo {
+  const methods: RepositoryMethod[] = [];
+
+  // 메서드 시그니처 추출
+  // 예: async postMemberListMember(params: PostMemberListMemberRequest, config?: ApiRequestConfig)
+  const methodRegex = /async\s+(\w+)\([^)]*:\s*(\w+Request)[^)]*\)/g;
+
+  let match;
+  while ((match = methodRegex.exec(sourceCode)) !== null) {
+    const [, methodName, requestType] = match;
+
+    // Response 타입도 추출 (선택)
+    const responseMatch = sourceCode.match(
+      new RegExp(`${methodName}[^{]*{[^}]*_apiWrapper<(${methodName}Response)>`)
+    );
+    const responseType = responseMatch?.[1];
+
+    methods.push({
+      name: methodName,
+      requestType,
+      responseType,
+    });
+  }
+
+  return {
+    name: repositoryName,
+    filePath,
+    methods,
+  };
+}
+```
+
+#### 캐시 저장 위치
+
+```
+프젝트 루트/
+├── .mcp-cache/
+│   ├── search-params-meta.json         # 전체 메타데이터
+│   ├── .gitignore                      # (git에 커밋 안됨)
+│   └── README.md                       # 캐시 폴더 설명
+├── src/
+└── package.json
+```
+
+#### .gitignore
+
+```
+# MCP Cache
+.mcp-cache/
+```
+
+### GENERATE 툴: SearchParams 대화형 생성
+
+#### 입력 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `outPath` | string | ✅ | 출력 SearchParams 파일 경로 (절대 경로) |
+| `dtoName` | string | ❌ | Request DTO 명 (선택 시 캐시에서 필드 목록 자동 완성) |
+
+#### 캐시 없는 경우: Fail-safe 자동 스캔
+
+```typescript
+// GENERATE 툴 실행 시 캐시 확인
+async function generateSearchParams(params: GenerateParams) {
+  const cache = await loadCache();
+
+  if (!cache || isCacheStale(cache)) {
+    // 캐시 없음 or 오래됨 → 백그라운드 자동 스캔
+    console.log('[MCP] 캐시 없음. 백그라운드에서 DTO 스캔을 시작합니다...');
+
+    const newCache = await scanProjectMetadata();
+    await saveCache(newCache);
+
+    return newCache;
+  }
+
+  return cache;
+}
+```
+
+#### 대화형 필드 선택 (캐시 기반)
+
+```
+[MCP] MemberListRequest DTO에서 6개 필드를 발견했습니다.
+      (캐시: 2024-01-15 10:30:00)
+
+┌─────────────────────────────────────────────┐
+│ 1. usrNm (회원명) - string, optional       │
+│ 2. usrEmailAddr (이메일) - string, optional│
+│ 3. useYn (사용여부) - 'Y'|'N'|''           │
+│ 4. statusCd (상태코드) - string, optional  │
+│ 5. pageNumber (페이지번호) - number        │
+│ 6. pageSize (페이지크기) - number          │
+└─────────────────────────────────────────────┘
+
+어떤 필드로 SearchParams를 생성할까요?
+(번호 입력, 엔터: 전체, q: 종료)
+```
+
+### 파일 감시 + 증분 스캔
+
+#### 자동 업데이트 흐름
+
+```
+1. MCP 서버 시작
+   ↓
+2. chokidar watch 시작
+   ↓
+3. DTO 파일 변경 감지
+   ↓
+4. 변경된 DTO만 재스캔 (증분 업데이트)
+   ↓
+5. 캐시 업데이트
+   ↓
+6. 다음 SearchParams 생성 시 최신 캐시 사용
+```
+
+#### watch 대상
+
+```typescript
+const WATCH_PATTERNS = [
+  'src/services/@interface/dto/**/*.ts',
+  'src/services/**/*Repository.ts',
+  'src/modals/**/*Modal.ts',
+];
+```
+
+#### 증분 업데이트
+
+```typescript
+// 변경된 파일만 재스캔
+watcher.on('change', (filePath) => {
+  if (filePath.includes('/dto/')) {
+    // DTO 변경: 해당 DTO만 재스캔
+    const dto = await scanSingleDto(filePath);
+    cache.dtos[dto.name] = dto;
+    await saveCache(cache);
+  }
+
+  if (filePath.includes('Repository.ts')) {
+    // Repository 변경: 해당 Repository만 재스캔
+    const repo = await scanSingleRepository(filePath);
+    cache.repositories[repo.name] = repo;
+    await saveCache(cache);
+  }
+});
+```
+
+### 장점
+
+| 장점 | 설명 |
+|------|------|
+| **누락 방지** | 전체 DTO를 스캔하여 Request 타입 누락 없음 |
+| **위치 독립적** | DTO가 어디에 있든 상관없이 자동 발견 |
+| **Repository 연동** | Repository 메서드 시그니처와 DTO 자동 매칭 |
+| **빠른 대화형** | 캐시된 데이터로 즉시 필드 선택 가능 |
+| **자동 업데이트** | 파일 감시로 최신 상태 유지 |
+| **Fail-safe** | 캐시 없으면 백그라운드 자동 스캔 |
+
+### MCP 툴 스키마
+
+#### SCAN 툴
+
+```typescript
+{
+  name: 'scan_search_params_metadata',
+  description: 'SearchParams 생성을 위한 프로젝트 메타데이터 수집',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      projectRoot: {
+        type: 'string',
+        description: '프로젝트 루트 경로 (절대 경로)',
+      },
+      forceRescan: {
+        type: 'boolean',
+        description: '강제 재스캔 여부',
+      },
+    },
+    required: ['projectRoot'],
+  },
+}
+```
+
+#### GENERATE 툴
+
+```typescript
+{
+  name: 'generate_search_params_interactive',
+  description: 'SearchParams를 대화형으로 생성 (캐시 기반)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      outPath: {
+        type: 'string',
+        description: '출력 SearchParams 파일 경로 (절대 경로)',
+      },
+      dtoName: {
+        type: 'string',
+        description: 'Request DTO 명 (선택 시 캐시에서 필드 목록 자동 완성)',
+      },
+    },
+    required: ['outPath'],
+  },
+}
+```
+```