XMZ MCP Server

Instructions

Implementation Reference

• src/server.ts:148-180 (registration)

  Registration of the 'putBase64' tool, including description, Zod input schema, and inline async handler function that delegates to CosService.uploadBase64 and formats the response.

  server.tool(
    'putBase64',
    '上传base64编码内容到存储桶',
    {
      base64Content: z.string().describe('base64编码的内容'),
      fileName: z.string().describe('文件名 (存在存储桶里的名称)'),
      targetDir: z
        .string()
        .optional()
        .describe('目标目录 (存在存储桶的哪个目录)'),
      contentType: z
        .string()
        .optional()
        .describe('内容类型，如 image/png (图片), application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (文档) 等，如果base64带头部则默认自带的头部否则默认为 application/octet-stream'),
    },
    async ({ base64Content, fileName, targetDir, contentType }) => {
      const res = await COSInstance.uploadBase64({
        base64Content,
        fileName,
        targetDir,
        contentType,
      });
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(res.data, null, 2),
          },
        ],
        isError: !res.isSuccess,
      };
    },
  );

• src/services/cos/cos.service.ts:195-232 (handler)

  Core handler logic for uploading base64 content to COS: validates params, processes base64 (extracts data and mime if data URI), converts to Buffer, builds COS key, performs putObject.

  async uploadBase64(params: UploadBase64Params) {
    const validParams = UploadBase64ParamsSchema.parse(params);
    let { base64Content, fileName, targetDir = '' } = validParams;
    
    try {
      // 构建COS路径
      const cosPath = this.buildCosPath(fileName, targetDir);
  
      // 处理base64
      let { base64Data, contentType } = this.processBase64(base64Content, validParams.contentType);
  
      // 将base64转换为Buffer
      const buffer = Buffer.from(base64Data, 'base64');
  
      // 上传buffer内容
      const cosParams: COS.PutObjectParams = {
        Bucket: this.bucket,
        Region: this.region,
        Key: cosPath,
        Body: buffer,
        ContentType: contentType || 'application/octet-stream',
      };
  
      const result = await this.cos.putObject(cosParams);
  
      return {
        isSuccess: true,
        message: '上传成功',
        data: result,
      };
    } catch (error) {
      return {
        isSuccess: false,
        message: '上传失败',
        data: error,
      };
    }
  }

• src/services/cos/cos.service.ts:26-32 (schema)

  Zod schema for UploadBase64Params used by the uploadBase64 method.

  export const UploadBase64ParamsSchema = z.object({
    base64Content: z.string(),
    fileName: z.string(),
    targetDir: z.string().optional(),
    contentType: z.string().optional()
  });
  export type UploadBase64Params = z.infer<typeof UploadBase64ParamsSchema>;

• src/services/cos/cos.service.ts:54-86 (helper)

  Helper method to process base64 string: handles data URI prefixes, extracts clean base64 data and MIME type.

    private processBase64(base64 = '', contentType = '') {
    // 基础验证
    if (typeof base64 !== 'string') {
      throw new Error('base64参数必须是字符串');
    }
    
    if (typeof contentType !== 'string') {
      throw new Error('contentType参数必须是字符串');
    }
    
    let base64Data = base64;
    let finalContentType = contentType;
    
    // 检查base64是否包含数据头
    const dataUriRegex = /^data:([^;]+);base64,/;
    const match = base64.match(dataUriRegex);
    
    if (match) {
      // 如果base64有数据头，提取纯数据和contentType
      const headerEndIndex = base64.indexOf(',') + 1;
      base64Data = base64.substring(headerEndIndex);
      
      // 如果没有传递contentType，则从base64头中提取
      if (!contentType.trim()) {
        finalContentType = match[1];
      }
    }
    
    return {
      base64Data: base64Data.trim(),
      contentType: finalContentType.trim()
    };
  }

• src/services/cos/cos.service.ts:94-102 (helper)

  Helper method to build the COS object key/path from filename and optional target directory.

  private buildCosPath(fileName: string, targetDir?: string): string {
    if (!targetDir) {
      return fileName;
    }
    
    // 规范化目标目录：移除头尾斜杠
    const normalizedDir = targetDir.replace(/^\/+|\/+$/g, '');
    return normalizedDir ? `${normalizedDir}/${fileName}` : fileName;
  }