# AI Context & Instructions
This file is designed to provide AI Agents with a high-level overview of the project, critical constraints, and a map of the documentation. **Read this first.**
## 1. Project Overview
**Goal**: Build a Model Context Protocol (MCP) server that allows AI agents to search for files based on their **modification time (mtime)** or **creation time (birth time)**.
**Tool Name**: `fs.search_by_time`
**Tech Stack**: Node.js, TypeScript, `@modelcontextprotocol/sdk`, `zod`.
## 2. Documentation Map (Where to look)
| Document | Purpose | AI Action |
| :--- | :--- | :--- |
| **[PRD-API.md](PRD-API.md)** | **The Contract**. Input/Output Schema, Error Codes. | **Strictly Follow**. Do not modify the schema. |
| **[PRD-v0-Policy.md](PRD-v0-Policy.md)** | **Hard Constraints**. Decisions that are fixed for v0. | **Strictly Follow**. Do not debate these policies. |
| **[PRD-Defaults-v0.md](PRD-Defaults-v0.md)** | Default values and limits (guardrails). | Use these values for default parameters. |
| [PRD-FileTimeSearch-MCP.md](PRD-FileTimeSearch-MCP.md) | General Requirements & Goals. | Read for context and user scenarios. |
| [PRD-ImplementationNotes.md](PRD-ImplementationNotes.md) | Technical details (Windows ctime, security). | Read before implementing file system logic. |
| [TS-Project-Guide.md](TS-Project-Guide.md) | TypeScript setup & structure guide. | Follow this for project scaffolding. |
| [TS-Implementation-Plan.md](TS-Implementation-Plan.md) | Step-by-step implementation checklist. | Use this to track progress. |
## 3. Critical Constraints & Rules
1. **Schema is Law**: The input/output schema defined in `PRD-API.md` is final for v0. Do not add fields or change types unless explicitly instructed.
2. **Security First**:
- **`ALLOW_ROOTS`**: The server must ONLY search within directories specified in the `ALLOW_ROOTS` environment variable.
- **Path Traversal**: Prevent `../` attacks.
3. **Date Format**: All dates (`from`, `to`) must be ISO 8601 strings.
4. **Error Handling**: Use the error codes defined in `PRD-ErrorCodes-v0.md`.
5. **Output Format**: The tool must return `structuredContent` (JSON) AND a text representation in `content`.
## 4. Implementation Strategy (TypeScript)
1. **Setup**: Initialize project using `TS-Project-Guide.md`.
2. **Schema**: Define Zod schemas matching `PRD-API.md`.
3. **Logic**: Implement file walking and filtering.
- *Note*: Windows `ctime` behavior is tricky. See `PRD-ImplementationNotes.md`.
4. **Testing**: Verify against `PRD-TestPlan.md`.
## 5. Common Pitfalls to Avoid
- **Ignoring `ALLOW_ROOTS`**: The server must fail if no roots are allowed or if the user asks for a path outside allowed roots.
- **Infinite Loops**: Symlinks can cause infinite loops. Handle them (ignore or detect cycles).
- **Large Directories**: The `limit` parameter is mandatory. Do not return 100,000 files. Default limit is 100.
