diff --git a/colaflow-api/src/ColaFlow.API/ColaFlow.API.csproj b/colaflow-api/src/ColaFlow.API/ColaFlow.API.csproj index c623d6b..1d3af72 100644 --- a/colaflow-api/src/ColaFlow.API/ColaFlow.API.csproj +++ b/colaflow-api/src/ColaFlow.API/ColaFlow.API.csproj @@ -22,6 +22,7 @@ + diff --git a/colaflow-api/src/ColaFlow.API/Program.cs b/colaflow-api/src/ColaFlow.API/Program.cs index b4d4ffe..e817a03 100644 --- a/colaflow-api/src/ColaFlow.API/Program.cs +++ b/colaflow-api/src/ColaFlow.API/Program.cs @@ -6,6 +6,7 @@ using ColaFlow.API.Services; using ColaFlow.Modules.Identity.Application; using ColaFlow.Modules.Identity.Infrastructure; using ColaFlow.Modules.Identity.Infrastructure.Persistence; +using ColaFlow.Modules.Mcp.Infrastructure.Extensions; using ColaFlow.Modules.ProjectManagement.Infrastructure.Persistence; using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.EntityFrameworkCore; @@ -25,6 +26,9 @@ builder.Services.AddIssueManagementModule(builder.Configuration, builder.Environ builder.Services.AddIdentityApplication(); builder.Services.AddIdentityInfrastructure(builder.Configuration, builder.Environment); +// Register MCP Module +builder.Services.AddMcpModule(); + // Add Response Caching builder.Services.AddResponseCaching(); builder.Services.AddMemoryCache(); @@ -177,6 +181,9 @@ app.UsePerformanceLogging(); // Global exception handler (should be first in pipeline) app.UseExceptionHandler(); +// MCP middleware (before CORS and authentication) +app.UseMcpMiddleware(); + // Enable Response Compression (should be early in pipeline) app.UseResponseCompression(); diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/ColaFlow.Modules.Mcp.Application.csproj b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/ColaFlow.Modules.Mcp.Application.csproj new file mode 100644 index 0000000..6ff5bc7 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/ColaFlow.Modules.Mcp.Application.csproj @@ -0,0 +1,20 @@ + + + + net9.0 + enable + enable + ColaFlow.Modules.Mcp.Application + ColaFlow.Modules.Mcp.Application + + + + + + + + + + + + diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/IMcpMethodHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/IMcpMethodHandler.cs new file mode 100644 index 0000000..fb96921 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/IMcpMethodHandler.cs @@ -0,0 +1,22 @@ +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Interface for MCP method handlers +/// +public interface IMcpMethodHandler +{ + /// + /// The method name this handler supports + /// + string MethodName { get; } + + /// + /// Handles the MCP method request + /// + /// Request parameters + /// Cancellation token + /// Method result + Task HandleAsync(object? @params, CancellationToken cancellationToken); +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/IMcpProtocolHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/IMcpProtocolHandler.cs new file mode 100644 index 0000000..562a8b2 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/IMcpProtocolHandler.cs @@ -0,0 +1,17 @@ +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Interface for MCP protocol handler +/// +public interface IMcpProtocolHandler +{ + /// + /// Handles a JSON-RPC 2.0 request + /// + /// JSON-RPC request + /// Cancellation token + /// JSON-RPC response + Task HandleRequestAsync(JsonRpcRequest request, CancellationToken cancellationToken); +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/InitializeMethodHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/InitializeMethodHandler.cs new file mode 100644 index 0000000..6288d57 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/InitializeMethodHandler.cs @@ -0,0 +1,67 @@ +using System.Text.Json; +using ColaFlow.Modules.Mcp.Contracts.Mcp; +using Microsoft.Extensions.Logging; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Handler for the 'initialize' MCP method +/// +public class InitializeMethodHandler : IMcpMethodHandler +{ + private readonly ILogger _logger; + + public string MethodName => "initialize"; + + public InitializeMethodHandler(ILogger logger) + { + _logger = logger; + } + + public Task HandleAsync(object? @params, CancellationToken cancellationToken) + { + try + { + // Parse initialize request + McpInitializeRequest? initRequest = null; + if (@params != null) + { + var json = JsonSerializer.Serialize(@params); + initRequest = JsonSerializer.Deserialize(json); + } + + _logger.LogInformation( + "MCP Initialize handshake received. Client: {ClientName} {ClientVersion}, Protocol: {ProtocolVersion}", + initRequest?.ClientInfo?.Name ?? "Unknown", + initRequest?.ClientInfo?.Version ?? "Unknown", + initRequest?.ProtocolVersion ?? "Unknown"); + + // Validate protocol version + if (initRequest?.ProtocolVersion != "1.0") + { + _logger.LogWarning("Unsupported protocol version: {ProtocolVersion}", initRequest?.ProtocolVersion); + } + + // Create initialize response + var response = new McpInitializeResponse + { + ProtocolVersion = "1.0", + ServerInfo = new McpServerInfo + { + Name = "ColaFlow MCP Server", + Version = "1.0.0" + }, + Capabilities = McpServerCapabilities.CreateDefault() + }; + + _logger.LogInformation("MCP Initialize handshake completed successfully"); + + return Task.FromResult(response); + } + catch (Exception ex) + { + _logger.LogError(ex, "Error handling initialize request"); + throw; + } + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/McpProtocolHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/McpProtocolHandler.cs new file mode 100644 index 0000000..2568b1f --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/McpProtocolHandler.cs @@ -0,0 +1,70 @@ +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; +using Microsoft.Extensions.Logging; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Main MCP protocol handler that routes requests to method handlers +/// +public class McpProtocolHandler : IMcpProtocolHandler +{ + private readonly ILogger _logger; + private readonly Dictionary _methodHandlers; + + public McpProtocolHandler( + ILogger logger, + IEnumerable methodHandlers) + { + _logger = logger; + _methodHandlers = methodHandlers.ToDictionary(h => h.MethodName, h => h); + + _logger.LogInformation("MCP Protocol Handler initialized with {Count} method handlers: {Methods}", + _methodHandlers.Count, + string.Join(", ", _methodHandlers.Keys)); + } + + public async Task HandleRequestAsync( + JsonRpcRequest request, + CancellationToken cancellationToken) + { + try + { + // Validate request structure + if (!request.IsValid(out var errorMessage)) + { + _logger.LogWarning("Invalid JSON-RPC request: {ErrorMessage}", errorMessage); + return JsonRpcResponse.InvalidRequest(errorMessage, request.Id); + } + + _logger.LogDebug("Processing MCP request: method={Method}, id={Id}, isNotification={IsNotification}", + request.Method, request.Id, request.IsNotification); + + // Find method handler + if (!_methodHandlers.TryGetValue(request.Method, out var handler)) + { + _logger.LogWarning("Method not found: {Method}", request.Method); + return JsonRpcResponse.MethodNotFound(request.Method, request.Id); + } + + // Execute method handler + var result = await handler.HandleAsync(request.Params, cancellationToken); + + _logger.LogDebug("MCP request processed successfully: method={Method}, id={Id}", + request.Method, request.Id); + + // Return success response + return JsonRpcResponse.Success(result, request.Id); + } + catch (ArgumentException ex) + { + _logger.LogWarning(ex, "Invalid parameters for method {Method}", request.Method); + return JsonRpcResponse.InvalidParams(ex.Message, request.Id); + } + catch (Exception ex) + { + _logger.LogError(ex, "Internal error processing MCP request: method={Method}, id={Id}", + request.Method, request.Id); + return JsonRpcResponse.InternalError(ex.Message, request.Id); + } + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ResourcesListMethodHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ResourcesListMethodHandler.cs new file mode 100644 index 0000000..4dc4da2 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ResourcesListMethodHandler.cs @@ -0,0 +1,32 @@ +using Microsoft.Extensions.Logging; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Handler for the 'resources/list' MCP method +/// +public class ResourcesListMethodHandler : IMcpMethodHandler +{ + private readonly ILogger _logger; + + public string MethodName => "resources/list"; + + public ResourcesListMethodHandler(ILogger logger) + { + _logger = logger; + } + + public Task HandleAsync(object? @params, CancellationToken cancellationToken) + { + _logger.LogDebug("Handling resources/list request"); + + // TODO: Implement in Story 5.5 (Core MCP Resources) + // For now, return empty list + var response = new + { + resources = Array.Empty() + }; + + return Task.FromResult(response); + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ToolsCallMethodHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ToolsCallMethodHandler.cs new file mode 100644 index 0000000..631a503 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ToolsCallMethodHandler.cs @@ -0,0 +1,27 @@ +using Microsoft.Extensions.Logging; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Handler for the 'tools/call' MCP method +/// +public class ToolsCallMethodHandler : IMcpMethodHandler +{ + private readonly ILogger _logger; + + public string MethodName => "tools/call"; + + public ToolsCallMethodHandler(ILogger logger) + { + _logger = logger; + } + + public Task HandleAsync(object? @params, CancellationToken cancellationToken) + { + _logger.LogDebug("Handling tools/call request"); + + // TODO: Implement in Story 5.11 (Core MCP Tools) + // For now, return error + throw new NotImplementedException("tools/call is not yet implemented. Will be added in Story 5.11"); + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ToolsListMethodHandler.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ToolsListMethodHandler.cs new file mode 100644 index 0000000..89fc3bc --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Application/Handlers/ToolsListMethodHandler.cs @@ -0,0 +1,32 @@ +using Microsoft.Extensions.Logging; + +namespace ColaFlow.Modules.Mcp.Application.Handlers; + +/// +/// Handler for the 'tools/list' MCP method +/// +public class ToolsListMethodHandler : IMcpMethodHandler +{ + private readonly ILogger _logger; + + public string MethodName => "tools/list"; + + public ToolsListMethodHandler(ILogger logger) + { + _logger = logger; + } + + public Task HandleAsync(object? @params, CancellationToken cancellationToken) + { + _logger.LogDebug("Handling tools/list request"); + + // TODO: Implement in Story 5.11 (Core MCP Tools) + // For now, return empty list + var response = new + { + tools = Array.Empty() + }; + + return Task.FromResult(response); + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/ColaFlow.Modules.Mcp.Contracts.csproj b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/ColaFlow.Modules.Mcp.Contracts.csproj new file mode 100644 index 0000000..0ca8499 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/ColaFlow.Modules.Mcp.Contracts.csproj @@ -0,0 +1,11 @@ + + + + net9.0 + enable + enable + ColaFlow.Modules.Mcp.Contracts + ColaFlow.Modules.Mcp.Contracts + + + diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcError.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcError.cs new file mode 100644 index 0000000..38f4ed3 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcError.cs @@ -0,0 +1,102 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.JsonRpc; + +/// +/// JSON-RPC 2.0 error object +/// +public class JsonRpcError +{ + /// + /// A Number that indicates the error type that occurred + /// + [JsonPropertyName("code")] + public int Code { get; set; } + + /// + /// A String providing a short description of the error + /// + [JsonPropertyName("message")] + public string Message { get; set; } = string.Empty; + + /// + /// A Primitive or Structured value that contains additional information about the error (optional) + /// + [JsonPropertyName("data")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public object? Data { get; set; } + + /// + /// Creates a new JSON-RPC error + /// + public JsonRpcError(JsonRpcErrorCode code, string message, object? data = null) + { + Code = (int)code; + Message = message; + Data = data; + } + + /// + /// Creates a new JSON-RPC error with custom code + /// + public JsonRpcError(int code, string message, object? data = null) + { + Code = code; + Message = message; + Data = data; + } + + /// + /// Creates a ParseError (-32700) + /// + public static JsonRpcError ParseError(string? details = null) => + new(JsonRpcErrorCode.ParseError, "Parse error", details); + + /// + /// Creates an InvalidRequest error (-32600) + /// + public static JsonRpcError InvalidRequest(string? details = null) => + new(JsonRpcErrorCode.InvalidRequest, "Invalid Request", details); + + /// + /// Creates a MethodNotFound error (-32601) + /// + public static JsonRpcError MethodNotFound(string method) => + new(JsonRpcErrorCode.MethodNotFound, $"Method not found: {method}"); + + /// + /// Creates an InvalidParams error (-32602) + /// + public static JsonRpcError InvalidParams(string? details = null) => + new(JsonRpcErrorCode.InvalidParams, "Invalid params", details); + + /// + /// Creates an InternalError (-32603) + /// + public static JsonRpcError InternalError(string? details = null) => + new(JsonRpcErrorCode.InternalError, "Internal error", details); + + /// + /// Creates an Unauthorized error (-32001) + /// + public static JsonRpcError Unauthorized(string? details = null) => + new(JsonRpcErrorCode.Unauthorized, "Unauthorized", details); + + /// + /// Creates a Forbidden error (-32002) + /// + public static JsonRpcError Forbidden(string? details = null) => + new(JsonRpcErrorCode.Forbidden, "Forbidden", details); + + /// + /// Creates a NotFound error (-32003) + /// + public static JsonRpcError NotFound(string? details = null) => + new(JsonRpcErrorCode.NotFound, "Not found", details); + + /// + /// Creates a ValidationFailed error (-32004) + /// + public static JsonRpcError ValidationFailed(string? details = null) => + new(JsonRpcErrorCode.ValidationFailed, "Validation failed", details); +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcErrorCode.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcErrorCode.cs new file mode 100644 index 0000000..be212fc --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcErrorCode.cs @@ -0,0 +1,52 @@ +namespace ColaFlow.Modules.Mcp.Contracts.JsonRpc; + +/// +/// JSON-RPC 2.0 error codes +/// +public enum JsonRpcErrorCode +{ + /// + /// Invalid JSON was received by the server (-32700) + /// + ParseError = -32700, + + /// + /// The JSON sent is not a valid Request object (-32600) + /// + InvalidRequest = -32600, + + /// + /// The method does not exist or is not available (-32601) + /// + MethodNotFound = -32601, + + /// + /// Invalid method parameter(s) (-32602) + /// + InvalidParams = -32602, + + /// + /// Internal JSON-RPC error (-32603) + /// + InternalError = -32603, + + /// + /// Authentication failed (-32001) + /// + Unauthorized = -32001, + + /// + /// Authorization failed (-32002) + /// + Forbidden = -32002, + + /// + /// Resource not found (-32003) + /// + NotFound = -32003, + + /// + /// Request validation failed (-32004) + /// + ValidationFailed = -32004 +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcRequest.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcRequest.cs new file mode 100644 index 0000000..15a6ac3 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcRequest.cs @@ -0,0 +1,62 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.JsonRpc; + +/// +/// JSON-RPC 2.0 request object +/// +public class JsonRpcRequest +{ + /// + /// A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0" + /// + [JsonPropertyName("jsonrpc")] + public string JsonRpc { get; set; } = "2.0"; + + /// + /// A String containing the name of the method to be invoked + /// + [JsonPropertyName("method")] + public string Method { get; set; } = string.Empty; + + /// + /// A Structured value that holds the parameter values to be used during the invocation of the method (optional) + /// + [JsonPropertyName("params")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public object? Params { get; set; } + + /// + /// An identifier established by the Client. If not included, it's a notification (optional) + /// + [JsonPropertyName("id")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public object? Id { get; set; } + + /// + /// Indicates if this is a notification (no response expected) + /// + [JsonIgnore] + public bool IsNotification => Id == null; + + /// + /// Validates the JSON-RPC request structure + /// + public bool IsValid(out string? errorMessage) + { + if (JsonRpc != "2.0") + { + errorMessage = "jsonrpc must be exactly '2.0'"; + return false; + } + + if (string.IsNullOrWhiteSpace(Method)) + { + errorMessage = "method is required"; + return false; + } + + errorMessage = null; + return true; + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcResponse.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcResponse.cs new file mode 100644 index 0000000..9101eef --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/JsonRpc/JsonRpcResponse.cs @@ -0,0 +1,100 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.JsonRpc; + +/// +/// JSON-RPC 2.0 response object +/// +public class JsonRpcResponse +{ + /// + /// A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0" + /// + [JsonPropertyName("jsonrpc")] + public string JsonRpc { get; set; } = "2.0"; + + /// + /// This member is REQUIRED on success. Must not exist if there was an error + /// + [JsonPropertyName("result")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public object? Result { get; set; } + + /// + /// This member is REQUIRED on error. Must not exist if there was no error + /// + [JsonPropertyName("error")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public JsonRpcError? Error { get; set; } + + /// + /// This member is REQUIRED. It MUST be the same as the value of the id member in the Request Object. + /// If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null. + /// + [JsonPropertyName("id")] + public object? Id { get; set; } + + /// + /// Creates a success response + /// + public static JsonRpcResponse Success(object? result, object? id) + { + return new JsonRpcResponse + { + Result = result, + Id = id + }; + } + + /// + /// Creates an error response + /// + public static JsonRpcResponse CreateError(JsonRpcError error, object? id) + { + return new JsonRpcResponse + { + Error = error, + Id = id + }; + } + + /// + /// Creates a ParseError response (id is null because request couldn't be parsed) + /// + public static JsonRpcResponse ParseError(string? details = null) + { + return CreateError(JsonRpcError.ParseError(details), null); + } + + /// + /// Creates an InvalidRequest response + /// + public static JsonRpcResponse InvalidRequest(string? details = null, object? id = null) + { + return CreateError(JsonRpcError.InvalidRequest(details), id); + } + + /// + /// Creates a MethodNotFound response + /// + public static JsonRpcResponse MethodNotFound(string method, object? id) + { + return CreateError(JsonRpcError.MethodNotFound(method), id); + } + + /// + /// Creates an InvalidParams response + /// + public static JsonRpcResponse InvalidParams(string? details, object? id) + { + return CreateError(JsonRpcError.InvalidParams(details), id); + } + + /// + /// Creates an InternalError response + /// + public static JsonRpcResponse InternalError(string? details, object? id) + { + return CreateError(JsonRpcError.InternalError(details), id); + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpClientInfo.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpClientInfo.cs new file mode 100644 index 0000000..95fa0aa --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpClientInfo.cs @@ -0,0 +1,21 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.Mcp; + +/// +/// Information about the MCP client +/// +public class McpClientInfo +{ + /// + /// Name of the client application + /// + [JsonPropertyName("name")] + public string Name { get; set; } = string.Empty; + + /// + /// Version of the client application + /// + [JsonPropertyName("version")] + public string Version { get; set; } = string.Empty; +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpInitializeRequest.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpInitializeRequest.cs new file mode 100644 index 0000000..27366e8 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpInitializeRequest.cs @@ -0,0 +1,21 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.Mcp; + +/// +/// MCP initialize request parameters +/// +public class McpInitializeRequest +{ + /// + /// Protocol version requested by the client + /// + [JsonPropertyName("protocolVersion")] + public string ProtocolVersion { get; set; } = string.Empty; + + /// + /// Information about the client + /// + [JsonPropertyName("clientInfo")] + public McpClientInfo ClientInfo { get; set; } = new(); +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpInitializeResponse.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpInitializeResponse.cs new file mode 100644 index 0000000..5eda340 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpInitializeResponse.cs @@ -0,0 +1,27 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.Mcp; + +/// +/// MCP initialize response +/// +public class McpInitializeResponse +{ + /// + /// Protocol version supported by the server + /// + [JsonPropertyName("protocolVersion")] + public string ProtocolVersion { get; set; } = "1.0"; + + /// + /// Information about the server + /// + [JsonPropertyName("serverInfo")] + public McpServerInfo ServerInfo { get; set; } = new(); + + /// + /// Server capabilities + /// + [JsonPropertyName("capabilities")] + public McpServerCapabilities Capabilities { get; set; } = McpServerCapabilities.CreateDefault(); +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpServerCapabilities.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpServerCapabilities.cs new file mode 100644 index 0000000..93a2067 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpServerCapabilities.cs @@ -0,0 +1,79 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.Mcp; + +/// +/// MCP server capabilities +/// +public class McpServerCapabilities +{ + /// + /// Resources capability + /// + [JsonPropertyName("resources")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public McpResourcesCapability? Resources { get; set; } + + /// + /// Tools capability + /// + [JsonPropertyName("tools")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public McpToolsCapability? Tools { get; set; } + + /// + /// Prompts capability + /// + [JsonPropertyName("prompts")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public McpPromptsCapability? Prompts { get; set; } + + /// + /// Creates default server capabilities with all features supported + /// + public static McpServerCapabilities CreateDefault() + { + return new McpServerCapabilities + { + Resources = new McpResourcesCapability { Supported = true }, + Tools = new McpToolsCapability { Supported = true }, + Prompts = new McpPromptsCapability { Supported = true } + }; + } +} + +/// +/// Resources capability +/// +public class McpResourcesCapability +{ + /// + /// Indicates if resources are supported + /// + [JsonPropertyName("supported")] + public bool Supported { get; set; } +} + +/// +/// Tools capability +/// +public class McpToolsCapability +{ + /// + /// Indicates if tools are supported + /// + [JsonPropertyName("supported")] + public bool Supported { get; set; } +} + +/// +/// Prompts capability +/// +public class McpPromptsCapability +{ + /// + /// Indicates if prompts are supported + /// + [JsonPropertyName("supported")] + public bool Supported { get; set; } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpServerInfo.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpServerInfo.cs new file mode 100644 index 0000000..4550e71 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Contracts/Mcp/McpServerInfo.cs @@ -0,0 +1,21 @@ +using System.Text.Json.Serialization; + +namespace ColaFlow.Modules.Mcp.Contracts.Mcp; + +/// +/// Information about the MCP server +/// +public class McpServerInfo +{ + /// + /// Name of the server application + /// + [JsonPropertyName("name")] + public string Name { get; set; } = "ColaFlow MCP Server"; + + /// + /// Version of the server application + /// + [JsonPropertyName("version")] + public string Version { get; set; } = "1.0.0"; +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Domain/ColaFlow.Modules.Mcp.Domain.csproj b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Domain/ColaFlow.Modules.Mcp.Domain.csproj new file mode 100644 index 0000000..3bc0e5b --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Domain/ColaFlow.Modules.Mcp.Domain.csproj @@ -0,0 +1,15 @@ + + + + net9.0 + enable + enable + ColaFlow.Modules.Mcp.Domain + ColaFlow.Modules.Mcp.Domain + + + + + + + diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/ColaFlow.Modules.Mcp.Infrastructure.csproj b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/ColaFlow.Modules.Mcp.Infrastructure.csproj new file mode 100644 index 0000000..36cbf83 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/ColaFlow.Modules.Mcp.Infrastructure.csproj @@ -0,0 +1,19 @@ + + + + net9.0 + enable + enable + ColaFlow.Modules.Mcp.Infrastructure + ColaFlow.Modules.Mcp.Infrastructure + + + + + + + + + + + diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Extensions/McpServiceExtensions.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Extensions/McpServiceExtensions.cs new file mode 100644 index 0000000..28da6ea --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Extensions/McpServiceExtensions.cs @@ -0,0 +1,38 @@ +using ColaFlow.Modules.Mcp.Application.Handlers; +using ColaFlow.Modules.Mcp.Infrastructure.Middleware; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; + +namespace ColaFlow.Modules.Mcp.Infrastructure.Extensions; + +/// +/// Extension methods for registering MCP services +/// +public static class McpServiceExtensions +{ + /// + /// Registers MCP module services + /// + public static IServiceCollection AddMcpModule(this IServiceCollection services) + { + // Register protocol handler + services.AddScoped(); + + // Register method handlers + services.AddScoped(); + services.AddScoped(); + services.AddScoped(); + services.AddScoped(); + + return services; + } + + /// + /// Adds MCP middleware to the application pipeline + /// + public static IApplicationBuilder UseMcpMiddleware(this IApplicationBuilder app) + { + app.UseMiddleware(); + return app; + } +} diff --git a/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Middleware/McpMiddleware.cs b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Middleware/McpMiddleware.cs new file mode 100644 index 0000000..eea1428 --- /dev/null +++ b/colaflow-api/src/Modules/Mcp/ColaFlow.Modules.Mcp.Infrastructure/Middleware/McpMiddleware.cs @@ -0,0 +1,107 @@ +using System.Text.Json; +using ColaFlow.Modules.Mcp.Application.Handlers; +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.Logging; + +namespace ColaFlow.Modules.Mcp.Infrastructure.Middleware; + +/// +/// Middleware for handling MCP JSON-RPC 2.0 requests +/// +public class McpMiddleware +{ + private readonly RequestDelegate _next; + private readonly ILogger _logger; + + public McpMiddleware(RequestDelegate next, ILogger logger) + { + _next = next; + _logger = logger; + } + + public async Task InvokeAsync(HttpContext context, IMcpProtocolHandler protocolHandler) + { + // Only handle POST requests to /mcp endpoint + if (context.Request.Method != "POST" || !context.Request.Path.StartsWithSegments("/mcp")) + { + await _next(context); + return; + } + + _logger.LogDebug("MCP request received from {RemoteIp}", context.Connection.RemoteIpAddress); + + JsonRpcResponse? response = null; + JsonRpcRequest? request = null; + + try + { + // Read request body + using var reader = new StreamReader(context.Request.Body); + var requestBody = await reader.ReadToEndAsync(); + + _logger.LogTrace("MCP request body: {RequestBody}", requestBody); + + // Parse JSON-RPC request + try + { + request = JsonSerializer.Deserialize(requestBody); + if (request == null) + { + response = JsonRpcResponse.ParseError("Request is null"); + } + } + catch (JsonException ex) + { + _logger.LogWarning(ex, "Failed to parse JSON-RPC request"); + response = JsonRpcResponse.ParseError(ex.Message); + } + + // Process request if parsing succeeded + if (response == null && request != null) + { + response = await protocolHandler.HandleRequestAsync(request, context.RequestAborted); + } + + // Send response (unless it's a notification) + if (response != null && request?.IsNotification != true) + { + context.Response.ContentType = "application/json"; + context.Response.StatusCode = 200; + + var responseJson = JsonSerializer.Serialize(response, new JsonSerializerOptions + { + PropertyNamingPolicy = JsonNamingPolicy.CamelCase, + DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull + }); + + _logger.LogTrace("MCP response: {ResponseJson}", responseJson); + + await context.Response.WriteAsync(responseJson); + } + else if (request?.IsNotification == true) + { + // For notifications, return 204 No Content + context.Response.StatusCode = 204; + _logger.LogDebug("Notification processed, no response sent"); + } + } + catch (Exception ex) + { + _logger.LogError(ex, "Unhandled exception in MCP middleware"); + + // Send internal error response (id is null because we don't know the request id) + response = JsonRpcResponse.InternalError("Unhandled server error", null); + context.Response.ContentType = "application/json"; + context.Response.StatusCode = 500; + + var responseJson = JsonSerializer.Serialize(response, new JsonSerializerOptions + { + PropertyNamingPolicy = JsonNamingPolicy.CamelCase, + DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull + }); + + await context.Response.WriteAsync(responseJson); + } + } +} diff --git a/colaflow-api/tests/ColaFlow.IntegrationTests/Mcp/McpProtocolIntegrationTests.cs b/colaflow-api/tests/ColaFlow.IntegrationTests/Mcp/McpProtocolIntegrationTests.cs new file mode 100644 index 0000000..69a175a --- /dev/null +++ b/colaflow-api/tests/ColaFlow.IntegrationTests/Mcp/McpProtocolIntegrationTests.cs @@ -0,0 +1,287 @@ +using System.Net; +using System.Net.Http.Json; +using System.Text; +using System.Text.Json; +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; +using ColaFlow.Modules.Mcp.Contracts.Mcp; +using FluentAssertions; +using Microsoft.AspNetCore.Mvc.Testing; + +namespace ColaFlow.IntegrationTests.Mcp; + +/// +/// Integration tests for MCP Protocol endpoint +/// +public class McpProtocolIntegrationTests : IClassFixture> +{ + private readonly HttpClient _client; + + public McpProtocolIntegrationTests(WebApplicationFactory factory) + { + _client = factory.CreateClient(); + } + + [Fact] + public async Task McpEndpoint_WithInitializeRequest_ReturnsSuccess() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "initialize", + Params = new + { + protocolVersion = "1.0", + clientInfo = new + { + name = "Test Client", + version = "1.0.0" + } + }, + Id = 1 + }; + + var json = JsonSerializer.Serialize(request, new JsonSerializerOptions + { + PropertyNamingPolicy = JsonNamingPolicy.CamelCase + }); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + + // Assert + response.StatusCode.Should().Be(HttpStatusCode.OK); + response.Content.Headers.ContentType?.MediaType.Should().Be("application/json"); + + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + rpcResponse.Should().NotBeNull(); + rpcResponse!.JsonRpc.Should().Be("2.0"); + rpcResponse.Id.Should().NotBeNull(); + rpcResponse.Error.Should().BeNull(); + rpcResponse.Result.Should().NotBeNull(); + } + + [Fact] + public async Task McpEndpoint_InitializeResponse_ContainsServerInfo() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "initialize", + Params = new + { + protocolVersion = "1.0", + clientInfo = new { name = "Test", version = "1.0" } + }, + Id = 1 + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + // Assert + rpcResponse.GetProperty("result").TryGetProperty("serverInfo", out var serverInfo).Should().BeTrue(); + serverInfo.GetProperty("name").GetString().Should().Be("ColaFlow MCP Server"); + serverInfo.GetProperty("version").GetString().Should().NotBeNullOrEmpty(); + } + + [Fact] + public async Task McpEndpoint_InitializeResponse_ContainsCapabilities() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "initialize", + Params = new + { + protocolVersion = "1.0", + clientInfo = new { name = "Test", version = "1.0" } + }, + Id = 1 + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + // Assert + rpcResponse.GetProperty("result").TryGetProperty("capabilities", out var capabilities).Should().BeTrue(); + capabilities.TryGetProperty("resources", out var resources).Should().BeTrue(); + resources.GetProperty("supported").GetBoolean().Should().BeTrue(); + capabilities.TryGetProperty("tools", out var tools).Should().BeTrue(); + tools.GetProperty("supported").GetBoolean().Should().BeTrue(); + capabilities.TryGetProperty("prompts", out var prompts).Should().BeTrue(); + prompts.GetProperty("supported").GetBoolean().Should().BeTrue(); + } + + [Fact] + public async Task McpEndpoint_WithInvalidJson_ReturnsParseError() + { + // Arrange + var invalidJson = "{ invalid json }"; + var content = new StringContent(invalidJson, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + + // Assert + response.StatusCode.Should().Be(HttpStatusCode.OK); + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + rpcResponse.Should().NotBeNull(); + rpcResponse!.Error.Should().NotBeNull(); + rpcResponse.Error!.Code.Should().Be((int)JsonRpcErrorCode.ParseError); + } + + [Fact] + public async Task McpEndpoint_WithUnknownMethod_ReturnsMethodNotFound() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "unknown_method", + Id = 1 + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + // Assert + rpcResponse.Should().NotBeNull(); + rpcResponse!.Error.Should().NotBeNull(); + rpcResponse.Error!.Code.Should().Be((int)JsonRpcErrorCode.MethodNotFound); + rpcResponse.Error.Message.Should().Contain("unknown_method"); + } + + [Fact] + public async Task McpEndpoint_WithResourcesList_ReturnsEmptyList() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "resources/list", + Id = 1 + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + + // Assert + response.StatusCode.Should().Be(HttpStatusCode.OK); + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + rpcResponse.TryGetProperty("result", out var result).Should().BeTrue(); + result.TryGetProperty("resources", out var resources).Should().BeTrue(); + resources.GetArrayLength().Should().Be(0); + } + + [Fact] + public async Task McpEndpoint_WithToolsList_ReturnsEmptyList() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "tools/list", + Id = 1 + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + + // Assert + response.StatusCode.Should().Be(HttpStatusCode.OK); + var responseJson = await response.Content.ReadAsStringAsync(); + var rpcResponse = JsonSerializer.Deserialize(responseJson); + + rpcResponse.TryGetProperty("result", out var result).Should().BeTrue(); + result.TryGetProperty("tools", out var tools).Should().BeTrue(); + tools.GetArrayLength().Should().Be(0); + } + + [Fact] + public async Task McpEndpoint_WithNotification_Returns204NoContent() + { + // Arrange - Notification has no "id" field + var request = new + { + jsonrpc = "2.0", + method = "notification_method", + @params = new { test = "value" } + // No "id" field = notification + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Act + var response = await _client.PostAsync("/mcp", content); + + // Assert + // Notifications should return 204 or not return a response + // For now, check that it doesn't fail + response.StatusCode.Should().BeOneOf(HttpStatusCode.NoContent, HttpStatusCode.OK); + } + + [Fact] + public async Task McpEndpoint_ProtocolOverhead_IsLessThan5Milliseconds() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "initialize", + Params = new + { + protocolVersion = "1.0", + clientInfo = new { name = "Test", version = "1.0" } + }, + Id = 1 + }; + + var json = JsonSerializer.Serialize(request); + var content = new StringContent(json, Encoding.UTF8, "application/json"); + + // Warmup + await _client.PostAsync("/mcp", content); + + // Act + var stopwatch = System.Diagnostics.Stopwatch.StartNew(); + var response = await _client.PostAsync("/mcp", new StringContent(json, Encoding.UTF8, "application/json")); + stopwatch.Stop(); + + // Assert + response.StatusCode.Should().Be(HttpStatusCode.OK); + // Note: This includes network overhead in tests, actual protocol overhead will be much less + stopwatch.ElapsedMilliseconds.Should().BeLessThan(100); // Generous for integration test + } +} diff --git a/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/ColaFlow.Modules.Mcp.Tests.csproj b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/ColaFlow.Modules.Mcp.Tests.csproj new file mode 100644 index 0000000..c5e1d3e --- /dev/null +++ b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/ColaFlow.Modules.Mcp.Tests.csproj @@ -0,0 +1,28 @@ + + + + net9.0 + enable + enable + false + + + + + + + + + + + + + + + + + + + + + diff --git a/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Contracts/JsonRpcRequestTests.cs b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Contracts/JsonRpcRequestTests.cs new file mode 100644 index 0000000..e573bb5 --- /dev/null +++ b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Contracts/JsonRpcRequestTests.cs @@ -0,0 +1,160 @@ +using System.Text.Json; +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; +using FluentAssertions; + +namespace ColaFlow.Modules.Mcp.Tests.Contracts; + +/// +/// Unit tests for JsonRpcRequest +/// +public class JsonRpcRequestTests +{ + [Fact] + public void IsValid_WithValidRequest_ReturnsTrue() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Id = 1 + }; + + // Act + var isValid = request.IsValid(out var errorMessage); + + // Assert + isValid.Should().BeTrue(); + errorMessage.Should().BeNull(); + } + + [Fact] + public void IsValid_WithInvalidJsonRpcVersion_ReturnsFalse() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "1.0", + Method = "test_method" + }; + + // Act + var isValid = request.IsValid(out var errorMessage); + + // Assert + isValid.Should().BeFalse(); + errorMessage.Should().Contain("jsonrpc must be exactly '2.0'"); + } + + [Fact] + public void IsValid_WithEmptyMethod_ReturnsFalse() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "" + }; + + // Act + var isValid = request.IsValid(out var errorMessage); + + // Assert + isValid.Should().BeFalse(); + errorMessage.Should().Contain("method is required"); + } + + [Fact] + public void IsNotification_WithNoId_ReturnsTrue() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "notification_method", + Id = null + }; + + // Act & Assert + request.IsNotification.Should().BeTrue(); + } + + [Fact] + public void IsNotification_WithId_ReturnsFalse() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "regular_method", + Id = 1 + }; + + // Act & Assert + request.IsNotification.Should().BeFalse(); + } + + [Fact] + public void Deserialize_WithValidJson_CreatesRequest() + { + // Arrange + var json = @"{ + ""jsonrpc"": ""2.0"", + ""method"": ""test_method"", + ""params"": { ""key"": ""value"" }, + ""id"": 1 + }"; + + // Act + var request = JsonSerializer.Deserialize(json); + + // Assert + request.Should().NotBeNull(); + request!.JsonRpc.Should().Be("2.0"); + request.Method.Should().Be("test_method"); + request.Params.Should().NotBeNull(); + // Id can be number or string, System.Text.Json deserializes number to JsonElement + // Just check it's not null + request.Id.Should().NotBeNull(); + } + + [Fact] + public void Deserialize_WithoutParams_CreatesRequestWithNullParams() + { + // Arrange + var json = @"{ + ""jsonrpc"": ""2.0"", + ""method"": ""test_method"", + ""id"": 1 + }"; + + // Act + var request = JsonSerializer.Deserialize(json); + + // Assert + request.Should().NotBeNull(); + request!.Params.Should().BeNull(); + } + + [Fact] + public void Serialize_IncludesAllFields() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Params = new { key = "value" }, + Id = 1 + }; + + // Act + var json = JsonSerializer.Serialize(request); + + // Assert + json.Should().Contain("\"jsonrpc\":\"2.0\""); + json.Should().Contain("\"method\":\"test_method\""); + json.Should().Contain("\"params\":"); + json.Should().Contain("\"id\":1"); + } +} diff --git a/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Contracts/JsonRpcResponseTests.cs b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Contracts/JsonRpcResponseTests.cs new file mode 100644 index 0000000..8b9e77d --- /dev/null +++ b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Contracts/JsonRpcResponseTests.cs @@ -0,0 +1,106 @@ +using System.Text.Json; +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; +using FluentAssertions; + +namespace ColaFlow.Modules.Mcp.Tests.Contracts; + +/// +/// Unit tests for JsonRpcResponse +/// +public class JsonRpcResponseTests +{ + [Fact] + public void Success_CreatesValidSuccessResponse() + { + // Arrange + var result = new { message = "success" }; + var id = 1; + + // Act + var response = JsonRpcResponse.Success(result, id); + + // Assert + response.Should().NotBeNull(); + response.JsonRpc.Should().Be("2.0"); + response.Result.Should().NotBeNull(); + response.Error.Should().BeNull(); + response.Id.Should().Be(id); + } + + [Fact] + public void CreateError_CreatesValidErrorResponse() + { + // Arrange + var error = JsonRpcError.InternalError("Test error"); + var id = 1; + + // Act + var response = JsonRpcResponse.CreateError(error, id); + + // Assert + response.Should().NotBeNull(); + response.JsonRpc.Should().Be("2.0"); + response.Result.Should().BeNull(); + response.Error.Should().NotBeNull(); + response.Error.Should().Be(error); + response.Id.Should().Be(id); + } + + [Fact] + public void ParseError_CreatesResponseWithNullId() + { + // Act + var response = JsonRpcResponse.ParseError("Invalid JSON"); + + // Assert + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.ParseError); + response.Id.Should().BeNull(); + } + + [Fact] + public void MethodNotFound_IncludesMethodNameInError() + { + // Act + var response = JsonRpcResponse.MethodNotFound("unknown_method", 1); + + // Assert + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.MethodNotFound); + response.Error.Message.Should().Contain("unknown_method"); + } + + [Fact] + public void Serialize_SuccessResponse_DoesNotIncludeError() + { + // Arrange + var response = JsonRpcResponse.Success(new { result = "ok" }, 1); + + // Act + var json = JsonSerializer.Serialize(response, new JsonSerializerOptions + { + DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull + }); + + // Assert + json.Should().Contain("\"result\":"); + json.Should().NotContain("\"error\":"); + } + + [Fact] + public void Serialize_ErrorResponse_DoesNotIncludeResult() + { + // Arrange + var response = JsonRpcResponse.CreateError(JsonRpcError.InternalError(), 1); + + // Act + var json = JsonSerializer.Serialize(response, new JsonSerializerOptions + { + DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull + }); + + // Assert + json.Should().Contain("\"error\":"); + json.Should().NotContain("\"result\":"); + } +} diff --git a/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Handlers/InitializeMethodHandlerTests.cs b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Handlers/InitializeMethodHandlerTests.cs new file mode 100644 index 0000000..aee1c68 --- /dev/null +++ b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Handlers/InitializeMethodHandlerTests.cs @@ -0,0 +1,135 @@ +using System.Text.Json; +using ColaFlow.Modules.Mcp.Application.Handlers; +using ColaFlow.Modules.Mcp.Contracts.Mcp; +using FluentAssertions; +using Microsoft.Extensions.Logging; +using NSubstitute; + +namespace ColaFlow.Modules.Mcp.Tests.Handlers; + +/// +/// Unit tests for InitializeMethodHandler +/// +public class InitializeMethodHandlerTests +{ + private readonly ILogger _logger; + private readonly InitializeMethodHandler _sut; + + public InitializeMethodHandlerTests() + { + _logger = Substitute.For>(); + _sut = new InitializeMethodHandler(_logger); + } + + [Fact] + public void MethodName_ReturnsInitialize() + { + // Assert + _sut.MethodName.Should().Be("initialize"); + } + + [Fact] + public async Task HandleAsync_WithValidRequest_ReturnsInitializeResponse() + { + // Arrange + var initRequest = new McpInitializeRequest + { + ProtocolVersion = "1.0", + ClientInfo = new McpClientInfo + { + Name = "Claude Desktop", + Version = "1.0.0" + } + }; + + // Act + var result = await _sut.HandleAsync(initRequest, CancellationToken.None); + + // Assert + result.Should().NotBeNull(); + result.Should().BeOfType(); + + var response = (McpInitializeResponse)result!; + response.ProtocolVersion.Should().Be("1.0"); + response.ServerInfo.Should().NotBeNull(); + response.ServerInfo.Name.Should().Be("ColaFlow MCP Server"); + response.ServerInfo.Version.Should().Be("1.0.0"); + response.Capabilities.Should().NotBeNull(); + } + + [Fact] + public async Task HandleAsync_ReturnsCapabilitiesWithAllFeaturesSupported() + { + // Arrange + var initRequest = new McpInitializeRequest + { + ProtocolVersion = "1.0", + ClientInfo = new McpClientInfo { Name = "Test", Version = "1.0" } + }; + + // Act + var result = await _sut.HandleAsync(initRequest, CancellationToken.None); + + // Assert + var response = (McpInitializeResponse)result!; + response.Capabilities.Resources.Should().NotBeNull(); + response.Capabilities.Resources!.Supported.Should().BeTrue(); + response.Capabilities.Tools.Should().NotBeNull(); + response.Capabilities.Tools!.Supported.Should().BeTrue(); + response.Capabilities.Prompts.Should().NotBeNull(); + response.Capabilities.Prompts!.Supported.Should().BeTrue(); + } + + [Fact] + public async Task HandleAsync_WithNullParams_ReturnsValidResponse() + { + // Act + var result = await _sut.HandleAsync(null, CancellationToken.None); + + // Assert + result.Should().NotBeNull(); + result.Should().BeOfType(); + } + + [Fact] + public async Task HandleAsync_WithObjectParams_DeserializesCorrectly() + { + // Arrange - Simulate how JSON deserialization works with object params + var paramsObj = new + { + protocolVersion = "1.0", + clientInfo = new + { + name = "Claude Desktop", + version = "1.0.0" + } + }; + + // Act + var result = await _sut.HandleAsync(paramsObj, CancellationToken.None); + + // Assert + result.Should().NotBeNull(); + var response = (McpInitializeResponse)result!; + response.ProtocolVersion.Should().Be("1.0"); + } + + [Fact] + public async Task HandleAsync_WithUnsupportedProtocolVersion_StillReturnsResponse() + { + // Arrange + var initRequest = new McpInitializeRequest + { + ProtocolVersion = "2.0", // Unsupported version + ClientInfo = new McpClientInfo { Name = "Test", Version = "1.0" } + }; + + // Act + var result = await _sut.HandleAsync(initRequest, CancellationToken.None); + + // Assert + result.Should().NotBeNull(); + var response = (McpInitializeResponse)result!; + response.ProtocolVersion.Should().Be("1.0"); // Server returns its supported version + } +} diff --git a/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Handlers/McpProtocolHandlerTests.cs b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Handlers/McpProtocolHandlerTests.cs new file mode 100644 index 0000000..01c979f --- /dev/null +++ b/colaflow-api/tests/Modules/Mcp/ColaFlow.Modules.Mcp.Tests/Handlers/McpProtocolHandlerTests.cs @@ -0,0 +1,223 @@ +using ColaFlow.Modules.Mcp.Application.Handlers; +using ColaFlow.Modules.Mcp.Contracts.JsonRpc; +using FluentAssertions; +using Microsoft.Extensions.Logging; +using NSubstitute; + +namespace ColaFlow.Modules.Mcp.Tests.Handlers; + +/// +/// Unit tests for McpProtocolHandler +/// +public class McpProtocolHandlerTests +{ + private readonly ILogger _logger; + private readonly List _methodHandlers; + private readonly McpProtocolHandler _sut; + + public McpProtocolHandlerTests() + { + _logger = Substitute.For>(); + _methodHandlers = new List(); + _sut = new McpProtocolHandler(_logger, _methodHandlers); + } + + [Fact] + public async Task HandleRequestAsync_WithInvalidJsonRpc_ReturnsInvalidRequest() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "1.0", // Invalid version + Method = "test" + }; + + // Act + var response = await _sut.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Should().NotBeNull(); + response.JsonRpc.Should().Be("2.0"); + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.InvalidRequest); + response.Result.Should().BeNull(); + } + + [Fact] + public async Task HandleRequestAsync_WithMissingMethod_ReturnsInvalidRequest() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "" // Empty method + }; + + // Act + var response = await _sut.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Should().NotBeNull(); + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.InvalidRequest); + } + + [Fact] + public async Task HandleRequestAsync_WithUnknownMethod_ReturnsMethodNotFound() + { + // Arrange + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "unknown_method", + Id = 1 + }; + + // Act + var response = await _sut.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Should().NotBeNull(); + response.JsonRpc.Should().Be("2.0"); + response.Id.Should().Be(1); + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.MethodNotFound); + response.Error.Message.Should().Contain("unknown_method"); + response.Result.Should().BeNull(); + } + + [Fact] + public async Task HandleRequestAsync_WithValidMethod_ReturnsSuccess() + { + // Arrange + var mockHandler = Substitute.For(); + mockHandler.MethodName.Returns("test_method"); + mockHandler.HandleAsync(Arg.Any(), Arg.Any()) + .Returns(Task.FromResult(new { result = "success" })); + + var handler = new McpProtocolHandler(_logger, new[] { mockHandler }); + + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Id = 1 + }; + + // Act + var response = await handler.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Should().NotBeNull(); + response.JsonRpc.Should().Be("2.0"); + response.Id.Should().Be(1); + response.Error.Should().BeNull(); + response.Result.Should().NotBeNull(); + } + + [Fact] + public async Task HandleRequestAsync_WhenHandlerThrowsArgumentException_ReturnsInvalidParams() + { + // Arrange + var mockHandler = Substitute.For(); + mockHandler.MethodName.Returns("test_method"); + mockHandler.HandleAsync(Arg.Any(), Arg.Any()) + .Returns(_ => throw new ArgumentException("Invalid parameter")); + + var handler = new McpProtocolHandler(_logger, new[] { mockHandler }); + + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Id = 1 + }; + + // Act + var response = await handler.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Should().NotBeNull(); + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.InvalidParams); + } + + [Fact] + public async Task HandleRequestAsync_WhenHandlerThrowsException_ReturnsInternalError() + { + // Arrange + var mockHandler = Substitute.For(); + mockHandler.MethodName.Returns("test_method"); + mockHandler.HandleAsync(Arg.Any(), Arg.Any()) + .Returns(_ => throw new InvalidOperationException("Something went wrong")); + + var handler = new McpProtocolHandler(_logger, new[] { mockHandler }); + + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Id = 1 + }; + + // Act + var response = await handler.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Should().NotBeNull(); + response.Error.Should().NotBeNull(); + response.Error!.Code.Should().Be((int)JsonRpcErrorCode.InternalError); + } + + [Fact] + public async Task HandleRequestAsync_WithStringId_PreservesIdInResponse() + { + // Arrange + var mockHandler = Substitute.For(); + mockHandler.MethodName.Returns("test_method"); + mockHandler.HandleAsync(Arg.Any(), Arg.Any()) + .Returns(Task.FromResult(new { result = "success" })); + + var handler = new McpProtocolHandler(_logger, new[] { mockHandler }); + + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Id = "abc-123" + }; + + // Act + var response = await handler.HandleRequestAsync(request, CancellationToken.None); + + // Assert + response.Id.Should().Be("abc-123"); + } + + [Fact] + public async Task HandleRequestAsync_WithParams_PassesParamsToHandler() + { + // Arrange + var mockHandler = Substitute.For(); + mockHandler.MethodName.Returns("test_method"); + mockHandler.HandleAsync(Arg.Any(), Arg.Any()) + .Returns(Task.FromResult(new { result = "success" })); + + var handler = new McpProtocolHandler(_logger, new[] { mockHandler }); + + var testParams = new { param1 = "value1", param2 = 42 }; + var request = new JsonRpcRequest + { + JsonRpc = "2.0", + Method = "test_method", + Params = testParams, + Id = 1 + }; + + // Act + await handler.HandleRequestAsync(request, CancellationToken.None); + + // Assert + await mockHandler.Received(1).HandleAsync(testParams, Arg.Any()); + } +} diff --git a/docs/stories/sprint_5/README.md b/docs/stories/sprint_5/README.md new file mode 100644 index 0000000..5f71d89 --- /dev/null +++ b/docs/stories/sprint_5/README.md @@ -0,0 +1,290 @@ +# Sprint 5 Stories - MCP Server Foundation + +**Sprint**: Sprint 5 +**Milestone**: M2 - MCP Server Implementation +**Duration**: 8 weeks (40 working days) +**Created**: 2025-11-06 +**Total Stories**: 12 +**Total Story Points**: 63 + +--- + +## Overview + +This directory contains detailed Story documents for Sprint 5: MCP Server Foundation (Phase 1-3). These Stories establish the foundational infrastructure for AI integration through the Model Context Protocol (MCP). + +**Sprint Goal**: Build the foundational MCP Server infrastructure to enable AI agents (Claude, ChatGPT) to safely read and modify ColaFlow project data through the MCP protocol. + +--- + +## Phase 1: Foundation (Week 1-2) + +**Goal**: Establish MCP protocol infrastructure, API Key authentication, and basic error handling. + +| Story ID | Title | Priority | Story Points | Est. Days | Dependencies | +|----------|-------|----------|--------------|-----------|--------------| +| [story_5_1](story_5_1.md) | MCP Protocol Handler Implementation | P0 | 8 | 3 | - | +| [story_5_2](story_5_2.md) | API Key Management System | P0 | 5 | 2 | - | +| [story_5_3](story_5_3.md) | MCP Domain Layer Design | P0 | 5 | 2 | - | +| [story_5_4](story_5_4.md) | Error Handling & Logging | P0 | 3 | 1 | story_5_1 | + +**Phase 1 Total**: 21 Story Points (8 days) + +**Milestone**: MCP infrastructure ready, API Key authentication working + +--- + +## Phase 2: Resources (Week 3-4) + +**Goal**: Implement read-only data exposure (5 core Resources), multi-tenant isolation, Redis caching. + +| Story ID | Title | Priority | Story Points | Est. Days | Dependencies | +|----------|-------|----------|--------------|-----------|--------------| +| [story_5_5](story_5_5.md) | Core MCP Resources Implementation | P0 | 8 | 3 | story_5_1, story_5_2, story_5_3 | +| [story_5_6](story_5_6.md) | Resource Registration & Discovery | P0 | 3 | 1 | story_5_5 | +| [story_5_7](story_5_7.md) | Multi-Tenant Isolation Verification | P0 | 5 | 2 | story_5_5, story_5_2 | +| [story_5_8](story_5_8.md) | Redis Caching Integration | P1 | 5 | 2 | story_5_5 | + +**Phase 2 Total**: 21 Story Points (8 days) + +**Milestone**: AI can read ColaFlow data via MCP Resources + +--- + +## Phase 3: Tools & Diff Preview (Week 5-6) + +**Goal**: Implement write operations (3 core Tools), build Diff Preview mechanism, SignalR real-time notifications. + +| Story ID | Title | Priority | Story Points | Est. Days | Dependencies | +|----------|-------|----------|--------------|-----------|--------------| +| [story_5_9](story_5_9.md) | Diff Preview Service Implementation | P0 | 5 | 2 | story_5_3 | +| [story_5_10](story_5_10.md) | PendingChange Management | P0 | 5 | 2 | story_5_3, story_5_9 | +| [story_5_11](story_5_11.md) | Core MCP Tools Implementation | P0 | 8 | 3 | story_5_1, story_5_9, story_5_10 | +| [story_5_12](story_5_12.md) | SignalR Real-Time Notifications | P0 | 3 | 1 | story_5_10 | + +**Phase 3 Total**: 21 Story Points (8 days) + +**Milestone**: AI can request write operations (with approval workflow) + +--- + +## Story Summary + +### By Priority +- **P0 (Critical)**: 11 Stories, 58 Story Points +- **P1 (High)**: 1 Story, 5 Story Points + +### By Phase +- **Phase 1 (Foundation)**: 4 Stories, 21 Story Points +- **Phase 2 (Resources)**: 4 Stories, 21 Story Points +- **Phase 3 (Tools & Diff Preview)**: 4 Stories, 21 Story Points + +### Dependency Graph + +``` +Phase 1: + story_5_1 (Protocol Handler) ──┐ + story_5_2 (API Key) ├──> story_5_5 (Resources) ──> story_5_6 (Registry) + story_5_3 (Domain Layer) ──────┤ ├──> story_5_7 (Multi-Tenant) + │ └──> story_5_8 (Redis Cache) + story_5_1 ──> story_5_4 (Error Handling) + +Phase 2 → Phase 3: + story_5_3 ──> story_5_9 (Diff Preview) ──> story_5_10 (PendingChange) ──> story_5_11 (Tools) + └──> story_5_12 (SignalR) + story_5_1 ──────────────────────────────────────────────────────────────> story_5_11 +``` + +--- + +## Key Deliverables + +### Phase 1: Foundation +- ✅ JSON-RPC 2.0 protocol handler +- ✅ MCP initialize handshake +- ✅ API Key authentication (BCrypt hashing) +- ✅ Domain entities (McpApiKey, PendingChange, DiffPreview) +- ✅ Structured logging (Serilog) +- ✅ Exception handling + +### Phase 2: Resources +- ✅ 6 MCP Resources (projects.list, projects.get, issues.search, issues.get, sprints.current, users.list) +- ✅ Resource registration and discovery +- ✅ Multi-tenant isolation (100% verified) +- ✅ Redis caching (30-50% performance improvement) + +### Phase 3: Tools & Diff Preview +- ✅ 3 MCP Tools (create_issue, update_status, add_comment) +- ✅ Diff Preview service (CREATE, UPDATE, DELETE) +- ✅ PendingChange approval workflow +- ✅ SignalR real-time notifications + +--- + +## Definition of Done (Sprint-Level) + +### Functional +- [ ] All P0 stories completed (Stories 1-12) +- [ ] MCP protocol `initialize` handshake works +- [ ] API Key authentication functional +- [ ] 5 Resources return correct data with < 200ms latency +- [ ] 3 Tools generate Diff Preview correctly +- [ ] Approval workflow complete (PendingChange → Approve → Execute) +- [ ] SignalR real-time notifications working + +### Quality +- [ ] Multi-tenant isolation 100% verified +- [ ] Redis caching improves performance by 30%+ +- [ ] Unit test coverage > 80% +- [ ] Integration tests pass +- [ ] No CRITICAL security vulnerabilities + +### Documentation +- [ ] Architecture documentation updated +- [ ] API documentation (Swagger) +- [ ] Integration guide for AI clients + +--- + +## Success Metrics + +### Performance Metrics +- **API Response Time**: < 200ms (P50), < 500ms (P95) +- **MCP Protocol Overhead**: < 5ms per request +- **Cache Hit Rate**: > 80% for hot Resources +- **Throughput**: > 100 requests/second per instance + +### Quality Metrics +- **Unit Test Coverage**: > 80% +- **Integration Test Coverage**: > 70% +- **Security Vulnerabilities**: 0 CRITICAL, 0 HIGH +- **Code Duplication**: < 5% + +### Functional Metrics +- **Resources Implemented**: 6/6 (100%) +- **Tools Implemented**: 3/3 (100%) +- **Multi-Tenant Isolation**: 100% verified +- **Diff Preview Accuracy**: 100% (all changed fields detected) + +--- + +## Risk Register + +### Critical Risks +| Risk ID | Description | Mitigation | Owner | Story | +|---------|-------------|------------|-------|-------| +| RISK-001 | Multi-tenant data leak | 100% test coverage, security audit | Backend | story_5_7 | +| RISK-002 | API Key security breach | BCrypt hashing, IP whitelist, rate limiting | Backend | story_5_2 | +| RISK-003 | Diff Preview inaccurate | Comprehensive testing, JSON diff library | Backend | story_5_9 | + +### High Risks +| Risk ID | Description | Mitigation | Owner | Story | +|---------|-------------|------------|-------|-------| +| RISK-004 | MCP protocol changes | Version control, quick adaptation | Architect | story_5_1 | +| RISK-005 | Performance bottleneck | Redis caching, horizontal scaling | Backend | story_5_8 | +| RISK-006 | SignalR scalability | Redis backplane for multi-instance | Backend | story_5_12 | + +--- + +## Technical Stack + +### Backend +- .NET 9 (ASP.NET Core) +- PostgreSQL 15+ +- Redis 7+ +- EF Core 9 +- MediatR (CQRS) +- SignalR +- BCrypt.Net +- Serilog + +### Testing +- xUnit +- Moq +- FluentAssertions +- Integration Tests (EF Core In-Memory) + +--- + +## Sprint Timeline + +### Week 1-2: Phase 1 - Foundation +- **Day 1-3**: Story 1 - MCP Protocol Handler +- **Day 4-5**: Story 2 - API Key Management +- **Day 6-7**: Story 3 - MCP Domain Layer +- **Day 8**: Story 4 - Error Handling & Logging + +### Week 3-4: Phase 2 - Resources +- **Day 9-11**: Story 5 - Core Resources Implementation +- **Day 12**: Story 6 - Resource Registration +- **Day 13-14**: Story 7 - Multi-Tenant Isolation Verification +- **Day 15-16**: Story 8 - Redis Caching Integration + +### Week 5-6: Phase 3 - Tools & Diff Preview +- **Day 17-18**: Story 9 - Diff Preview Service +- **Day 19-20**: Story 10 - PendingChange Management +- **Day 21-23**: Story 11 - Core Tools Implementation +- **Day 24**: Story 12 - SignalR Notifications + +--- + +## How to Use These Stories + +### For Backend Developers +1. Read Story document thoroughly +2. Understand acceptance criteria +3. Follow task breakdown (estimated hours) +4. Write tests first (TDD recommended) +5. Implement feature +6. Submit PR with all DoD items checked + +### For QA Engineers +1. Review acceptance criteria +2. Prepare test scenarios +3. Verify unit test coverage +4. Execute integration tests +5. Report bugs with Story ID reference + +### For Product Manager +1. Track Story status (not_started, in_progress, completed) +2. Monitor dependencies +3. Update Sprint progress +4. Coordinate Story sequencing + +--- + +## Related Documents + +### Planning Documents +- [Sprint 5 Plan](../../plans/sprint_5.md) - Sprint overview and timeline +- [Product Roadmap](../../../product.md) - M2 section + +### Architecture Documents +- [MCP Server Architecture](../../M2-MCP-SERVER-ARCHITECTURE.md) - Complete 73KB design doc +- [MCP Suggestions](../../mcp-suggestion.md) - Architect's analysis + +### Technical References +- [MCP Protocol Specification](https://modelcontextprotocol.io/docs) +- [JSON-RPC 2.0 Spec](https://www.jsonrpc.org/specification) + +--- + +## Notes + +### Why Sprint 5 Matters +- **AI Integration Foundation**: Enables ColaFlow to become AI-native +- **Market Differentiation**: MCP support is cutting-edge (few competitors) +- **M2 Milestone Progress**: 50% of M2 completed after this Sprint +- **User Value**: AI automates 50% of manual project management work + +### What Makes This Sprint Unique +- **Security First**: Multi-tenant isolation is P0 +- **Diff Preview**: Unique safety mechanism (not in competitors) +- **Human-in-the-Loop**: AI proposes, human approves +- **Real-Time**: SignalR notifications complete the loop + +--- + +**Created**: 2025-11-06 by Product Manager Agent +**Last Updated**: 2025-11-06 +**Next Review**: Sprint Planning Meeting (2025-11-27) diff --git a/docs/stories/sprint_5/story_5_1.md b/docs/stories/sprint_5/story_5_1.md new file mode 100644 index 0000000..ee5522d --- /dev/null +++ b/docs/stories/sprint_5/story_5_1.md @@ -0,0 +1,322 @@ +--- +story_id: story_5_1 +sprint_id: sprint_5 +phase: Phase 1 - Foundation +status: not_started +priority: P0 +story_points: 8 +assignee: backend +estimated_days: 3 +created_date: 2025-11-06 +dependencies: [] +--- + +# Story 5.1: MCP Protocol Handler Implementation + +**Phase**: Phase 1 - Foundation (Week 1-2) +**Priority**: P0 CRITICAL +**Estimated Effort**: 8 Story Points (3 days) + +## User Story + +**As a** ColaFlow System +**I want** to implement a JSON-RPC 2.0 protocol handler for MCP communication +**So that** AI agents (Claude, ChatGPT) can communicate with ColaFlow using the MCP protocol + +## Business Value + +This is the foundational infrastructure for M2 MCP Server. Without this, AI agents cannot communicate with ColaFlow. This Story enables all future MCP Resources and Tools. + +**Impact**: +- Enables AI integration foundation +- Supports 11 Resources + 10 Tools in future Stories +- 100% required for M2 milestone completion + +## Acceptance Criteria + +### AC1: MCP Protocol Parsing +- [ ] JSON-RPC 2.0 messages correctly parsed +- [ ] Request validation (jsonrpc: "2.0", method, params, id) +- [ ] Error responses conform to JSON-RPC 2.0 spec +- [ ] Invalid requests return proper error codes (-32700, -32600, -32602) + +### AC2: Initialize Handshake +- [ ] MCP `initialize` method implemented +- [ ] Server capabilities returned (resources, tools, prompts) +- [ ] Protocol version negotiation works (1.0) +- [ ] Client initialization validated + +### AC3: Request Routing +- [ ] Route requests to Resource handlers (e.g., `resources/list`, `resources/read`) +- [ ] Route requests to Tool handlers (e.g., `tools/list`, `tools/call`) +- [ ] Route requests to Prompt handlers (e.g., `prompts/list`) +- [ ] Method not found returns -32601 error + +### AC4: Response Generation +- [ ] Success responses with `result` field +- [ ] Error responses with `error` field (code, message, data) +- [ ] Request ID correctly echoed in response +- [ ] Notification support (no `id` field) + +### AC5: Testing +- [ ] Unit test coverage > 80% +- [ ] Integration tests for initialize handshake +- [ ] Error handling tests (invalid JSON, missing fields) +- [ ] Performance test: protocol overhead < 5ms + +## Technical Design + +### Architecture + +``` +┌─────────────────────────────────────┐ +│ ASP.NET Core Controller │ +│ POST /mcp (JSON-RPC endpoint) │ +└───────────────┬─────────────────────┘ + │ +┌───────────────┴─────────────────────┐ +│ McpProtocolHandler │ +│ - Parse JSON-RPC 2.0 │ +│ - Validate request │ +│ - Route to handler │ +│ - Format response │ +└───────────────┬─────────────────────┘ + │ + ┌─────────┴─────────┐ + │ │ +┌─────┴──────┐ ┌──────┴──────┐ +│ Resource │ │ Tool │ +│ Dispatcher │ │ Dispatcher │ +└────────────┘ └─────────────┘ +``` + +### Key Interfaces + +```csharp +public interface IMcpProtocolHandler +{ + Task HandleRequestAsync( + McpRequest request, + CancellationToken cancellationToken); +} + +public class McpRequest +{ + public string JsonRpc { get; set; } = "2.0"; + public string Method { get; set; } + public object? Params { get; set; } + public string? Id { get; set; } +} + +public class McpResponse +{ + public string JsonRpc { get; set; } = "2.0"; + public object? Result { get; set; } + public McpError? Error { get; set; } + public string? Id { get; set; } +} + +public class McpError +{ + public int Code { get; set; } + public string Message { get; set; } + public object? Data { get; set; } +} +``` + +### MCP Error Codes + +```csharp +public enum McpErrorCode +{ + ParseError = -32700, // Invalid JSON + InvalidRequest = -32600, // Invalid Request object + MethodNotFound = -32601, // Method does not exist + InvalidParams = -32602, // Invalid method parameters + InternalError = -32603, // Internal JSON-RPC error + Unauthorized = -32001, // Authentication failed + Forbidden = -32002, // Authorization failed + NotFound = -32003, // Resource not found + ValidationFailed = -32004 // Request validation failed +} +``` + +### Initialize Handshake Flow + +```json +// Request +{ + "jsonrpc": "2.0", + "method": "initialize", + "params": { + "protocolVersion": "1.0", + "clientInfo": { + "name": "Claude Desktop", + "version": "1.0.0" + } + }, + "id": 1 +} + +// Response +{ + "jsonrpc": "2.0", + "result": { + "protocolVersion": "1.0", + "serverInfo": { + "name": "ColaFlow MCP Server", + "version": "1.0.0" + }, + "capabilities": { + "resources": { "supported": true }, + "tools": { "supported": true }, + "prompts": { "supported": true } + } + }, + "id": 1 +} +``` + +## Tasks + +### Task 1: Create Core Protocol Infrastructure (6 hours) +- [ ] Create `IMcpProtocolHandler` interface +- [ ] Create `McpRequest`, `McpResponse`, `McpError` DTOs +- [ ] Implement `McpProtocolHandler` class +- [ ] Add JSON serialization configuration (System.Text.Json) +- [ ] Create ASP.NET Core controller endpoint `POST /mcp` + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Contracts/IMcpProtocolHandler.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpRequest.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpResponse.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpError.cs` +- `ColaFlow.Modules.Mcp/Services/McpProtocolHandler.cs` +- `ColaFlow.Modules.Mcp/Controllers/McpController.cs` + +### Task 2: Implement Initialize Handshake (4 hours) +- [ ] Implement `initialize` method handler +- [ ] Return server capabilities (resources, tools, prompts) +- [ ] Protocol version validation (support 1.0) +- [ ] Client info parsing and logging + +**Files to Modify**: +- `ColaFlow.Modules.Mcp/Services/McpProtocolHandler.cs` + +### Task 3: Implement Request Routing (6 hours) +- [ ] Create `IMcpResourceDispatcher` interface +- [ ] Create `IMcpToolDispatcher` interface +- [ ] Implement method-based routing logic +- [ ] Handle `resources/list`, `resources/read` methods +- [ ] Handle `tools/list`, `tools/call` methods +- [ ] Return -32601 for unknown methods + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Contracts/IMcpResourceDispatcher.cs` +- `ColaFlow.Modules.Mcp/Contracts/IMcpToolDispatcher.cs` +- `ColaFlow.Modules.Mcp/Services/McpResourceDispatcher.cs` +- `ColaFlow.Modules.Mcp/Services/McpToolDispatcher.cs` + +### Task 4: Error Handling & Validation (4 hours) +- [ ] Implement JSON parsing error handling (ParseError -32700) +- [ ] Validate request structure (InvalidRequest -32600) +- [ ] Validate method parameters (InvalidParams -32602) +- [ ] Create exception-to-error-code mapping +- [ ] Add structured logging (Serilog) + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Exceptions/McpException.cs` +- `ColaFlow.Modules.Mcp/Middleware/McpExceptionHandler.cs` + +### Task 5: Unit Tests (4 hours) +- [ ] Test JSON-RPC request parsing +- [ ] Test initialize handshake +- [ ] Test request routing (valid methods) +- [ ] Test error handling (invalid requests) +- [ ] Test protocol overhead performance (< 5ms) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Services/McpProtocolHandlerTests.cs` +- `ColaFlow.Modules.Mcp.Tests/Controllers/McpControllerTests.cs` + +### Task 6: Integration Tests (4 hours) +- [ ] Test end-to-end initialize handshake +- [ ] Test routing to Resources (mock handler) +- [ ] Test routing to Tools (mock handler) +- [ ] Test error responses (invalid JSON, missing fields) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/McpProtocolIntegrationTests.cs` + +## Testing Strategy + +### Unit Tests (Target: > 80% coverage) +- Protocol parsing logic +- Request validation +- Error code mapping +- Method routing +- Response formatting + +### Integration Tests +- Initialize handshake flow +- Request/response round-trip +- Error handling end-to-end +- Performance benchmarks + +### Manual Testing Checklist +- [ ] Send valid initialize request → success +- [ ] Send invalid JSON → ParseError -32700 +- [ ] Send request without `method` → InvalidRequest -32600 +- [ ] Send unknown method → MethodNotFound -32601 +- [ ] Measure protocol overhead < 5ms + +## Dependencies + +**Prerequisites**: +- .NET 9 ASP.NET Core project structure +- System.Text.Json (JSON serialization) +- Serilog (logging) + +**Blocks**: +- Story 5.5 (Core MCP Resources) - Needs protocol handler +- Story 5.11 (Core MCP Tools) - Needs protocol handler + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| MCP spec changes | High | Medium | Version control, quick adaptation | +| JSON parsing performance | Medium | Low | Use System.Text.Json (fastest) | +| Request routing complexity | Medium | Medium | Simple method name mapping | +| Protocol overhead > 5ms | Medium | Low | Benchmark early, optimize if needed | + +## Definition of Done + +- [ ] Code compiles without warnings +- [ ] All unit tests passing (> 80% coverage) +- [ ] All integration tests passing +- [ ] Code reviewed and approved +- [ ] XML documentation for public APIs +- [ ] Performance benchmark < 5ms protocol overhead +- [ ] Logging implemented (request/response at DEBUG level) +- [ ] Exception handling complete +- [ ] Initialize handshake works end-to-end + +## Notes + +### Why This Story Matters +- **Foundation for M2**: All MCP features depend on this +- **Protocol Compliance**: JSON-RPC 2.0 compatibility ensures AI tool integration +- **Performance**: Low overhead design enables high throughput + +### Key Design Decisions +1. **Custom .NET Implementation**: No Node.js SDK dependency +2. **System.Text.Json**: Fastest JSON serialization in .NET +3. **Method-Based Routing**: Simple string matching for method dispatch +4. **Stateless Handler**: Each request independent, easy to scale + +### Reference Materials +- MCP Protocol Specification: https://modelcontextprotocol.io/docs +- JSON-RPC 2.0 Spec: https://www.jsonrpc.org/specification +- Sprint 5 Plan: `docs/plans/sprint_5.md` +- Architecture Design: `docs/M2-MCP-SERVER-ARCHITECTURE.md` diff --git a/docs/stories/sprint_5/story_5_10.md b/docs/stories/sprint_5/story_5_10.md new file mode 100644 index 0000000..b4980cb --- /dev/null +++ b/docs/stories/sprint_5/story_5_10.md @@ -0,0 +1,445 @@ +--- +story_id: story_5_10 +sprint_id: sprint_5 +phase: Phase 3 - Tools & Diff Preview +status: not_started +priority: P0 +story_points: 5 +assignee: backend +estimated_days: 2 +created_date: 2025-11-06 +dependencies: [story_5_3, story_5_9] +--- + +# Story 5.10: PendingChange Management + +**Phase**: Phase 3 - Tools & Diff Preview (Week 5-6) +**Priority**: P0 CRITICAL +**Estimated Effort**: 5 Story Points (2 days) + +## User Story + +**As a** User +**I want** to approve or reject AI-proposed changes +**So that** I maintain control over my project data + +## Business Value + +PendingChange management is the **approval workflow** for AI operations. It enables: +- **Human-in-the-Loop**: AI proposes, human approves +- **Audit Trail**: Complete history of all AI operations +- **Safety**: Prevents unauthorized or erroneous changes +- **Compliance**: Required for enterprise adoption + +## Acceptance Criteria + +### AC1: PendingChange CRUD +- [ ] Create PendingChange with Diff Preview +- [ ] Query PendingChanges (by tenant, by status, by user) +- [ ] Get PendingChange by ID +- [ ] Approve PendingChange (execute operation) +- [ ] Reject PendingChange (log reason) + +### AC2: Approval Workflow +- [ ] Approve action executes actual operation (create/update/delete) +- [ ] Approve action updates status to Approved +- [ ] Approve action logs approver and timestamp +- [ ] Reject action updates status to Rejected +- [ ] Reject action logs reason and rejecter + +### AC3: Auto-Expiration +- [ ] 24-hour expiration timer +- [ ] Background job checks expired changes +- [ ] Expired changes marked as Expired status +- [ ] Expired changes NOT executed + +### AC4: REST API Endpoints +- [ ] `GET /api/mcp/pending-changes` - List (filter by status) +- [ ] `GET /api/mcp/pending-changes/{id}` - Get details +- [ ] `POST /api/mcp/pending-changes/{id}/approve` - Approve +- [ ] `POST /api/mcp/pending-changes/{id}/reject` - Reject + +### AC5: Testing +- [ ] Unit tests for PendingChange service +- [ ] Integration tests for CRUD operations +- [ ] Integration tests for approval/rejection workflow +- [ ] Test auto-expiration mechanism + +## Technical Design + +### Service Interface + +```csharp +public interface IPendingChangeService +{ + Task CreateAsync( + string toolName, + DiffPreview diff, + CancellationToken cancellationToken); + + Task GetByIdAsync( + Guid id, + CancellationToken cancellationToken); + + Task> GetPendingChangesAsync( + PendingChangeStatus? status, + int page, + int pageSize, + CancellationToken cancellationToken); + + Task ApproveAsync( + Guid pendingChangeId, + Guid approvedBy, + CancellationToken cancellationToken); + + Task RejectAsync( + Guid pendingChangeId, + Guid rejectedBy, + string reason, + CancellationToken cancellationToken); + + Task ExpireOldChangesAsync(CancellationToken cancellationToken); +} +``` + +### Service Implementation + +```csharp +public class PendingChangeService : IPendingChangeService +{ + private readonly IPendingChangeRepository _repository; + private readonly ITenantContext _tenantContext; + private readonly IMediator _mediator; + private readonly ILogger _logger; + + public async Task CreateAsync( + string toolName, + DiffPreview diff, + CancellationToken ct) + { + var tenantId = _tenantContext.CurrentTenantId; + var apiKeyId = (Guid)_httpContext.HttpContext.Items["ApiKeyId"]!; + + var pendingChange = PendingChange.Create( + toolName, diff, tenantId, apiKeyId); + + await _repository.AddAsync(pendingChange, ct); + await _repository.SaveChangesAsync(ct); + + _logger.LogInformation( + "PendingChange created: {Id} - {ToolName} {Operation} {EntityType}", + pendingChange.Id, toolName, diff.Operation, diff.EntityType); + + return pendingChange; + } + + public async Task ApproveAsync( + Guid pendingChangeId, + Guid approvedBy, + CancellationToken ct) + { + var pendingChange = await _repository.GetByIdAsync(pendingChangeId, ct); + if (pendingChange == null) + throw new McpNotFoundException("PendingChange", pendingChangeId.ToString()); + + // Domain method (raises PendingChangeApprovedEvent) + pendingChange.Approve(approvedBy); + + await _repository.UpdateAsync(pendingChange, ct); + await _repository.SaveChangesAsync(ct); + + // Publish domain events (will trigger operation execution) + foreach (var domainEvent in pendingChange.DomainEvents) + { + await _mediator.Publish(domainEvent, ct); + } + + _logger.LogInformation( + "PendingChange approved: {Id} by {ApprovedBy}", + pendingChangeId, approvedBy); + } + + public async Task RejectAsync( + Guid pendingChangeId, + Guid rejectedBy, + string reason, + CancellationToken ct) + { + var pendingChange = await _repository.GetByIdAsync(pendingChangeId, ct); + if (pendingChange == null) + throw new McpNotFoundException("PendingChange", pendingChangeId.ToString()); + + pendingChange.Reject(rejectedBy, reason); + + await _repository.UpdateAsync(pendingChange, ct); + await _repository.SaveChangesAsync(ct); + + _logger.LogInformation( + "PendingChange rejected: {Id} by {RejectedBy} - Reason: {Reason}", + pendingChangeId, rejectedBy, reason); + } + + public async Task ExpireOldChangesAsync(CancellationToken ct) + { + var expiredChanges = await _repository.GetExpiredPendingChangesAsync(ct); + + foreach (var change in expiredChanges) + { + change.Expire(); + await _repository.UpdateAsync(change, ct); + + _logger.LogWarning( + "PendingChange expired: {Id} - {ToolName}", + change.Id, change.ToolName); + } + + await _repository.SaveChangesAsync(ct); + + _logger.LogInformation( + "Expired {Count} pending changes", + expiredChanges.Count); + } +} +``` + +### Approval Event Handler (Executes Operation) + +```csharp +public class PendingChangeApprovedEventHandler + : INotificationHandler +{ + private readonly IMediator _mediator; + private readonly ILogger _logger; + + public async Task Handle(PendingChangeApprovedEvent e, CancellationToken ct) + { + var diff = e.Diff; + + _logger.LogInformation( + "Executing approved operation: {Operation} {EntityType}", + diff.Operation, diff.EntityType); + + try + { + // Route to appropriate command handler based on operation + entity type + object command = (diff.Operation, diff.EntityType) switch + { + ("CREATE", "Story") => MapToCreateStoryCommand(diff), + ("UPDATE", "Story") => MapToUpdateStoryCommand(diff), + ("DELETE", "Story") => MapToDeleteStoryCommand(diff), + ("CREATE", "Epic") => MapToCreateEpicCommand(diff), + ("UPDATE", "Epic") => MapToUpdateEpicCommand(diff), + // ... more mappings + _ => throw new NotSupportedException( + $"Unsupported operation: {diff.Operation} {diff.EntityType}") + }; + + await _mediator.Send(command, ct); + + _logger.LogInformation( + "Operation executed successfully: {PendingChangeId}", + e.PendingChangeId); + } + catch (Exception ex) + { + _logger.LogError(ex, + "Failed to execute operation: {PendingChangeId}", + e.PendingChangeId); + + // TODO: Update PendingChange status to ExecutionFailed + throw; + } + } + + private CreateStoryCommand MapToCreateStoryCommand(DiffPreview diff) + { + var afterData = JsonSerializer.Deserialize( + JsonSerializer.Serialize(diff.AfterData)); + + return new CreateStoryCommand + { + ProjectId = afterData.ProjectId, + Title = afterData.Title, + Description = afterData.Description, + Priority = afterData.Priority, + // ... map all fields + }; + } +} +``` + +### Background Job (Expiration Check) + +```csharp +public class PendingChangeExpirationJob : BackgroundService +{ + private readonly IServiceProvider _serviceProvider; + private readonly ILogger _logger; + + protected override async Task ExecuteAsync(CancellationToken ct) + { + while (!ct.IsCancellationRequested) + { + try + { + using var scope = _serviceProvider.CreateScope(); + var pendingChangeService = scope.ServiceProvider + .GetRequiredService(); + + await pendingChangeService.ExpireOldChangesAsync(ct); + } + catch (Exception ex) + { + _logger.LogError(ex, "Error in PendingChange expiration job"); + } + + // Run every 5 minutes + await Task.Delay(TimeSpan.FromMinutes(5), ct); + } + } +} +``` + +## Tasks + +### Task 1: PendingChangeRepository (3 hours) +- [ ] Create `IPendingChangeRepository` interface +- [ ] Implement `PendingChangeRepository` (EF Core) +- [ ] CRUD methods (Add, Update, GetById, Query) +- [ ] GetExpiredPendingChangesAsync() method + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Infrastructure/Repositories/PendingChangeRepository.cs` + +### Task 2: PendingChangeService (4 hours) +- [ ] Implement `CreateAsync()` +- [ ] Implement `ApproveAsync()` +- [ ] Implement `RejectAsync()` +- [ ] Implement `GetPendingChangesAsync()` with pagination +- [ ] Implement `ExpireOldChangesAsync()` + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Application/Services/PendingChangeService.cs` + +### Task 3: PendingChangeApprovedEventHandler (4 hours) +- [ ] Create event handler +- [ ] Map DiffPreview to CQRS commands +- [ ] Execute command via MediatR +- [ ] Error handling (log failures) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Application/EventHandlers/PendingChangeApprovedEventHandler.cs` + +### Task 4: REST API Controller (2 hours) +- [ ] `GET /api/mcp/pending-changes` endpoint +- [ ] `GET /api/mcp/pending-changes/{id}` endpoint +- [ ] `POST /api/mcp/pending-changes/{id}/approve` endpoint +- [ ] `POST /api/mcp/pending-changes/{id}/reject` endpoint + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Controllers/PendingChangesController.cs` + +### Task 5: Background Job (2 hours) +- [ ] Create `PendingChangeExpirationJob` (BackgroundService) +- [ ] Run every 5 minutes +- [ ] Call `ExpireOldChangesAsync()` +- [ ] Register in DI container + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Infrastructure/Jobs/PendingChangeExpirationJob.cs` + +### Task 6: Unit Tests (4 hours) +- [ ] Test CreateAsync +- [ ] Test ApproveAsync (happy path) +- [ ] Test ApproveAsync (already approved throws exception) +- [ ] Test RejectAsync +- [ ] Test ExpireOldChangesAsync + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Services/PendingChangeServiceTests.cs` + +### Task 7: Integration Tests (3 hours) +- [ ] Test full approval workflow (create → approve → verify execution) +- [ ] Test rejection workflow +- [ ] Test expiration (create → wait 24 hours → expire) +- [ ] Test multi-tenant isolation + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/PendingChangeIntegrationTests.cs` + +## Testing Strategy + +### Integration Test Workflow + +```csharp +[Fact] +public async Task ApprovalWorkflow_CreateStory_Success() +{ + // Arrange + var diff = new DiffPreview( + operation: "CREATE", + entityType: "Story", + entityId: null, + entityKey: null, + beforeData: null, + afterData: new { title = "New Story", priority = "High" }, + changedFields: new[] { /* ... */ } + ); + + // Act - Create PendingChange + var pendingChange = await _service.CreateAsync("create_issue", diff, CancellationToken.None); + + Assert.Equal(PendingChangeStatus.PendingApproval, pendingChange.Status); + + // Act - Approve + await _service.ApproveAsync(pendingChange.Id, _userId, CancellationToken.None); + + // Assert - Verify Story created + var story = await _storyRepo.GetByIdAsync(/* ... */); + Assert.NotNull(story); + Assert.Equal("New Story", story.Title); +} +``` + +## Dependencies + +**Prerequisites**: +- Story 5.3 (MCP Domain Layer) - PendingChange aggregate +- Story 5.9 (Diff Preview Service) - DiffPreview value object + +**Used By**: +- Story 5.11 (Core MCP Tools) - Creates PendingChange +- Story 5.12 (SignalR Notifications) - Notifies on approval/rejection + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Operation execution fails | Medium | Medium | Transaction rollback, error logging, retry mechanism | +| Expiration job stops | Medium | Low | Health checks, monitoring, alerting | +| Race condition (concurrent approval) | Low | Low | Optimistic concurrency, database constraints | + +## Definition of Done + +- [ ] All CRUD operations working +- [ ] Approval executes operation correctly +- [ ] Rejection logs reason +- [ ] Expiration job running +- [ ] API endpoints working +- [ ] Unit tests passing (> 80%) +- [ ] Integration tests passing +- [ ] Code reviewed + +## Notes + +### Why This Story Matters +- **Core M2 Feature**: Enables human-in-the-loop AI operations +- **Safety**: Prevents AI mistakes +- **Compliance**: Audit trail required +- **User Trust**: Users control their data + +### Key Design Decisions +1. **Domain Events**: Approval triggers execution (loose coupling) +2. **Background Job**: Auto-expiration runs every 5 minutes +3. **24-Hour TTL**: Balance between user convenience and system cleanup +4. **Status Enum**: Clear lifecycle (Pending → Approved/Rejected/Expired) diff --git a/docs/stories/sprint_5/story_5_11.md b/docs/stories/sprint_5/story_5_11.md new file mode 100644 index 0000000..9909ee2 --- /dev/null +++ b/docs/stories/sprint_5/story_5_11.md @@ -0,0 +1,508 @@ +--- +story_id: story_5_11 +sprint_id: sprint_5 +phase: Phase 3 - Tools & Diff Preview +status: not_started +priority: P0 +story_points: 8 +assignee: backend +estimated_days: 3 +created_date: 2025-11-06 +dependencies: [story_5_1, story_5_9, story_5_10] +--- + +# Story 5.11: Core MCP Tools Implementation + +**Phase**: Phase 3 - Tools & Diff Preview (Week 5-6) +**Priority**: P0 CRITICAL +**Estimated Effort**: 8 Story Points (3 days) + +## User Story + +**As an** AI Agent +**I want** to create, update, and comment on issues through MCP Tools +**So that** I can automate project management tasks + +## Business Value + +MCP Tools enable AI **write operations**, completing the AI integration loop: +- AI can create Issues (Epic/Story/Task) via natural language +- AI can update issue status automatically +- AI can add comments and collaborate with team +- **50% reduction in manual project management work** + +## Acceptance Criteria + +### AC1: create_issue Tool +- [ ] Create Epic, Story, or Task +- [ ] Support all required fields (title, description, type, priority) +- [ ] Support optional fields (assignee, estimated hours, parent) +- [ ] Generate Diff Preview before execution +- [ ] Create PendingChange (NOT execute immediately) +- [ ] Return pendingChangeId to AI + +### AC2: update_status Tool +- [ ] Update issue status (Todo → InProgress → Done, etc.) +- [ ] Validate status transitions (workflow rules) +- [ ] Generate Diff Preview +- [ ] Create PendingChange +- [ ] Return pendingChangeId to AI + +### AC3: add_comment Tool +- [ ] Add comment to any issue (Epic/Story/Task) +- [ ] Support markdown formatting +- [ ] Track comment author (AI API Key) +- [ ] Generate Diff Preview +- [ ] Create PendingChange +- [ ] Return pendingChangeId to AI + +### AC4: Tool Registration +- [ ] All 3 Tools auto-register at startup +- [ ] `tools/list` returns complete catalog +- [ ] Each Tool has name, description, input schema + +### AC5: Input Validation +- [ ] JSON Schema validation for tool inputs +- [ ] Required fields validation +- [ ] Type validation (UUID, enum, etc.) +- [ ] Return -32602 (InvalidParams) for validation errors + +### AC6: Testing +- [ ] Unit tests for each Tool (> 80% coverage) +- [ ] Integration tests (end-to-end tool execution) +- [ ] Test Diff Preview generation +- [ ] Test PendingChange creation (NOT execution) + +## Technical Design + +### Tool Interface + +```csharp +public interface IMcpTool +{ + string Name { get; } + string Description { get; } + McpToolInputSchema InputSchema { get; } + + Task ExecuteAsync( + McpToolCall toolCall, + CancellationToken cancellationToken); +} + +public class McpToolCall +{ + public string Name { get; set; } + public Dictionary Arguments { get; set; } +} + +public class McpToolResult +{ + public IEnumerable Content { get; set; } + public bool IsError { get; set; } +} + +public class McpToolContent +{ + public string Type { get; set; } // "text" or "resource" + public string Text { get; set; } +} +``` + +### Example: CreateIssueTool + +```csharp +public class CreateIssueTool : IMcpTool +{ + public string Name => "create_issue"; + public string Description => "Create a new issue (Epic/Story/Task/Bug)"; + + public McpToolInputSchema InputSchema => new() + { + Type = "object", + Properties = new Dictionary + { + ["projectId"] = new() { Type = "string", Format = "uuid", Required = true }, + ["title"] = new() { Type = "string", MinLength = 1, MaxLength = 200, Required = true }, + ["description"] = new() { Type = "string" }, + ["type"] = new() { Type = "string", Enum = new[] { "Epic", "Story", "Task", "Bug" }, Required = true }, + ["priority"] = new() { Type = "string", Enum = new[] { "Low", "Medium", "High", "Critical" } }, + ["assigneeId"] = new() { Type = "string", Format = "uuid" }, + ["estimatedHours"] = new() { Type = "number", Minimum = 0 }, + ["parentId"] = new() { Type = "string", Format = "uuid" } + } + }; + + private readonly IDiffPreviewService _diffPreview; + private readonly IPendingChangeService _pendingChange; + private readonly ILogger _logger; + + public async Task ExecuteAsync( + McpToolCall toolCall, + CancellationToken ct) + { + _logger.LogInformation("Executing create_issue tool"); + + // 1. Parse and validate input + var input = ParseAndValidateInput(toolCall.Arguments); + + // 2. Build "after data" object + var afterData = new IssueDto + { + ProjectId = input.ProjectId, + Title = input.Title, + Description = input.Description, + Type = input.Type, + Priority = input.Priority ?? Priority.Medium, + AssigneeId = input.AssigneeId, + EstimatedHours = input.EstimatedHours, + ParentId = input.ParentId + }; + + // 3. Generate Diff Preview (CREATE operation) + var diff = await _diffPreview.GeneratePreviewAsync( + entityId: null, + afterData: afterData, + operation: "CREATE", + cancellationToken: ct); + + // 4. Create PendingChange (do NOT execute yet) + var pendingChange = await _pendingChange.CreateAsync( + toolName: Name, + diff: diff, + cancellationToken: ct); + + _logger.LogInformation( + "PendingChange created: {PendingChangeId} - {Operation} {EntityType}", + pendingChange.Id, diff.Operation, diff.EntityType); + + // 5. Return pendingChangeId to AI (NOT the created issue) + return new McpToolResult + { + Content = new[] + { + new McpToolContent + { + Type = "text", + Text = $"Change pending approval. ID: {pendingChange.Id}\n\n" + + $"Operation: Create {input.Type}\n" + + $"Title: {input.Title}\n" + + $"Priority: {input.Priority}\n\n" + + $"A human user must approve this change before it takes effect." + } + }, + IsError = false + }; + } + + private CreateIssueInput ParseAndValidateInput(Dictionary args) + { + // Parse and validate using JSON Schema + var input = new CreateIssueInput + { + ProjectId = ParseGuid(args, "projectId"), + Title = ParseString(args, "title", required: true), + Description = ParseString(args, "description"), + Type = ParseEnum(args, "type", required: true), + Priority = ParseEnum(args, "priority"), + AssigneeId = ParseGuid(args, "assigneeId"), + EstimatedHours = ParseDecimal(args, "estimatedHours"), + ParentId = ParseGuid(args, "parentId") + }; + + // Additional business validation + if (input.Type == IssueType.Task && input.ParentId == null) + throw new McpValidationException("Task must have a parent Story or Epic"); + + return input; + } +} + +public class CreateIssueInput +{ + public Guid ProjectId { get; set; } + public string Title { get; set; } + public string? Description { get; set; } + public IssueType Type { get; set; } + public Priority? Priority { get; set; } + public Guid? AssigneeId { get; set; } + public decimal? EstimatedHours { get; set; } + public Guid? ParentId { get; set; } +} +``` + +### Example: UpdateStatusTool + +```csharp +public class UpdateStatusTool : IMcpTool +{ + public string Name => "update_status"; + public string Description => "Update the status of an issue"; + + public McpToolInputSchema InputSchema => new() + { + Type = "object", + Properties = new Dictionary + { + ["issueId"] = new() { Type = "string", Format = "uuid", Required = true }, + ["newStatus"] = new() { Type = "string", Enum = new[] { + "Backlog", "Todo", "InProgress", "Review", "Done", "Cancelled" + }, Required = true } + } + }; + + private readonly IIssueRepository _issueRepo; + private readonly IDiffPreviewService _diffPreview; + private readonly IPendingChangeService _pendingChange; + + public async Task ExecuteAsync( + McpToolCall toolCall, + CancellationToken ct) + { + var issueId = ParseGuid(toolCall.Arguments, "issueId"); + var newStatus = ParseEnum(toolCall.Arguments, "newStatus"); + + // Fetch current issue + var issue = await _issueRepo.GetByIdAsync(issueId, ct); + if (issue == null) + throw new McpNotFoundException("Issue", issueId.ToString()); + + // Build "after data" (only status changed) + var afterData = issue.Clone(); + afterData.Status = newStatus; + + // Generate Diff Preview (UPDATE operation) + var diff = await _diffPreview.GeneratePreviewAsync( + entityId: issueId, + afterData: afterData, + operation: "UPDATE", + cancellationToken: ct); + + // Create PendingChange + var pendingChange = await _pendingChange.CreateAsync( + toolName: Name, + diff: diff, + cancellationToken: ct); + + return new McpToolResult + { + Content = new[] + { + new McpToolContent + { + Type = "text", + Text = $"Status change pending approval. ID: {pendingChange.Id}\n\n" + + $"Issue: {issue.Key} - {issue.Title}\n" + + $"Old Status: {issue.Status}\n" + + $"New Status: {newStatus}" + } + }, + IsError = false + }; + } +} +``` + +### Tools Catalog Response + +```json +{ + "tools": [ + { + "name": "create_issue", + "description": "Create a new issue (Epic/Story/Task/Bug)", + "inputSchema": { + "type": "object", + "properties": { + "projectId": { "type": "string", "format": "uuid" }, + "title": { "type": "string", "minLength": 1, "maxLength": 200 }, + "type": { "type": "string", "enum": ["Epic", "Story", "Task", "Bug"] } + }, + "required": ["projectId", "title", "type"] + } + }, + { + "name": "update_status", + "description": "Update the status of an issue", + "inputSchema": { + "type": "object", + "properties": { + "issueId": { "type": "string", "format": "uuid" }, + "newStatus": { "type": "string", "enum": ["Backlog", "Todo", "InProgress", "Review", "Done"] } + }, + "required": ["issueId", "newStatus"] + } + }, + { + "name": "add_comment", + "description": "Add a comment to an issue", + "inputSchema": { + "type": "object", + "properties": { + "issueId": { "type": "string", "format": "uuid" }, + "content": { "type": "string", "minLength": 1 } + }, + "required": ["issueId", "content"] + } + } + ] +} +``` + +## Tasks + +### Task 1: Tool Infrastructure (3 hours) +- [ ] Create `IMcpTool` interface +- [ ] Create `McpToolCall`, `McpToolResult`, `McpToolInputSchema` DTOs +- [ ] Create `IMcpToolDispatcher` interface +- [ ] Implement `McpToolDispatcher` (route tool calls) + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Contracts/IMcpTool.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpToolCall.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpToolResult.cs` +- `ColaFlow.Modules.Mcp/Services/McpToolDispatcher.cs` + +### Task 2: CreateIssueTool (6 hours) +- [ ] Implement `CreateIssueTool` class +- [ ] Define input schema (JSON Schema) +- [ ] Parse and validate input +- [ ] Generate Diff Preview +- [ ] Create PendingChange +- [ ] Return pendingChangeId + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Tools/CreateIssueTool.cs` +- `ColaFlow.Modules.Mcp.Tests/Tools/CreateIssueToolTests.cs` + +### Task 3: UpdateStatusTool (4 hours) +- [ ] Implement `UpdateStatusTool` class +- [ ] Fetch current issue +- [ ] Validate status transition (workflow rules) +- [ ] Generate Diff Preview +- [ ] Create PendingChange + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Tools/UpdateStatusTool.cs` +- `ColaFlow.Modules.Mcp.Tests/Tools/UpdateStatusToolTests.cs` + +### Task 4: AddCommentTool (3 hours) +- [ ] Implement `AddCommentTool` class +- [ ] Support markdown formatting +- [ ] Generate Diff Preview +- [ ] Create PendingChange + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Tools/AddCommentTool.cs` +- `ColaFlow.Modules.Mcp.Tests/Tools/AddCommentToolTests.cs` + +### Task 5: Tool Registration (2 hours) +- [ ] Update `McpRegistry` to support Tools +- [ ] Auto-discover Tools via Reflection +- [ ] Implement `tools/list` method handler + +### Task 6: Input Validation (3 hours) +- [ ] Create JSON Schema validator +- [ ] Validate required fields +- [ ] Validate types (UUID, enum, number range) +- [ ] Return McpInvalidParamsException on validation failure + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Validation/JsonSchemaValidator.cs` + +### Task 7: Unit Tests (6 hours) +- [ ] Test CreateIssueTool (happy path) +- [ ] Test CreateIssueTool (validation errors) +- [ ] Test UpdateStatusTool +- [ ] Test AddCommentTool +- [ ] Test input validation + +### Task 8: Integration Tests (4 hours) +- [ ] Test end-to-end tool execution +- [ ] Test Diff Preview generation +- [ ] Test PendingChange creation +- [ ] Test tool does NOT execute immediately + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/McpToolsIntegrationTests.cs` + +## Testing Strategy + +### Integration Test Example + +```csharp +[Fact] +public async Task CreateIssueTool_ValidInput_CreatesPendingChange() +{ + // Arrange + var toolCall = new McpToolCall + { + Name = "create_issue", + Arguments = new Dictionary + { + ["projectId"] = _projectId.ToString(), + ["title"] = "New Story", + ["type"] = "Story", + ["priority"] = "High" + } + }; + + // Act + var result = await _tool.ExecuteAsync(toolCall, CancellationToken.None); + + // Assert + Assert.False(result.IsError); + Assert.Contains("pending approval", result.Content.First().Text); + + // Verify PendingChange created (but NOT executed yet) + var pendingChanges = await _pendingChangeRepo.GetAllAsync(); + Assert.Single(pendingChanges); + Assert.Equal(PendingChangeStatus.PendingApproval, pendingChanges[0].Status); + + // Verify Story NOT created yet + var stories = await _storyRepo.GetAllAsync(); + Assert.Empty(stories); // Not created until approval +} +``` + +## Dependencies + +**Prerequisites**: +- Story 5.1 (MCP Protocol Handler) - Tool routing +- Story 5.9 (Diff Preview Service) - Generate diff +- Story 5.10 (PendingChange Management) - Create pending change + +**Used By**: +- Story 5.12 (SignalR Notifications) - Notify on pending change created + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Input validation bypass | High | Low | Comprehensive JSON Schema validation, unit tests | +| Diff Preview generation fails | Medium | Medium | Error handling, fallback to manual entry | +| Tool execution blocks | Medium | Low | Async/await, timeout mechanism | + +## Definition of Done + +- [ ] All 3 Tools implemented and working +- [ ] Input validation working (JSON Schema) +- [ ] Diff Preview generated correctly +- [ ] PendingChange created (NOT executed) +- [ ] Tools registered and discoverable (`tools/list`) +- [ ] Unit test coverage > 80% +- [ ] Integration tests passing +- [ ] Code reviewed + +## Notes + +### Why This Story Matters +- **Core M2 Feature**: Enables AI write operations +- **50% Time Savings**: AI automates manual tasks +- **User Value**: Natural language project management +- **Milestone Completion**: Completes basic AI integration loop + +### Key Design Decisions +1. **Deferred Execution**: Tools create PendingChange, NOT execute immediately +2. **JSON Schema Validation**: Strict input validation prevents errors +3. **Diff Preview First**: Always show user what will change +4. **Return pendingChangeId**: AI knows what to track diff --git a/docs/stories/sprint_5/story_5_12.md b/docs/stories/sprint_5/story_5_12.md new file mode 100644 index 0000000..b865798 --- /dev/null +++ b/docs/stories/sprint_5/story_5_12.md @@ -0,0 +1,429 @@ +--- +story_id: story_5_12 +sprint_id: sprint_5 +phase: Phase 3 - Tools & Diff Preview +status: not_started +priority: P0 +story_points: 3 +assignee: backend +estimated_days: 1 +created_date: 2025-11-06 +dependencies: [story_5_10] +--- + +# Story 5.12: SignalR Real-Time Notifications + +**Phase**: Phase 3 - Tools & Diff Preview (Week 5-6) +**Priority**: P0 CRITICAL +**Estimated Effort**: 3 Story Points (1 day) + +## User Story + +**As an** AI Agent +**I want** to receive real-time notifications when my pending changes are approved or rejected +**So that** I can continue my workflow without polling + +## Business Value + +Real-time notifications complete the AI interaction loop: +- **Faster Feedback**: AI knows approval result within 1 second +- **Better UX**: No polling, immediate response +- **Scalability**: WebSocket more efficient than polling +- **Future-Proof**: Foundation for other real-time AI features + +## Acceptance Criteria + +### AC1: McpHub SignalR Hub +- [ ] Create `McpHub` SignalR hub +- [ ] Support `SubscribeToPendingChange(pendingChangeId)` method +- [ ] Support `UnsubscribeFromPendingChange(pendingChangeId)` method +- [ ] Authenticate connections via API Key + +### AC2: Approval Notification +- [ ] When PendingChange approved → push notification to AI +- [ ] Notification includes: pendingChangeId, status, execution result +- [ ] Delivered within 1 second of approval +- [ ] Use SignalR groups for targeting + +### AC3: Rejection Notification +- [ ] When PendingChange rejected → push notification to AI +- [ ] Notification includes: pendingChangeId, status, rejection reason +- [ ] Delivered within 1 second of rejection + +### AC4: Expiration Notification +- [ ] When PendingChange expired → push notification to AI +- [ ] Notification includes: pendingChangeId, status + +### AC5: Connection Management +- [ ] API Key authentication for SignalR connections +- [ ] Handle disconnections gracefully +- [ ] Reconnection support +- [ ] Fallback to polling if WebSocket unavailable + +### AC6: Testing +- [ ] Unit tests for event handlers +- [ ] Integration tests for SignalR notifications +- [ ] Test connection authentication +- [ ] Test group subscriptions + +## Technical Design + +### SignalR Hub + +```csharp +[Authorize] // Require JWT for REST API integration +public class McpHub : Hub +{ + private readonly ILogger _logger; + + public McpHub(ILogger logger) + { + _logger = logger; + } + + public override async Task OnConnectedAsync() + { + var connectionId = Context.ConnectionId; + var apiKeyId = Context.Items["ApiKeyId"]; + var tenantId = Context.Items["TenantId"]; + + _logger.LogInformation( + "MCP client connected: {ConnectionId} (ApiKeyId: {ApiKeyId}, TenantId: {TenantId})", + connectionId, apiKeyId, tenantId); + + await base.OnConnectedAsync(); + } + + public override async Task OnDisconnectedAsync(Exception? exception) + { + var connectionId = Context.ConnectionId; + + if (exception != null) + { + _logger.LogError(exception, + "MCP client disconnected with error: {ConnectionId}", + connectionId); + } + else + { + _logger.LogInformation( + "MCP client disconnected: {ConnectionId}", + connectionId); + } + + await base.OnDisconnectedAsync(exception); + } + + public async Task SubscribeToPendingChange(Guid pendingChangeId) + { + var groupName = $"pending-change-{pendingChangeId}"; + await Groups.AddToGroupAsync(Context.ConnectionId, groupName); + + _logger.LogInformation( + "Client {ConnectionId} subscribed to {GroupName}", + Context.ConnectionId, groupName); + } + + public async Task UnsubscribeFromPendingChange(Guid pendingChangeId) + { + var groupName = $"pending-change-{pendingChangeId}"; + await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName); + + _logger.LogInformation( + "Client {ConnectionId} unsubscribed from {GroupName}", + Context.ConnectionId, groupName); + } +} +``` + +### PendingChangeApproved Notification + +```csharp +public class PendingChangeApprovedEventHandler + : INotificationHandler +{ + private readonly IHubContext _hubContext; + private readonly ILogger _logger; + + public async Task Handle(PendingChangeApprovedEvent e, CancellationToken ct) + { + var groupName = $"pending-change-{e.PendingChangeId}"; + + var notification = new + { + PendingChangeId = e.PendingChangeId, + Status = "Approved", + ToolName = e.ToolName, + Operation = e.Diff.Operation, + EntityType = e.Diff.EntityType, + EntityId = e.Diff.EntityId, + ApprovedBy = e.ApprovedBy, + Timestamp = DateTime.UtcNow + }; + + await _hubContext.Clients + .Group(groupName) + .SendAsync("PendingChangeApproved", notification, ct); + + _logger.LogInformation( + "Sent PendingChangeApproved notification: {PendingChangeId}", + e.PendingChangeId); + } +} +``` + +### PendingChangeRejected Notification + +```csharp +public class PendingChangeRejectedEventHandler + : INotificationHandler +{ + private readonly IHubContext _hubContext; + private readonly ILogger _logger; + + public async Task Handle(PendingChangeRejectedEvent e, CancellationToken ct) + { + var groupName = $"pending-change-{e.PendingChangeId}"; + + var notification = new + { + PendingChangeId = e.PendingChangeId, + Status = "Rejected", + ToolName = e.ToolName, + Reason = e.Reason, + RejectedBy = e.RejectedBy, + Timestamp = DateTime.UtcNow + }; + + await _hubContext.Clients + .Group(groupName) + .SendAsync("PendingChangeRejected", notification, ct); + + _logger.LogInformation( + "Sent PendingChangeRejected notification: {PendingChangeId} - Reason: {Reason}", + e.PendingChangeId, e.Reason); + } +} +``` + +### API Key Authentication for SignalR + +```csharp +public class McpApiKeyAuthHandler : AuthenticationHandler +{ + private readonly IMcpApiKeyService _apiKeyService; + + protected override async Task HandleAuthenticateAsync() + { + // For SignalR, API Key may be in query string + var apiKey = Request.Query["access_token"].FirstOrDefault(); + + if (string.IsNullOrEmpty(apiKey)) + { + return AuthenticateResult.Fail("Missing API Key"); + } + + var validationResult = await _apiKeyService.ValidateAsync(apiKey); + if (!validationResult.IsValid) + { + return AuthenticateResult.Fail(validationResult.ErrorMessage); + } + + // Store in HttpContext.Items for Hub access + Context.Items["TenantId"] = validationResult.TenantId; + Context.Items["ApiKeyId"] = validationResult.ApiKeyId; + + var claims = new[] + { + new Claim("TenantId", validationResult.TenantId.ToString()), + new Claim("ApiKeyId", validationResult.ApiKeyId.ToString()) + }; + + var identity = new ClaimsIdentity(claims, "ApiKey"); + var principal = new ClaimsPrincipal(identity); + var ticket = new AuthenticationTicket(principal, "ApiKey"); + + return AuthenticateResult.Success(ticket); + } +} +``` + +### AI Client Example (Pseudo-code) + +```typescript +// AI Client (Claude Desktop / ChatGPT) +const connection = new HubConnection("https://colaflow.com/hubs/mcp", { + accessTokenFactory: () => apiKey +}); + +await connection.start(); + +// Subscribe to pending change notifications +await connection.invoke("SubscribeToPendingChange", pendingChangeId); + +// Listen for approval +connection.on("PendingChangeApproved", (notification) => { + console.log("Change approved:", notification); + console.log("EntityId:", notification.EntityId); + // Continue AI workflow... +}); + +// Listen for rejection +connection.on("PendingChangeRejected", (notification) => { + console.log("Change rejected:", notification.Reason); + // Adjust AI behavior... +}); +``` + +## Tasks + +### Task 1: Create McpHub (2 hours) +- [ ] Create `McpHub` class (inherit from `Hub`) +- [ ] Implement `SubscribeToPendingChange()` method +- [ ] Implement `UnsubscribeFromPendingChange()` method +- [ ] Add connection lifecycle logging + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Hubs/McpHub.cs` + +### Task 2: API Key Authentication for SignalR (3 hours) +- [ ] Update `McpApiKeyMiddleware` to support query string API Key +- [ ] Add API Key to `HttpContext.Items` for Hub access +- [ ] Test SignalR connection with API Key + +**Files to Modify**: +- `ColaFlow.Modules.Mcp/Middleware/McpApiKeyMiddleware.cs` + +### Task 3: PendingChangeApproved Event Handler (2 hours) +- [ ] Create `PendingChangeApprovedEventHandler` +- [ ] Use `IHubContext` to send notification +- [ ] Target specific group (`pending-change-{id}`) +- [ ] Log notification sent + +**Files to Create**: +- `ColaFlow.Modules.Mcp/EventHandlers/PendingChangeApprovedNotificationHandler.cs` + +### Task 4: PendingChangeRejected Event Handler (1 hour) +- [ ] Create `PendingChangeRejectedEventHandler` +- [ ] Send rejection notification with reason + +**Files to Create**: +- `ColaFlow.Modules.Mcp/EventHandlers/PendingChangeRejectedNotificationHandler.cs` + +### Task 5: PendingChangeExpired Event Handler (1 hour) +- [ ] Create `PendingChangeExpiredEventHandler` +- [ ] Send expiration notification + +**Files to Create**: +- `ColaFlow.Modules.Mcp/EventHandlers/PendingChangeExpiredNotificationHandler.cs` + +### Task 6: Configure SignalR (1 hour) +- [ ] Register `McpHub` in `Program.cs` +- [ ] Configure CORS for SignalR +- [ ] Configure authentication + +**Files to Modify**: +- `ColaFlow.Api/Program.cs` + +### Task 7: Integration Tests (4 hours) +- [ ] Test SignalR connection with API Key +- [ ] Test group subscription/unsubscription +- [ ] Test notification delivery (approval/rejection) +- [ ] Test multiple clients (isolation) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/McpHubIntegrationTests.cs` + +## Testing Strategy + +### Integration Test Example + +```csharp +[Fact] +public async Task ApprovalNotification_SentToSubscribedClient() +{ + // Arrange - Connect SignalR client + var hubConnection = new HubConnectionBuilder() + .WithUrl("http://localhost/hubs/mcp?access_token=" + _apiKey) + .Build(); + + await hubConnection.StartAsync(); + + // Subscribe to pending change + await hubConnection.InvokeAsync("SubscribeToPendingChange", _pendingChangeId); + + // Setup listener + var notificationReceived = new TaskCompletionSource(); + hubConnection.On("PendingChangeApproved", notification => + { + notificationReceived.SetResult(notification); + }); + + // Act - Approve pending change + await _pendingChangeService.ApproveAsync(_pendingChangeId, _userId, CancellationToken.None); + + // Assert - Notification received within 2 seconds + var notification = await notificationReceived.Task.WaitAsync(TimeSpan.FromSeconds(2)); + Assert.NotNull(notification); +} +``` + +## Dependencies + +**Prerequisites**: +- Story 5.10 (PendingChange Management) - Domain events to listen to +- M1 SignalR infrastructure (Day 11-17) - BaseHub, authentication + +**Optional**: Not strictly blocking for M2 MVP (can use polling fallback) + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| WebSocket not supported | Medium | Low | Fallback to long polling | +| SignalR connection drops | Medium | Medium | Auto-reconnect, message queue | +| Scalability issues (many clients) | Medium | Low | Use Redis backplane for multi-instance | + +## Definition of Done + +- [ ] McpHub implemented +- [ ] API Key authentication working +- [ ] Approval notification sent within 1 second +- [ ] Rejection notification sent within 1 second +- [ ] Group subscriptions working +- [ ] Integration tests passing +- [ ] Connection handling robust (disconnect/reconnect) +- [ ] Code reviewed + +## Notes + +### Why This Story Matters +- **Completes AI Loop**: AI can act on approval results immediately +- **Better Performance**: WebSocket > polling (10x less overhead) +- **Foundation**: Enables future real-time AI features +- **M2 Polish**: Demonstrates production-grade implementation + +### Key Design Decisions +1. **SignalR Groups**: Target specific pending changes (not broadcast) +2. **Domain Events**: Loosely coupled, easy to add more notifications +3. **API Key Auth**: Reuse existing authentication system +4. **Graceful Degradation**: Fallback to polling if WebSocket fails + +### Scalability (Future) +- Use Redis backplane for multi-instance SignalR +- Horizontal scaling (multiple app servers) +- Message queue for guaranteed delivery + +### SignalR Configuration + +```csharp +// Program.cs +builder.Services.AddSignalR() + .AddStackExchangeRedis(builder.Configuration.GetConnectionString("Redis")); + +app.MapHub("/hubs/mcp"); +``` + +## Reference Materials +- SignalR Documentation: https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction +- Sprint 5 Plan: `docs/plans/sprint_5.md` diff --git a/docs/stories/sprint_5/story_5_2.md b/docs/stories/sprint_5/story_5_2.md new file mode 100644 index 0000000..166d1ae --- /dev/null +++ b/docs/stories/sprint_5/story_5_2.md @@ -0,0 +1,431 @@ +--- +story_id: story_5_2 +sprint_id: sprint_5 +phase: Phase 1 - Foundation +status: not_started +priority: P0 +story_points: 5 +assignee: backend +estimated_days: 2 +created_date: 2025-11-06 +dependencies: [] +--- + +# Story 5.2: API Key Management System + +**Phase**: Phase 1 - Foundation (Week 1-2) +**Priority**: P0 CRITICAL +**Estimated Effort**: 5 Story Points (2 days) + +## User Story + +**As a** System Administrator +**I want** to securely manage API Keys for AI agents +**So that** only authorized AI agents can access ColaFlow through MCP protocol + +## Business Value + +Security is critical for M2. API Key management ensures only authorized AI agents can read/write ColaFlow data. Without this, MCP Server would be vulnerable to unauthorized access. + +**Impact**: +- Prevents unauthorized AI access +- Enables multi-tenant security isolation +- Supports audit trail for all AI operations +- Foundation for rate limiting and IP whitelisting + +## Acceptance Criteria + +### AC1: API Key Generation +- [ ] Generate unique 40-character random API Keys +- [ ] Format: `cola_` prefix + 36 random characters (e.g., `cola_abc123...xyz`) +- [ ] API Keys are cryptographically secure (using `RandomNumberGenerator`) +- [ ] No duplicate keys in database (unique constraint) + +### AC2: Secure Storage +- [ ] API Key hashed with BCrypt before storage +- [ ] Only first 8 characters stored as `key_prefix` for lookup +- [ ] Full hash stored in `key_hash` column +- [ ] Original API Key never stored (shown once at creation) + +### AC3: API Key Validation +- [ ] Middleware validates `Authorization: Bearer ` header +- [ ] API Key lookup by prefix (fast index) +- [ ] Hash verification with BCrypt.Verify +- [ ] Expired keys rejected (check `expires_at`) +- [ ] Revoked keys rejected (check `revoked_at`) +- [ ] Update `last_used_at` and `usage_count` on successful validation + +### AC4: Multi-Tenant Isolation +- [ ] API Key linked to specific `tenant_id` +- [ ] All MCP operations scoped to API Key's tenant +- [ ] Cross-tenant access blocked (Global Query Filters) +- [ ] TenantContext service extracts tenant from API Key + +### AC5: CRUD API Endpoints +- [ ] `POST /api/mcp/keys` - Create API Key (returns plain key once) +- [ ] `GET /api/mcp/keys` - List tenant's API Keys (no key_hash) +- [ ] `GET /api/mcp/keys/{id}` - Get API Key details +- [ ] `PATCH /api/mcp/keys/{id}` - Update name/permissions +- [ ] `DELETE /api/mcp/keys/{id}` - Revoke API Key (soft delete) + +### AC6: Testing +- [ ] Unit tests for key generation (uniqueness, format) +- [ ] Unit tests for BCrypt hashing/verification +- [ ] Integration tests for CRUD operations +- [ ] Integration tests for multi-tenant isolation +- [ ] Integration tests for authentication middleware + +## Technical Design + +### Database Schema + +```sql +CREATE TABLE mcp_api_keys ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, + user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + + -- Security + key_hash VARCHAR(64) NOT NULL UNIQUE, + key_prefix VARCHAR(16) NOT NULL, + + -- Metadata + name VARCHAR(255) NOT NULL, + description TEXT, + + -- Permissions (JSONB for flexibility) + permissions JSONB NOT NULL DEFAULT '{"read": true, "write": false}', + ip_whitelist JSONB, + + -- Status + status INT NOT NULL DEFAULT 1, -- 1=Active, 2=Revoked + last_used_at TIMESTAMP NULL, + usage_count BIGINT NOT NULL DEFAULT 0, + + -- Lifecycle + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + expires_at TIMESTAMP NOT NULL, -- Default: 90 days + revoked_at TIMESTAMP NULL, + revoked_by UUID REFERENCES users(id), + + -- Indexes + INDEX idx_key_prefix (key_prefix), + INDEX idx_tenant_user (tenant_id, user_id), + INDEX idx_expires_at (expires_at), + INDEX idx_status (status) +); +``` + +### Domain Model + +```csharp +public class McpApiKey : AggregateRoot +{ + public Guid TenantId { get; private set; } + public Guid UserId { get; private set; } + + public string KeyHash { get; private set; } + public string KeyPrefix { get; private set; } + + public string Name { get; private set; } + public string? Description { get; private set; } + + public ApiKeyPermissions Permissions { get; private set; } + public List? IpWhitelist { get; private set; } + + public ApiKeyStatus Status { get; private set; } + public DateTime? LastUsedAt { get; private set; } + public long UsageCount { get; private set; } + + public DateTime ExpiresAt { get; private set; } + public DateTime? RevokedAt { get; private set; } + public Guid? RevokedBy { get; private set; } + + // Factory method + public static (McpApiKey apiKey, string plainKey) Create( + string name, + Guid tenantId, + Guid userId, + ApiKeyPermissions permissions, + int expirationDays = 90) + { + var plainKey = GenerateApiKey(); + var keyHash = BCrypt.Net.BCrypt.HashPassword(plainKey); + var keyPrefix = plainKey.Substring(0, 12); // "cola_abc123..." + + var apiKey = new McpApiKey + { + Id = Guid.NewGuid(), + TenantId = tenantId, + UserId = userId, + KeyHash = keyHash, + KeyPrefix = keyPrefix, + Name = name, + Permissions = permissions, + Status = ApiKeyStatus.Active, + ExpiresAt = DateTime.UtcNow.AddDays(expirationDays) + }; + + apiKey.AddDomainEvent(new ApiKeyCreatedEvent(apiKey.Id, name)); + return (apiKey, plainKey); + } + + public void Revoke(Guid revokedBy) + { + if (Status == ApiKeyStatus.Revoked) + throw new InvalidOperationException("API Key already revoked"); + + Status = ApiKeyStatus.Revoked; + RevokedAt = DateTime.UtcNow; + RevokedBy = revokedBy; + + AddDomainEvent(new ApiKeyRevokedEvent(Id, Name)); + } + + public void RecordUsage() + { + LastUsedAt = DateTime.UtcNow; + UsageCount++; + } + + private static string GenerateApiKey() + { + var bytes = new byte[27]; // 36 chars in base64 + using var rng = RandomNumberGenerator.Create(); + rng.GetBytes(bytes); + return "cola_" + Convert.ToBase64String(bytes) + .Replace("+", "").Replace("/", "").Replace("=", "") + .Substring(0, 36); + } +} + +public class ApiKeyPermissions +{ + public bool Read { get; set; } = true; + public bool Write { get; set; } = false; + public List AllowedResources { get; set; } = new(); + public List AllowedTools { get; set; } = new(); +} + +public enum ApiKeyStatus +{ + Active = 1, + Revoked = 2 +} +``` + +### Authentication Middleware + +```csharp +public class McpApiKeyMiddleware +{ + private readonly RequestDelegate _next; + + public async Task InvokeAsync( + HttpContext context, + IMcpApiKeyService apiKeyService) + { + // Only apply to /mcp endpoints + if (!context.Request.Path.StartsWithSegments("/mcp")) + { + await _next(context); + return; + } + + // Extract API Key from Authorization header + var apiKey = ExtractApiKey(context.Request.Headers); + if (string.IsNullOrEmpty(apiKey)) + { + context.Response.StatusCode = 401; + await context.Response.WriteAsJsonAsync(new McpError + { + Code = McpErrorCode.Unauthorized, + Message = "Missing API Key" + }); + return; + } + + // Validate API Key + var validationResult = await apiKeyService.ValidateAsync(apiKey); + if (!validationResult.IsValid) + { + context.Response.StatusCode = 401; + await context.Response.WriteAsJsonAsync(new McpError + { + Code = McpErrorCode.Unauthorized, + Message = validationResult.ErrorMessage + }); + return; + } + + // Set TenantContext for downstream handlers + context.Items["TenantId"] = validationResult.TenantId; + context.Items["ApiKeyId"] = validationResult.ApiKeyId; + context.Items["ApiKeyPermissions"] = validationResult.Permissions; + + await _next(context); + } +} +``` + +## Tasks + +### Task 1: Domain Layer - McpApiKey Aggregate (4 hours) +- [ ] Create `McpApiKey` entity class +- [ ] Create `ApiKeyPermissions` value object +- [ ] Implement `Create()` factory method with key generation +- [ ] Implement `Revoke()` method +- [ ] Create domain events (ApiKeyCreated, ApiKeyRevoked) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Domain/Entities/McpApiKey.cs` +- `ColaFlow.Modules.Mcp.Domain/ValueObjects/ApiKeyPermissions.cs` +- `ColaFlow.Modules.Mcp.Domain/Events/ApiKeyCreatedEvent.cs` +- `ColaFlow.Modules.Mcp.Domain/Events/ApiKeyRevokedEvent.cs` + +### Task 2: Infrastructure - Repository & Database (4 hours) +- [ ] Create `IMcpApiKeyRepository` interface +- [ ] Implement `McpApiKeyRepository` (EF Core) +- [ ] Create database migration for `mcp_api_keys` table +- [ ] Configure EF Core entity (fluent API) +- [ ] Add indexes (key_prefix, tenant_id) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Domain/Repositories/IMcpApiKeyRepository.cs` +- `ColaFlow.Modules.Mcp.Infrastructure/Repositories/McpApiKeyRepository.cs` +- `ColaFlow.Modules.Mcp.Infrastructure/EntityConfigurations/McpApiKeyConfiguration.cs` +- `ColaFlow.Modules.Mcp.Infrastructure/Migrations/YYYYMMDDHHMMSS_AddMcpApiKeys.cs` + +### Task 3: Application Layer - API Key Service (4 hours) +- [ ] Create `IMcpApiKeyService` interface +- [ ] Implement `CreateApiKeyAsync()` method +- [ ] Implement `ValidateAsync()` method (BCrypt verification) +- [ ] Implement `RevokeApiKeyAsync()` method +- [ ] Implement `GetApiKeysAsync()` query + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Application/Contracts/IMcpApiKeyService.cs` +- `ColaFlow.Modules.Mcp.Application/Services/McpApiKeyService.cs` + +### Task 4: Authentication Middleware (3 hours) +- [ ] Create `McpApiKeyMiddleware` class +- [ ] Extract API Key from `Authorization: Bearer` header +- [ ] Validate API Key (call `IMcpApiKeyService.ValidateAsync`) +- [ ] Set TenantContext in HttpContext.Items +- [ ] Return 401 for invalid/expired keys + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Middleware/McpApiKeyMiddleware.cs` +- `ColaFlow.Modules.Mcp/Extensions/McpMiddlewareExtensions.cs` + +### Task 5: REST API Endpoints (3 hours) +- [ ] Create `McpKeysController` +- [ ] `POST /api/mcp/keys` - Create API Key +- [ ] `GET /api/mcp/keys` - List API Keys +- [ ] `GET /api/mcp/keys/{id}` - Get API Key details +- [ ] `DELETE /api/mcp/keys/{id}` - Revoke API Key +- [ ] Add [Authorize] attribute (require JWT) + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Controllers/McpKeysController.cs` +- `ColaFlow.Modules.Mcp/DTOs/CreateApiKeyRequest.cs` +- `ColaFlow.Modules.Mcp/DTOs/ApiKeyResponse.cs` + +### Task 6: Unit Tests (3 hours) +- [ ] Test API Key generation (format, uniqueness) +- [ ] Test BCrypt hashing/verification +- [ ] Test McpApiKey domain logic (Create, Revoke) +- [ ] Test validation logic (expired, revoked) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Domain/McpApiKeyTests.cs` +- `ColaFlow.Modules.Mcp.Tests/Services/McpApiKeyServiceTests.cs` + +### Task 7: Integration Tests (3 hours) +- [ ] Test CRUD API endpoints +- [ ] Test multi-tenant isolation (Tenant A cannot see Tenant B keys) +- [ ] Test authentication middleware (valid/invalid keys) +- [ ] Test expired key rejection + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/McpApiKeyIntegrationTests.cs` + +## Testing Strategy + +### Unit Tests (Target: > 80% coverage) +- API Key generation logic +- BCrypt hashing/verification +- Domain entity methods (Create, Revoke) +- Validation logic (expiration, revocation) + +### Integration Tests +- CRUD operations end-to-end +- Authentication middleware flow +- Multi-tenant isolation verification +- Database queries (repository) + +### Manual Testing Checklist +- [ ] Create API Key → returns plain key once +- [ ] Use API Key in Authorization header → success +- [ ] Use expired API Key → 401 Unauthorized +- [ ] Use revoked API Key → 401 Unauthorized +- [ ] Tenant A cannot see Tenant B's keys +- [ ] API Key usage count increments + +## Dependencies + +**Prerequisites**: +- .NET 9 ASP.NET Core +- BCrypt.Net NuGet package +- EF Core 9 +- PostgreSQL database + +**Blocks**: +- All MCP operations (Story 5.5, 5.11) - Need API Key authentication + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| API Key brute force | High | Low | BCrypt hashing (slow), rate limiting | +| Key prefix collision | Medium | Very Low | 12-char prefix, crypto RNG | +| BCrypt performance | Medium | Low | Prefix lookup optimization | +| Key storage security | High | Low | Hash only, audit access | + +## Definition of Done + +- [ ] Code compiles without warnings +- [ ] All unit tests passing (> 80% coverage) +- [ ] All integration tests passing +- [ ] Code reviewed and approved +- [ ] Database migration created and tested +- [ ] XML documentation for public APIs +- [ ] Authentication middleware works end-to-end +- [ ] Multi-tenant isolation verified (100%) +- [ ] API Key never logged in plain text + +## Notes + +### Why This Story Matters +- **Security Foundation**: All MCP operations depend on secure authentication +- **Multi-Tenant Isolation**: Prevents cross-tenant data access +- **Audit Trail**: Tracks which AI agent performed which operation +- **Compliance**: Supports GDPR, SOC2 requirements + +### Key Design Decisions +1. **BCrypt Hashing**: Slow by design, prevents brute force +2. **Prefix Lookup**: Fast lookup without full hash scan +3. **JSONB Permissions**: Flexible permission model for future +4. **Soft Delete**: Revocation preserves audit trail + +### Security Best Practices +- API Key shown only once at creation +- BCrypt with default cost factor (10) +- 90-day expiration by default +- Rate limiting (to be added in Phase 6) +- IP whitelisting (to be added in Phase 4) + +### Reference Materials +- Sprint 5 Plan: `docs/plans/sprint_5.md` +- Architecture Design: `docs/M2-MCP-SERVER-ARCHITECTURE.md` +- BCrypt.Net Documentation: https://github.com/BcryptNet/bcrypt.net diff --git a/docs/stories/sprint_5/story_5_3.md b/docs/stories/sprint_5/story_5_3.md new file mode 100644 index 0000000..7b54182 --- /dev/null +++ b/docs/stories/sprint_5/story_5_3.md @@ -0,0 +1,586 @@ +--- +story_id: story_5_3 +sprint_id: sprint_5 +phase: Phase 1 - Foundation +status: not_started +priority: P0 +story_points: 5 +assignee: backend +estimated_days: 2 +created_date: 2025-11-06 +dependencies: [] +--- + +# Story 5.3: MCP Domain Layer Design + +**Phase**: Phase 1 - Foundation (Week 1-2) +**Priority**: P0 CRITICAL +**Estimated Effort**: 5 Story Points (2 days) + +## User Story + +**As a** Backend Developer +**I want** well-designed domain entities and aggregates for MCP operations +**So that** the system has a solid foundation following DDD principles and can be easily extended + +## Business Value + +Clean domain design is critical for long-term maintainability. This Story establishes the domain model for all MCP operations, ensuring business rules are enforced consistently and the system can evolve without accumulating technical debt. + +**Impact**: +- Provides solid foundation for all MCP features +- Enforces business rules at domain level +- Enables rich domain events for audit and notifications +- Reduces bugs through domain-driven validation + +## Acceptance Criteria + +### AC1: McpApiKey Aggregate Root (Covered in Story 5.2) +- [ ] McpApiKey entity implemented as aggregate root +- [ ] Factory method for creation with validation +- [ ] Domain methods (Revoke, RecordUsage, UpdatePermissions) +- [ ] Domain events (ApiKeyCreated, ApiKeyRevoked) + +### AC2: PendingChange Aggregate Root +- [ ] PendingChange entity with status lifecycle +- [ ] Factory method for creation from Diff Preview +- [ ] Approve() method that triggers execution +- [ ] Reject() method with reason logging +- [ ] Expire() method for 24-hour timeout +- [ ] Domain events (PendingChangeCreated, Approved, Rejected, Expired) + +### AC3: DiffPreview Value Object +- [ ] Immutable value object for before/after data +- [ ] Field-level change tracking (DiffField collection) +- [ ] Support for CREATE, UPDATE, DELETE operations +- [ ] JSON serialization for complex objects +- [ ] Equality comparison (value semantics) + +### AC4: Domain Events +- [ ] ApiKeyCreatedEvent +- [ ] ApiKeyRevokedEvent +- [ ] PendingChangeCreatedEvent +- [ ] PendingChangeApprovedEvent +- [ ] PendingChangeRejectedEvent +- [ ] PendingChangeExpiredEvent +- [ ] All events inherit from `DomainEvent` base class + +### AC5: Business Rule Validation +- [ ] PendingChange cannot be approved if expired +- [ ] PendingChange cannot be rejected if already approved +- [ ] McpApiKey cannot be used if revoked or expired +- [ ] DiffPreview must have at least one changed field for UPDATE +- [ ] All invariants enforced in domain entities + +### AC6: Testing +- [ ] Unit test coverage > 90% for domain layer +- [ ] Test all domain methods (Create, Approve, Reject, etc.) +- [ ] Test domain events are raised correctly +- [ ] Test business rule violations throw exceptions + +## Technical Design + +### Domain Model Diagram + +``` +┌─────────────────────────────────────┐ +│ McpApiKey (Aggregate Root) │ +│ - TenantId │ +│ - KeyHash, KeyPrefix │ +│ - Permissions │ +│ - Status (Active, Revoked) │ +│ - ExpiresAt │ +│ + Create() │ +│ + Revoke() │ +│ + RecordUsage() │ +└─────────────────────────────────────┘ + +┌─────────────────────────────────────┐ +│ PendingChange (Aggregate Root) │ +│ - TenantId, ApiKeyId │ +│ - ToolName │ +│ - Diff (DiffPreview) │ +│ - Status (Pending, Approved, ...) │ +│ - ExpiresAt │ +│ + Create() │ +│ + Approve() │ +│ + Reject() │ +│ + Expire() │ +└─────────────────────────────────────┘ + │ + │ has-a + ↓ +┌─────────────────────────────────────┐ +│ DiffPreview (Value Object) │ +│ - Operation (CREATE/UPDATE/DELETE) │ +│ - EntityType, EntityId │ +│ - BeforeData, AfterData │ +│ - ChangedFields[] │ +│ + CalculateDiff() │ +└─────────────────────────────────────┘ +``` + +### PendingChange Aggregate Root + +```csharp +public class PendingChange : AggregateRoot +{ + public Guid TenantId { get; private set; } + public Guid ApiKeyId { get; private set; } + + public string ToolName { get; private set; } + public DiffPreview Diff { get; private set; } + + public PendingChangeStatus Status { get; private set; } + public DateTime ExpiresAt { get; private set; } + + public Guid? ApprovedBy { get; private set; } + public DateTime? ApprovedAt { get; private set; } + + public Guid? RejectedBy { get; private set; } + public DateTime? RejectedAt { get; private set; } + public string? RejectionReason { get; private set; } + + // Factory method + public static PendingChange Create( + string toolName, + DiffPreview diff, + Guid tenantId, + Guid apiKeyId) + { + if (string.IsNullOrWhiteSpace(toolName)) + throw new ArgumentException("Tool name required", nameof(toolName)); + + if (diff == null) + throw new ArgumentNullException(nameof(diff)); + + var pendingChange = new PendingChange + { + Id = Guid.NewGuid(), + TenantId = tenantId, + ApiKeyId = apiKeyId, + ToolName = toolName, + Diff = diff, + Status = PendingChangeStatus.PendingApproval, + ExpiresAt = DateTime.UtcNow.AddHours(24) + }; + + pendingChange.AddDomainEvent(new PendingChangeCreatedEvent( + pendingChange.Id, + toolName, + diff.EntityType, + diff.Operation + )); + + return pendingChange; + } + + // Domain method: Approve + public void Approve(Guid approvedBy) + { + if (Status != PendingChangeStatus.PendingApproval) + throw new InvalidOperationException( + $"Cannot approve change with status {Status}"); + + if (DateTime.UtcNow > ExpiresAt) + throw new InvalidOperationException( + "Cannot approve expired change"); + + Status = PendingChangeStatus.Approved; + ApprovedBy = approvedBy; + ApprovedAt = DateTime.UtcNow; + + AddDomainEvent(new PendingChangeApprovedEvent( + Id, + ToolName, + Diff, + approvedBy + )); + } + + // Domain method: Reject + public void Reject(Guid rejectedBy, string reason) + { + if (Status != PendingChangeStatus.PendingApproval) + throw new InvalidOperationException( + $"Cannot reject change with status {Status}"); + + Status = PendingChangeStatus.Rejected; + RejectedBy = rejectedBy; + RejectedAt = DateTime.UtcNow; + RejectionReason = reason; + + AddDomainEvent(new PendingChangeRejectedEvent( + Id, + ToolName, + reason, + rejectedBy + )); + } + + // Domain method: Expire + public void Expire() + { + if (Status != PendingChangeStatus.PendingApproval) + return; // Already processed + + if (DateTime.UtcNow <= ExpiresAt) + throw new InvalidOperationException( + "Cannot expire change before expiration time"); + + Status = PendingChangeStatus.Expired; + + AddDomainEvent(new PendingChangeExpiredEvent(Id, ToolName)); + } +} + +public enum PendingChangeStatus +{ + PendingApproval = 0, + Approved = 1, + Rejected = 2, + Expired = 3 +} +``` + +### DiffPreview Value Object + +```csharp +public class DiffPreview : ValueObject +{ + public string Operation { get; private set; } // CREATE, UPDATE, DELETE + public string EntityType { get; private set; } + public Guid? EntityId { get; private set; } + public string? EntityKey { get; private set; } // e.g., "COLA-146" + + public object? BeforeData { get; private set; } + public object? AfterData { get; private set; } + + public IReadOnlyList ChangedFields { get; private set; } + + public DiffPreview( + string operation, + string entityType, + Guid? entityId, + string? entityKey, + object? beforeData, + object? afterData, + IReadOnlyList changedFields) + { + if (string.IsNullOrWhiteSpace(operation)) + throw new ArgumentException("Operation required", nameof(operation)); + + if (string.IsNullOrWhiteSpace(entityType)) + throw new ArgumentException("EntityType required", nameof(entityType)); + + if (operation == "UPDATE" && (changedFields == null || !changedFields.Any())) + throw new ArgumentException( + "UPDATE operation must have at least one changed field", + nameof(changedFields)); + + Operation = operation; + EntityType = entityType; + EntityId = entityId; + EntityKey = entityKey; + BeforeData = beforeData; + AfterData = afterData; + ChangedFields = changedFields ?? new List().AsReadOnly(); + } + + // Value object equality + protected override IEnumerable GetEqualityComponents() + { + yield return Operation; + yield return EntityType; + yield return EntityId; + yield return EntityKey; + yield return BeforeData; + yield return AfterData; + foreach (var field in ChangedFields) + yield return field; + } +} + +public class DiffField : ValueObject +{ + public string FieldName { get; private set; } + public string DisplayName { get; private set; } + public object? OldValue { get; private set; } + public object? NewValue { get; private set; } + public string? DiffHtml { get; private set; } + + public DiffField( + string fieldName, + string displayName, + object? oldValue, + object? newValue, + string? diffHtml = null) + { + FieldName = fieldName; + DisplayName = displayName; + OldValue = oldValue; + NewValue = newValue; + DiffHtml = diffHtml; + } + + protected override IEnumerable GetEqualityComponents() + { + yield return FieldName; + yield return DisplayName; + yield return OldValue; + yield return NewValue; + yield return DiffHtml; + } +} +``` + +### Domain Events + +```csharp +// Base class (should already exist in M1) +public abstract record DomainEvent +{ + public Guid EventId { get; init; } = Guid.NewGuid(); + public DateTime OccurredAt { get; init; } = DateTime.UtcNow; +} + +// PendingChange events +public record PendingChangeCreatedEvent( + Guid PendingChangeId, + string ToolName, + string EntityType, + string Operation +) : DomainEvent; + +public record PendingChangeApprovedEvent( + Guid PendingChangeId, + string ToolName, + DiffPreview Diff, + Guid ApprovedBy +) : DomainEvent; + +public record PendingChangeRejectedEvent( + Guid PendingChangeId, + string ToolName, + string Reason, + Guid RejectedBy +) : DomainEvent; + +public record PendingChangeExpiredEvent( + Guid PendingChangeId, + string ToolName +) : DomainEvent; + +// ApiKey events (from Story 5.2) +public record ApiKeyCreatedEvent( + Guid ApiKeyId, + string Name +) : DomainEvent; + +public record ApiKeyRevokedEvent( + Guid ApiKeyId, + string Name +) : DomainEvent; +``` + +## Tasks + +### Task 1: Create Domain Base Classes (2 hours) +- [ ] Verify `AggregateRoot` base class exists (from M1) +- [ ] Verify `ValueObject` base class exists (from M1) +- [ ] Verify `DomainEvent` base class exists (from M1) +- [ ] Update if needed for MCP requirements + +**Files to Check/Update**: +- `ColaFlow.Core/Domain/AggregateRoot.cs` +- `ColaFlow.Core/Domain/ValueObject.cs` +- `ColaFlow.Core/Domain/DomainEvent.cs` + +### Task 2: PendingChange Aggregate Root (4 hours) +- [ ] Create `PendingChange` entity class +- [ ] Implement `Create()` factory method +- [ ] Implement `Approve()` domain method +- [ ] Implement `Reject()` domain method +- [ ] Implement `Expire()` domain method +- [ ] Add business rule validation + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Domain/Entities/PendingChange.cs` +- `ColaFlow.Modules.Mcp.Domain/Enums/PendingChangeStatus.cs` + +### Task 3: DiffPreview Value Object (3 hours) +- [ ] Create `DiffPreview` value object +- [ ] Create `DiffField` value object +- [ ] Implement equality comparison +- [ ] Add validation (operation, changed fields) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Domain/ValueObjects/DiffPreview.cs` +- `ColaFlow.Modules.Mcp.Domain/ValueObjects/DiffField.cs` + +### Task 4: Domain Events (2 hours) +- [ ] Create `PendingChangeCreatedEvent` +- [ ] Create `PendingChangeApprovedEvent` +- [ ] Create `PendingChangeRejectedEvent` +- [ ] Create `PendingChangeExpiredEvent` +- [ ] Ensure events inherit from `DomainEvent` + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Domain/Events/PendingChangeCreatedEvent.cs` +- `ColaFlow.Modules.Mcp.Domain/Events/PendingChangeApprovedEvent.cs` +- `ColaFlow.Modules.Mcp.Domain/Events/PendingChangeRejectedEvent.cs` +- `ColaFlow.Modules.Mcp.Domain/Events/PendingChangeExpiredEvent.cs` + +### Task 5: Unit Tests - PendingChange (4 hours) +- [ ] Test `Create()` factory method +- [ ] Test `Approve()` happy path +- [ ] Test `Approve()` when already approved (throws exception) +- [ ] Test `Approve()` when expired (throws exception) +- [ ] Test `Reject()` happy path +- [ ] Test `Reject()` when already approved (throws exception) +- [ ] Test `Expire()` happy path +- [ ] Test domain events are raised + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Domain/PendingChangeTests.cs` + +### Task 6: Unit Tests - DiffPreview (3 hours) +- [ ] Test `DiffPreview` creation +- [ ] Test validation (operation required, entity type required) +- [ ] Test UPDATE requires changed fields +- [ ] Test equality comparison (value semantics) +- [ ] Test `DiffField` creation and equality + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Domain/DiffPreviewTests.cs` + +## Testing Strategy + +### Unit Tests (Target: > 90% coverage) +- All domain entity methods (Create, Approve, Reject, Expire) +- All business rule validations +- Domain events raised at correct times +- Value object equality semantics +- Edge cases (null values, invalid states) + +### Test Cases for PendingChange + +```csharp +[Fact] +public void Create_ValidInput_Success() +{ + // Arrange + var diff = CreateValidDiff(); + + // Act + var pendingChange = PendingChange.Create( + "create_issue", diff, tenantId, apiKeyId); + + // Assert + Assert.NotEqual(Guid.Empty, pendingChange.Id); + Assert.Equal(PendingChangeStatus.PendingApproval, pendingChange.Status); + Assert.True(pendingChange.ExpiresAt > DateTime.UtcNow); + Assert.Single(pendingChange.DomainEvents); // PendingChangeCreatedEvent +} + +[Fact] +public void Approve_PendingChange_Success() +{ + // Arrange + var pendingChange = CreatePendingChange(); + var approverId = Guid.NewGuid(); + + // Act + pendingChange.Approve(approverId); + + // Assert + Assert.Equal(PendingChangeStatus.Approved, pendingChange.Status); + Assert.Equal(approverId, pendingChange.ApprovedBy); + Assert.NotNull(pendingChange.ApprovedAt); + Assert.Contains(pendingChange.DomainEvents, + e => e is PendingChangeApprovedEvent); +} + +[Fact] +public void Approve_AlreadyApproved_ThrowsException() +{ + // Arrange + var pendingChange = CreatePendingChange(); + pendingChange.Approve(Guid.NewGuid()); + + // Act & Assert + Assert.Throws( + () => pendingChange.Approve(Guid.NewGuid())); +} + +[Fact] +public void Approve_ExpiredChange_ThrowsException() +{ + // Arrange + var pendingChange = CreateExpiredPendingChange(); + + // Act & Assert + Assert.Throws( + () => pendingChange.Approve(Guid.NewGuid())); +} +``` + +## Dependencies + +**Prerequisites**: +- M1 domain base classes (AggregateRoot, ValueObject, DomainEvent) +- .NET 9 + +**Used By**: +- Story 5.9 (Diff Preview Service) - Uses DiffPreview value object +- Story 5.10 (PendingChange Management) - Uses PendingChange aggregate +- Story 5.11 (Core MCP Tools) - Creates PendingChange entities + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Business rules incomplete | Medium | Medium | Comprehensive unit tests, domain expert review | +| Domain events not raised | Medium | Low | Unit tests verify events, event sourcing pattern | +| Value object equality bugs | Low | Low | Thorough testing, use proven patterns | +| Over-engineering domain | Medium | Medium | Keep it simple, add complexity only when needed | + +## Definition of Done + +- [ ] Code compiles without warnings +- [ ] All unit tests passing (> 90% coverage) +- [ ] Code reviewed and approved +- [ ] XML documentation for all public APIs +- [ ] All aggregates follow DDD patterns +- [ ] All value objects are immutable +- [ ] All domain events inherit from DomainEvent +- [ ] Business rules enforced in domain entities (not services) +- [ ] No anemic domain model (rich behavior in entities) + +## Notes + +### Why This Story Matters +- **Clean Architecture**: Solid domain foundation prevents future refactoring +- **Business Rules**: Domain entities enforce invariants, reducing bugs +- **Domain Events**: Enable loose coupling, audit trail, notifications +- **Testability**: Rich domain model is easy to unit test + +### Key Design Principles +1. **Aggregates**: Consistency boundaries (McpApiKey, PendingChange) +2. **Value Objects**: Immutable, equality by value (DiffPreview, DiffField) +3. **Domain Events**: Side effects handled outside aggregate +4. **Factory Methods**: Encapsulate creation logic, enforce invariants +5. **Encapsulation**: Private setters, public domain methods + +### DDD Patterns Used +- **Aggregate Root**: PendingChange, McpApiKey +- **Value Object**: DiffPreview, DiffField +- **Domain Event**: 6 events for audit and notifications +- **Factory Method**: Create() methods with validation +- **Invariant Protection**: Business rules in domain entities + +### Reference Materials +- Domain-Driven Design (Eric Evans) +- Sprint 5 Plan: `docs/plans/sprint_5.md` +- Architecture Design: `docs/M2-MCP-SERVER-ARCHITECTURE.md` +- M1 Domain Layer: `ColaFlow.Core/Domain/` diff --git a/docs/stories/sprint_5/story_5_4.md b/docs/stories/sprint_5/story_5_4.md new file mode 100644 index 0000000..06ffd6a --- /dev/null +++ b/docs/stories/sprint_5/story_5_4.md @@ -0,0 +1,530 @@ +--- +story_id: story_5_4 +sprint_id: sprint_5 +phase: Phase 1 - Foundation +status: not_started +priority: P0 +story_points: 3 +assignee: backend +estimated_days: 1 +created_date: 2025-11-06 +dependencies: [story_5_1] +--- + +# Story 5.4: Error Handling & Logging + +**Phase**: Phase 1 - Foundation (Week 1-2) +**Priority**: P0 CRITICAL +**Estimated Effort**: 3 Story Points (1 day) + +## User Story + +**As a** Backend Developer +**I want** comprehensive error handling and structured logging for MCP operations +**So that** issues can be quickly diagnosed and the system is observable in production + +## Business Value + +Production-grade error handling and logging are critical for: +- **Debugging**: Quickly diagnose issues in production +- **Monitoring**: Track error rates and performance metrics +- **Audit**: Complete trail of all MCP operations +- **Security**: Detect and respond to suspicious activity + +**Impact**: +- Reduces mean time to resolution (MTTR) by 50% +- Enables proactive monitoring and alerting +- Supports compliance requirements (audit logs) +- Improves developer productivity + +## Acceptance Criteria + +### AC1: MCP Exception Hierarchy +- [ ] Custom exception classes for MCP operations +- [ ] Exception-to-MCP-error-code mapping (JSON-RPC 2.0) +- [ ] Preserve stack traces and inner exceptions +- [ ] Structured exception data (request ID, tenant ID, API Key ID) + +### AC2: Global Exception Handler +- [ ] Catch all unhandled exceptions +- [ ] Map exceptions to MCP error responses +- [ ] Log errors with full context +- [ ] Return appropriate HTTP status codes +- [ ] Never expose internal details to clients + +### AC3: Structured Logging +- [ ] Use Serilog with structured logging +- [ ] Include correlation ID in all logs +- [ ] Log request/response at DEBUG level +- [ ] Log errors at ERROR level with stack traces +- [ ] Log performance metrics (timing) +- [ ] Never log sensitive data (API Keys, passwords, PII) + +### AC4: Request/Response Logging Middleware +- [ ] Log all MCP requests (method, params, correlation ID) +- [ ] Log all MCP responses (result or error, timing) +- [ ] Performance timing (request duration) +- [ ] Exclude sensitive fields from logs (API Key hash) + +### AC5: Performance Monitoring +- [ ] Track request duration (P50, P95, P99) +- [ ] Track error rates (by method, by tenant) +- [ ] Track API Key usage (by key, by tenant) +- [ ] Export metrics for Prometheus (future) + +### AC6: Testing +- [ ] Unit tests for exception mapping +- [ ] Integration tests for error responses +- [ ] Verify sensitive data never logged +- [ ] Test correlation ID propagation + +## Technical Design + +### MCP Exception Hierarchy + +```csharp +public abstract class McpException : Exception +{ + public int ErrorCode { get; } + public object? ErrorData { get; } + + protected McpException( + int errorCode, + string message, + object? errorData = null, + Exception? innerException = null) + : base(message, innerException) + { + ErrorCode = errorCode; + ErrorData = errorData; + } + + public McpError ToMcpError() + { + return new McpError + { + Code = ErrorCode, + Message = Message, + Data = ErrorData + }; + } +} + +public class McpParseException : McpException +{ + public McpParseException(string message, Exception? innerException = null) + : base(McpErrorCode.ParseError, message, null, innerException) { } +} + +public class McpInvalidRequestException : McpException +{ + public McpInvalidRequestException(string message, object? errorData = null) + : base(McpErrorCode.InvalidRequest, message, errorData) { } +} + +public class McpMethodNotFoundException : McpException +{ + public McpMethodNotFoundException(string method) + : base(McpErrorCode.MethodNotFound, $"Method not found: {method}") { } +} + +public class McpInvalidParamsException : McpException +{ + public McpInvalidParamsException(string message, object? errorData = null) + : base(McpErrorCode.InvalidParams, message, errorData) { } +} + +public class McpUnauthorizedException : McpException +{ + public McpUnauthorizedException(string message = "Unauthorized") + : base(McpErrorCode.Unauthorized, message) { } +} + +public class McpForbiddenException : McpException +{ + public McpForbiddenException(string message = "Forbidden") + : base(McpErrorCode.Forbidden, message) { } +} + +public class McpNotFoundException : McpException +{ + public McpNotFoundException(string resourceType, string resourceId) + : base(McpErrorCode.NotFound, + $"{resourceType} not found: {resourceId}") { } +} + +public class McpValidationException : McpException +{ + public McpValidationException(string message, object? errorData = null) + : base(McpErrorCode.ValidationFailed, message, errorData) { } +} +``` + +### Global Exception Handler Middleware + +```csharp +public class McpExceptionHandlerMiddleware +{ + private readonly RequestDelegate _next; + private readonly ILogger _logger; + + public async Task InvokeAsync(HttpContext context) + { + try + { + await _next(context); + } + catch (McpException mcpEx) + { + await HandleMcpExceptionAsync(context, mcpEx); + } + catch (Exception ex) + { + await HandleUnexpectedExceptionAsync(context, ex); + } + } + + private async Task HandleMcpExceptionAsync( + HttpContext context, + McpException mcpEx) + { + var correlationId = context.Items["CorrelationId"] as string; + + _logger.LogError(mcpEx, + "MCP Error: {ErrorCode} - {Message} (CorrelationId: {CorrelationId})", + mcpEx.ErrorCode, mcpEx.Message, correlationId); + + var response = new McpResponse + { + JsonRpc = "2.0", + Error = mcpEx.ToMcpError(), + Id = context.Items["McpRequestId"] as string + }; + + context.Response.StatusCode = GetHttpStatusCode(mcpEx.ErrorCode); + context.Response.ContentType = "application/json"; + await context.Response.WriteAsJsonAsync(response); + } + + private async Task HandleUnexpectedExceptionAsync( + HttpContext context, + Exception ex) + { + var correlationId = context.Items["CorrelationId"] as string; + + _logger.LogError(ex, + "Unexpected error in MCP Server (CorrelationId: {CorrelationId})", + correlationId); + + var response = new McpResponse + { + JsonRpc = "2.0", + Error = new McpError + { + Code = McpErrorCode.InternalError, + Message = "Internal server error" + // Do NOT expose exception details + }, + Id = context.Items["McpRequestId"] as string + }; + + context.Response.StatusCode = 500; + context.Response.ContentType = "application/json"; + await context.Response.WriteAsJsonAsync(response); + } + + private static int GetHttpStatusCode(int mcpErrorCode) + { + return mcpErrorCode switch + { + McpErrorCode.Unauthorized => 401, + McpErrorCode.Forbidden => 403, + McpErrorCode.NotFound => 404, + McpErrorCode.ValidationFailed => 422, + _ => 400 + }; + } +} +``` + +### Request/Response Logging Middleware + +```csharp +public class McpLoggingMiddleware +{ + private readonly RequestDelegate _next; + private readonly ILogger _logger; + + public async Task InvokeAsync(HttpContext context) + { + // Generate correlation ID + var correlationId = Guid.NewGuid().ToString(); + context.Items["CorrelationId"] = correlationId; + + // Start timing + var stopwatch = Stopwatch.StartNew(); + + // Enable request buffering for logging + context.Request.EnableBuffering(); + + // Log request + await LogRequestAsync(context, correlationId); + + // Capture response + var originalBody = context.Response.Body; + using var memoryStream = new MemoryStream(); + context.Response.Body = memoryStream; + + try + { + await _next(context); + + stopwatch.Stop(); + + // Log response + await LogResponseAsync( + context, correlationId, stopwatch.ElapsedMilliseconds); + + // Copy response to original stream + memoryStream.Seek(0, SeekOrigin.Begin); + await memoryStream.CopyToAsync(originalBody); + } + finally + { + context.Response.Body = originalBody; + } + } + + private async Task LogRequestAsync( + HttpContext context, + string correlationId) + { + context.Request.Body.Seek(0, SeekOrigin.Begin); + var body = await new StreamReader(context.Request.Body).ReadToEndAsync(); + context.Request.Body.Seek(0, SeekOrigin.Begin); + + var tenantId = context.Items["TenantId"]; + var apiKeyId = context.Items["ApiKeyId"]; + + _logger.LogDebug( + "MCP Request: {Method} {Path} (CorrelationId: {CorrelationId}, " + + "TenantId: {TenantId}, ApiKeyId: {ApiKeyId})\n{Body}", + context.Request.Method, + context.Request.Path, + correlationId, + tenantId, + apiKeyId, + SanitizeBody(body)); + } + + private async Task LogResponseAsync( + HttpContext context, + string correlationId, + long elapsedMs) + { + context.Response.Body.Seek(0, SeekOrigin.Begin); + var body = await new StreamReader(context.Response.Body).ReadToEndAsync(); + context.Response.Body.Seek(0, SeekOrigin.Begin); + + var logLevel = context.Response.StatusCode >= 400 + ? LogLevel.Error + : LogLevel.Debug; + + _logger.Log(logLevel, + "MCP Response: {StatusCode} (CorrelationId: {CorrelationId}, " + + "Duration: {Duration}ms)\n{Body}", + context.Response.StatusCode, + correlationId, + elapsedMs, + body); + } + + private string SanitizeBody(string body) + { + // Remove sensitive data (API Keys, passwords, etc.) + // This is a simplified example + return body.Replace("\"key_hash\":", "\"key_hash\":[REDACTED]"); + } +} +``` + +### Serilog Configuration + +```csharp +public static class SerilogConfiguration +{ + public static void ConfigureSerilog(WebApplicationBuilder builder) + { + builder.Host.UseSerilog((context, services, configuration) => + { + configuration + .ReadFrom.Configuration(context.Configuration) + .Enrich.FromLogContext() + .Enrich.WithMachineName() + .Enrich.WithEnvironmentName() + .Enrich.WithProperty("Application", "ColaFlow") + .WriteTo.Console( + outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] " + + "{CorrelationId} {Message:lj}{NewLine}{Exception}") + .WriteTo.File( + path: "logs/colaflow-.log", + rollingInterval: RollingInterval.Day, + retainedFileCountLimit: 30, + outputTemplate: "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz}] " + + "[{Level:u3}] {CorrelationId} {Message:lj}{NewLine}{Exception}") + .WriteTo.PostgreSQL( + connectionString: context.Configuration.GetConnectionString("Default"), + tableName: "logs", + needAutoCreateTable: true); + }); + } +} +``` + +## Tasks + +### Task 1: MCP Exception Classes (2 hours) +- [ ] Create `McpException` base class +- [ ] Create 8 specific exception classes +- [ ] Implement `ToMcpError()` method +- [ ] Add XML documentation + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Exceptions/McpException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpParseException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpInvalidRequestException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpMethodNotFoundException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpInvalidParamsException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpUnauthorizedException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpForbiddenException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpNotFoundException.cs` +- `ColaFlow.Modules.Mcp/Exceptions/McpValidationException.cs` + +### Task 2: Global Exception Handler Middleware (2 hours) +- [ ] Create `McpExceptionHandlerMiddleware` +- [ ] Handle `McpException` (map to MCP error) +- [ ] Handle unexpected exceptions (return InternalError) +- [ ] Map error codes to HTTP status codes +- [ ] Add structured logging + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Middleware/McpExceptionHandlerMiddleware.cs` + +### Task 3: Request/Response Logging Middleware (3 hours) +- [ ] Create `McpLoggingMiddleware` +- [ ] Generate correlation ID +- [ ] Log request (method, params, timing) +- [ ] Log response (result/error, timing) +- [ ] Sanitize sensitive data (API Keys, passwords) + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Middleware/McpLoggingMiddleware.cs` + +### Task 4: Serilog Configuration (1 hour) +- [ ] Configure Serilog (Console, File, PostgreSQL sinks) +- [ ] Add enrichers (correlation ID, machine name, environment) +- [ ] Configure structured logging format +- [ ] Set log levels (DEBUG for dev, INFO for prod) + +**Files to Modify**: +- `ColaFlow.Api/Program.cs` + +### Task 5: Unit Tests (3 hours) +- [ ] Test exception-to-MCP-error mapping +- [ ] Test HTTP status code mapping +- [ ] Test sensitive data sanitization +- [ ] Test correlation ID generation + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Exceptions/McpExceptionTests.cs` +- `ColaFlow.Modules.Mcp.Tests/Middleware/McpExceptionHandlerTests.cs` +- `ColaFlow.Modules.Mcp.Tests/Middleware/McpLoggingMiddlewareTests.cs` + +### Task 6: Integration Tests (2 hours) +- [ ] Test end-to-end error handling +- [ ] Test logging middleware (verify logs written) +- [ ] Test correlation ID propagation +- [ ] Test sensitive data never logged + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/ErrorHandlingIntegrationTests.cs` + +## Testing Strategy + +### Unit Tests +- Exception class creation and properties +- Exception-to-MCP-error conversion +- HTTP status code mapping +- Sensitive data sanitization + +### Integration Tests +- End-to-end error handling flow +- Logging middleware writes logs correctly +- Correlation ID in all log entries +- No sensitive data in logs + +### Manual Testing Checklist +- [ ] Trigger ParseError → verify logs and response +- [ ] Trigger MethodNotFound → verify logs and response +- [ ] Trigger InternalError → verify logs and response +- [ ] Check logs for correlation ID +- [ ] Check logs do NOT contain API Keys or passwords + +## Dependencies + +**Prerequisites**: +- Story 5.1 (MCP Protocol Handler) - Exception handling integrated here +- Serilog NuGet packages +- Serilog.Sinks.PostgreSQL + +**Used By**: +- All MCP Stories (5.5-5.12) - Rely on error handling + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Sensitive data logged | High | Medium | Sanitization function, code review | +| Logging performance | Medium | Low | Async logging, buffering | +| Log storage growth | Medium | Medium | 30-day retention, log rotation | +| Exception details leaked | High | Low | Never expose internal details to clients | + +## Definition of Done + +- [ ] Code compiles without warnings +- [ ] All unit tests passing (> 80% coverage) +- [ ] All integration tests passing +- [ ] Code reviewed and approved +- [ ] XML documentation for exceptions +- [ ] Serilog configured correctly +- [ ] Correlation ID in all logs +- [ ] No sensitive data in logs (verified) +- [ ] Error responses conform to JSON-RPC 2.0 + +## Notes + +### Why This Story Matters +- **Production Readiness**: Cannot deploy without proper error handling +- **Observability**: Structured logging enables monitoring and alerting +- **Debugging**: Correlation ID makes troubleshooting 10x faster +- **Security**: Prevents sensitive data leaks in logs + +### Key Design Decisions +1. **Custom Exceptions**: Clear error semantics, easy to map to MCP errors +2. **Correlation ID**: Track requests across distributed system +3. **Structured Logging**: Machine-readable, queryable logs +4. **Sanitization**: Prevent sensitive data leaks +5. **Async Logging**: Minimal performance impact + +### Logging Best Practices +- Use structured logging (not string interpolation) +- Include correlation ID in all logs +- Log at appropriate levels (DEBUG, INFO, ERROR) +- Never log sensitive data (API Keys, passwords, PII) +- Use async logging to avoid blocking +- Rotate logs daily, retain for 30 days + +### Reference Materials +- Serilog Documentation: https://serilog.net/ +- JSON-RPC 2.0 Error Codes: https://www.jsonrpc.org/specification#error_object +- Sprint 5 Plan: `docs/plans/sprint_5.md` diff --git a/docs/stories/sprint_5/story_5_5.md b/docs/stories/sprint_5/story_5_5.md new file mode 100644 index 0000000..8d7775c --- /dev/null +++ b/docs/stories/sprint_5/story_5_5.md @@ -0,0 +1,397 @@ +--- +story_id: story_5_5 +sprint_id: sprint_5 +phase: Phase 2 - Resources +status: not_started +priority: P0 +story_points: 8 +assignee: backend +estimated_days: 3 +created_date: 2025-11-06 +dependencies: [story_5_1, story_5_2, story_5_3] +--- + +# Story 5.5: Core MCP Resources Implementation + +**Phase**: Phase 2 - Resources (Week 3-4) +**Priority**: P0 CRITICAL +**Estimated Effort**: 8 Story Points (3 days) + +## User Story + +**As an** AI Agent (Claude, ChatGPT) +**I want** to read ColaFlow project data through MCP Resources +**So that** I can understand project context and answer user questions + +## Business Value + +This is the first user-facing MCP feature. AI agents can now READ ColaFlow data, enabling: +- AI-powered project queries ("Show me high-priority bugs") +- Natural language reporting ("What's the status of Sprint 5?") +- Context-aware AI assistance ("Who's assigned to this Story?") + +**Impact**: +- Enables 50% of M2 user stories (read-only AI features) +- Foundation for future write operations (Phase 3) +- Demonstrates MCP Server working end-to-end + +## Acceptance Criteria + +### AC1: Projects Resources +- [ ] `colaflow://projects.list` - List all projects +- [ ] `colaflow://projects.get/{id}` - Get project details +- [ ] Multi-tenant isolation (only current tenant's projects) +- [ ] Response time < 200ms + +### AC2: Issues Resources +- [ ] `colaflow://issues.search` - Search issues with filters +- [ ] `colaflow://issues.get/{id}` - Get issue details (Epic/Story/Task) +- [ ] Query parameters: status, priority, assignee, type, project +- [ ] Pagination support (limit, offset) +- [ ] Response time < 200ms + +### AC3: Sprints Resources +- [ ] `colaflow://sprints.current` - Get current active Sprint +- [ ] `colaflow://sprints.get/{id}` - Get Sprint details +- [ ] Include Sprint statistics (total issues, completed, in progress) + +### AC4: Users Resource +- [ ] `colaflow://users.list` - List team members +- [ ] Filter by project, role +- [ ] Include user profile data (name, email, avatar) + +### AC5: Resource Registration +- [ ] All Resources auto-register at startup +- [ ] `resources/list` returns complete catalog +- [ ] Each Resource has URI, name, description, MIME type + +### AC6: Testing +- [ ] Unit tests for each Resource (> 80% coverage) +- [ ] Integration tests for Resource endpoints +- [ ] Multi-tenant isolation tests +- [ ] Performance tests (< 200ms response time) + +## Technical Design + +### Resource Interface + +```csharp +public interface IMcpResource +{ + string Uri { get; } + string Name { get; } + string Description { get; } + string MimeType { get; } + + Task GetContentAsync( + McpResourceRequest request, + CancellationToken cancellationToken); +} + +public class McpResourceRequest +{ + public string Uri { get; set; } + public Dictionary Params { get; set; } = new(); +} + +public class McpResourceContent +{ + public string Uri { get; set; } + public string MimeType { get; set; } + public string Text { get; set; } // JSON serialized data +} +``` + +### Example: ProjectsListResource + +```csharp +public class ProjectsListResource : IMcpResource +{ + public string Uri => "colaflow://projects.list"; + public string Name => "Projects List"; + public string Description => "List all projects in current tenant"; + public string MimeType => "application/json"; + + private readonly IProjectRepository _projectRepo; + private readonly ITenantContext _tenantContext; + private readonly ILogger _logger; + + public async Task GetContentAsync( + McpResourceRequest request, + CancellationToken cancellationToken) + { + var tenantId = _tenantContext.CurrentTenantId; + + _logger.LogDebug( + "Fetching projects list for tenant {TenantId}", + tenantId); + + var projects = await _projectRepo.GetAllAsync( + tenantId, + cancellationToken); + + var projectDtos = projects.Select(p => new + { + id = p.Id, + name = p.Name, + key = p.Key, + status = p.Status.ToString(), + owner = new { id = p.OwnerId, name = p.Owner?.Name }, + issueCount = p.IssueCount, + memberCount = p.MemberCount, + createdAt = p.CreatedAt + }); + + var json = JsonSerializer.Serialize(new { projects = projectDtos }); + + return new McpResourceContent + { + Uri = Uri, + MimeType = MimeType, + Text = json + }; + } +} +``` + +### Resource Catalog Response + +```json +{ + "resources": [ + { + "uri": "colaflow://projects.list", + "name": "Projects List", + "description": "List all projects in current tenant", + "mimeType": "application/json" + }, + { + "uri": "colaflow://projects.get/{id}", + "name": "Project Details", + "description": "Get detailed information about a project", + "mimeType": "application/json" + }, + { + "uri": "colaflow://issues.search", + "name": "Issues Search", + "description": "Search issues with filters (status, priority, assignee, etc.)", + "mimeType": "application/json" + }, + { + "uri": "colaflow://issues.get/{id}", + "name": "Issue Details", + "description": "Get detailed information about an issue (Epic/Story/Task)", + "mimeType": "application/json" + }, + { + "uri": "colaflow://sprints.current", + "name": "Current Sprint", + "description": "Get the currently active Sprint", + "mimeType": "application/json" + }, + { + "uri": "colaflow://users.list", + "name": "Team Members", + "description": "List all team members in current tenant", + "mimeType": "application/json" + } + ] +} +``` + +## Tasks + +### Task 1: Resource Infrastructure (4 hours) +- [ ] Create `IMcpResource` interface +- [ ] Create `McpResourceRequest`, `McpResourceContent` DTOs +- [ ] Create `IMcpResourceDispatcher` interface +- [ ] Implement `McpResourceDispatcher` (route requests to Resources) +- [ ] Update `McpProtocolHandler` to call dispatcher + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Contracts/IMcpResource.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpResourceRequest.cs` +- `ColaFlow.Modules.Mcp/DTOs/McpResourceContent.cs` +- `ColaFlow.Modules.Mcp/Contracts/IMcpResourceDispatcher.cs` +- `ColaFlow.Modules.Mcp/Services/McpResourceDispatcher.cs` + +### Task 2: ProjectsListResource (3 hours) +- [ ] Implement `ProjectsListResource` class +- [ ] Query ProjectManagement repository +- [ ] Apply TenantId filter +- [ ] Serialize to JSON +- [ ] Unit tests + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Resources/ProjectsListResource.cs` +- `ColaFlow.Modules.Mcp.Tests/Resources/ProjectsListResourceTests.cs` + +### Task 3: ProjectsGetResource (2 hours) +- [ ] Implement `ProjectsGetResource` class +- [ ] Extract `{id}` from URI +- [ ] Query project by ID + TenantId +- [ ] Return 404 if not found or wrong tenant +- [ ] Unit tests + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Resources/ProjectsGetResource.cs` +- `ColaFlow.Modules.Mcp.Tests/Resources/ProjectsGetResourceTests.cs` + +### Task 4: IssuesSearchResource (4 hours) +- [ ] Implement `IssuesSearchResource` class +- [ ] Parse query params (status, priority, assignee, type, project) +- [ ] Build dynamic query (EF Core) +- [ ] Apply pagination (limit, offset) +- [ ] Apply TenantId filter +- [ ] Unit tests + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Resources/IssuesSearchResource.cs` +- `ColaFlow.Modules.Mcp.Tests/Resources/IssuesSearchResourceTests.cs` + +### Task 5: IssuesGetResource (3 hours) +- [ ] Implement `IssuesGetResource` class +- [ ] Support Epic, Story, WorkTask lookup +- [ ] Return full issue details (including parent/children) +- [ ] Apply TenantId filter +- [ ] Unit tests + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Resources/IssuesGetResource.cs` +- `ColaFlow.Modules.Mcp.Tests/Resources/IssuesGetResourceTests.cs` + +### Task 6: SprintsCurrentResource (2 hours) +- [ ] Implement `SprintsCurrentResource` class +- [ ] Query active Sprint (status = InProgress) +- [ ] Include Sprint statistics +- [ ] Apply TenantId filter +- [ ] Unit tests + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Resources/SprintsCurrentResource.cs` +- `ColaFlow.Modules.Mcp.Tests/Resources/SprintsCurrentResourceTests.cs` + +### Task 7: UsersListResource (2 hours) +- [ ] Implement `UsersListResource` class +- [ ] Query users in current tenant +- [ ] Filter by project (optional) +- [ ] Include profile data (name, email, avatar URL) +- [ ] Unit tests + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Resources/UsersListResource.cs` +- `ColaFlow.Modules.Mcp.Tests/Resources/UsersListResourceTests.cs` + +### Task 8: Resource Registration (2 hours) +- [ ] Create `IMcpRegistry` interface +- [ ] Implement auto-discovery via Reflection +- [ ] Register all Resources at startup +- [ ] Implement `resources/list` method handler + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Contracts/IMcpRegistry.cs` +- `ColaFlow.Modules.Mcp/Services/McpRegistry.cs` + +### Task 9: Integration Tests (4 hours) +- [ ] Test end-to-end Resource requests +- [ ] Test multi-tenant isolation (Tenant A cannot read Tenant B data) +- [ ] Test pagination +- [ ] Test query filters +- [ ] Test performance (< 200ms) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/McpResourcesIntegrationTests.cs` + +## Testing Strategy + +### Unit Tests (> 80% coverage) +- Each Resource class independently +- Query building logic +- JSON serialization +- Error handling (not found, invalid params) + +### Integration Tests +- End-to-end Resource requests +- Multi-tenant isolation verification +- Pagination correctness +- Performance benchmarks + +### Manual Testing with Claude Desktop + +```bash +# Install MCP Inspector +npm install -g @modelcontextprotocol/inspector + +# Test projects.list +mcp-inspector colaflow://projects.list + +# Test issues.search with filters +mcp-inspector colaflow://issues.search?status=InProgress&priority=High + +# Test sprints.current +mcp-inspector colaflow://sprints.current +``` + +## Dependencies + +**Prerequisites**: +- Story 5.1 (MCP Protocol Handler) - Resource routing +- Story 5.2 (API Key Management) - Authentication +- Story 5.3 (MCP Domain Layer) - Domain entities +- M1 ProjectManagement Module - Data source + +**Blocks**: +- Story 5.11 (Core MCP Tools) - Tools depend on Resources working + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Performance slow (> 200ms) | Medium | Medium | Redis caching (Story 5.8), database indexes | +| Multi-tenant leak | High | Low | 100% test coverage, Global Query Filters | +| Query complexity | Medium | Medium | Limit query params, use IQueryable | +| JSON serialization bugs | Low | Low | Unit tests, use System.Text.Json | + +## Definition of Done + +- [ ] Code compiles without warnings +- [ ] All 6 Resources implemented and working +- [ ] Unit test coverage > 80% +- [ ] Integration tests passing +- [ ] Multi-tenant isolation verified (100%) +- [ ] Performance < 200ms (P95) +- [ ] Code reviewed and approved +- [ ] XML documentation for public APIs +- [ ] Resources registered and discoverable (`resources/list`) + +## Notes + +### Why This Story Matters +- **First AI Integration**: AI can now read ColaFlow data +- **Foundation for M2**: 50% of M2 features are read-only +- **User Value**: Enables natural language project queries +- **Milestone Demo**: Demonstrates MCP Server working + +### Key Design Decisions +1. **URI Scheme**: `colaflow://` custom protocol +2. **JSON Responses**: All Resources return JSON +3. **Pagination**: Limit/offset for large result sets +4. **Filtering**: Query params for fine-grained control +5. **Multi-Tenant**: TenantContext ensures data isolation + +### Performance Optimization +- Use `AsNoTracking()` for read-only queries (30% faster) +- Add database indexes on commonly filtered columns +- Implement Redis caching (Story 5.8) for hot Resources +- Limit pagination size (max 100 items) + +### Resource URI Design Guidelines +- Use descriptive names: `projects.list`, `issues.search` +- Use `{id}` for parameterized URIs: `projects.get/{id}` +- Use query params for filters: `issues.search?status=InProgress` +- Keep URIs stable (versioning if needed) + +### Reference Materials +- MCP Resources Spec: https://modelcontextprotocol.io/docs/concepts/resources +- Sprint 5 Plan: `docs/plans/sprint_5.md` +- Architecture Design: `docs/M2-MCP-SERVER-ARCHITECTURE.md` diff --git a/docs/stories/sprint_5/story_5_6.md b/docs/stories/sprint_5/story_5_6.md new file mode 100644 index 0000000..97a8a48 --- /dev/null +++ b/docs/stories/sprint_5/story_5_6.md @@ -0,0 +1,128 @@ +--- +story_id: story_5_6 +sprint_id: sprint_5 +phase: Phase 2 - Resources +status: not_started +priority: P0 +story_points: 3 +assignee: backend +estimated_days: 1 +created_date: 2025-11-06 +dependencies: [story_5_5] +--- + +# Story 5.6: Resource Registration & Discovery + +**Phase**: Phase 2 - Resources (Week 3-4) +**Priority**: P0 CRITICAL +**Estimated Effort**: 3 Story Points (1 day) + +## User Story + +**As an** AI Agent +**I want** to discover available MCP Resources dynamically +**So that** I know what data I can access from ColaFlow + +## Business Value + +Dynamic Resource discovery enables: +- AI agents to explore available capabilities +- Easy addition of new Resources without code changes +- Version compatibility checking +- Documentation generation + +## Acceptance Criteria + +### AC1: Auto-Discovery +- [ ] All `IMcpResource` implementations auto-registered at startup +- [ ] Use Assembly scanning (Reflection) +- [ ] Singleton registration in DI container + +### AC2: Resource Catalog +- [ ] `resources/list` method returns all Resources +- [ ] Each Resource includes: URI, name, description, MIME type +- [ ] Response conforms to MCP specification + +### AC3: Resource Versioning +- [ ] Support for Resource versioning (future-proof) +- [ ] Optional `version` field in Resource metadata + +### AC4: Configuration +- [ ] Enable/disable Resources via `appsettings.json` +- [ ] Filter Resources by tenant (optional) + +### AC5: Testing +- [ ] Unit tests for registry logic +- [ ] Integration test for `resources/list` + +## Technical Design + +```csharp +public interface IMcpRegistry +{ + void RegisterResource(IMcpResource resource); + IMcpResource? GetResource(string uri); + IReadOnlyList GetAllResources(); +} + +public class McpRegistry : IMcpRegistry +{ + private readonly Dictionary _resources = new(); + + public void RegisterResource(IMcpResource resource) + { + _resources[resource.Uri] = resource; + } + + public IMcpResource? GetResource(string uri) + { + return _resources.TryGetValue(uri, out var resource) ? resource : null; + } + + public IReadOnlyList GetAllResources() + { + return _resources.Values.ToList().AsReadOnly(); + } +} + +// Auto-registration +public static class McpServiceExtensions +{ + public static IServiceCollection AddMcpResources( + this IServiceCollection services) + { + var assembly = typeof(IMcpResource).Assembly; + var resourceTypes = assembly.GetTypes() + .Where(t => typeof(IMcpResource).IsAssignableFrom(t) + && !t.IsInterface && !t.IsAbstract); + + foreach (var type in resourceTypes) + { + services.AddSingleton(typeof(IMcpResource), type); + } + + services.AddSingleton(); + return services; + } +} +``` + +## Tasks + +- [ ] Create `IMcpRegistry` interface (1 hour) +- [ ] Implement `McpRegistry` class (2 hours) +- [ ] Implement auto-discovery via Reflection (2 hours) +- [ ] Implement `resources/list` handler (1 hour) +- [ ] Add configuration support (1 hour) +- [ ] Unit tests (2 hours) + +## Definition of Done + +- [ ] All Resources auto-registered +- [ ] `resources/list` returns complete catalog +- [ ] Unit tests passing +- [ ] Code reviewed + +## Reference + +- MCP Spec: https://modelcontextprotocol.io/docs/concepts/resources diff --git a/docs/stories/sprint_5/story_5_7.md b/docs/stories/sprint_5/story_5_7.md new file mode 100644 index 0000000..b17c075 --- /dev/null +++ b/docs/stories/sprint_5/story_5_7.md @@ -0,0 +1,279 @@ +--- +story_id: story_5_7 +sprint_id: sprint_5 +phase: Phase 2 - Resources +status: not_started +priority: P0 +story_points: 5 +assignee: backend +estimated_days: 2 +created_date: 2025-11-06 +dependencies: [story_5_5, story_5_2] +--- + +# Story 5.7: Multi-Tenant Isolation Verification + +**Phase**: Phase 2 - Resources (Week 3-4) +**Priority**: P0 CRITICAL +**Estimated Effort**: 5 Story Points (2 days) + +## User Story + +**As a** Security Engineer +**I want** 100% multi-tenant data isolation for all MCP operations +**So that** AI agents cannot access data from other tenants + +## Business Value + +Multi-tenant security is CRITICAL for M2. A single data leak could: +- Violate customer trust +- Cause legal liability (GDPR, SOC2) +- Damage brand reputation +- Block enterprise adoption + +**This Story ensures zero cross-tenant data access.** + +## Acceptance Criteria + +### AC1: TenantContext Service +- [ ] Extract `TenantId` from API Key +- [ ] Set `CurrentTenantId` in request context +- [ ] Accessible to all MCP operations + +### AC2: Global Query Filters +- [ ] EF Core Global Query Filters applied to all entities +- [ ] All queries automatically filtered by `TenantId` +- [ ] Cannot be disabled by accident + +### AC3: Repository Level Isolation +- [ ] All repositories enforce `TenantId` filter +- [ ] No queries bypass tenant check +- [ ] Aggregate roots include `TenantId` property + +### AC4: Integration Tests +- [ ] Create 2 test tenants (Tenant A, Tenant B) +- [ ] Create test data in each tenant +- [ ] Test 1: Tenant A API Key cannot read Tenant B projects +- [ ] Test 2: Tenant A API Key cannot read Tenant B issues +- [ ] Test 3: Tenant A API Key cannot read Tenant B users +- [ ] Test 4: Direct ID access fails for other tenant's data +- [ ] Test 5: Search queries never return cross-tenant results +- [ ] All tests must pass (100% isolation) + +### AC5: Security Audit +- [ ] Code review by security team +- [ ] Static analysis (no raw SQL without TenantId) +- [ ] Verify all API endpoints enforce tenant filter + +## Technical Design + +### TenantContext Service + +```csharp +public interface ITenantContext +{ + Guid CurrentTenantId { get; } +} + +public class McpTenantContext : ITenantContext +{ + private readonly IHttpContextAccessor _httpContextAccessor; + + public Guid CurrentTenantId + { + get + { + var tenantId = _httpContextAccessor.HttpContext?.Items["TenantId"]; + if (tenantId == null) + throw new McpUnauthorizedException("Tenant context not set"); + + return (Guid)tenantId; + } + } +} +``` + +### Global Query Filters + +```csharp +public class ColaFlowDbContext : DbContext +{ + private readonly ITenantContext _tenantContext; + + protected override void OnModelCreating(ModelBuilder modelBuilder) + { + base.OnModelCreating(modelBuilder); + + // Apply tenant filter to all tenant-scoped entities + modelBuilder.Entity() + .HasQueryFilter(p => p.TenantId == _tenantContext.CurrentTenantId); + + modelBuilder.Entity() + .HasQueryFilter(e => e.TenantId == _tenantContext.CurrentTenantId); + + modelBuilder.Entity() + .HasQueryFilter(s => s.TenantId == _tenantContext.CurrentTenantId); + + modelBuilder.Entity() + .HasQueryFilter(t => t.TenantId == _tenantContext.CurrentTenantId); + + modelBuilder.Entity() + .HasQueryFilter(s => s.TenantId == _tenantContext.CurrentTenantId); + + modelBuilder.Entity() + .HasQueryFilter(u => u.TenantId == _tenantContext.CurrentTenantId); + } +} +``` + +### Integration Test Example + +```csharp +[Fact] +public async Task TenantA_CannotReadTenantB_Projects() +{ + // Arrange + var tenantA = await CreateTestTenant("Tenant A"); + var tenantB = await CreateTestTenant("Tenant B"); + + var apiKeyA = await CreateApiKey(tenantA.Id, "API Key A"); + var projectB = await CreateProject(tenantB.Id, "Project B"); + + // Act - Tenant A tries to access Tenant B's project + var result = await CallMcpResource( + apiKeyA, + $"colaflow://projects.get/{projectB.Id}"); + + // Assert + Assert.Equal(404, result.StatusCode); // NOT 403 (don't leak existence) + Assert.Null(result.Data); +} + +[Fact] +public async Task IssuesSearch_NeverReturnsCrossTenant_Results() +{ + // Arrange + var tenantA = await CreateTestTenant("Tenant A"); + var tenantB = await CreateTestTenant("Tenant B"); + + await CreateIssue(tenantA.Id, "Issue A"); + await CreateIssue(tenantB.Id, "Issue B"); + + var apiKeyA = await CreateApiKey(tenantA.Id, "API Key A"); + + // Act - Tenant A searches all issues + var result = await CallMcpResource( + apiKeyA, + "colaflow://issues.search"); + + // Assert + var issues = result.Data["issues"]; + Assert.Single(issues); // Only Tenant A's issue + Assert.Equal("Issue A", issues[0]["title"]); +} +``` + +## Tasks + +### Task 1: TenantContext Service (2 hours) +- [ ] Create `ITenantContext` interface +- [ ] Implement `McpTenantContext` (extract from HttpContext) +- [ ] Register in DI container +- [ ] Update API Key middleware to set TenantId + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Services/McpTenantContext.cs` + +### Task 2: Global Query Filters (3 hours) +- [ ] Add `TenantId` to all aggregate roots (if missing) +- [ ] Configure Global Query Filters in DbContext +- [ ] Test filters apply automatically +- [ ] Verify cannot be disabled + +**Files to Modify**: +- `ColaFlow.Infrastructure/Data/ColaFlowDbContext.cs` + +### Task 3: Repository Validation (2 hours) +- [ ] Audit all repository methods +- [ ] Ensure all queries include TenantId +- [ ] Add TenantId to method signatures if needed + +### Task 4: Integration Tests - Cross-Tenant Access (6 hours) +- [ ] Create multi-tenant test infrastructure +- [ ] Test 1: Projects cross-tenant access +- [ ] Test 2: Issues cross-tenant access +- [ ] Test 3: Users cross-tenant access +- [ ] Test 4: Direct ID access (404, not 403) +- [ ] Test 5: Search never returns cross-tenant results + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/MultiTenantIsolationTests.cs` + +### Task 5: Security Audit (3 hours) +- [ ] Code review by security team +- [ ] Static analysis (grep for raw SQL) +- [ ] Verify all API endpoints use TenantContext +- [ ] Document security architecture + +**Files to Create**: +- `docs/security/multi-tenant-isolation-audit.md` + +## Testing Strategy + +### Integration Tests (Critical) +- 2 test tenants with separate data +- 10+ test scenarios covering all Resources +- 100% isolation verified +- Tests must fail if isolation broken + +### Security Audit Checklist +- [ ] All entities have TenantId property +- [ ] Global Query Filters configured +- [ ] No raw SQL without TenantId +- [ ] All API endpoints use TenantContext +- [ ] Return 404 (not 403) for cross-tenant access +- [ ] Audit logs include TenantId + +## Dependencies + +**Prerequisites**: +- Story 5.2 (API Key Management) - API Key linked to Tenant +- Story 5.5 (Core Resources) - Resources to test + +**Critical Path**: BLOCKS M2 production deployment + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Tenant leak vulnerability | CRITICAL | Low | 100% test coverage, code review | +| Global filter bypass | HIGH | Low | EF Core best practices, testing | +| Performance impact | Medium | Low | Indexed TenantId columns | + +## Definition of Done + +- [ ] TenantContext service working +- [ ] Global Query Filters applied +- [ ] ALL integration tests passing (100%) +- [ ] Security audit complete (no findings) +- [ ] Code reviewed by security team +- [ ] Documentation updated + +## Notes + +### Why This Story Matters +- **CRITICAL SECURITY**: Single most important security Story in M2 +- **Compliance**: Required for GDPR, SOC2, enterprise customers +- **Trust**: Multi-tenant leaks destroy customer trust +- **Legal**: Data breaches have severe legal consequences + +### Security Best Practices +1. **Defense in Depth**: Multiple layers (API Key, TenantContext, Global Filters) +2. **Fail Closed**: No data if TenantId missing (throw exception) +3. **404 not 403**: Don't leak existence of other tenant's data +4. **Audit Everything**: Log all tenant context access +5. **Test Religiously**: 100% integration test coverage + +### Reference Materials +- Multi-Tenant Security: https://learn.microsoft.com/en-us/ef/core/querying/filters +- Sprint 5 Plan: `docs/plans/sprint_5.md` diff --git a/docs/stories/sprint_5/story_5_8.md b/docs/stories/sprint_5/story_5_8.md new file mode 100644 index 0000000..0028b80 --- /dev/null +++ b/docs/stories/sprint_5/story_5_8.md @@ -0,0 +1,304 @@ +--- +story_id: story_5_8 +sprint_id: sprint_5 +phase: Phase 2 - Resources +status: not_started +priority: P1 +story_points: 5 +assignee: backend +estimated_days: 2 +created_date: 2025-11-06 +dependencies: [story_5_5] +--- + +# Story 5.8: Redis Caching Integration + +**Phase**: Phase 2 - Resources (Week 3-4) +**Priority**: P1 HIGH +**Estimated Effort**: 5 Story Points (2 days) + +## User Story + +**As a** System Architect +**I want** Redis caching for frequently accessed MCP Resources +**So that** AI agents get fast responses and database load is reduced + +## Business Value + +Performance optimization delivers: +- 30-50% faster response times (from 200ms to 80ms) +- Reduced database load (80% cache hit rate target) +- Better scalability (support more concurrent AI agents) +- Improved user experience (faster AI responses) + +## Acceptance Criteria + +### AC1: Redis Integration +- [ ] Redis client configured (StackExchange.Redis) +- [ ] Connection pooling and retry logic +- [ ] Health checks for Redis availability + +### AC2: Cache-Aside Pattern +- [ ] Check cache before database query +- [ ] Populate cache on cache miss +- [ ] Return cached data on cache hit + +### AC3: TTL Configuration +- [ ] `projects.list`: 5 minutes TTL +- [ ] `users.list`: 5 minutes TTL +- [ ] `sprints.current`: 2 minutes TTL +- [ ] `issues.search`: 2 minutes TTL (cache by query params) + +### AC4: Cache Invalidation +- [ ] Invalidate on data updates (domain events) +- [ ] Manual cache clear API endpoint +- [ ] Tenant-scoped cache keys + +### AC5: Performance Metrics +- [ ] Track cache hit rate (target > 80%) +- [ ] Track cache miss rate +- [ ] Track response time improvement +- [ ] Export metrics for monitoring + +### AC6: Testing +- [ ] Unit tests for caching logic +- [ ] Integration tests (cache hit/miss scenarios) +- [ ] Performance benchmarks (with/without cache) + +## Technical Design + +### Cache Service Interface + +```csharp +public interface IMcpCacheService +{ + Task GetAsync(string key, CancellationToken cancellationToken = default); + Task SetAsync(string key, T value, TimeSpan ttl, CancellationToken cancellationToken = default); + Task RemoveAsync(string key, CancellationToken cancellationToken = default); + Task RemoveByPatternAsync(string pattern, CancellationToken cancellationToken = default); +} + +public class RedisMcpCacheService : IMcpCacheService +{ + private readonly IConnectionMultiplexer _redis; + private readonly ILogger _logger; + + public async Task GetAsync(string key, CancellationToken ct) + { + var db = _redis.GetDatabase(); + var value = await db.StringGetAsync(key); + + if (!value.HasValue) + { + _logger.LogDebug("Cache miss: {Key}", key); + return default; + } + + _logger.LogDebug("Cache hit: {Key}", key); + return JsonSerializer.Deserialize(value!); + } + + public async Task SetAsync(string key, T value, TimeSpan ttl, CancellationToken ct) + { + var db = _redis.GetDatabase(); + var json = JsonSerializer.Serialize(value); + await db.StringSetAsync(key, json, ttl); + _logger.LogDebug("Cache set: {Key} (TTL: {TTL}s)", key, ttl.TotalSeconds); + } + + public async Task RemoveAsync(string key, CancellationToken ct) + { + var db = _redis.GetDatabase(); + await db.KeyDeleteAsync(key); + _logger.LogDebug("Cache removed: {Key}", key); + } + + public async Task RemoveByPatternAsync(string pattern, CancellationToken ct) + { + var server = _redis.GetServer(_redis.GetEndPoints().First()); + var keys = server.Keys(pattern: pattern); + + var db = _redis.GetDatabase(); + foreach (var key in keys) + { + await db.KeyDeleteAsync(key); + } + + _logger.LogDebug("Cache removed by pattern: {Pattern}", pattern); + } +} +``` + +### Cached Resource Example + +```csharp +public class ProjectsListResource : IMcpResource +{ + private readonly IProjectRepository _projectRepo; + private readonly ITenantContext _tenantContext; + private readonly IMcpCacheService _cache; + + public async Task GetContentAsync( + McpResourceRequest request, + CancellationToken cancellationToken) + { + var tenantId = _tenantContext.CurrentTenantId; + var cacheKey = $"mcp:{tenantId}:projects.list"; + + // Try cache first + var cached = await _cache.GetAsync(cacheKey, cancellationToken); + if (cached != null) + { + return CreateResponse(cached); + } + + // Cache miss - query database + var projects = await _projectRepo.GetAllAsync(tenantId, cancellationToken); + var projectDtos = projects.Select(MapToDto).ToArray(); + + // Populate cache + await _cache.SetAsync(cacheKey, projectDtos, TimeSpan.FromMinutes(5), cancellationToken); + + return CreateResponse(projectDtos); + } +} +``` + +### Cache Key Format + +``` +mcp:{tenantId}:{resourceUri}[:{params_hash}] + +Examples: +- mcp:00000000-0000-0000-0000-000000000001:projects.list +- mcp:00000000-0000-0000-0000-000000000001:issues.search:abc123 +- mcp:00000000-0000-0000-0000-000000000001:sprints.current +``` + +### Cache Invalidation (Domain Events) + +```csharp +public class ProjectUpdatedEventHandler : INotificationHandler +{ + private readonly IMcpCacheService _cache; + + public async Task Handle(ProjectUpdatedEvent e, CancellationToken ct) + { + // Invalidate projects.list for this tenant + await _cache.RemoveAsync($"mcp:{e.TenantId}:projects.list", ct); + + // Invalidate specific project + await _cache.RemoveAsync($"mcp:{e.TenantId}:projects.get/{e.ProjectId}", ct); + } +} +``` + +## Tasks + +### Task 1: Redis Client Setup (2 hours) +- [ ] Add StackExchange.Redis NuGet package +- [ ] Configure connection string in `appsettings.json` +- [ ] Create `RedisMcpCacheService` implementation +- [ ] Add health checks + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Services/RedisMcpCacheService.cs` + +### Task 2: Cache Service Interface (2 hours) +- [ ] Create `IMcpCacheService` interface +- [ ] Implement Get/Set/Remove methods +- [ ] Add logging and metrics + +**Files to Create**: +- `ColaFlow.Modules.Mcp/Contracts/IMcpCacheService.cs` + +### Task 3: Update Resources with Caching (6 hours) +- [ ] Update `ProjectsListResource` to use cache +- [ ] Update `UsersListResource` to use cache +- [ ] Update `SprintsCurrentResource` to use cache +- [ ] Update `IssuesSearchResource` to use cache (with query hash) + +### Task 4: Cache Invalidation Event Handlers (3 hours) +- [ ] ProjectCreated/Updated/Deleted → invalidate projects cache +- [ ] EpicCreated/Updated/Deleted → invalidate issues cache +- [ ] StoryCreated/Updated/Deleted → invalidate issues cache +- [ ] TaskCreated/Updated/Deleted → invalidate issues cache + +**Files to Create**: +- `ColaFlow.Modules.Mcp/EventHandlers/CacheInvalidationEventHandlers.cs` + +### Task 5: Performance Metrics (2 hours) +- [ ] Track cache hit/miss rates +- [ ] Track response time improvement +- [ ] Log metrics to structured logs + +### Task 6: Unit & Integration Tests (4 hours) +- [ ] Test cache hit scenario +- [ ] Test cache miss scenario +- [ ] Test cache invalidation +- [ ] Performance benchmarks (with/without cache) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Services/RedisMcpCacheServiceTests.cs` +- `ColaFlow.Modules.Mcp.Tests/Integration/CachingIntegrationTests.cs` + +## Testing Strategy + +### Performance Benchmarks +``` +Scenario: projects.list (100 projects) +- Without cache: 180ms (database query) +- With cache: 60ms (67% improvement) +- Cache hit rate: 85% +``` + +### Integration Tests +- Test cache hit after first request +- Test cache miss on first request +- Test cache invalidation on update +- Test TTL expiration + +## Dependencies + +**Prerequisites**: +- Story 5.5 (Core Resources) - Resources to cache +- Redis server running (Docker or cloud) + +**Optional**: Not blocking for M2 MVP + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Redis unavailable | Medium | Low | Fallback to database, circuit breaker | +| Cache inconsistency | Medium | Medium | Short TTL, event-driven invalidation | +| Memory usage | Low | Low | Set max memory limit in Redis | + +## Definition of Done + +- [ ] Redis integration working +- [ ] Cache hit rate > 80% +- [ ] Response time improved by 30%+ +- [ ] Cache invalidation working +- [ ] All tests passing +- [ ] Performance benchmarks documented + +## Notes + +### Why This Story Matters +- **Performance**: 30-50% faster response times +- **Scalability**: Reduce database load by 80% +- **Cost**: Lower database resource usage +- **User Experience**: Faster AI responses + +### Redis Configuration + +```json +{ + "Redis": { + "ConnectionString": "localhost:6379", + "InstanceName": "colaflow:", + "DefaultTTL": 300 + } +} +``` diff --git a/docs/stories/sprint_5/story_5_9.md b/docs/stories/sprint_5/story_5_9.md new file mode 100644 index 0000000..b67465c --- /dev/null +++ b/docs/stories/sprint_5/story_5_9.md @@ -0,0 +1,445 @@ +--- +story_id: story_5_9 +sprint_id: sprint_5 +phase: Phase 3 - Tools & Diff Preview +status: not_started +priority: P0 +story_points: 5 +assignee: backend +estimated_days: 2 +created_date: 2025-11-06 +dependencies: [story_5_3] +--- + +# Story 5.9: Diff Preview Service Implementation + +**Phase**: Phase 3 - Tools & Diff Preview (Week 5-6) +**Priority**: P0 CRITICAL +**Estimated Effort**: 5 Story Points (2 days) + +## User Story + +**As a** User +**I want** to see what changes AI will make before they are applied +**So that** I can approve or reject AI operations safely + +## Business Value + +Diff Preview is the **core safety mechanism** for M2. It enables: +- **Transparency**: Users see exactly what will change +- **Safety**: Prevents AI mistakes from affecting production data +- **Compliance**: Audit trail for all AI operations +- **Trust**: Users confident in AI automation + +**Without Diff Preview, AI write operations would be too risky for production.** + +## Acceptance Criteria + +### AC1: Diff Preview Generation +- [ ] Generate before/after snapshots for CREATE, UPDATE, DELETE +- [ ] Calculate field-level differences (changed fields only) +- [ ] Support complex objects (nested, arrays, JSON) +- [ ] Handle null values and type changes + +### AC2: Diff Output Format +- [ ] JSON format with before/after data +- [ ] Array of changed fields (field name, old value, new value) +- [ ] HTML diff for text fields (visual diff) +- [ ] Entity metadata (type, ID, key) + +### AC3: Supported Operations +- [ ] CREATE: Show all new fields (before = null, after = new data) +- [ ] UPDATE: Show only changed fields (before vs after) +- [ ] DELETE: Show all deleted fields (before = data, after = null) + +### AC4: Edge Cases +- [ ] Nested object changes (e.g., assignee change) +- [ ] Array/list changes (e.g., add/remove tags) +- [ ] Date/time formatting +- [ ] Large text fields (truncate in preview) + +### AC5: Testing +- [ ] Unit tests for all operations (CREATE, UPDATE, DELETE) +- [ ] Test complex object changes +- [ ] Test edge cases (null, arrays, nested) +- [ ] Performance test (< 50ms for typical diff) + +## Technical Design + +### Service Interface + +```csharp +public interface IDiffPreviewService +{ + Task GeneratePreviewAsync( + Guid? entityId, + TEntity afterData, + string operation, + CancellationToken cancellationToken) where TEntity : class; +} + +public class DiffPreviewService : IDiffPreviewService +{ + private readonly IGenericRepository _repository; + private readonly ILogger _logger; + + public async Task GeneratePreviewAsync( + Guid? entityId, + TEntity afterData, + string operation, + CancellationToken ct) where TEntity : class + { + switch (operation) + { + case "CREATE": + return GenerateCreatePreview(afterData); + + case "UPDATE": + if (!entityId.HasValue) + throw new ArgumentException("EntityId required for UPDATE"); + + var beforeData = await _repository.GetByIdAsync(entityId.Value, ct); + if (beforeData == null) + throw new McpNotFoundException(typeof(TEntity).Name, entityId.Value.ToString()); + + return GenerateUpdatePreview(entityId.Value, beforeData, afterData); + + case "DELETE": + if (!entityId.HasValue) + throw new ArgumentException("EntityId required for DELETE"); + + var dataToDelete = await _repository.GetByIdAsync(entityId.Value, ct); + if (dataToDelete == null) + throw new McpNotFoundException(typeof(TEntity).Name, entityId.Value.ToString()); + + return GenerateDeletePreview(entityId.Value, dataToDelete); + + default: + throw new ArgumentException($"Unknown operation: {operation}"); + } + } + + private DiffPreview GenerateCreatePreview(TEntity afterData) + { + var changedFields = new List(); + var properties = typeof(TEntity).GetProperties(); + + foreach (var prop in properties) + { + var newValue = prop.GetValue(afterData); + if (newValue != null) // Skip null fields + { + changedFields.Add(new DiffField( + fieldName: prop.Name, + displayName: FormatFieldName(prop.Name), + oldValue: null, + newValue: newValue + )); + } + } + + return new DiffPreview( + operation: "CREATE", + entityType: typeof(TEntity).Name, + entityId: null, + entityKey: null, + beforeData: null, + afterData: afterData, + changedFields: changedFields.AsReadOnly() + ); + } + + private DiffPreview GenerateUpdatePreview( + Guid entityId, + TEntity beforeData, + TEntity afterData) + { + var changedFields = new List(); + var properties = typeof(TEntity).GetProperties(); + + foreach (var prop in properties) + { + var oldValue = prop.GetValue(beforeData); + var newValue = prop.GetValue(afterData); + + if (!Equals(oldValue, newValue)) + { + var diffHtml = GenerateHtmlDiff(oldValue, newValue, prop.PropertyType); + + changedFields.Add(new DiffField( + fieldName: prop.Name, + displayName: FormatFieldName(prop.Name), + oldValue: oldValue, + newValue: newValue, + diffHtml: diffHtml + )); + } + } + + return new DiffPreview( + operation: "UPDATE", + entityType: typeof(TEntity).Name, + entityId: entityId, + entityKey: GetEntityKey(afterData), + beforeData: beforeData, + afterData: afterData, + changedFields: changedFields.AsReadOnly() + ); + } + + private DiffPreview GenerateDeletePreview(Guid entityId, TEntity dataToDelete) + { + var changedFields = new List(); + var properties = typeof(TEntity).GetProperties(); + + foreach (var prop in properties) + { + var oldValue = prop.GetValue(dataToDelete); + if (oldValue != null) + { + changedFields.Add(new DiffField( + fieldName: prop.Name, + displayName: FormatFieldName(prop.Name), + oldValue: oldValue, + newValue: null + )); + } + } + + return new DiffPreview( + operation: "DELETE", + entityType: typeof(TEntity).Name, + entityId: entityId, + entityKey: GetEntityKey(dataToDelete), + beforeData: dataToDelete, + afterData: null, + changedFields: changedFields.AsReadOnly() + ); + } + + private string? GenerateHtmlDiff(object? oldValue, object? newValue, Type propertyType) + { + // For string properties, generate HTML diff + if (propertyType == typeof(string) && oldValue != null && newValue != null) + { + var oldStr = oldValue.ToString(); + var newStr = newValue.ToString(); + + // Use simple diff algorithm (can be improved with DiffPlex library) + return $"{oldStr} {newStr}"; + } + + return null; + } + + private string FormatFieldName(string fieldName) + { + // Convert "EstimatedHours" to "Estimated Hours" + return System.Text.RegularExpressions.Regex.Replace( + fieldName, "([a-z])([A-Z])", "$1 $2"); + } + + private string? GetEntityKey(TEntity entity) + { + // Try to get a human-readable key (e.g., "COLA-146") + var keyProp = typeof(TEntity).GetProperty("Key"); + return keyProp?.GetValue(entity)?.ToString(); + } +} +``` + +### Example Diff Output (UPDATE Issue) + +```json +{ + "operation": "UPDATE", + "entityType": "Story", + "entityId": "12345678-1234-1234-1234-123456789012", + "entityKey": "COLA-146", + "beforeData": { + "title": "Implement MCP Server", + "priority": "High", + "status": "InProgress", + "assigneeId": "aaaa-bbbb-cccc-dddd" + }, + "afterData": { + "title": "Implement MCP Server (updated)", + "priority": "Critical", + "status": "InProgress", + "assigneeId": "aaaa-bbbb-cccc-dddd" + }, + "changedFields": [ + { + "fieldName": "title", + "displayName": "Title", + "oldValue": "Implement MCP Server", + "newValue": "Implement MCP Server (updated)", + "diffHtml": "Implement MCP Server Implement MCP Server (updated)" + }, + { + "fieldName": "priority", + "displayName": "Priority", + "oldValue": "High", + "newValue": "Critical" + } + ] +} +``` + +## Tasks + +### Task 1: Create DiffPreviewService Interface (1 hour) +- [ ] Define `IDiffPreviewService` interface +- [ ] Define method signature (generic TEntity) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Application/Contracts/IDiffPreviewService.cs` + +### Task 2: Implement CREATE Preview (2 hours) +- [ ] Extract all non-null properties from afterData +- [ ] Format field names (camelCase → Title Case) +- [ ] Return DiffPreview with changedFields + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Application/Services/DiffPreviewService.cs` + +### Task 3: Implement UPDATE Preview (4 hours) +- [ ] Fetch beforeData from repository +- [ ] Compare all properties (old vs new) +- [ ] Build changedFields list (only changed) +- [ ] Generate HTML diff for text fields + +### Task 4: Implement DELETE Preview (1 hour) +- [ ] Fetch dataToDelete from repository +- [ ] Extract all non-null properties +- [ ] Return DiffPreview with oldValue set, newValue null + +### Task 5: Handle Complex Types (3 hours) +- [ ] Nested objects (e.g., assignee change) +- [ ] Arrays/lists (e.g., tags) +- [ ] Date/time formatting +- [ ] Large text truncation + +### Task 6: Unit Tests (5 hours) +- [ ] Test CREATE preview (all fields) +- [ ] Test UPDATE preview (only changed fields) +- [ ] Test DELETE preview (all fields) +- [ ] Test nested object changes +- [ ] Test array changes +- [ ] Test null handling + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Services/DiffPreviewServiceTests.cs` + +### Task 7: Integration Tests (2 hours) +- [ ] Test with real entities (Story, Epic, WorkTask) +- [ ] Test performance (< 50ms) + +**Files to Create**: +- `ColaFlow.Modules.Mcp.Tests/Integration/DiffPreviewIntegrationTests.cs` + +## Testing Strategy + +### Unit Tests (Target: > 90% coverage) +- All operations (CREATE, UPDATE, DELETE) +- All data types (string, int, enum, nested object, array) +- Edge cases (null, empty, large text) + +### Test Cases + +```csharp +[Fact] +public async Task GeneratePreview_CreateOperation_AllFieldsIncluded() +{ + // Arrange + var newIssue = new Story + { + Title = "New Story", + Priority = Priority.High, + Status = IssueStatus.Todo + }; + + // Act + var diff = await _service.GeneratePreviewAsync( + null, newIssue, "CREATE", CancellationToken.None); + + // Assert + Assert.Equal("CREATE", diff.Operation); + Assert.Null(diff.EntityId); + Assert.Null(diff.BeforeData); + Assert.NotNull(diff.AfterData); + Assert.Equal(3, diff.ChangedFields.Count); // Title, Priority, Status +} + +[Fact] +public async Task GeneratePreview_UpdateOperation_OnlyChangedFields() +{ + // Arrange + var existingIssue = new Story + { + Id = Guid.NewGuid(), + Title = "Original Title", + Priority = Priority.Medium, + Status = IssueStatus.InProgress + }; + + var updatedIssue = new Story + { + Id = existingIssue.Id, + Title = "Updated Title", + Priority = Priority.High, // Changed + Status = IssueStatus.InProgress // Unchanged + }; + + _mockRepo.Setup(r => r.GetByIdAsync(existingIssue.Id, It.IsAny())) + .ReturnsAsync(existingIssue); + + // Act + var diff = await _service.GeneratePreviewAsync( + existingIssue.Id, updatedIssue, "UPDATE", CancellationToken.None); + + // Assert + Assert.Equal("UPDATE", diff.Operation); + Assert.Equal(2, diff.ChangedFields.Count); // Title, Priority (Status unchanged) + Assert.Contains(diff.ChangedFields, f => f.FieldName == "Title"); + Assert.Contains(diff.ChangedFields, f => f.FieldName == "Priority"); +} +``` + +## Dependencies + +**Prerequisites**: +- Story 5.3 (MCP Domain Layer) - Uses DiffPreview value object + +**Used By**: +- Story 5.11 (Core MCP Tools) - Generates diff before creating PendingChange + +## Risks & Mitigation + +| Risk | Impact | Probability | Mitigation | +|------|--------|-------------|------------| +| Complex object diff bugs | Medium | Medium | Comprehensive unit tests, code review | +| Performance slow (> 50ms) | Medium | Low | Optimize reflection, cache property info | +| Large text diff memory | Low | Low | Truncate long text fields | + +## Definition of Done + +- [ ] All 3 operations (CREATE, UPDATE, DELETE) working +- [ ] Unit test coverage > 90% +- [ ] Integration tests passing +- [ ] Performance < 50ms for typical diff +- [ ] Code reviewed and approved +- [ ] Handles complex types (nested, arrays) + +## Notes + +### Why This Story Matters +- **Core Safety Mechanism**: Without diff preview, AI operations too risky +- **User Trust**: Transparency builds confidence in AI +- **Compliance**: Required audit trail +- **M2 Critical Path**: Blocks all write operations + +### Performance Optimization +- Cache property reflection info +- Use source generators for serialization (future) +- Limit max diff size (truncate large fields)