# PRD — File Time Search MCP
## 1. 배경
AI Agent(호스트/클라이언트)가 로컬 파일 시스템에서 **최근 수정일** 또는 **생성일**을 기준으로 파일을 검색할 수 있으면,
- “최근에 수정한 설정 파일 찾아줘”
- “지난주에 만든 문서만 모아줘”
같은 요청을 빠르고 신뢰성 있게 처리할 수 있습니다.
본 문서는 MCP(Model Context Protocol) 서버로 해당 기능을 제공하는 제품 요구사항(PRD)을 정의합니다.
## 2. 목표(Goals)
- 지정된 루트(허용된 경로) 내부에서 파일을 **mtime(최근 수정 시각)** 또는 **생성 시각** 기준으로 검색할 수 있다.
- 날짜 범위(시작/끝) 기반 필터링을 제공한다.
- 검색 결과를 기계가 읽기 쉬운 **structuredContent**로 반환하고, 동일 내용을 사람이 읽을 수 있는 텍스트로도 제공한다.
- 안전한 기본값(권한·경계·로깅·타임아웃)에 기반해 AI Agent 환경에서 동작한다.
## 3. 비목표(Non-Goals)
- 파일 내용(content) 검색(전문 검색, 인덱싱)은 범위 밖이다.
- 파일 수정/삭제/이동 같은 파괴적 작업은 범위 밖이다.
- 네트워크 공유/원격 파일시스템 최적화는 범위 밖이다.
## 4. 사용자 및 사용 시나리오
### 4.1 사용자
- MCP Host(예: IDE/Agent 런타임)
- LLM 기반 Agent(도구 호출을 통해 파일 타임라인 탐색)
### 4.2 주요 시나리오
- “최근 24시간 내 수정된 *.md 파일 목록 보여줘”
- “2025-12-01~2025-12-15 사이에 만든 파일만 찾아줘”
- “특정 폴더(루트 하위)에서 최근 수정된 순으로 50개만”
## 5. 제품 범위
### 5.1 제공 기능(Functional Requirements)
- FR-01: 시간 기준 선택
- `modified`(mtime)
- `created`(생성/birth time)
- FR-02: 기간 필터
- `from`(inclusive), `to`(exclusive) 기준의 범위 검색
- FR-03: 경로 범위 제한
- 서버는 **허용된 루트 경로(allowed roots)** 밖을 절대로 탐색하면 안 된다.
- FR-04: 필터
- 파일/디렉터리 포함 여부
- glob 패턴 필터(예: `**/*.md`)
- FR-05: 정렬 및 페이징
- 시간 기준 오름차순/내림차순 정렬
- `limit` 및 `cursor`를 통한 페이지네이션
- FR-06: 결과 메타데이터
- 각 결과 항목에 대해 최소:
- 상대/절대 경로(서버 정책에 따라)
- `modifiedAt`(ISO 8601)
- `createdAt`(가능 시)
- `isDirectory`
### 5.2 비기능 요구사항(Non-Functional Requirements)
- NFR-01 보안
- 입력 검증(경로 traversal 방지, 루트 이탈 방지)
- 결과 최소화(필요 이상의 정보 노출 방지)
- 요청량 제한(최대 depth/최대 결과/최대 스캔 수 등)
- NFR-02 신뢰성
- 잘못된 입력은 명확한 에러 메시지로 반환한다.
- 생성 시간이 OS/FS에서 지원되지 않는 경우를 명시적으로 처리한다.
- NFR-03 성능
- 대규모 트리에서도 안전하게 동작(최대 스캔 수, 타임아웃, 취소 지원)
- NFR-04 로깅
- STDIO 기반 서버는 stdout을 오염시키지 않도록 **로그를 stderr 또는 파일로만 출력**한다.
## 6. 제약 및 가정
- 본 워크스페이스 OS는 Windows이지만, PRD는 가능한 범위에서 크로스플랫폼도 고려한다.
- “생성 시간(created/birth time)”은 Windows에서는 보통 제공되지만, 일부 OS/파일시스템에서는 제공되지 않을 수 있다.
## 7. 안전/권한 모델
- MCP 스펙의 권고에 따라, tool 호출은 Host 측에서 사용자 승인/제어(휴먼 인 더 루프)를 지원하는 것을 전제로 한다.
- 서버는 자체적으로도 다음을 방어해야 한다:
- 허용된 루트 밖 탐색 거부
- 심볼릭 링크/리파스 포인트 처리 정책(기본: 따라가지 않음)
## 8. 인터페이스(도구)
- MCP Tools는 1개의 핵심 도구로 제공한다:
- `fs.search_by_time`
상세 스키마/예시는 [PRD-API.md](PRD-API.md)에 정의한다.
## 9. 수용 기준(Acceptance Criteria)
- AC-01: `modified` 기준 기간 검색이 정확히 동작한다.
- AC-02: `created` 기준 기간 검색이 정확히 동작한다(Windows 기준).
- AC-03: 허용 루트 밖 요청은 반드시 거부한다.
- AC-04: 결과는 structuredContent + text를 함께 제공한다.
- AC-05: `limit/cursor`로 페이지네이션이 동작한다.
- AC-06: 표준 오류는 MCP 프로토콜 에러 vs tool 실행 에러(`isError=true`) 규칙을 따른다.
## 10. 릴리즈 단계(권장)
- v0 (MVP)
- `fs.search_by_time` 제공
- mtime/created 필터, glob, recursive, limit, sort
- v1
- 성능/안전 강화(최대 스캔 수/타임아웃/취소/진행률)
- 선택적 outputSchema 기반 structuredContent 검증
