// Copyright 2019 Yunion // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package tools import ( "context" "encoding/json" "fmt" "strconv" "strings" "github.com/mark3labs/mcp-go/mcp" "yunion.io/x/log" "yunion.io/x/onecloud/pkg/mcp-server/adapters" "yunion.io/x/onecloud/pkg/mcp-server/models" ) // CloudpodsImagesTool 是一个用于查询 Cloudpods 镜像列表的工具 // 它封装了 Cloudpods 适配器和日志记录器 type CloudpodsImagesTool struct { // adapter 用于与 Cloudpods API 进行交互 adapter *adapters.CloudpodsAdapter } // NewCloudpodsImagesTool 创建一个新的 CloudpodsImagesTool 实例 // 参数: // - adapter: Cloudpods 适配器实例，用于与 Cloudpods API 交互 // // 返回值: // - *CloudpodsImagesTool: 新创建的 CloudpodsImagesTool 实例 func NewCloudpodsImagesTool(adapter *adapters.CloudpodsAdapter) *CloudpodsImagesTool { return &CloudpodsImagesTool{ adapter: adapter, } } // GetTool 定义并返回 Cloudpods 镜像列表查询工具的元数据 // 该工具允许用户查询 Cloudpods 中的磁盘镜像列表，并支持多种查询参数 // 返回值: // - mcp.Tool: 定义了工具名称、描述和参数的工具对象 func (c *CloudpodsImagesTool) GetTool() mcp.Tool { return mcp.NewTool( "cloudpods_list_images", mcp.WithDescription("查询Cloudpods磁盘镜像列表，获取系统镜像信息"), mcp.WithString("limit", mcp.Description("返回结果数量限制，默认为20")), mcp.WithString("offset", mcp.Description("返回结果偏移量，默认为0")), mcp.WithString("search", mcp.Description("搜索关键词，可以按镜像名称搜索")), mcp.WithString("os_types", mcp.Description("操作系统类型，多个用逗号分隔，如：Linux,Windows,FreeBSD")), mcp.WithString("ak", mcp.Description("用户登录cloudpods后获取的access key")), mcp.WithString("sk", mcp.Description("用户登录cloudpods后获取的secret key")), ) } // Handle 处理 Cloudpods 镜像列表查询请求 // 该方法解析请求参数，调用适配器查询镜像列表，并格式化返回结果 // 参数: // - ctx: 上下文对象，用于控制请求生命周期 // - req: 工具调用请求对象，包含查询参数 // // 返回值: // - *mcp.CallToolResult: 格式化后的镜像列表查询结果 // - error: 如果查询过程中发生错误，则返回相应的错误信息 func (c *CloudpodsImagesTool) Handle(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) { // 设置默认的查询结果数量限制为20 limit := 20 // 如果请求中包含limit参数且为有效正整数，则使用该值 if limitStr := req.GetString("limit", ""); limitStr != "" { if parsedLimit, err := strconv.Atoi(limitStr); err == nil && parsedLimit > 0 { limit = parsedLimit } } // 设置默认的查询偏移量为0 offset := 0 // 如果请求中包含offset参数且为有效非负整数，则使用该值 if offsetStr := req.GetString("offset", ""); offsetStr != "" { if parsedOffset, err := strconv.Atoi(offsetStr); err == nil && parsedOffset >= 0 { offset = parsedOffset } } // 获取搜索关键词参数 search := req.GetString("search", "") // 解析操作系统类型参数，支持多个类型用逗号分隔 var osTypes []string if osTypesStr := req.GetString("os_types", ""); osTypesStr != "" { osTypes = strings.Split(osTypesStr, ",") for i, osType := range osTypes { osTypes[i] = strings.TrimSpace(osType) } } // 获取访问凭证 ak := req.GetString("ak", "") sk := req.GetString("sk", "") // 调用适配器查询镜像列表 imagesResponse, err := c.adapter.ListImages(ctx, limit, offset, search, osTypes, ak, sk) if err != nil { log.Errorf("Fail to query image: %s", err) return nil, fmt.Errorf("fail to query image: %w", err) } // 格式化查询结果 formattedResult := c.formatImagesResult(imagesResponse, limit, offset, search, osTypes) // 将结果序列化为JSON格式 resultJSON, err := json.MarshalIndent(formattedResult, "", " ") if err != nil { log.Errorf("Fail to serialize result: %s", err) return nil, fmt.Errorf("fail to serialize result: %w", err) } // 返回格式化后的结果 return mcp.NewToolResultText(string(resultJSON)), nil } // GetName 返回工具的名称标识符 // 返回值: // - string: 工具名称，用于唯一标识该工具 func (c *CloudpodsImagesTool) GetName() string { return "cloudpods_list_images" } // formatImagesResult 格式化镜像列表查询结果 // 该方法将从适配器获取的原始镜像数据转换为结构化的响应格式，包含查询信息、镜像详情和摘要信息 // 参数: // - response: 从适配器获取的原始镜像列表响应数据 // - limit: 查询结果数量限制 // - offset: 查询偏移量 // - search: 搜索关键词 // - osTypes: 操作系统类型过滤条件 // // 返回值: // - map[string]interface{}: 格式化后的镜像列表数据，包含查询信息、镜像详情和摘要 func (c *CloudpodsImagesTool) formatImagesResult(response *models.ImageListResponse, limit, offset int, search string, osTypes []string) map[string]interface{} { // 初始化格式化结果结构 formatted := map[string]interface{}{ // 查询信息部分，包含查询参数和结果统计 "query_info": map[string]interface{}{ "limit": limit, "offset": offset, "search": search, "os_types": osTypes, "total": response.Total, "count": len(response.Images), }, // 镜像列表部分，初始化为空数组 "images": make([]map[string]interface{}, 0, len(response.Images)), } // 遍历原始镜像数据，提取每个镜像的详细信息 for _, image := range response.Images { // 构造单个镜像的详细信息 imageInfo := map[string]interface{}{ "id": image.Id, "name": image.Name, "description": image.Description, "status": image.Status, "disk_format": image.DiskFormat, "size": image.Size, "checksum": image.Checksum, "oss_checksum": image.OssChecksum, "fast_hash": image.FastHash, "location": image.Location, "os_arch": image.OsArch, "min_disk": image.MinDisk, "min_ram": image.MinRam, "is_data": image.IsData, "is_guest_image": image.IsGuestImage, "is_public": image.IsPublic, "is_standard": image.IsStandard, "is_system": image.IsSystem, "is_emulated": image.IsEmulated, "protected": image.Protected, "disable_delete": image.DisableDelete, "freezed": image.Freezed, "pending_deleted": image.PendingDeleted, "pending_deleted_at": image.PendingDeletedAt, "auto_delete_at": image.AutoDeleteAt, "encrypt_alg": image.EncryptAlg, "encrypt_key": image.EncryptKey, "encrypt_key_id": image.EncryptKeyId, "encrypt_key_user": image.EncryptKeyUser, "encrypt_key_user_domain": image.EncryptKeyUserDomain, "encrypt_key_user_domain_id": image.EncryptKeyUserDomainId, "encrypt_key_user_id": image.EncryptKeyUserId, "encrypt_status": image.EncryptStatus, "owner": image.Owner, "project": image.Project, "project_id": image.ProjectId, "project_domain": image.ProjectDomain, "project_metadata": image.ProjectMetadata, "project_src": image.ProjectSrc, "tenant": image.Tenant, "tenant_id": image.TenantId, "domain_id": image.DomainId, "public_scope": image.PublicScope, "public_src": image.PublicSrc, "shared_domains": image.SharedDomains, "shared_projects": image.SharedProjects, "properties": image.Properties, "metadata": image.Metadata, "progress": image.Progress, "can_delete": image.CanDelete, "can_update": image.CanUpdate, "update_version": image.UpdateVersion, "created_at": image.CreatedAt, "updated_at": image.UpdatedAt, } // 将镜像信息添加到结果数组中 formatted["images"] = append(formatted["images"].([]map[string]interface{}), imageInfo) } // 构造结果摘要信息 formatted["summary"] = map[string]interface{}{ "total_images": response.Total, "returned_count": len(response.Images), "has_more": response.Total > int64(offset+len(response.Images)), "next_offset": offset + len(response.Images), } // 返回格式化后的完整结果 return formatted }