# TypeScript 구현 Plan — File Time Search MCP
이 문서는 [PRD-FileTimeSearch-MCP.md](PRD-FileTimeSearch-MCP.md), [PRD-API.md](PRD-API.md), [PRD-ImplementationNotes.md](PRD-ImplementationNotes.md), [PRD-TestPlan.md](PRD-TestPlan.md)를 기준으로 **TypeScript** 구현을 끝까지 완료하기 위한 실행 계획입니다.
범위: MCP Server(도구 `fs.search_by_time`) 구현 + 로컬 실행(stdio) + 선택적 Streamable HTTP + Inspector 검증 + 최소 테스트.
---
## 0) 결정 사항(고정)
- 언어/런타임: Node.js + TypeScript
- MCP SDK: `@modelcontextprotocol/sdk` + `zod`
- 도구명: `fs.search_by_time`
- 핵심 기능: 지정 루트 하위에서 `modified` 또는 `created` 시간 기준으로 파일 목록 검색
- 반환: `structuredContent` + 동일 내용을 `content.text`에 JSON 문자열로 동시 제공
---
## 1) Milestone A — 프로젝트 스캐폴딩(0.5~1일)
**목표**: 빌드/실행 가능하고, MCP 서버가 “빈 tool”이라도 뜨는 상태.
**작업**
- [x] `package.json`/`tsconfig.json` 구성
- [x] 의존성 설치: `@modelcontextprotocol/sdk`, `zod`, dev deps(`typescript`, `tsx`, `@types/node`)
- [x] `src/stdio.ts` (stdio 엔트리) 생성
- [x] `src/index.ts`에서 `createServer()` 제공(공통)
**완료 기준**
- [x] `npm run dev:stdio` 실행 시 프로세스가 정상 유지
- [x] stdout 오염 없음(로그는 stderr)
---
## 2) Milestone B — 도구 스키마/계약 정리(0.5일)
**목표**: [PRD-API.md](PRD-API.md)의 입력/출력 스키마를 TypeScript에서 일관되게 재현.
**작업**
- [x] `src/tools/searchByTime/schema.ts`
- 입력 Zod 스키마 정의(필드: `root`, `timeField`, `from`, `to`, `glob`, `recursive`, `limit`, `cursor`, `sort` 등)
- 출력 Zod 스키마 정의(검색 결과 배열 + `nextCursor` 등)
- [x] `server.registerTool('fs.search_by_time', { inputSchema, outputSchema }, handler)` 연결
**완료 기준**
- [x] Inspector에서 tool이 노출되고, 입력 폼이 스키마 기반으로 표시
---
## 3) Milestone C — 파일 시스템 스캔 코어 구현(1~2일)
**목표**: 안전하고 예측 가능한 파일 열람/시간 추출/필터링/정렬/페이지네이션.
### 3.1 경로/보안 레이어
**작업**
- [x] `src/core/config.ts`
- `allowRoots` (예: 환경변수 또는 고정 배열) 결정
- 기본 제한값(예: `defaultLimit`, `maxLimit`, `maxFilesScanned`, `timeoutMs`) 정의
- [x] `src/core/pathPolicy.ts`
- `root` 정규화(Windows 드라이브 포함)
- `allowRoots` 하위인지 검증(탈출 방지)
- 심볼릭 링크 정책(기본 follow 금지 권장)
**완료 기준**
- [x] 루트 밖 경로 요청 시 tool 에러(`isError: true`)로 거절
### 3.2 시간 추출/필터
**작업**
- [x] `src/core/fileTimes.ts`
- `mtimeMs`(수정) / `birthtimeMs`(생성) 읽기
- Windows/FS 특성에 대한 주의 메시지 문서화(이미 PRD에 있음)
- [x] `src/core/timeRange.ts`
- `from/to` 파싱(v0: ISO 8601 date-time 문자열만, [PRD-v0-Policy.md](PRD-v0-Policy.md) 준수)
- 경계 규칙 고정: `from` inclusive, `to` exclusive
**완료 기준**
- [x] `created`/`modified` 모두 동작
- [x] 잘못된 날짜/범위는 tool 에러로 안내
### 3.3 glob/재귀 스캔
**작업**
- [x] glob 처리 방식 결정
- 옵션 A: 표준 라이브러리만으로 단순 확장자/패턴 제한
- 옵션 B(권장): `fast-glob` 같은 라이브러리 사용
- [x] `recursive=false`일 때는 1-depth만
- [x] 스캔 중 권한 오류/깨진 엔트리는 “부분 스킵 + 필요 시 오류 카운트”
**완료 기준**
- [x] 대규모 폴더에서도 무한 대기 없이 종료(타임아웃/스캔 상한)
### 3.4 정렬/페이지네이션(cursor)
**작업**
- [x] 정렬 키: `(time, path)`로 안정 정렬
- [x] `src/core/cursor.ts`
- 커서에 마지막 항목의 `(time, path)`를 저장
- base64url(JSON) 인코딩/디코딩
- 커서가 깨졌으면 tool 에러로 안내
- [x] 다음 페이지는 “strictly after last” 기준으로 재개
**완료 기준**
- [x] 동일 요청을 여러 번 호출해도 페이지 경계가 안정적
---
## 4) Milestone D — Tool handler 완성(0.5~1일)
**목표**: `fs.search_by_time`가 PRD 요구를 만족하는 최종 형태로 응답.
**작업**
- [x] `src/tools/searchByTime/handler.ts`
- 입력 검증
- 검색 실행
- 결과를 outputSchema에 맞게 구성
- `content.text`에 `JSON.stringify(structuredContent)` 포함
- tool 오류는 `isError: true`로 반환
**완료 기준**
- [x] [PRD-TestPlan.md](PRD-TestPlan.md)의 기본 시나리오들이 모두 통과
---
## 5) Milestone E — 실행 모드 2종(선택)(0.5~1일)
### 5.1 stdio (필수)
- [x] `src/stdio.ts` 완성
- [x] stdout 로깅 금지 준수
### 5.2 Streamable HTTP (선택)
**결정 포인트**
- 원격 배포/서버 운영이 목표면 Streamable HTTP 추가 권장
**작업(요지)**
- [ ] `src/http.ts` 추가 (Placeholder 구현됨)
- [ ] `createMcpExpressApp()` 사용(로컬 DNS rebinding 방어 기본 포함)
- [ ] 세션별 transport 재사용 맵 구성
---
## 6) Milestone F — 테스트/검증(1일)
**목표**: 최소 단위 테스트 + 수동 Inspector 검증.
**작업**
- [x] 자동 테스트(권장): `vitest` 또는 `node:test` 중 택1
- 입력 파싱/시간 필터/정렬/커서 인코딩 단위 테스트
- Windows 경로 정규화 테스트(가능한 범위)
- [ ] 수동 테스트: MCP Inspector로 tool 호출
- Inspector 가이드: [TS-Runbook.md](TS-Runbook.md)
**완료 기준**
- [x] 정상 케이스/엣지 케이스(권한 오류/빈 결과/잘못된 입력) 모두 기대대로
---
## 7) Milestone G — 배포 준비(0.5일)
**작업**
- [x] `npm run build` 결과(`dist`)가 실행 가능
- [ ] npm 배포를 고려하면 `files`/`bin`/`exports` 정책 확정
- [x] README(루트 또는 docs)에 “Claude Desktop/Inspector 실행 방법” 요약 포함(필요 시)
---
## 8) 리스크/주의사항
- stdio transport에서는 stdout 출력이 JSON-RPC를 깨뜨립니다(로그는 stderr).
- Windows 생성 시간(`birthtime`)은 파일 작업 방식에 따라 기대와 달라질 수 있습니다.
- 대규모 디렉터리 스캔은 반드시 제한값(파일 수/시간)을 둬야 합니다.
- 심볼릭 링크/리파스 포인트로 루트 탈출 위험이 있으므로 정책을 명확히 해야 합니다.
---
## 9) 산출물 목록(최종)
- [ ] TypeScript 서버 코드
- `src/index.ts`, `src/stdio.ts`
- (선택) `src/http.ts`
- `src/tools/searchByTime/*`, `src/core/*`
- [ ] 테스트 코드(선택이지만 권장)
- [ ] 문서
- [TS-Project-Guide.md](TS-Project-Guide.md)
- [TS-Runbook.md](TS-Runbook.md)
- 본 문서: [TS-Implementation-Plan.md](TS-Implementation-Plan.md)
