# PRD — Implementation Notes
이 문서는 PRD를 만족시키기 위한 구현 시 주의사항/결정 포인트를 정리합니다.
## 1. 생성 시간(created/birth time) 정의
- Windows(NTFS)는 일반적으로 “Creation Time”을 제공한다.
- Linux/macOS에서는 “파일 생성 시간(birth time)”이 파일시스템/커널/언어 런타임에 따라 제공되지 않을 수 있다.
### 권장 정책
- `timeField=created`인데 생성 시간이 제공되지 않는 항목은:
- 기본적으로 결과에서 제외 (`includeUnknownTime=false`)
- 옵션 `includeUnknownTime=true`일 경우 `createdAt=null`로 포함
## 2. 시간 포맷/타임존
- 입력 `from/to`는 ISO 8601 date-time(타임존 포함)을 권장한다.
- 구현은 내부적으로 UTC로 정규화 후 비교하는 것을 권장한다.
- 경계 규칙은 단순하게 유지:
- `from` inclusive
- `to` exclusive
## 3. 경로 보안(루트 경계)
- 서버는 시작 시점에 “허용 루트(allowed roots)”를 설정해야 한다.
- 예: 환경변수, 설정 파일, 또는 실행 인자
- tool 호출의 `root` 및 `path`는 반드시 허용 루트 하위로 정규화(normalize) 후 검증한다.
- `..`/심볼릭 링크/리파스 포인트로 루트를 탈출하는 경로를 차단해야 한다.
### 심볼릭 링크/리파스 포인트
- 기본값: `followSymlinks=false`
- follow 정책을 지원한다면, follow하더라도 “최종 대상 경로가 허용 루트 안에 있어야 함” 규칙을 강제한다.
## 4. 성능/안정성
### 4.1 스캔 제한
대형 폴더에서 무제한 워크는 위험하므로 서버 기본 제한을 둔다.
권장 기본값:
- 최대 스캔 파일 수: 200,000
- 최대 스캔 디렉터리 수: 50,000
- 최대 실행 시간(soft): 10초
제한 도달 시:
- 부분 결과를 반환하고 `nextCursor`로 이어받기를 제공하거나
- `isError=true`로 “too many results / scanned limit exceeded” 반환
### 4.2 페이지네이션(cursor)
- `cursor`는 opaque token이어야 한다.
- 단순 구현: 정렬 기준(time + path)으로 마지막 항목을 커서에 담아 “그 이후부터 계속”하도록 구현.
- 커서는 서버 내부 구조/경로를 필요 이상으로 노출하지 않도록 Base64(JSON) 등으로 캡슐화하는 것을 권장.
### 4.3 취소/진행률
- MCP는 cancellation/progress 메커니즘을 제공한다.
- v0(MVP)에서는 내부 타임아웃만으로도 충분할 수 있으나,
v1에서는 `notifications/progress`와 `notifications/cancelled`를 고려한다.
## 5. 로깅(중요)
- STDIO 기반 서버는 stdout에 로그를 출력하면 JSON-RPC 프레이밍을 깨뜨린다.
- 따라서 반드시 stderr(또는 파일)로 로깅한다.
## 6. 결과 표현(content + structuredContent)
- 스펙 상, structured output을 반환하는 도구는 backwards compatibility를 위해
`content`에 JSON 문자열을 함께 넣는 것을 권장한다.
- 즉, `structuredContent` + `content`(요약 텍스트 + JSON 직렬화 텍스트) 조합을 권장.
## 7. 구현 언어 선택(권장)
- TypeScript SDK 또는 Java SDK 모두 가능.
- 이 워크스페이스가 Windows + Maven 작업 흐름을 쓸 가능성이 있으므로 Java SDK 선택 시 장점:
- 배포(단일 jar) 및 Windows 환경 호환
참고:
- Java SDK: https://github.com/modelcontextprotocol/java-sdk
- TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
