Refactor common code shared amongst built in MCP tools (#2986)

## Why make this change?

Closes #2932

## What is this change?

Add helper class `McpMetadataHelper`, extend `McpArgumentParser`, and
utilize `McpAuthorizationHelper` to factor out common code. We now do
the initialization of the metadata, the parsing of arguments, and the
authorization checks in these shared helper classes.

## How was this tested?

With MCP Inspector and against the normal test suite.

* DESCRIBE_ENTITIES
<img width="427" height="653" alt="image"
src="https://github.com/user-attachments/assets/7ba74cfb-5a71-402b-afd2-17f7a24d0295"
/>


* CREATE
<img width="1435" height="655" alt="image"
src="https://github.com/user-attachments/assets/f189bb22-6f25-46ef-b2f0-20e80bc2850f"
/>

* READ
<img width="1131" height="651" alt="image"
src="https://github.com/user-attachments/assets/16f3e6f6-24e9-4613-a8fd-61546b199305"
/>

* UPDATE
<img width="1083" height="292" alt="image"
src="https://github.com/user-attachments/assets/ce284b6f-1f2f-4dc4-b73d-8242605ee20a"
/>


* DELETE
<img width="1425" height="648" alt="image"
src="https://github.com/user-attachments/assets/8768baf6-96f3-441c-b47d-c17e5fae9300"
/>


## Sample Request(s)

N/A

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Souvik Ghosh <[email protected]>

Author: 3 people

src/Azure.DataApiBuilder.Mcp/BuiltInTools/CreateRecordTool.cs

@@ -5,14 +5,13 @@
 using Azure.DataApiBuilder.Auth;
 using Azure.DataApiBuilder.Config.DatabasePrimitives;
 using Azure.DataApiBuilder.Config.ObjectModel;
-using Azure.DataApiBuilder.Core.Authorization;
 using Azure.DataApiBuilder.Core.Configurations;
 using Azure.DataApiBuilder.Core.Models;
 using Azure.DataApiBuilder.Core.Resolvers;
 using Azure.DataApiBuilder.Core.Resolvers.Factories;
 using Azure.DataApiBuilder.Core.Services;
-using Azure.DataApiBuilder.Core.Services.MetadataProviders;
 using Azure.DataApiBuilder.Mcp.Model;
+using Azure.DataApiBuilder.Mcp.Utils;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.DependencyInjection;
@@ -60,78 +59,61 @@ public async Task<CallToolResult> ExecuteAsync(
             string toolName = GetToolMetadata().Name;
             if (arguments == null)
             {
-                return Utils.McpResponseBuilder.BuildErrorResult(toolName, "Invalid Arguments", "No arguments provided", logger);
+                return McpResponseBuilder.BuildErrorResult(toolName, "InvalidArguments", "No arguments provided.", logger);
             }
 
             RuntimeConfigProvider runtimeConfigProvider = serviceProvider.GetRequiredService<RuntimeConfigProvider>();
             if (!runtimeConfigProvider.TryGetConfig(out RuntimeConfig? runtimeConfig))
             {
-                return Utils.McpResponseBuilder.BuildErrorResult(toolName, "Invalid Configuration", "Runtime configuration not available", logger);
+                return McpResponseBuilder.BuildErrorResult(toolName, "InvalidConfiguration", "Runtime configuration not available.", logger);
             }
 
             if (runtimeConfig.McpDmlTools?.CreateRecord != true)
             {
-                return Utils.McpResponseBuilder.BuildErrorResult(
-                    toolName,
-                    "ToolDisabled",
-                    "The create_record tool is disabled in the configuration.",
-                    logger);
+                return McpErrorHelpers.ToolDisabled(toolName, logger);
             }
 
             try
             {
                 cancellationToken.ThrowIfCancellationRequested();
                 JsonElement root = arguments.RootElement;
 
-                if (!root.TryGetProperty("entity", out JsonElement entityElement) ||
-                    !root.TryGetProperty("data", out JsonElement dataElement))
+                if (!McpArgumentParser.TryParseEntityAndData(root, out string entityName, out JsonElement dataElement, out string parseError))
                 {
-                    return Utils.McpResponseBuilder.BuildErrorResult(toolName, "InvalidArguments", "Missing required arguments 'entity' or 'data'", logger);
+                    return McpResponseBuilder.BuildErrorResult(toolName, "InvalidArguments", parseError, logger);
                 }
 
-                string entityName = entityElement.GetString() ?? string.Empty;
-                if (string.IsNullOrWhiteSpace(entityName))
+                if (!McpMetadataHelper.TryResolveMetadata(
+                        entityName,
+                        runtimeConfig,
+                        serviceProvider,
+                        out ISqlMetadataProvider sqlMetadataProvider,
+                        out DatabaseObject dbObject,
+                        out string dataSourceName,
+                        out string metadataError))
                 {
-                    return Utils.McpResponseBuilder.BuildErrorResult(toolName, "InvalidArguments", "Entity name cannot be empty", logger);
-                }
-
-                string dataSourceName;
-                try
-                {
-                    dataSourceName = runtimeConfig.GetDataSourceNameFromEntityName(entityName);
-                }
-                catch (Exception)
-                {
-                    return Utils.McpResponseBuilder.BuildErrorResult(toolName, "InvalidConfiguration", $"Entity '{entityName}' not found in configuration", logger);
-                }
-
-                IMetadataProviderFactory metadataProviderFactory = serviceProvider.GetRequiredService<IMetadataProviderFactory>();
-                ISqlMetadataProvider sqlMetadataProvider = metadataProviderFactory.GetMetadataProvider(dataSourceName);
-
-                DatabaseObject dbObject;
-                try
-                {
-                    dbObject = sqlMetadataProvider.GetDatabaseObjectByKey(entityName);
-                }
-                catch (Exception)
-                {
-                    return Utils.McpResponseBuilder.BuildErrorResult(toolName, "InvalidConfiguration", $"Database object for entity '{entityName}' not found", logger);
+                    return McpResponseBuilder.BuildErrorResult(toolName, "EntityNotFound", metadataError, logger);
                 }
 
                 // Create an HTTP context for authorization
                 IHttpContextAccessor httpContextAccessor = serviceProvider.GetRequiredService<IHttpContextAccessor>();
                 HttpContext httpContext = httpContextAccessor.HttpContext ?? new DefaultHttpContext();
                 IAuthorizationResolver authorizationResolver = serviceProvider.GetRequiredService<IAuthorizationResolver>();
 
-                if (httpContext is null || !authorizationResolver.IsValidRoleContext(httpContext))
+                if (!McpAuthorizationHelper.ValidateRoleContext(httpContext, authorizationResolver, out string roleCtxError))
                 {
-                    return Utils.McpResponseBuilder.BuildErrorResult(toolName, "PermissionDenied", "Permission denied: Unable to resolve a valid role context for update operation.", logger);
+                    return McpErrorHelpers.PermissionDenied(toolName, entityName, "create", roleCtxError, logger);
                 }
 
-                // Validate that we have at least one role authorized for create
-                if (!TryResolveAuthorizedRole(httpContext, authorizationResolver, entityName, out string authError))
+                if (!McpAuthorizationHelper.TryResolveAuthorizedRole(
+                        httpContext,
+                        authorizationResolver,
+                        entityName,
+                        EntityActionOperation.Create,
+                        out string? effectiveRole,
+                        out string authError))
                 {
-                    return Utils.McpResponseBuilder.BuildErrorResult(toolName, "PermissionDenied", authError, logger);
+                    return McpErrorHelpers.PermissionDenied(toolName, entityName, "create", authError, logger);
                 }
 
                 JsonElement insertPayloadRoot = dataElement.Clone();
@@ -152,12 +134,12 @@ public async Task<CallToolResult> ExecuteAsync(
                     }
                     catch (Exception ex)
                     {
-                        return Utils.McpResponseBuilder.BuildErrorResult(toolName, "ValidationFailed", $"Request validation failed: {ex.Message}", logger);
+                        return McpResponseBuilder.BuildErrorResult(toolName, "ValidationFailed", $"Request validation failed: {ex.Message}", logger);
                     }
                 }
                 else
                 {
-                    return Utils.McpResponseBuilder.BuildErrorResult(
+                    return McpResponseBuilder.BuildErrorResult(
                         toolName,
                         "InvalidCreateTarget",
                         "The create_record tool is only available for tables.",
@@ -172,7 +154,7 @@ public async Task<CallToolResult> ExecuteAsync(
 
                 if (result is CreatedResult createdResult)
                 {
-                    return Utils.McpResponseBuilder.BuildSuccessResult(
+                    return McpResponseBuilder.BuildSuccessResult(
                         new Dictionary<string, object?>
                         {
                             ["entity"] = entityName,
@@ -187,15 +169,15 @@ public async Task<CallToolResult> ExecuteAsync(
                     bool isError = objectResult.StatusCode.HasValue && objectResult.StatusCode.Value >= 400 && objectResult.StatusCode.Value != 403;
                     if (isError)
                     {
-                        return Utils.McpResponseBuilder.BuildErrorResult(
+                        return McpResponseBuilder.BuildErrorResult(
                             toolName,
                             "CreateFailed",
                             $"Failed to create record in entity '{entityName}'. Error: {JsonSerializer.Serialize(objectResult.Value)}",
                             logger);
                     }
                     else
                     {
-                        return Utils.McpResponseBuilder.BuildSuccessResult(
+                        return McpResponseBuilder.BuildSuccessResult(
                             new Dictionary<string, object?>
                             {
                                 ["entity"] = entityName,
@@ -210,15 +192,15 @@ public async Task<CallToolResult> ExecuteAsync(
                 {
                     if (result is null)
                     {
-                        return Utils.McpResponseBuilder.BuildErrorResult(
+                        return McpResponseBuilder.BuildErrorResult(
                             toolName,
                             "UnexpectedError",
                             $"Mutation engine returned null result for entity '{entityName}'",
                             logger);
                     }
                     else
                     {
-                        return Utils.McpResponseBuilder.BuildSuccessResult(
+                        return McpResponseBuilder.BuildSuccessResult(
                             new Dictionary<string, object?>
                             {
                                 ["entity"] = entityName,
@@ -231,50 +213,8 @@ public async Task<CallToolResult> ExecuteAsync(
             }
             catch (Exception ex)
             {
-                return Utils.McpResponseBuilder.BuildErrorResult(toolName, "Error", $"Error: {ex.Message}", logger);
+                return McpResponseBuilder.BuildErrorResult(toolName, "Error", $"Error: {ex.Message}", logger);
             }
         }
-
-        private static bool TryResolveAuthorizedRole(
-            HttpContext httpContext,
-            IAuthorizationResolver authorizationResolver,
-            string entityName,
-            out string error)
-        {
-            error = string.Empty;
-
-            string roleHeader = httpContext.Request.Headers[AuthorizationResolver.CLIENT_ROLE_HEADER].ToString();
-
-            if (string.IsNullOrWhiteSpace(roleHeader))
-            {
-                error = "Client role header is missing or empty.";
-                return false;
-            }
-
-            string[] roles = roleHeader
-                .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
-                .Distinct(StringComparer.OrdinalIgnoreCase)
-                .ToArray();
-
-            if (roles.Length == 0)
-            {
-                error = "Client role header is missing or empty.";
-                return false;
-            }
-
-            foreach (string role in roles)
-            {
-                bool allowed = authorizationResolver.AreRoleAndOperationDefinedForEntity(
-                    entityName, role, EntityActionOperation.Create);
-
-                if (allowed)
-                {
-                    return true;
-                }
-            }
-
-            error = "You do not have permission to create records for this entity.";
-            return false;
-        }
     }
 }

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DeleteRecordTool.cs

@@ -87,11 +87,7 @@ public async Task<CallToolResult> ExecuteAsync(
                 // 2) Check if the tool is enabled in configuration before proceeding
                 if (config.McpDmlTools?.DeleteRecord != true)
                 {
-                    return McpResponseBuilder.BuildErrorResult(
-                        toolName,
-                        "ToolDisabled",
-                        $"The {this.GetToolMetadata().Name} tool is disabled in the configuration.",
-                        logger);
+                    return McpErrorHelpers.ToolDisabled(GetToolMetadata().Name, logger);
                 }
 
                 // 3) Parsing & basic argument validation
@@ -105,26 +101,17 @@ public async Task<CallToolResult> ExecuteAsync(
                     return McpResponseBuilder.BuildErrorResult(toolName, "InvalidArguments", parseError, logger);
                 }
 
-                IMetadataProviderFactory metadataProviderFactory = serviceProvider.GetRequiredService<IMetadataProviderFactory>();
-                IMutationEngineFactory mutationEngineFactory = serviceProvider.GetRequiredService<IMutationEngineFactory>();
-
-                // 4) Resolve metadata for entity existence check
-                string dataSourceName;
-                ISqlMetadataProvider sqlMetadataProvider;
-
-                try
+                // 4) Resolve metadata for entity existence
+                if (!McpMetadataHelper.TryResolveMetadata(
+                        entityName,
+                        config,
+                        serviceProvider,
+                        out ISqlMetadataProvider sqlMetadataProvider,
+                        out DatabaseObject dbObject,
+                        out string dataSourceName,
+                        out string metadataError))
                 {
-                    dataSourceName = config.GetDataSourceNameFromEntityName(entityName);
-                    sqlMetadataProvider = metadataProviderFactory.GetMetadataProvider(dataSourceName);
-                }
-                catch (Exception)
-                {
-                    return McpResponseBuilder.BuildErrorResult(toolName, "EntityNotFound", $"Entity '{entityName}' is not defined in the configuration.", logger);
-                }
-
-                if (!sqlMetadataProvider.EntityToDatabaseObject.TryGetValue(entityName, out DatabaseObject? dbObject) || dbObject is null)
-                {
-                    return McpResponseBuilder.BuildErrorResult(toolName, "EntityNotFound", $"Entity '{entityName}' is not defined in the configuration.", logger);
+                    return McpResponseBuilder.BuildErrorResult(toolName, "EntityNotFound", metadataError, logger);
                 }
 
                 // Validate it's a table or view
@@ -140,7 +127,7 @@ public async Task<CallToolResult> ExecuteAsync(
 
                 if (!McpAuthorizationHelper.ValidateRoleContext(httpContext, authResolver, out string roleError))
                 {
-                    return McpResponseBuilder.BuildErrorResult(toolName, "PermissionDenied", $"Permission denied: {roleError}", logger);
+                    return McpErrorHelpers.PermissionDenied(toolName, entityName, "delete", roleError, logger);
                 }
 
                 if (!McpAuthorizationHelper.TryResolveAuthorizedRole(
@@ -151,10 +138,11 @@ public async Task<CallToolResult> ExecuteAsync(
                     out string? effectiveRole,
                     out string authError))
                 {
-                    return McpResponseBuilder.BuildErrorResult(toolName, "PermissionDenied", $"Permission denied: {authError}", logger);
+                    return McpErrorHelpers.PermissionDenied(toolName, entityName, "delete", authError, logger);
                 }
 
-                // 6) Build and validate Delete context
+                // Need MetadataProviderFactory for RequestValidator; resolve here.
+                IMetadataProviderFactory metadataProviderFactory = serviceProvider.GetRequiredService<IMetadataProviderFactory>();
                 RequestValidator requestValidator = new(metadataProviderFactory, runtimeConfigProvider);
 
                 DeleteRequestContext context = new(
@@ -174,7 +162,7 @@ public async Task<CallToolResult> ExecuteAsync(
 
                 requestValidator.ValidatePrimaryKey(context);
 
-                // 7) Execute
+                IMutationEngineFactory mutationEngineFactory = serviceProvider.GetRequiredService<IMutationEngineFactory>();
                 DatabaseType dbType = config.GetDataSourceFromDataSourceName(dataSourceName).DatabaseType;
                 IMutationEngine mutationEngine = mutationEngineFactory.GetMutationEngine(dbType);
 
@@ -343,8 +331,7 @@ public async Task<CallToolResult> ExecuteAsync(
             }
             catch (Exception ex)
             {
-                ILogger<DeleteRecordTool>? innerLogger = serviceProvider.GetService<ILogger<DeleteRecordTool>>();
-                innerLogger?.LogError(ex, "Unexpected error in DeleteRecordTool.");
+                logger?.LogError(ex, "Unexpected error in DeleteRecordTool.");
 
                 return McpResponseBuilder.BuildErrorResult(
                     toolName,

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs

@@ -78,11 +78,7 @@ public Task<CallToolResult> ExecuteAsync(
 
                 if (!IsToolEnabled(runtimeConfig))
                 {
-                    return Task.FromResult(McpResponseBuilder.BuildErrorResult(
-                        toolName,
-                        "ToolDisabled",
-                        $"The {GetToolMetadata().Name} tool is disabled in the configuration.",
-                        logger));
+                    return Task.FromResult(McpErrorHelpers.ToolDisabled(GetToolMetadata().Name, logger));
                 }
 
                 // Get authorization services to determine current user's role