Add server-level description field to MCP runtime configuration

[Copilot]

Why make this change?

Closes #3015

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

MCP server response

• HandleInitialize() retrieves description from RuntimeConfig.Runtime.Mcp.Description
• Conditionally includes instructions in initialize response when non-empty

Example configuration:

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

How was this tested?

• Unit Tests

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):

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

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Enh]: Include server-level description value</issue_title>
<issue_description>## What?

Add a server-level description to Data API Builder so the SQL MCP Server can expose semantic guidance to MCP clients via the MCP initialize response.

Why?

Provide semantic guidance that will augment agent instructions or even provide agent instructions on the use of the server. MCP clients and agents need high-level behavioral context for the server, not just per-tool metadata. The MCP protocol exposes this through the top-level instructions field of the initialize response; DAB should surface a configurable value there.

Example value

Descriptions are drafted and provided by the user and cannot be inferred by the engine any other way.

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

How?

Configuration file

Add an optional description field under the existing MCP runtime configuration:

{
  "runtime": {
    "mcp": {
      "description": "text"
    }
  }
}

Command line

Extend dab configure to include the new configuration value:

dab configure --mcp-description "text"

Implementation

Add description to the MCP-related runtime configuration model (e.g., RuntimeConfig / McpOptions in the main config file, such as dab-config.json’s backing C# type). In the MCP server implementation (e.g., the class that handles MCP initialize, such as McpServer or equivalent), wire the config into the response:

var instructions = _runtimeConfig.Mcp?.Description;
var initializeResult = new InitializeResult
{
    Instructions = string.IsNullOrWhiteSpace(instructions) ? null : instructions,
    // ...existing fields...
};

Checklist

• Add runtime.mcp.description configuration field
• Add --mcp-description option to dab configure
• Ensure hot reload supports runtime.mcp.description
• Inject resolved value into initialize.instructions
• Add minimal unit tests (config load, hot reload, initialize payload)
• Update documentation (hand-off to @JerryNixon)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Enh]: Include server-level description value #3015

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[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.

[Copilot]

While CLI configuration tests exist, there are no unit tests verifying the serialization and deserialization of the description field in McpRuntimeOptions. Consider adding tests to verify that the description is correctly serialized to JSON and deserialized back, especially edge cases like empty strings, very long strings, and strings with special characters.

[Copilot]

The HandleInitialize method now includes logic to retrieve and include the description in the response, but there are no unit tests verifying this behavior. Consider adding tests to ensure that: 1) when a description is configured, it appears in the instructions field of the initialize response, 2) when no description is configured or it's empty, the instructions field is omitted from the response, and 3) the error handling path works correctly when the RuntimeConfigProvider service is unavailable or throws an exception.