feat(mcp-server): implement read-only SQL Server tools (M6)

Build out CloudEngAgent.Mcp.Server as a working MCP server exposing
four read-only SQL Server introspection tools over MCP/HTTP at /mcp:

  - list_databases  -> sys.databases (system DBs filtered)
  - list_tables     -> INFORMATION_SCHEMA.TABLES
  - describe_table  -> INFORMATION_SCHEMA.COLUMNS
  - sample_rows     -> SELECT TOP (n) * FROM <quoted>; (n capped at 100)

Safety model:
  - All values flow through SqlParameter; identifiers are allow-listed
    (^[A-Za-z_][A-Za-z0-9_]{0,127}\$) and verified against
    INFORMATION_SCHEMA before being bracket-quoted.
  - Errors return McpException with friendly messages; SqlException
    details are logged but never leaked through MCP.
  - Connection strings bind from Mcp:SqlServer:ConnectionStrings; the
    server still boots with no DBs configured (tools then return
    InvalidParams 'no connection configured').

Tests (CloudEngAgent.Mcp.Server.Tests):
  - SqlIdentifier unit tests (allow-list / injection rejection / quoting).
  - Testcontainers MsSql integration tests for all four tools, skipped
    automatically when 'docker info' fails (Windows-without-Docker safe).
  - WebApplicationFactory health-endpoint test that boots the server
    with no SQL config to confirm the DI graph stays optional.

README: new 'MCP Server (M6)' section + roadmap mark.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: razeone

CloudEngAgent.slnx

@@ -10,5 +10,6 @@
     <Project Path="tests/CloudEngAgent.Api.Tests/CloudEngAgent.Api.Tests.csproj" />
     <Project Path="tests/CloudEngAgent.Domain.Tests/CloudEngAgent.Domain.Tests.csproj" />
     <Project Path="tests/CloudEngAgent.Infrastructure.Tests/CloudEngAgent.Infrastructure.Tests.csproj" />
+    <Project Path="tests/CloudEngAgent.Mcp.Server.Tests/CloudEngAgent.Mcp.Server.Tests.csproj" />
   </Folder>
 </Solution>

README.md

@@ -251,6 +251,67 @@ Selection is driven by `WorkflowEngine:Mode`:
 
 Multi-agent orchestration via `Microsoft.Agents.AI.Workflows` (orchestrator → {explorer, analyst, …}) is the M5.2 follow-up; the M5.1 slice runs the workflow's entry persona as a single agent.
 
