# v0 입출력 예시 모음 — File Time Search MCP
본 문서는 `fs.search_by_time`의 “바로 복사해서 쓸 수 있는” 예시를 제공합니다.
주의:
- `cursor` 값은 **opaque** 입니다. 아래 예시의 cursor 문자열은 예시를 위한 샘플이며, 구현에 따라 달라질 수 있습니다.
- 모든 성공 응답은 `structuredContent`와 `content`(요약 텍스트 + JSON 문자열)를 함께 포함하는 것을 권장합니다.
참조:
- 스키마/계약: [PRD-API.md](PRD-API.md)
- v0 정책: [PRD-v0-Policy.md](PRD-v0-Policy.md)
---
## 예시 1) 기본 호출(최근 수정 기준, 범위 지정)
### 요청(tools/call)
```json
{
"jsonrpc": "2.0",
"id": 100,
"method": "tools/call",
"params": {
"name": "fs.search_by_time",
"arguments": {
"timeField": "modified",
"root": "D:/work/project",
"path": "docs",
"from": "2025-12-01T00:00:00Z",
"to": "2025-12-16T00:00:00Z",
"glob": "**/*.md",
"recursive": true,
"sort": "time_desc",
"limit": 2
}
}
}
```
### 응답(tools/call result)
```json
{
"jsonrpc": "2.0",
"id": 100,
"result": {
"content": [
{
"type": "text",
"text": "Found 2 items (sorted by modified desc)."
},
{
"type": "text",
"text": "{\"timeField\":\"modified\",\"range\":{\"from\":\"2025-12-01T00:00:00Z\",\"to\":\"2025-12-16T00:00:00Z\"},\"matches\":[{\"path\":\"docs/README.md\",\"isDirectory\":false,\"sizeBytes\":1240,\"modifiedAt\":\"2025-12-15T03:10:00Z\",\"createdAt\":\"2025-11-30T10:00:00Z\"},{\"path\":\"docs/PRD-API.md\",\"isDirectory\":false,\"sizeBytes\":8032,\"modifiedAt\":\"2025-12-14T18:00:00Z\",\"createdAt\":\"2025-12-01T09:00:00Z\"}],\"nextCursor\":\"<opaque>\",\"stats\":{\"scannedFiles\":120,\"scannedDirectories\":12,\"returned\":2}}"
}
],
"structuredContent": {
"timeField": "modified",
"range": {
"from": "2025-12-01T00:00:00Z",
"to": "2025-12-16T00:00:00Z"
},
"matches": [
{
"path": "docs/README.md",
"isDirectory": false,
"sizeBytes": 1240,
"modifiedAt": "2025-12-15T03:10:00Z",
"createdAt": "2025-11-30T10:00:00Z"
},
{
"path": "docs/PRD-API.md",
"isDirectory": false,
"sizeBytes": 8032,
"modifiedAt": "2025-12-14T18:00:00Z",
"createdAt": "2025-12-01T09:00:00Z"
}
],
"nextCursor": "eyJ2IjoxLCJzIjoidGltZV9kZXNjIiwidCI6MTc2NTc1NDQwMDAwMCwicCI6ImRvY3MvUFJELUFQSS5tZCJ9",
"stats": {
"scannedFiles": 120,
"scannedDirectories": 12,
"returned": 2
}
},
"isError": false
}
}
```
---
## 예시 2) 페이지네이션(cursor) — 2페이지 호출
### 2-1) 1페이지 요청
```json
{
"jsonrpc": "2.0",
"id": 200,
"method": "tools/call",
"params": {
"name": "fs.search_by_time",
"arguments": {
"timeField": "modified",
"root": "D:/work/project",
"path": "docs",
"recursive": true,
"sort": "time_desc",
"limit": 2
}
}
}
```
### 2-2) 1페이지 응답(요약)
- `nextCursor`가 존재하므로 다음 페이지가 있을 수 있음
```json
{
"jsonrpc": "2.0",
"id": 200,
"result": {
"content": [{ "type": "text", "text": "..." }],
"structuredContent": {
"timeField": "modified",
"range": { "from": null, "to": null },
"matches": [
{
"path": "docs/README.md",
"isDirectory": false,
"sizeBytes": 1240,
"modifiedAt": "2025-12-15T03:10:00Z",
"createdAt": "2025-11-30T10:00:00Z"
},
{
"path": "docs/PRD-API.md",
"isDirectory": false,
"sizeBytes": 8032,
"modifiedAt": "2025-12-14T18:00:00Z",
"createdAt": "2025-12-01T09:00:00Z"
}
],
"nextCursor": "eyJ2IjoxLCJzIjoidGltZV9kZXNjIiwidCI6MTc2NTcwNjQwMDAwMCwicCI6ImRvY3MvUFJELUFQSS5tZCJ9",
"stats": { "scannedFiles": 100, "scannedDirectories": 10, "returned": 2 }
},
"isError": false
}
}
```
### 2-3) 2페이지 요청(이전 `nextCursor`를 그대로 전달)
```json
{
"jsonrpc": "2.0",
"id": 201,
"method": "tools/call",
"params": {
"name": "fs.search_by_time",
"arguments": {
"timeField": "modified",
"root": "D:/work/project",
"path": "docs",
"recursive": true,
"sort": "time_desc",
"limit": 2,
"cursor": "eyJ2IjoxLCJzIjoidGltZV9kZXNjIiwidCI6MTc2NTcwNjQwMDAwMCwicCI6ImRvY3MvUFJELUFQSS5tZCJ9"
}
}
}
```
### 2-4) 2페이지 응답(요약)
```json
{
"jsonrpc": "2.0",
"id": 201,
"result": {
"content": [{ "type": "text", "text": "..." }],
"structuredContent": {
"timeField": "modified",
"range": { "from": null, "to": null },
"matches": [
{
"path": "docs/PRD-TestPlan.md",
"isDirectory": false,
"sizeBytes": 2011,
"modifiedAt": "2025-12-14T10:00:00Z",
"createdAt": "2025-12-01T10:00:00Z"
},
{
"path": "docs/PRD-ImplementationNotes.md",
"isDirectory": false,
"sizeBytes": 5020,
"modifiedAt": "2025-12-13T21:30:00Z",
"createdAt": "2025-12-01T11:00:00Z"
}
],
"nextCursor": null,
"stats": { "scannedFiles": 140, "scannedDirectories": 10, "returned": 2 }
},
"isError": false
}
}
```
---
## 예시 3) created + includeUnknownTime=true (createdAt=null 포함)
일부 OS/FS에서는 created/birth time이 없을 수 있으며, v0 정책에서 `includeUnknownTime=true`이면 `createdAt=null`로 결과에 포함할 수 있습니다.
### 요청
```json
{
"jsonrpc": "2.0",
"id": 300,
"method": "tools/call",
"params": {
"name": "fs.search_by_time",
"arguments": {
"timeField": "created",
"root": "D:/work/project",
"path": "docs",
"includeUnknownTime": true,
"sort": "time_desc",
"limit": 2
}
}
}
```
### 응답(요약)
```json
{
"jsonrpc": "2.0",
"id": 300,
"result": {
"content": [{ "type": "text", "text": "..." }],
"structuredContent": {
"timeField": "created",
"range": { "from": null, "to": null },
"matches": [
{
"path": "docs/PRD-FileTimeSearch-MCP.md",
"isDirectory": false,
"sizeBytes": 9000,
"modifiedAt": "2025-12-12T10:00:00Z",
"createdAt": "2025-12-01T09:00:00Z"
},
{
"path": "docs/legacy-note.txt",
"isDirectory": false,
"sizeBytes": 120,
"modifiedAt": "2025-12-11T10:00:00Z",
"createdAt": null
}
],
"nextCursor": null,
"stats": { "scannedFiles": 50, "scannedDirectories": 3, "returned": 2 }
},
"isError": false
}
}
```
---
## 예시 4) 디렉터리 포함(includeDirectories=true)
### 요청(디렉터리만)
```json
{
"jsonrpc": "2.0",
"id": 400,
"method": "tools/call",
"params": {
"name": "fs.search_by_time",
"arguments": {
"timeField": "modified",
"root": "D:/work/project",
"path": "docs",
"recursive": false,
"includeFiles": false,
"includeDirectories": true,
"sort": "path_asc",
"limit": 50
}
}
}
```
### 응답(요약)
```json
{
"jsonrpc": "2.0",
"id": 400,
"result": {
"content": [{ "type": "text", "text": "..." }],
"structuredContent": {
"timeField": "modified",
"range": { "from": null, "to": null },
"matches": [
{
"path": "docs",
"isDirectory": true,
"sizeBytes": null,
"modifiedAt": "2025-12-15T03:00:00Z",
"createdAt": "2025-12-01T08:30:00Z"
}
],
"nextCursor": null,
"stats": { "scannedFiles": 0, "scannedDirectories": 1, "returned": 1 }
},
"isError": false
}
}
```
---
## 예시 5) tool 실행 에러(isError=true)
### 요청(`from > to`)
```json
{
"jsonrpc": "2.0",
"id": 500,
"method": "tools/call",
"params": {
"name": "fs.search_by_time",
"arguments": {
"timeField": "modified",
"from": "2025-12-16T00:00:00Z",
"to": "2025-12-15T00:00:00Z"
}
}
}
```
### 응답
```json
{
"jsonrpc": "2.0",
"id": 500,
"result": {
"content": [
{
"type": "text",
"text": "ErrorCode: InvalidRange\nMessage: 'from' must not be later than 'to'.\nFix: Set 'from' <= 'to' (from inclusive, to exclusive)."
}
],
"isError": true
}
}
```
