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
| 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) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"entityNamePlural": {
"description": "The plural name of the entity (e.g., 'accounts', 'contacts')",
"type": "string"
},
"filter": {
"description": "OData filter expression (e.g., \"name eq 'test'\" or \"createdon gt 2023-01-01\")",
"type": "string"
},
"maxRecords": {
"description": "Maximum number of records to retrieve (default: 50)",
"type": "number"
}
},
"required": [
"entityNamePlural",
"filter"
],
"type": "object"
}
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}`); }