API-get-block-children
Retrieve nested block content from Notion by providing a block ID, optional cursor, and page size. Enables efficient querying of structured data for AI assistants.
Instructions
Retrieve block children
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | Identifier for a [block](ref:block) | |
| page_size | No | The number of items from the full list desired in the response. Maximum: 100 | |
| start_cursor | No | If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results. |
Implementation Reference
- Primary handler function that implements the API-get-block-children tool logic by fetching all paginated block children in parallel with batching and merging results.private async handleBlockChildrenParallel( operation: OpenAPIV3.OperationObject & { method: string; path: string }, params: any, options?: RecursiveExplorationOptions ) { if (options?.runInBackground) { console.log(`Starting Notion API parallel processing: ${operation.method.toUpperCase()} ${operation.path}`); } // Get first page const initialResponse = await this.httpClient.executeOperation(operation, params); if (initialResponse.status !== 200) { if (options?.runInBackground) { console.error('Response error:', initialResponse.data); } return { content: [{ type: 'text', text: JSON.stringify(initialResponse.data) }], }; } const results = initialResponse.data.results || []; let nextCursor = initialResponse.data.next_cursor; // Array for parallel processing const pageRequests = []; const maxParallelRequests = 5; // Limit simultaneous requests if (options?.runInBackground) { console.log(`Retrieved ${results.length} blocks from first page`); } // Request subsequent pages in parallel if available while (nextCursor) { // Clone parameters for next page const nextPageParams = { ...params, start_cursor: nextCursor }; // Add page request pageRequests.push( this.httpClient.executeOperation(operation, nextPageParams) .then(response => { if (response.status === 200) { if (options?.runInBackground) { console.log(`Retrieved ${response.data.results?.length || 0} blocks from additional page`); } return { results: response.data.results || [], next_cursor: response.data.next_cursor }; } return { results: [], next_cursor: null }; }) .catch(error => { if (options?.runInBackground) { console.error('Error retrieving page:', error); } return { results: [], next_cursor: null }; }) ); // Execute parallel requests when batch size reached or no more pages if (pageRequests.length >= maxParallelRequests || !nextCursor) { if (options?.runInBackground) { console.log(`Processing ${pageRequests.length} pages in parallel...`); } const pageResponses = await Promise.all(pageRequests); // Merge results for (const response of pageResponses) { results.push(...response.results); // Set next cursor for next batch if (response.next_cursor) { nextCursor = response.next_cursor; } else { nextCursor = null; } } // Reset request array pageRequests.length = 0; } // Exit loop if no more pages if (!nextCursor) break; } if (options?.runInBackground) { console.log(`Retrieved ${results.length} blocks in total`); } // Return merged response const mergedResponse = { ...initialResponse.data, results, has_more: false, next_cursor: null }; return { content: [{ type: 'text', text: JSON.stringify(mergedResponse) }], }; }
- Dispatch logic in the main MCP CallToolRequestSchema handler that specially routes API-get-block-children calls to the optimized parallel handler.// Optimized parallel processing for API-get-block-children if (name === 'API-get-block-children') { // Create basic options for logging control const blockOptions: RecursiveExplorationOptions = { runInBackground: false, // Default to not showing logs for regular API calls }; return await this.handleBlockChildrenParallel(operation, params, blockOptions); }
- src/openapi-mcp-server/mcp/proxy.ts:115-126 (registration)Registration of the tool in the MCP ListToolsRequestSchema response. Converts OpenAPI operations (including get-block-children) to MCP tools named 'API-get-block-children'.Object.entries(this.tools).forEach(([toolName, def]) => { def.methods.forEach(method => { const toolNameWithMethod = `${toolName}-${method.name}`; const truncatedToolName = this.truncateToolName(toolNameWithMethod); tools.push({ name: truncatedToolName, description: method.description, inputSchema: method.inputSchema as Tool['inputSchema'], }) console.log(`- ${truncatedToolName}: ${method.description}`) }) })
- Internal helper usage of the tool within recursive block retrieval for the one-pager feature.const operation = this.findOperation('API-get-block-children'); if (!operation) { throw new Error('API-get-block-children method not found.'); } const blocksResponse = await this.handleBlockChildrenParallel(operation, { block_id: blockId, page_size: 100 }, options);
- Schema generation for the tool via OpenAPIToMCPConverter.convertToMCPTools(), creating inputSchema from OpenAPI operation for 'get-block-children' operationId.const mcpMethod = this.convertOperationToMCPMethod(operation, method, path) if (mcpMethod) { const uniqueName = this.ensureUniqueName(mcpMethod.name) mcpMethod.name = uniqueName tools[apiName]!.methods.push(mcpMethod) openApiLookup[apiName + '-' + uniqueName] = { ...operation, method, path } zip[apiName + '-' + uniqueName] = { openApi: { ...operation, method, path }, mcp: mcpMethod } } } } return { tools, openApiLookup, zip } }