@axboot-mcp/mcp-server 1.0.0

package/SEARCH_PARAMS_MCP_TOOL_COMPLETE_PLAN.md

@@ -0,0 +1,646 @@
+# SearchParams 대화형 생성 MCP 툴 완전 계획서
+
+> **목차**
+> 1. [개요](#1-개요)
+> 2. [SearchParamType 상세](#2-searchparamtype-상세)
+> 3. [패턴 카탈로그 및 대화형 설정](#3-패턴-카탈로그-및-대화형-설정)
+> 4. [메타데이터 수집 시스템](#4-메타데이터-수집-시스템)
+> 5. [MCP 툴 스키마](#5-mcp-툴-스키마)
+> 6. [코드 생성 예시](#6-코드-생성-예시)
+
+---
+
+## 1. 개요
+
+### 1.1 목적
+
+SearchParams(검색 폼) 컴포넌트를 대화형으로 생성하는 MCP 툴입니다.
+
+### 1.2 핵심 컨셉
+
+- **자연어 대화**: 사용자가 자연어로 설명하면 AI가 패턴을 추론하여 코드 생성
+- **패턴 카탈로그**: 16가지 검색 컴포넌트 패턴 제공
+- **메타데이터 기반**: 프로젝트의 DTO, Repository, Code 등을 스캔하여 자동 완성
+- **extends 체인 추적**: Repository 인터페이스의 Request 타입이 실제 DTO를 extend하는 경우 모든 필드 수집
+
+### 1.3 처리 흐름
+
+```
+1. 메타데이터 스캔 (SCAN 툴)
+   └─ DTO, Repository, Modal, Service, Hook, Code 수집
+   └─ extends 체인 추적으로 완전한 필드 수집
+   └─ .mcp-cache/에 저장
+
+2. 대화형 생성 (GENERATE 툴)
+   └─ 필드별 패턴 선택 (16가지 옵션)
+   └─ 추가 설정 (옵션, 기본값, 너비 등)
+   └─ SearchParams JSX 코드 생성
+
+3. 파일 생성
+   └─ App.tsx의 <PageSearchBar> 내부에 삽입
+```
+
+---
+
+## 2. SearchParamType 상세
+
+### 2.1 타입 목록
+
+| # | 타입 | 설명 | 빈도 |
+|---|------|------|------|
+| 1 | INPUT | 텍스트 입력 | 115회 |
+| 2 | GROUP | 검색구분 + 텍스트 | 110회 |
+| 3 | SELECT | 드롭다운 선택 | 191회 |
+| 4 | CHECKBOX | 체크박스 다중 선택 | 14회 |
+| 5 | SELECT_MULTI | 멀티 셀렉트 | 38회 |
+| 6 | RADIO | 라디오 버튼 | 127회 |
+| 7 | DTPICKER_DATE | 단일 날짜 | 1회 |
+| 8 | DTPICKER_DATE_RANGE | 날짜 범위 | 100회 |
+| 9 | NUMBER_RANGE | 숫자 범위 | 1회 |
+| 10 | AUTOCOMPLETE | 자동완성 검색 | - |
+| 11 | CASCADE | 계층 선택 | - |
+| 12 | MODAL | 모달 검색 | - |
+| 13 | CONDITIONAL | 조건부 필드 | - |
+| 14 | SKIP | 제외 | - |
+| 15 | HIDDEN | 숨김 | - |
+| 16 | LINE_BREAK | 줄바꿈 | 15회 |
+
+---
+
+## 3. 패턴 카탈로그 및 대화형 설정
+
+### 3.1 패턴 선택 메인 화면
+
+```
+[MCP] usrNm (회원명) 필드를 발견했습니다.
+      어떤 검색 컴포넌트를 사용할까요?
+
+┌─────────────────────────────────────────────────────────────────────┐
+│ 1. 🤖 AI에게 맡기기 (자연어로 설명)                                │
+├─────────────────────────────────────────────────────────────────────┤
+│ 2. 📝 일반 텍스트 입력 (INPUT)                                      │
+├─────────────────────────────────────────────────────────────────────┤
+│ 3. 🔍 검색구분 + 텍스트 (GROUP)                                    │
+├─────────────────────────────────────────────────────────────────────┤
+│ 4. 📋 드롭다운 선택 (SELECT)                                       │
+├─────────────────────────────────────────────────────────────────────┤
+│ 5. ✓ 체크박스 다중 선택 (CHECKBOX)                                 │
+├─────────────────────────────────────────────────────────────────────┤
+│ 6. ☐ 멀티 셀렉트 (SELECT_MULTI)                                   │
+├─────────────────────────────────────────────────────────────────────┤
+│ 7. ○ 라디오 버튼 (RADIO)                                           │
+├─────────────────────────────────────────────────────────────────────┤
+│ 8. 📅 단일 날짜 (DTPICKER_DATE)                                    │
+├─────────────────────────────────────────────────────────────────────┤
+│ 9. 📆 날짜 범위 (DTPICKER_DATE_RANGE)                              │
+├─────────────────────────────────────────────────────────────────────┤
+│ 10. 🔢 숫자 범위 (NUMBER_RANGE)                                    │
+├─────────────────────────────────────────────────────────────────────┤
+│ 11. ⏭️ 스킵 (SKIP)                                                 │
+├─────────────────────────────────────────────────────────────────────┤
+│ 12. 👁️ 숨김 (HIDDEN)                                              │
+├─────────────────────────────────────────────────────────────────────┤
+│ 13. 🔀 조건부 필드 (CONDITIONAL)                                   │
+├─────────────────────────────────────────────────────────────────────┤
+│ 14. 🔍 자동완성 (AUTOCOMPLETE)                                     │
+├─────────────────────────────────────────────────────────────────────┤
+│ 15. 🌊 계층 선택 (CASCADE)                                        │
+├─────────────────────────────────────────────────────────────────────┤
+│ 16. 🪟 모달 검색 (MODAL)                                          │
+└─────────────────────────────────────────────────────────────────────┘
+
+번호를 입력하세요:
+```
+
+### 3.2 INPUT (일반 텍스트)
+
+```tsx
+{
+  label: t("회원명"),
+  name: "usrNm",
+  type: SearchParamType.INPUT,
+  width: 200,
+  placeholder: t("회원명을 입력하세요"),
+}
+```
+
+### 3.3 GROUP (검색구분 + 텍스트)
+
+```tsx
+{
+  type: SearchParamType.GROUP,
+  children: [
+    {
+      label: t("검색어구분"),
+      name: "searchType",
+      type: SearchParamType.SELECT,
+      options: [
+        { label: t("제목"), value: "TITLE" },
+        { label: t("내용"), value: "CONTENT" },
+      ],
+      width: 120,
+    },
+    {
+      label: t("검색어"),
+      name: "searchText",
+      type: SearchParamType.INPUT,
+    },
+  ],
+}
+```
+
+### 3.4 SELECT (드롭다운)
+
+```tsx
+// Code Store 사용
+{
+  label: t("상태코드"),
+  name: "statusCd",
+  type: SearchParamType.SELECT,
+  codeVar: "STATUS_CD",  // useCodeStore에서 자동 추출
+  width: 150,
+}
+
+// 직접 옵션
+{
+  label: t("정렬"),
+  name: "sortType",
+  type: SearchParamType.SELECT,
+  options: [
+    { label: t("최신순"), value: "latest" },
+    { label: t("이름순"), value: "name" },
+  ],
+  width: 150,
+}
+```
+
+### 3.5 CHECKBOX (체크박스 다중)
+
+```tsx
+{
+  label: t("회원가입채널"),
+  name: "sbscrbPathClcdArr",
+  type: SearchParamType.CHECKBOX,
+  options: SBSCRB_PATH_CLCD?.options ?? [],
+  checkAllItem: true,  // "전체" 옵션 추가
+  defaultValue: ["Y", "02"],
+}
+```
+
+### 3.6 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" },
+  ],
+  initialValue: "Y",
+}
+```
+
+### 3.7 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" }),
+  defaultValue: [dayjs().subtract(30, 'day'), dayjs()],
+}
+```
+
+### 3.8 NUMBER_RANGE (숫자 범위)
+
+```tsx
+{
+  label: t("방문회수"),
+  placeholder: [t("MIN"), t("MAX")],
+  name: "visitCount",
+  type: SearchParamType.NUMBER_RANGE,
+  defaultValue: [10, 100],
+}
+```
+
+### 3.9 AUTOCOMPLETE (자동완성)
+
+```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: n,  // 전체 객체 저장
+      label: `${n.custNm} (${bizNumFormatter(n.bizNum)})`,
+    }));
+  },
+}
+```
+
+### 3.10 CASCADE (계층 선택)
+
+```tsx
+const { list: organizationOption } = useOrganizationCascadeData();
+
+{
+  placeholder: t("조직"),
+  name: "_orgCd",
+  width: 200,
+  type: SearchParamType.CASCADE,
+  options: organizationOption,
+  displayRender: (labels: string[]) => labels[labels.length - 1],
+  onSelect: (option) => {
+    setUserComboParams({ ...option });
+  },
+}
+```
+
+### 3.11 MODAL (모달 검색)
+
+```tsx
+{
+  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,
+}
+```
+
+### 3.12 CONDITIONAL (조건부 필드)
+
+```tsx
+// prdBbsRvwTpcd가 "1"일 때만 표시
+...(listRequestValue.prdBbsRvwTpcd === "1"
+  ? [{
+      label: t("상세옵션"),
+      name: "prdBbsRvwDtlTpcdArray",
+      type: SearchParamType.CHECKBOX,
+      options: PRD_BBS_RVW_DTL_TPCD?.options,
+    }]
+  : [])
+```
+
+---
+
+## 4. 메타데이터 수집 시스템
+
+### 4.1 수집 항목
+
+| 항목 | 설명 | 사용처 |
+|------|------|--------|
+| DTO 필드 | Request/Response DTO의 모든 필드 | 필드 목록 자동 완성 |
+| Repository API | Repository 인터페이스의 메서드 시그니처 | API 연동 패턴 |
+| 모달 함수 | `openXxxModal()` 형태의 함수 | MODAL 타입 |
+| 서비스 | API 서비스 메서드 | AUTOCOMPLETE 타입 |
+| 훅 | 계층 데이터 훅 | CASCADE 타입 |
+| 코드 | Code Store의 코드 변수명 | SELECT, CHECKBOX |
+
+### 4.2 extends 체인 추적 (중요!)
+
+**실제 프로젝트에서 Repository 인터페이스의 Request 타입이 실제 DTO를 `extends` 합니다.**
+
+```typescript
+// 예시 구조
+export interface PostMemberListMemberRequest extends MemberSearch {
+  pageNumber?: number;
+  pageSize?: number;
+}
+
+export interface MemberSearch extends DefaultDto {
+  usrNm?: string;
+  usrTpcd?: string;
+}
+
+export interface DefaultDto {
+  __status__?: DtoItemStatus;
+  rowId?: string;
+  crtrId?: string;
+  // ...
+}
+```
+
+**체인 추적 인터페이스:**
+
+```typescript
+interface DtoIndex {
+  name: string;              // 인터페이스 명
+  filePath: string;          // 파일 경로
+  extends?: string[];        // 상속 체인 (예: ["MemberSearch", "DefaultDto"])
+  fields: DtoField[];        // 모든 필드 (extends 포함)
+}
+
+interface DtoField {
+  name: string;              // 필드명
+  type: string;              // 타입
+  isOptional: boolean;       // optional 여부
+  comment?: string;          // 주석
+  source?: string;           // 정의 위치 (예: "MemberSearch")
+}
+```
+
+**체인 추적 알고리즘:**
+
+```typescript
+async function resolveExtendsChain(
+  interfaceName: string,
+  cache: MetadataCache,
+  visited = new Set<string>()
+): Promise<DtoIndex> {
+  if (visited.has(interfaceName)) {
+    return { name: interfaceName, fields: [] };  // 순환 참조 방지
+  }
+  visited.add(interfaceName);
+
+  const current = cache.dtos[interfaceName];
+  if (!current) return { name: interfaceName, fields: [] };
+
+  const allFields = [...current.fields];
+  const extendsChain: string[] = [];
+
+  if (current.extends) {
+    for (const parent of current.extends) {
+      extendsChain.push(parent);
+      const parentDto = await resolveExtendsChain(parent, cache, visited);
+      allFields.push(...parentDto.fields);
+    }
+  }
+
+  // 필드 중복 제거 (하위 클래스가 우선)
+  const uniqueFields = Array.from(
+    new Map(allFields.map(f => [f.name, f])).values()
+  );
+
+  return {
+    ...current,
+    extends: [...new Set(extendsChain)],
+    fields: uniqueFields,
+  };
+}
+```
+
+> **이미 구현됨**: `analyze_interface` MCP 툴(`src/handlers/analyze.ts`)의 `extractRequestFields()` 함수가 이미 extends 체인 추적을 구현하고 있습니다.
+
+### 4.3 스캔 경로 패턴
+
+```typescript
+const DTO_PATTERNS = [
+  'src/services/@interface/dto/**/*.ts',        // 1순위
+  'src/services/**/dto/**/*.ts',               // 2순위
+  'src/types/**/*Dto*.ts',                     // 3순위
+  'src/interfaces/**/*Request*.ts',            // 4순위
+  'src/interfaces/**/*Response*.ts',           // 5순위
+];
+
+const SCAN_PATTERNS = {
+  repository: ['src/services/**/*Repository.ts'],
+  modal: ['src/modals/**/*Modal.ts'],
+  service: ['src/services/**/*.ts'],
+  hook: ['src/hooks/**/*.ts'],
+};
+```
+
+### 4.4 캐시 저장 위치
+
+```
+프젝트 루트/
+├── .mcp-cache/
+│   ├── search-params-meta.json
+│   ├── .gitignore
+│   └── README.md
+├── src/
+└── package.json
+```
+
+### 4.5 캐시 구조 예시
+
+```json
+{
+  "version": "1.0.0",
+  "scannedAt": "2024-01-15T10:30:00Z",
+  "projectRoot": "/Users/kyle/Desktop/nh-fe-bo",
+  "dtos": {
+    "PostMemberListMemberRequest": {
+      "name": "PostMemberListMemberRequest",
+      "filePath": "/path/to/MemberInterface.ts",
+      "extends": ["MemberSearch", "DefaultDto"],
+      "fields": [
+        { "name": "__status__", "type": "DtoItemStatus", "source": "DefaultDto" },
+        { "name": "usrNm", "type": "string", "source": "MemberSearch" },
+        { "name": "pageNumber", "type": "number", "source": "PostMemberListMemberRequest" }
+      ]
+    }
+  },
+  "repositories": {
+    "MemberRepository": {
+      "filePath": "/path/to/MemberRepository.ts",
+      "methods": [
+        {
+          "name": "postMemberListMember",
+          "requestType": "PostMemberListMemberRequest",
+          "responseType": "PostMemberListMemberResponse"
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 5. MCP 툴 스키마
+
+### 5.1 SCAN 툴 (메타데이터 수집)
+
+```typescript
+{
+  name: 'scan_search_params_metadata',
+  description: 'SearchParams 생성을 위한 프로젝트 메타데이터 수집',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      projectRoot: {
+        type: 'string',
+        description: '프로젝트 루트 경로 (절대 경로)',
+      },
+      forceRescan: {
+        type: 'boolean',
+        description: '강제 재스캔 여부',
+      },
+    },
+    required: ['projectRoot'],
+  },
+}
+```
+
+### 5.2 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'],
+  },
+}
+```
+
+---
+
+## 6. 코드 생성 예시
+
+### 6.1 기본 예시
+
+```tsx
+<SearchParams
+  form={searchForm}
+  params={[
+    { label: t("이름"), name: 'usrNm', type: SearchParamType.INPUT },
+    { label: t("이메일"), name: 'usrEmailAddr', type: SearchParamType.INPUT },
+    null,  // 줄바꿈
+    { 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" }) },
+  ]}
+  paramsValue={listRequestValue}
+  onChangeParamsValue={setListRequestValue}
+  onSearch={handleSearch}
+  spinning={listSpinning}
+/>
+```
+
+### 6.2 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>
+      <SearchParams
+        form={searchForm}
+        params={[/* 생성된 params 배열 */]}
+        paramsValue={listRequestValue}
+        onChangeParamsValue={setListRequestValue}
+        onSearch={handleSearch}
+        spinning={listSpinning}
+      />
+    </PageSearchBar>
+  </Header>
+
+  <Body>
+    <Frame>
+      <ListDataGrid />
+    </Frame>
+  </Body>
+</Container>
+```
+
+### 6.3 필요한 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)``;
+```
+
+---
+
+## 7. 자연어 처리 규칙
+
+| 키워드 | 컴포넌트 | 예시 |
+|--------|----------|------|
+| 검색어, 텍스트, 입력 | INPUT | "이름으로 검색" |
+| 드롭다운, 셀렉트 | SELECT | "드롭다운으로" |
+| 체크박스, 다중 선택 | CHECKBOX | "여러 개 선택" |
+| 라디오, Y/N | RADIO | "사용여부 Y/N" |
+| 날짜, 일자 | DTPICKER_DATE | "가입일자" |
+| 기간, 범위 | DTPICKER_DATE_RANGE | "가입기간" |
+| 숫자 범위 | NUMBER_RANGE | "방문회수 범위" |
+| 검색구분 + 텍스트 | GROUP | "제목/내용 검색" |
+| 코드, 분류 | SELECT + codeVar | "상태코드" |
+| 필수, 필수입력 | required: true | "필수 입력" |
+| placeholder ~ | placeholder: "~" | "placeholder는 '검색어'" |
+
+---
+
+## 8. 파일 감시 및 증분 스캔
+
+```typescript
+// watch 대상
+const WATCH_PATTERNS = [
+  'src/services/@interface/dto/**/*.ts',
+  'src/services/**/*Repository.ts',
+  'src/modals/**/*Modal.ts',
+];
+
+// 증분 업데이트
+watcher.on('change', (filePath) => {
+  if (filePath.includes('/dto/')) {
+    const dto = await scanSingleDto(filePath);
+    cache.dtos[dto.name] = dto;
+    await saveCache(cache);
+  }
+});
+```
+
+---
+
+## 9. 장점
+
+| 장점 | 설명 |
+|------|------|
+| 누락 방지 | 전체 DTO를 스캔하여 Request 타입 누락 없음 |
+| 위치 독립적 | DTO가 어디에 있든 상관없이 자동 발견 |
+| Repository 연동 | Repository 메서드 시그니처와 DTO 자동 매칭 |
+| 빠른 대화형 | 캐시된 데이터로 즉시 필드 선택 가능 |
+| 자동 업데이트 | 파일 감시로 최신 상태 유지 |
+| Fail-safe | 캐시 없으면 백그라운드 자동 스캔 |