[MCP] Added read_records tool implementation

[RubenCerna2079]

Why make this change?

• [Enh]: Add DML tool: read_records #2833
  One of the main DML tools that will be used is read_records, which will allow the MCP to read the records of an entity based on the needs of the user.

What is this change?

• Create the read_records tool:
  • First it ensures that the MCP has the proper authorization to run the query
  • Then it creates the context with the parameters that were requested by the user
  • Lastly it calls the SqlQueryEngine in order to create and run the query and receive the results
• The GenerateOrderByLists function inside the RequestParser.cs file was changed from private to public in order to allow the read_records tool to also use it to generate the proper context for the query.
• Some functions inside of the SqlResponseHelper.cs file were changed to check if the query request comes from the read_records tool. This is done in order to output the correct information, right now the REST requests can also return a nextLink object which gives the API link necessary to get values in the case that not all of them were shown. We want to do something similar with the read_records tool, however we only want to return the after object which is the parameter that allows the query to know the exact place where it left from the previous query. This gets rid of unecessary information that can be found in the nextLink object.

Exceptions thrown when:

1. Entity is empty or null.
2. Parameters are not of the correct type.
3. Parameters are not correctly written.
4. Values inside orderby parameter are empty or null. (Note: orderby is an optional value as a whole, but the individual values it contains need to exist)
5. Not having necessary permissions.

Errors:

1. PermissionDenied - No permssions to execute.
2. InvalidArguments - No arguments provided.
3. InvalidArguments - Some missing arguments.
4. EntityNotFound - Entity not defined in the configuration.
5. UnexpectedError - Any other UnexpectedError.

How was this tested?

• Integration Tests
• Unit Tests
• Manual testing via MCP Inspector

These scenarios were manually tested with the MCP Inspector, as automated tests are not yet implemented.

Valid Cases

1. Successful Read

• Provided valid entity and other parameters
• Verified that the received values are the same for MCP as for REST endpoint

2. Permission Enforcement

• Modified role permissions and verified that access control is enforced correctly.

3. Parameter Testing

• Provided different valid values for the multiple optional parameters and ensured they work the same way they do with the REST endpoint.

Failure Cases

1. Null/Empty Entity Name

• Provided an empty string for entity
• Received InvalidArguments error

2. Invalid Entity Name

• Provided string that is not found in config
• Received InvalidArguments error

3. Invalid Parameters

• Provided non-existent fields for select parameter
  • Received InvalidArguments error
• Provided invalid string for filter parameter
  • Received InvalidArguments error
• Provided integer values less than or equal to 0 in the first parameter
  • Received InvalidArguments error
• Provided invalid string for orderby parameter
  • Received InvalidArguments error
• Provided invalid string for after parameter
  • Received InvalidArguments error

4. Unauthorized Role Context

• Removed or misconfigured role-header
• Received PermissionDenied error

Sample Request(s)

{ Entity: Book }
{ Select: title,publisher_id }
{ First: 3 }
{ Orderby: ["publisher_id asc", "title desc"] }

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[Copilot]

Pull Request Overview

This PR implements the read_records tool for the MCP (Model Context Protocol), enabling reading of entity records with parameters like select, filter, first, orderby, and after for pagination. The implementation includes proper authorization checks and handles both REST and MCP endpoint responses differently.

• Added a new ReadRecordsTool class that implements the MCP read_records functionality
• Modified response formatting to support both REST (nextLink) and MCP (after) pagination approaches
• Changed GenerateOrderByLists method visibility from private to public for reuse

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
src/Azure.DataApiBuilder.Mcp/BuiltInTools/ReadRecordsTool.cs	Complete implementation of the read_records tool with argument parsing, authorization, and query execution
src/Core/Resolvers/SqlResponseHelpers.cs	Enhanced response formatting to support both REST nextLink and MCP after pagination patterns
src/Core/Parsers/RequestParser.cs	Changed GenerateOrderByLists method from private to public for reuse
src/Core/Parsers/FilterParser.cs	Removed blank line formatting change

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

nit: Fix the description, Manual testing via MCP Inspecto

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[souvikghosh04]

LGTM. please address the open comments. also please add a task to address the refactoring as requested in https://github.com/Azure/data-api-builder/pull/2893/files#r2411041957

[RubenCerna2079]

/azp run

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[souvikghosh04]

LGTM

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

I received 2 important comments from Aniruddh on the update record tool which will also apply for all other tools.

1. We should use the SqlResponseHelper to create a response that MCP endpoint needs to avoid the duplicate serialization and deserialization. (I think this is addressed in your PR`
2. If the ClientRoleHeaderAuthenticationMiddleware isn't invoked, the roleheader here will be empty. Please test that out.

[anushakolan]

Requested a couple of important changes, please check that out. Rest looks good to me.

[RubenCerna2079]

I received 2 important comments from Aniruddh on the update record tool which will also apply for all other tools.

1. We should use the SqlResponseHelper to create a response that MCP endpoint needs to avoid the duplicate serialization and deserialization. (I think this is addressed in your PR`
2. If the ClientRoleHeaderAuthenticationMiddleware isn't invoked, the roleheader here will be empty. Please test that out.

1. You are correct, my PR already uses SqlResponseHelper you can see it under the // Execute comment.
2. Tested to make sure that the role header isn't empty. Tests were successful.

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[RubenCerna2079]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[anushakolan]

I received 2 important comments from Aniruddh on the update record tool which will also apply for all other tools.

1. We should use the SqlResponseHelper to create a response that MCP endpoint needs to avoid the duplicate serialization and deserialization. (I think this is addressed in your PR`
2. If the ClientRoleHeaderAuthenticationMiddleware isn't invoked, the roleheader here will be empty. Please test that out.

1. You are correct, my PR already uses SqlResponseHelper you can see it under the // Execute comment.
2. Tested to make sure that the role header isn't empty. Tests were successful.

Nice work Ruben!! Please update the testing section in the PR description with point no. 2. Everything else LGTM.