+## MCP Server (M6)
+
+`CloudEngAgent.Mcp.Server` is an ASP.NET Core 10 host that exposes a small set of **read-only** SQL Server introspection tools over the [Model Context Protocol](https://modelcontextprotocol.io). It is the server side of the MCP integration; the API project consumes it through the `IMcpToolRegistry` HTTP client (M7).
+
+### Run locally
+
+```powershell
+dotnet run --project src\CloudEngAgent.Mcp.Server
+```
+
+The server listens on a Kestrel-assigned port and exposes:
+
+| Method | Route      | Description                                                             |
+| ------ | ---------- | ----------------------------------------------------------------------- |
+| GET    | `/healthz` | Liveness probe.                                                         |
+| ANY    | `/mcp`     | MCP endpoint (`Streamable HTTP` transport from `ModelContextProtocol.AspNetCore`). |
+
+### Configuration
+
+Connection strings live under `Mcp:SqlServer:ConnectionStrings`. Each entry maps a logical database name (the value MCP callers pass as the `database` argument) to a SQL Server ADO.NET connection string. The first non-empty entry is used when callers omit `database`.
+
+```jsonc
+{
+  "Mcp": {
+    "SqlServer": {
+      "ConnectionStrings": {
+        "default": "Server=localhost,1433;Database=master;User Id=sa;Password=...;TrustServerCertificate=true",
+        "warehouse": "Server=warehouse.example.com;Database=dw;Authentication=Active Directory Default"
+      }
+    }
+  }
+}
+```
+
+For local development use user-secrets (the project ships with a user-secrets id):
+
+```powershell
+dotnet user-secrets set --project src\CloudEngAgent.Mcp.Server `
+  "Mcp:SqlServer:ConnectionStrings:default" `
+  "Server=localhost,1433;Database=master;User Id=sa;Password=Your_strong_Passw0rd!;TrustServerCertificate=true"
+```
+
+If no connection strings are configured the server still boots (and `/healthz` returns OK), but invoking any tool returns a structured `InvalidParams` error so callers get a clear "no connection configured" message.
+
+### Tool catalog
+
+| Tool             | Arguments                                                | Returns                                                                                  |
+| ---------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `list_databases` | `database?`                                              | User database names from `sys.databases` (system DBs excluded).                          |
+| `list_tables`    | `database?`                                              | `{schema, name}` for every base table in `INFORMATION_SCHEMA.TABLES`.                    |
+| `describe_table` | `schema`, `table`, `database?`                           | Columns from `INFORMATION_SCHEMA.COLUMNS` (name, type, nullability, length/precision).   |
+| `sample_rows`    | `schema`, `table`, `top` (1–100, default 10), `database?`| Up to N rows as `{column → value}` dictionaries. `SELECT TOP (n) * FROM ...`.            |
+
+### Safety model
+
+- All tool **values** are sent as `SqlParameter` instances — never concatenated into SQL.
+- All tool **identifiers** (schema/table) must pass a strict allow-list (`^[A-Za-z_][A-Za-z0-9_]{0,127}$`) **and** be present in `INFORMATION_SCHEMA` before being bracket-quoted and interpolated. Anything else is rejected up-front with `InvalidParams`.
+- `sample_rows` enforces a hard cap of 100 rows regardless of the requested `top`.
+- `SqlException` details are logged in full but only the SQL `Number` + the first line of the message are returned to the client; stack traces never leak through MCP.
+- All tools are **read-only** — there is no DDL/DML surface.
+
 ## API surface (v1)
 
 | Method | Route                                  | Description                                              |
@@ -339,7 +400,7 @@ See the in-session plan for the full P0/P1/P2 backlog. Milestones:
 - **M4 (YAML personas + hot reload)**: ✅ Complete — see the "Personas (M4)" section above.
 - **M5.1 (single-agent real LLM execution)**: ✅ Complete — see the "Workflow engine (M5.1)" section above.
 - **M5.2** (multi-agent graph orchestration via `Microsoft.Agents.AI.Workflows`)
-- **M6** (MCP SQL server)
+- **M6 (MCP SQL server)**: ✅ Complete — see the "MCP Server (M6)" section above.
 - **M7** (MCP client wiring)
 
 Forward-looking features (P3) include resumption, multi-tenancy, persona overlays, a workflow DSL, human-in-the-loop tool approval, cost/token telemetry, and saved investigations.

src/CloudEngAgent.Mcp.Server/Options/SqlServerOptions.cs

@@ -0,0 +1,16 @@
+namespace CloudEngAgent.Mcp.Server.Options;
+
+/// <summary>
+/// Bound from configuration section <c>Mcp:SqlServer</c>. Each entry in
+/// <see cref="ConnectionStrings"/> maps a logical database name (the value
+/// callers pass to MCP tools) → a SQL Server ADO.NET connection string.
+/// The first entry is the default when a tool's <c>database</c> argument is
+/// omitted or empty.
+/// </summary>
+public sealed class SqlServerOptions
+{
+    public const string SectionName = "Mcp:SqlServer";
+
+    public Dictionary<string, string> ConnectionStrings { get; init; } =
+        new(StringComparer.OrdinalIgnoreCase);
+}

src/CloudEngAgent.Mcp.Server/Program.cs

@@ -1,7 +1,27 @@
+using CloudEngAgent.Mcp.Server.Options;
+using CloudEngAgent.Mcp.Server.Sql;
+using CloudEngAgent.Mcp.Server.Tools;
+
 var builder = WebApplication.CreateBuilder(args);
 
+builder.Services
+    .AddOptions<SqlServerOptions>()
+    .Bind(builder.Configuration.GetSection(SqlServerOptions.SectionName));
+
+builder.Services.AddSingleton<ISqlConnectionFactory, SqlConnectionFactory>();
+builder.Services.AddSingleton<SqlServerTools>();
+
+builder.Services
+    .AddMcpServer()
+    .WithHttpTransport()
+    .WithToolsFromAssembly(typeof(Program).Assembly);
+
 var app = builder.Build();
 
 app.MapGet("/healthz", () => Results.Ok(new { status = "ok" }));
+app.MapMcp("/mcp");
 
 app.Run();
+
+// Exposed so WebApplicationFactory<Program> can boot the host in tests.
+public partial class Program;

src/CloudEngAgent.Mcp.Server/Sql/ISqlConnectionFactory.cs

@@ -0,0 +1,24 @@
+using Microsoft.Data.SqlClient;
+
+namespace CloudEngAgent.Mcp.Server.Sql;
+
+/// <summary>
+/// Resolves a logical database name (as configured in
+/// <c>Mcp:SqlServer:ConnectionStrings</c>) to an open
+/// <see cref="SqlConnection"/>. Centralized to keep tools unit-testable
+/// and to enforce a single connection-creation path.
+/// </summary>
+public interface ISqlConnectionFactory
+{
+    /// <summary>
+    /// The set of configured logical database names, in declaration order.
+    /// </summary>
+    IReadOnlyList<string> ConfiguredDatabases { get; }
+
+    /// <summary>
+    /// Opens a new <see cref="SqlConnection"/> for the named logical database.
+    /// If <paramref name="database"/> is null/empty the first configured
+    /// database is used.
+    /// </summary>
+    Task<SqlConnection> OpenAsync(string? database, CancellationToken cancellationToken);
+}

src/CloudEngAgent.Mcp.Server/Sql/SqlConnectionFactory.cs

@@ -0,0 +1,63 @@
+using CloudEngAgent.Mcp.Server.Options;
+using Microsoft.Data.SqlClient;
+using Microsoft.Extensions.Options;
+using ModelContextProtocol;
+
+namespace CloudEngAgent.Mcp.Server.Sql;
+
+public sealed class SqlConnectionFactory : ISqlConnectionFactory
+{
+    private readonly IReadOnlyList<KeyValuePair<string, string>> _entries;
+
+    public SqlConnectionFactory(IOptions<SqlServerOptions> options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        _entries = options.Value.ConnectionStrings
+            .Where(kvp => !string.IsNullOrWhiteSpace(kvp.Value))
+            .ToArray();
+    }
+
+    public IReadOnlyList<string> ConfiguredDatabases =>
+        _entries.Select(e => e.Key).ToArray();
+
+    public async Task<SqlConnection> OpenAsync(string? database, CancellationToken cancellationToken)
+    {
+        if (_entries.Count == 0)
+        {
+            throw new McpException(
+                "No SQL Server connection strings are configured. Set 'Mcp:SqlServer:ConnectionStrings' in configuration.",
+                McpErrorCode.InvalidParams);
+        }
+
+        string connectionString;
+        if (string.IsNullOrWhiteSpace(database))
+        {
+            connectionString = _entries[0].Value;
+        }
+        else
+        {
+            var match = _entries.FirstOrDefault(
+                e => string.Equals(e.Key, database, StringComparison.OrdinalIgnoreCase));
+            if (match.Value is null)
+            {
+                var known = string.Join(", ", _entries.Select(e => e.Key));
+                throw new McpException(
+                    $"Unknown database '{database}'. Configured: [{known}].",
+                    McpErrorCode.InvalidParams);
+            }
+            connectionString = match.Value;
+        }
+
+        var conn = new SqlConnection(connectionString);
+        try
+        {
+            await conn.OpenAsync(cancellationToken).ConfigureAwait(false);
+            return conn;
+        }
+        catch
+        {
+            await conn.DisposeAsync().ConfigureAwait(false);
+            throw;
+        }
+    }
+}

src/CloudEngAgent.Mcp.Server/Sql/SqlIdentifier.cs

@@ -0,0 +1,76 @@
+using System.Diagnostics.CodeAnalysis;
+using ModelContextProtocol;
+
+namespace CloudEngAgent.Mcp.Server.Sql;
+
+/// <summary>
+/// Helpers for validating and quoting SQL identifiers (schema/table/column
+/// names). The MCP tools never accept arbitrary SQL: every identifier passed
+/// in by a caller must pass <see cref="IsValid"/> AND be present in
+/// <c>INFORMATION_SCHEMA</c> before it is interpolated into a query.
+/// Values are always sent as parameters; identifiers go through
+/// <see cref="Quote(string)"/>.
+/// </summary>
+public static class SqlIdentifier
+{
+    private const int MaxLength = 128;
+
+    /// <summary>
+    /// Returns true when <paramref name="identifier"/> is a "safe" SQL
+    /// identifier: 1-128 chars, starts with a letter or underscore, and
+    /// contains only ASCII letters, digits, and underscores. We deliberately
+    /// reject anything else (dots, brackets, quotes, spaces, hyphens) so that
+    /// SQL-injection attempts via identifier slots are rejected before any
+    /// query is built.
+    /// </summary>
+    public static bool IsValid([NotNullWhen(true)] string? identifier)
+    {
+        if (string.IsNullOrEmpty(identifier) || identifier.Length > MaxLength)
+        {
+            return false;
+        }
+
+        var first = identifier[0];
+        if (!IsAsciiLetter(first) && first != '_')
+        {
+            return false;
+        }
+
+        for (var i = 1; i < identifier.Length; i++)
+        {
+            var c = identifier[i];
+            if (!IsAsciiLetter(c) && !IsAsciiDigit(c) && c != '_')
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /// <summary>
+    /// Validates and quotes <paramref name="identifier"/> using T-SQL bracket
+    /// quoting (e.g., <c>dbo</c> → <c>[dbo]</c>). Throws
+    /// <see cref="McpException"/> with <see cref="McpErrorCode.InvalidParams"/>
+    /// when the identifier fails <see cref="IsValid"/>.
+    /// </summary>
+    public static string Quote(string? identifier)
+    {
+        if (!IsValid(identifier))
+        {
+            throw new McpException(
+                $"Invalid SQL identifier '{identifier}'. Only ASCII letters, digits, and underscores are allowed (must start with a letter or underscore, max {MaxLength} chars).",
+                McpErrorCode.InvalidParams);
+        }
+
+        // Identifier is already constrained to [A-Za-z0-9_], so no embedded
+        // ']' is possible — bracket quoting is sufficient. Defense-in-depth:
+        // double any ']' anyway in case the validation surface ever changes.
+        return "[" + identifier.Replace("]", "]]", StringComparison.Ordinal) + "]";
+    }
+
+    private static bool IsAsciiLetter(char c) =>
+        (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+
+    private static bool IsAsciiDigit(char c) => c >= '0' && c <= '9';
+}