# 문서 충분성 리뷰 — File Time Search MCP (for AI Agent)
이 문서는 현재 `docs/`에 있는 PRD/가이드/런북을 기준으로, **다른 AI Agent가 추가 질문 없이 구현을 완료할 수 있는지**를 상세 점검한 결과입니다.
결론 요약:
- **요구사항/계약(what)**은 충분히 정의되어 있어 구현 착수는 가능합니다.
- 다만 **운영 정책(allowRoots 제공 방식), glob 라이브러리 선택, cursor 포맷(opaque지만 내부 규칙), 스캔 제한 도달 시 동작** 등은 “팀/프로젝트 결정”이 필요하며, 이를 고정하지 않으면 구현체 간 동작이 달라질 수 있습니다.
---
## 1) 현재 문서 세트가 커버하는 것(충분한 부분)
### 1.1 제품 요구사항(기능/수용 기준)
- 파일 시간 기준(`modified`/`created`) 검색, 기간 필터(`from` inclusive / `to` exclusive), glob/recursive/limit/sort, 루트 경계 보안 등 핵심 요구사항이 명확합니다.
- 수용 기준(AC-01~AC-06)이 있어 구현 완료 여부를 판단할 수 있습니다.
참조:
- PRD 본문: [PRD-FileTimeSearch-MCP.md](PRD-FileTimeSearch-MCP.md)
### 1.2 MCP Tools 계약(입력/출력/에러)
- 도구명 `fs.search_by_time` 및 inputSchema/outputSchema가 구체적으로 정의되어 있습니다.
- **프로토콜 에러 vs tool 실행 에러(`isError=true`)**의 구분이 명확합니다.
- `structuredContent` + `content`(JSON 문자열) 병행 반환 원칙이 문서화되어 있습니다.
참조:
- API 계약: [PRD-API.md](PRD-API.md)
### 1.3 플랫폼 주의사항/보안/성능 고려
- `created/birth time`의 플랫폼 차이와 `includeUnknownTime` 정책이 정리되어 있습니다.
- allowed roots, 경로 정규화, 심볼릭 링크/리파스 포인트 등 보안 이슈가 인지되어 있습니다.
- 스캔 제한(파일/디렉터리/시간) 권장값이 제시되어 있습니다.
참조:
- 구현 노트: [PRD-ImplementationNotes.md](PRD-ImplementationNotes.md)
### 1.4 테스트 관점(무엇을 검증해야 하는가)
- 기본 동작/경계/필터/보안/스키마 호환 테스트가 케이스 단위로 정리되어 있습니다.
참조:
- 테스트 플랜: [PRD-TestPlan.md](PRD-TestPlan.md)
### 1.5 TypeScript 진행 가이드(실행/Inspector)
- TypeScript SDK 기반 실행 흐름(stdio, Streamable HTTP, Inspector)과 주요 함정(stdout 로깅 금지)이 정리되어 있습니다.
참조:
- TS 가이드: [TS-Project-Guide.md](TS-Project-Guide.md)
- TS 런북: [TS-Runbook.md](TS-Runbook.md)
- TS 구현 Plan: [TS-Implementation-Plan.md](TS-Implementation-Plan.md)
---
## 2) “구현이 갈릴 수 있는” 모호/미결정 사항(결정 필요)
아래 항목은 문서가 틀린 게 아니라, **정책을 고정하지 않으면 구현체가 달라질 수 있는 지점**입니다.
### 2.1 `root` 기본값과 allowRoots 공급 방식
- PRD-API는 `root`를 생략 가능으로 두고 “기본 루트 사용”이라고만 되어 있습니다.
- 하지만 실제 구현은 다음 중 하나로 고정해야 합니다.
- (A) 환경변수 `ALLOW_ROOTS` 같은 방식
- (B) 실행 인자 `--allow-root <path>` 반복
- (C) 설정 파일(`config.json`) 경로
- (D) 하드코딩(개발용만)
권장(에이전트 친화):
- stdio 기준으로 `ALLOW_ROOTS`(세미콜론/쉼표 구분) + `DEFAULT_ROOT` 조합을 문서/코드로 고정.
### 2.2 `path`의 정규화/표준화 규칙
inputSchema에 `path`는 “root 하위 상대경로”로 정의되어 있으나, 다음을 명시적으로 결정해야 합니다.
- 슬래시/역슬래시 허용 여부(Windows)
- 빈 문자열 vs `.` 처리
- `path`가 절대경로로 들어왔을 때 처리(거부/정규화/루트로 강제)
권장:
- `path`는 **반드시 상대경로**로 강제하고, 절대경로 입력은 `isError=true`로 거부.
### 2.3 결과의 `matches[].path`가 상대/절대 중 무엇인지
PRD-FileTimeSearch-MCP.md에서 “상대/절대(서버 정책)”이라 되어 있어 선택지가 열려 있습니다.
- 에이전트/클라이언트 관점에서는 **root 기준 상대경로**가 보통 더 안전합니다(루트 경로 노출 최소화).
권장:
- `matches[].path`는 `root` 기준 상대경로로 고정.
- 필요하면 `root`를 별도 필드로 포함(현재 outputSchema에는 없음)하거나, 텍스트 설명으로만 제공.
### 2.4 glob 처리 엔진/호환성
- PRD는 glob 문자열만 정의하고 엔진은 미정입니다.
- 구현체가 Node 표준만으로 처리하면 `**` 같은 패턴에서 기대와 다를 수 있습니다.
권장:
- `fast-glob`(또는 동급)을 의존성으로 채택하고, 문서에 glob 문법 링크/차이를 명시.
### 2.5 스캔 제한 도달 시 동작(부분 결과 vs 에러)
PRD-ImplementationNotes.md에 “부분 결과 + nextCursor 또는 isError” 두 가지 옵션이 제시되어 있습니다.
- 이 선택이 구현/테스트/사용자 경험에 큰 영향을 줍니다.
권장:
- v0: **부분 결과 반환 + nextCursor 제공**을 우선(에이전트가 이어서 호출 가능)
- 단, timeouts/limits로 인해 정렬 안정성이 깨질 수 있으면 `isError=true`로 전환
### 2.6 `from/to` 입력 타입(ISO만? epoch도?)
- PRD-API는 ISO date-time만을 계약으로 정의합니다.
- TS 가이드는 epoch ms 가능성을 언급합니다.
권장:
- v0에서는 PRD-API대로 **ISO date-time만 허용**(명확한 계약 유지)
- epoch ms 지원은 v1 옵션으로 문서에 분리
### 2.7 `sort=path_asc`의 의미
- `sort`에 `path_asc`가 존재합니다.
- 이 경우 cursor 기준을 `(path)`로만 둘지, `(path,time)`를 포함할지 결정이 필요합니다.
권장:
- 모든 sort에서 안정성을 위해 tie-breaker를 포함:
- `time_desc`/`time_asc`: `(time, path)`
- `path_asc`: `(path, time)`
---
## 3) 빠진 정보(있으면 더 빠른 구현/검증 가능)
아래는 “없어도 구현은 가능”하지만, 있으면 AI Agent가 더 정확하게 구현할 수 있는 보완 항목입니다.
### 3.1 예시 입출력 더 추가
- `cursor`가 있는 예시(두 페이지 이상)
- `includeUnknownTime=true`일 때 `createdAt=null` 예시
- `includeDirectories=true` 예시
### 3.2 운영 기본값 테이블
다음 기본값을 문서로 고정하면 구현이 흔들리지 않습니다.
- `defaultLimit`, `maxLimit`
- `defaultRecursive`
- `defaultIncludeDirectories`
- `defaultIncludeUnknownTime`
- `maxFilesScanned`, `maxDirectoriesScanned`, `timeoutMs`
### 3.3 에러 메시지 표준화
- `isError=true`일 때 메시지 템플릿(에러 코드/문구) 표준을 정의하면 회귀 테스트가 쉬워집니다.
- 예: `InvalidRange`, `RootNotAllowed`, `PathTraversalDetected`, `CursorInvalid`, `ScanLimitExceeded` 등
---
## 4) 다른 AI Agent에게 “바로 실행 가능한” 체크리스트
### 4.1 착수 전 결정(필수 5개)
- [ ] allowRoots를 어떻게 입력받는가(ENV/args/config)
- [ ] 결과 path를 상대/절대 중 무엇으로 반환하는가
- [ ] glob 라이브러리/문법을 무엇으로 고정할 것인가
- [ ] 제한 도달 시 정책(부분 결과 vs isError)
- [ ] from/to는 ISO만 허용할 것인가
### 4.2 구현 완료 판정(최소)
- [ ] [PRD-TestPlan.md](PRD-TestPlan.md)의 TC-01~TC-13 통과
- [ ] TC-30~TC-32(경로/루트/링크) 방어 확인
- [ ] 성공 결과에 `structuredContent` + `content`(JSON 포함) 존재
---
## 5) 종합 판단
현 상태 문서만으로도:
- “기능과 계약을 구현한다” 수준의 작업은 충분히 가능합니다.
다만 위 2장(미결정 사항)을 고정하지 않으면:
- 다른 에이전트가 구현해도 “동작이 약간 다른” 결과가 나올 수 있고,
- 테스트 플랜을 자동화할 때 기준점이 흔들릴 수 있습니다.
따라서 다음 액션을 권장합니다.
1) 2장의 미결정 5개를 v0 정책으로 고정
2) 그 정책을 PRD-API 또는 TS-Implementation-Plan에 짧게 반영
3) 이후 코드 스캐폴딩/구현으로 진행
