list_records
Retrieve records from a PocketBase collection with filtering, sorting, pagination, and field selection options to manage database data.
Instructions
List records from a collection with optional filters
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| expand | No | Comma-separated list of relation fields to expand (e.g. 'author,comments.user') | |
| fields | No | Comma-separated fields to return in the response (e.g. 'id,title,author') | |
| filter | No | Filter query using PocketBase filter syntax (e.g. 'status = true && created > "2022-08-01 10:00:00"') | |
| page | No | Page number for pagination (default: 1) | |
| perPage | No | Items per page (default: 50, max: 500) | |
| skipTotal | No | If set to true, the total count query will be skipped to improve performance | |
| sort | No | Sort field and direction (e.g. '-created,title' for descending created date followed by ascending title) |
Implementation Reference
- src/tools/handlers/record.ts:38-63 (handler)Implements the core logic for the list_records tool: constructs query options from args, calls PocketBase collection.getList(), and returns JSON response or handles errors.
export function createListRecordsHandler(pb: PocketBase): ToolHandler { return async (args: ListRecordsArgs) => { try { const options: any = {}; // Add optional parameters if (args.filter) options.filter = args.filter; if (args.sort) options.sort = args.sort; if (args.expand) options.expand = args.expand; if (args.fields) options.fields = args.fields; if (args.skipTotal !== undefined) options.skipTotal = args.skipTotal; // Set pagination const page = args.page || 1; const perPage = args.perPage || 50; const result = await pb .collection(args.collection) .getList(page, perPage, options); return createJsonResponse(result); } catch (error: unknown) { throw handlePocketBaseError("list records", error); } }; } - src/tools/schemas/record.ts:28-65 (schema)Input schema (JSON Schema) for validating arguments to the list_records tool, defining properties like collection, filter, sort, pagination, etc.
export const listRecordsSchema = { type: "object", properties: { collection: { type: "string", description: "Collection name", }, filter: { type: "string", description: "Filter query using PocketBase filter syntax (e.g. 'status = true && created > \"2022-08-01 10:00:00\"')", }, sort: { type: "string", description: "Sort field and direction (e.g. '-created,title' for descending created date followed by ascending title)", }, page: { type: "number", description: "Page number for pagination (default: 1)", }, perPage: { type: "number", description: "Items per page (default: 50, max: 500)", }, expand: { type: "string", description: "Comma-separated list of relation fields to expand (e.g. 'author,comments.user')", }, fields: { type: "string", description: "Comma-separated fields to return in the response (e.g. 'id,title,author')", }, skipTotal: { type: "boolean", description: "If set to true, the total count query will be skipped to improve performance", }, }, required: ["collection"], }; - src/server.ts:131-136 (registration)Registers the list_records tool in the MCP server array, linking the name, description, input schema, and instantiated handler.
{ name: "list_records", description: "List records from a collection with optional filters", inputSchema: listRecordsSchema, handler: createListRecordsHandler(pb), }, - src/types/index.ts:91-100 (schema)TypeScript interface defining the structure of input arguments for the list_records handler, used for type safety.
export interface ListRecordsArgs { collection: string; filter?: string; sort?: string; page?: number; perPage?: number; expand?: string; fields?: string; skipTotal?: boolean; }