Advanced PocketBase MCP Server

Implementation Reference

• src/server.ts:496-522 (registration)

  Primary registration of the 'list_records' MCP tool, including inline input schema (Zod validation) and handler function that queries PocketBase collection using getList method with optional filtering, sorting, and pagination.

  server.tool(
    'list_records',
    {
      collection: z.string().describe('Collection name'),
      filter: z.string().optional().describe('Filter query'),
      sort: z.string().optional().describe('Sort field and direction'),
      page: z.number().optional().describe('Page number'),
      perPage: z.number().optional().describe('Items per page')
    },
    async ({ collection, filter, sort, page = 1, perPage = 50 }) => {
      try {
        const options: any = {};
        if (filter) options.filter = filter;
        if (sort) options.sort = sort;
  
        const result = await this.pb.collection(collection).getList(page, perPage, options);
        return {
          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
        };
      } catch (error: any) {
        return {
          content: [{ type: 'text', text: `Failed to list records: ${error.message}` }],
          isError: true
        };
      }
    }
  );

• src/server.ts:505-521 (handler)

  Core handler logic for executing the list_records tool: constructs query options and calls PocketBase's getList API.

  async ({ collection, filter, sort, page = 1, perPage = 50 }) => {
    try {
      const options: any = {};
      if (filter) options.filter = filter;
      if (sort) options.sort = sort;
  
      const result = await this.pb.collection(collection).getList(page, perPage, options);
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
      };
    } catch (error: any) {
      return {
        content: [{ type: 'text', text: `Failed to list records: ${error.message}` }],
        isError: true
      };
    }
  }

• src/server.ts:498-503 (schema)

  Zod-based input schema defining parameters for the list_records tool: required collection name and optional filter, sort, page, perPage.

  {
    collection: z.string().describe('Collection name'),
    filter: z.string().optional().describe('Filter query'),
    sort: z.string().optional().describe('Sort field and direction'),
    page: z.number().optional().describe('Page number'),
    perPage: z.number().optional().describe('Items per page')

• src/agent-worker-compatible.ts:365-391 (handler)

  Worker-compatible handler method listRecords for list_records tool, supporting pagination, filtering, and sorting via PocketBase getList.

  private async listRecords(collection: string, options: any = {}) {
    if (!this.pb) {
      throw new Error('PocketBase not configured');
    }
  
    try {
      const records = await this.pb.collection(collection).getList(
        options.page || 1,
        options.perPage || 30,
        {
          filter: options.filter,
          sort: options.sort
        }
      );
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(records, null, 2)
          }
        ]
      };
    } catch (error: any) {
      throw new Error(`Failed to list records: ${error.message}`);
    }
  }

• src/agent-worker-compatible.ts:129-134 (registration)

  Dispatch/registration case in unified tool handler for list_records, validates input and delegates to listRecords method.

  case "list_records": {
    if (!args || typeof args !== "object" || typeof (args as any).collection !== "string") {
      throw new Error("'collection' is required and must be a string for list_records");
    }
    return await this.listRecords((args as any).collection, args);
  }