# AI Coding Instructions for File Time Search MCP
This project is a **Model Context Protocol (MCP) Server** that enables file searching by modification or creation time.
## 1. Documentation & Truth Sources
* **Primary Context**: Read `docs/AI_CONTEXT.md` first. It contains the project map and critical constraints.
* **API Contract**: `docs/PRD-API.md` is the **absolute source of truth** for Input/Output schemas. Do not modify the schema without explicit instruction.
* **Policies**: `docs/PRD-v0-Policy.md` defines hard constraints (e.g., `ALLOW_ROOTS`, path handling) that must be followed.
## 2. Architecture & Structure
Follow the structure defined in `docs/TS-Project-Guide.md`:
* **Entry Points**: `src/stdio.ts` (Stdio Transport), `src/http.ts` (Optional HTTP).
* **Core Logic**: `src/tools/searchByTime.ts` (The main tool implementation).
* **Shared**: `src/core/` for config, error handling, and cursor logic.
## 3. Critical Development Rules
* **Stdio Hygiene**: NEVER use `console.log` in the stdio server. It corrupts the JSON-RPC transport. Use `console.error` for logging.
* **Security**:
* Respect `ALLOW_ROOTS` environment variable.
* Reject absolute paths in tool inputs (must be relative to a root).
* Prevent path traversal (`../`).
* **Date Handling**: All dates must be ISO 8601 strings.
* **Windows Compatibility**: Handle Windows `ctime` (creation time) nuances carefully (see `docs/PRD-ImplementationNotes.md`).
## 4. Tech Stack & Conventions
* **Runtime**: Node.js 20+
* **Language**: TypeScript (Target ES2022, Module NodeNext)
* **Libraries**: `@modelcontextprotocol/sdk`, `zod`
* **Tool Registration**: Use `server.tool(...)` or `server.registerTool(...)` with Zod schemas matching `PRD-API.md`.
## 5. Common Workflows
* **Run (Dev)**: `npm run dev:stdio` (uses `tsx`)
* **Build**: `npm run build` (uses `tsc`)
* **Test**: Refer to `docs/PRD-TestPlan.md` for acceptance criteria.
## 6. Implementation Checklist
Refer to `docs/TS-Implementation-Plan.md` for the step-by-step implementation order.
