Add server-level description field to MCP runtime configuration

[Copilot]

Why make this change?

MCP clients and agents require high-level behavioral context for servers via the initialize response's instructions field. DAB previously had no mechanism to surface this configurable semantic guidance.

What is this change?

Added optional description field to MCP runtime configuration that populates the MCP protocol's instructions field:

Configuration model

• McpRuntimeOptions now accepts description parameter
• McpRuntimeOptionsConverter handles serialization/deserialization

CLI integration

• dab configure --runtime.mcp.description "text" command support
• Configuration generator validates and persists the value
• Fixed config persistence bug: Added DML tools options to condition check to ensure MCP configuration updates are properly written to config file

MCP server response

• Stdio Server: HandleInitialize() retrieves description from RuntimeConfig.Runtime.Mcp.Description and conditionally includes instructions in initialize response when non-empty
• HTTP Server: Updated server name to "SQL MCP Server"
• Both servers now use explicit object type instead of var for better type clarity

Testing

• Added comprehensive unit tests in McpRuntimeOptionsSerializationTests covering:
  • Serialization/deserialization with description
  • Edge cases: null, empty strings, whitespace, very long strings (5000+ characters)
  • Special characters: quotes, newlines, tabs, unicode characters
  • Backward compatibility with existing configurations without description field
  • Improved assertion order to validate JSON field presence before value matching
• Consolidated CLI tests: removed duplicate TestAddDescriptionToMcpSettings and renamed TestUpdateDescriptionForMcpSettings to TestConfigureDescriptionForMcpSettings

Code quality fixes

• Fixed build errors by removing nullable reference type annotations (project has nullable disabled)
• Fixed IDE0090 code style error by using target-typed new expression
• Fixed whitespace formatting error by removing trailing whitespace
• Fixed IDE0005 warnings by removing unnecessary using directives
• Fixed IDE0059 warnings by removing unnecessary variable assignments (response and requestId)

Example configuration:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "description": "This MCP provides access to the Products database..."
    }
  }
}

How was this tested?

• Unit Tests
  • 9 serialization/deserialization tests for MCP description field
  • 2 CLI configuration tests for description option (consolidated from 3)
  • All existing ConfigureOptionsTests pass (58 tests)
• Build verification - all projects build successfully with no errors or warnings

Sample Request(s)

CLI usage:

dab configure --runtime.mcp.description "This MCP provides access to the Products database and should be used to answer product-related or inventory-related questions from the user."

MCP initialize response (when description configured - Stdio Server):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { ... },
    "serverInfo": {
      "name": "SQL MCP Server",
      "version": "1.0.0"
    },
    "instructions": "This MCP provides access to the Products database..."
  }
}

Note: The HTTP server currently only updates the server name to "SQL MCP Server". Instructions support will be added when the ModelContextProtocol.AspNetCore library adds support for this field in future versions.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds a server-level description field to the MCP runtime configuration that enables DAB to expose semantic guidance to MCP clients via the initialize response's instructions field.

• Adds optional description parameter to MCP runtime configuration model
• Implements CLI support for configuring the description via dab configure --runtime.mcp.description
• Wires the description value into the MCP initialize response as the instructions field

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Config/ObjectModel/McpRuntimeOptions.cs	Adds Description property to store the server-level description
src/Config/Converters/McpRuntimeOptionsConverterFactory.cs	Implements serialization/deserialization for the description field
src/Cli/ConfigGenerator.cs	Updates configuration generator to handle description parameter and adds it to the MCP configuration check
src/Cli/Commands/ConfigureOptions.cs	Adds CLI option --runtime.mcp.description for setting the description
src/Cli.Tests/ConfigureOptionsTests.cs	Adds unit tests for setting and updating MCP description via CLI
src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs	Retrieves description from runtime config and includes it as instructions in initialize response

Comments suppressed due to low confidence (1)

src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs:209

• The serialization uses JsonSerializer.Serialize without specifying JsonSerializerOptions. By default, System.Text.Json includes null properties in the output, which means the instructions field will be present with a null value when the description is not configured. To omit null properties from the response, you should configure JsonSerializerOptions with DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull. This is important for MCP protocol compliance where optional fields should be omitted rather than included with null values.

            string json = JsonSerializer.Serialize(response);
            Console.Out.WriteLine(json);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Aniruddh25]

@copilot, can you fix the warnings seen in this log as well:

https://dev.azure.com/sqldab/Data%20API%20builder%20Dependency%20Packages/Data%20API%20builder%20Dependency%20Packages%20Team/_build/results?buildId=16269&view=logs&j=12f1170f-54f2-53f3-20dd-22fc7dff55f9&t=006e6f7c-8314-5e02-a3df-483f3a1f4cfa&l=70

/home/vsts/work/1/s/src/Service.Tests/Configuration/McpRuntimeOptionsSerializationTests.cs(5,1): warning IDE0005: Using directive is unnecessary. [/home/vsts/work/1/s/src/Service.Tests/Azure.DataApiBuilder.Service.Tests.csproj]
/home/vsts/work/1/s/src/Azure.DataApiBuilder.Mcp/Core/McpServerConfiguration.cs(5,1): warning IDE0005: Using directive is unnecessary. [/home/vsts/work/1/s/src/Azure.DataApiBuilder.Mcp/Azure.DataApiBuilder.Mcp.csproj]

[Copilot]

@copilot, can you fix the warnings seen in this log as well:

https://dev.azure.com/sqldab/Data%20API%20builder%20Dependency%20Packages/Data%20API%20builder%20Dependency%20Packages%20Team/_build/res...

Fixed IDE0005 warnings by removing unnecessary using directives:

• Removed using System.Text.Json; from McpRuntimeOptionsSerializationTests.cs
• Removed using Azure.DataApiBuilder.Config.ObjectModel; from McpServerConfiguration.cs

Build succeeds with 0 errors and 0 warnings. All tests pass. Commit: 91a43a8

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[Aniruddh25]

@copilot, fix dotnet formatting error: McpStdioServer.cs(201,20): error IDE0059: Unnecessary assignment of a value to 'response

[Copilot]

@copilot, fix dotnet formatting error: McpStdioServer.cs(201,20): error IDE0059: Unnecessary assignment of a value to 'response

Fixed IDE0059 formatting error by removing the unused response variable assignment in McpStdioServer.cs. The variable was created but never used - only the result object is passed to WriteResult(). Build succeeds with 0 errors and 0 warnings. Commit: 6a631d5

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[Aniruddh25]

@copilot, fix this error: /home/vsts/work/1/s/src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs(164,21): error IDE0059: Unnecessary assignment of a value to 'requestId' [/home/vsts/work/1/s/src/Azure.DataApiBuilder.Mcp/Azure.DataApiBuilder.Mcp.csproj]

[Copilot]

@copilot, fix this error: `/home/vsts/work/1/s/src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs(164,21): error IDE0059: Unnecessary assignment of a value to 'requestId' [/home/vsts/work/1/s/src/Azu...

Fixed IDE0059 error by removing the unused requestId variable assignment. The variable was extracted from the id parameter but never used since WriteResult() is called with the original id parameter directly. Build succeeds with 0 errors and 0 warnings. Commit: 65a5c40

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).