query_pages

Instructions

Implementation Reference

• src/presentation/mcp/MCPServer.ts:419-449 (handler)

  MCP tool handler method that executes the query_pages tool. It calls the QueryPagesUseCase with input arguments and formats the response as MCP content.

  private async handleQueryPages(args: any) {
    const result = await this.dependencies.queryPagesUseCase.execute({
      databaseId: args.databaseId,
      filter: args.filter,
      sorts: args.sorts,
      startCursor: args.startCursor,
      pageSize: args.pageSize,
    });
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(
            {
              pages: result.pages.map((page) => ({
                id: page.id.toString(),
                properties: page.properties,
                createdTime: page.createdTime,
                archived: page.archived,
              })),
              hasMore: result.hasMore,
              nextCursor: result.nextCursor,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/presentation/mcp/MCPServer.ts:217-258 (registration)

  Tool registration in the getTools() method, defining the name 'query_pages', description, and input schema for the MCP ListTools response.

        {
          name: 'query_pages',
          description: 'Queries and retrieves pages (records) from a Notion database. Supports filtering and sorting. Examples: "tasks with status In Progress", "projects due this week", "tasks assigned to me". Retrieve pages matching specific conditions.',
          inputSchema: {
            type: 'object',
            properties: {
              databaseId: {
                type: 'string',
                description: 'The ID of the Notion database to query (32 or 36 character UUID format). Example: "123e4567-e89b-12d3-a456-426614174000"',
              },
              filter: {
                type: 'object',
                description: `Filter conditions (optional). Follows Notion API filter syntax.
  
  Examples:
  - Status equals "In Progress": { "property": "Status", "select": { "equals": "In Progress" } }
  - Checkbox is checked: { "property": "Completed", "checkbox": { "equals": true } }
  - Date is this week: { "property": "Due Date", "date": { "this_week": {} } }
  - Multiple conditions (AND): { "and": [condition1, condition2] }
  - Multiple conditions (OR): { "or": [condition1, condition2] }`,
              },
              sorts: {
                type: 'array',
                description: `Sort conditions (optional). Array of sort specifications.
  
  Examples:
  - Date ascending: [{ "property": "Due Date", "direction": "ascending" }]
  - Priority descending: [{ "property": "Priority", "direction": "descending" }]
  - Created time descending: [{ "timestamp": "created_time", "direction": "descending" }]`,
              },
              startCursor: {
                type: 'string',
                description: 'Pagination cursor (optional). Use the nextCursor from a previous query to fetch the next page of results.',
              },
              pageSize: {
                type: 'number',
                description: 'Number of pages to retrieve at once (optional, default: 100, max: 100). Use with pagination for large datasets.',
              },
            },
            required: ['databaseId'],
          },
        },

• src/application/use-cases/QueryPagesUseCase.ts:8-14 (schema)

  TypeScript interface defining the input schema for the QueryPagesUseCase, matching the MCP tool input.

  export interface QueryPagesInput {
    databaseId: string;
    filter?: Record<string, unknown>;
    sorts?: Array<{ property: string; direction: 'ascending' | 'descending' }>;
    startCursor?: string;
    pageSize?: number;
  }

• src/application/use-cases/QueryPagesUseCase.ts:16-31 (handler)

  Core business logic handler in QueryPagesUseCase.execute(), which validates input, constructs query options, and delegates to the page repository.

  export class QueryPagesUseCase {
    constructor(private readonly pageRepository: IPageRepository) {}
  
    async execute(input: QueryPagesInput): Promise<PageQueryResult> {
      const databaseId = new DatabaseId(input.databaseId);
      
      const options: PageQueryOptions = {
        filter: input.filter,
        sorts: input.sorts,
        startCursor: input.startCursor,
        pageSize: input.pageSize,
      };
  
      return await this.pageRepository.query(databaseId, options);
    }
  }