namespace ColaFlow.Modules.Mcp.Contracts.Resources;

/// <summary>
/// Interface for MCP Resources
/// Resources provide read-only data to AI agents through the MCP protocol
/// </summary>
public interface IMcpResource
{
    /// <summary>
    /// Resource URI (e.g., "colaflow://projects.list")
    /// </summary>
    string Uri { get; }

    /// <summary>
    /// Resource display name
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Resource description
    /// </summary>
    string Description { get; }

    /// <summary>
    /// MIME type of the resource content (typically "application/json")
    /// </summary>
    string MimeType { get; }

    /// <summary>
    /// Resource category (e.g., "Projects", "Issues", "Sprints", "Users")
    /// Default: "General"
    /// </summary>
    string Category => "General";

    /// <summary>
    /// Resource version (for future compatibility)
    /// Default: "1.0"
    /// </summary>
    string Version => "1.0";

    /// <summary>
    /// Get resource descriptor with full metadata
    /// </summary>
    McpResourceDescriptor GetDescriptor()
    {
        return new McpResourceDescriptor
        {
            Uri = Uri,
            Name = Name,
            Description = Description,
            MimeType = MimeType,
            Category = Category,
            Version = Version,
            IsEnabled = true
        };
    }

    /// <summary>
    /// Get resource content
    /// </summary>
    /// <param name="request">Resource request with URI and parameters</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Resource content</returns>
    Task<McpResourceContent> GetContentAsync(
        McpResourceRequest request,
        CancellationToken cancellationToken);
}
