query-records
Retrieve and filter PowerPlatform/Dataverse records using OData expressions. Specify the entity name, filter criteria, and max records to extract targeted data efficiently.
Instructions
Query records using an OData filter expression
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entityNamePlural | Yes | The plural name of the entity (e.g., 'accounts', 'contacts') | |
| filter | Yes | OData filter expression (e.g., "name eq 'test'" or "createdon gt 2023-01-01") | |
| maxRecords | No | Maximum number of records to retrieve (default: 50) |
Implementation Reference
- src/index.ts:580-618 (registration)Registration of the 'query-records' MCP tool, including inline schema definition and handler function.server.tool( "query-records", "Query records using an OData filter expression", { entityNamePlural: z.string().describe("The plural name of the entity (e.g., 'accounts', 'contacts')"), filter: z.string().describe("OData filter expression (e.g., \"name eq 'test'\" or \"createdon gt 2023-01-01\")"), maxRecords: z.number().optional().describe("Maximum number of records to retrieve (default: 50)"), }, async ({ entityNamePlural, filter, maxRecords }) => { try { // Get or initialize PowerPlatformService const service = getPowerPlatformService(); const records = await service.queryRecords(entityNamePlural, filter, maxRecords || 50); // Format the records as a string for text display const recordsStr = JSON.stringify(records, null, 2); const recordCount = records.value?.length || 0; return { content: [ { type: "text", text: `Retrieved ${recordCount} records from '${entityNamePlural}' with filter '${filter}':\n\n${recordsStr}`, }, ], }; } catch (error: any) { console.error("Error querying records:", error); return { content: [ { type: "text", text: `Failed to query records: ${error.message}`, }, ], }; } } );
- src/index.ts:588-617 (handler)The main handler function for the 'query-records' tool. It calls PowerPlatformService.queryRecords, formats the results as JSON string, and returns a text response.async ({ entityNamePlural, filter, maxRecords }) => { try { // Get or initialize PowerPlatformService const service = getPowerPlatformService(); const records = await service.queryRecords(entityNamePlural, filter, maxRecords || 50); // Format the records as a string for text display const recordsStr = JSON.stringify(records, null, 2); const recordCount = records.value?.length || 0; return { content: [ { type: "text", text: `Retrieved ${recordCount} records from '${entityNamePlural}' with filter '${filter}':\n\n${recordsStr}`, }, ], }; } catch (error: any) { console.error("Error querying records:", error); return { content: [ { type: "text", text: `Failed to query records: ${error.message}`, }, ], }; } }
- src/index.ts:583-587 (schema)Input schema using Zod for validating tool parameters: entityNamePlural (string), filter (string), maxRecords (optional number).{ entityNamePlural: z.string().describe("The plural name of the entity (e.g., 'accounts', 'contacts')"), filter: z.string().describe("OData filter expression (e.g., \"name eq 'test'\" or \"createdon gt 2023-01-01\")"), maxRecords: z.number().optional().describe("Maximum number of records to retrieve (default: 50)"), },
- src/PowerPlatformService.ts:260-262 (helper)Core helper method in PowerPlatformService that performs the OData query to retrieve filtered records from the Dataverse Web API.async queryRecords(entityNamePlural: string, filter: string, maxRecords: number = 50): Promise<ApiCollectionResponse<any>> { return this.makeRequest<ApiCollectionResponse<any>>(`api/data/v9.2/${entityNamePlural}?$filter=${encodeURIComponent(filter)}&$top=${maxRecords}`); }