Strapi MCP Server

Instructions

Implementation Reference

• src/index.ts:1598-1648 (handler)

  Main execution handler for the 'strapi_upload_media' tool within the CallToolRequestSchema handler. Validates input, downloads image from URL, processes it (format/quality), uploads to Strapi /api/upload endpoint, and returns formatted response with usage instructions.
  // Validate input using Zod (includes authorization check) const validatedArgs = validateToolInput("strapi_upload_media", args, requestId); const { server, url, format, quality, metadata, userAuthorized } = validatedArgs; logger.startRequest(requestId, name, server); // Extract filename from URL const fileName = url.split('/').pop() || 'image'; // Download the image const imageBuffer = await downloadImage(url); // Process the image if format conversion is requested const processedBuffer = await processImage(imageBuffer, format, quality); // Upload to Strapi with metadata (with authorization check) const data = await uploadMedia(server, processedBuffer, fileName, format, metadata, userAuthorized, requestId); // Format response with helpful usage information const response = { success: true, data: data, image_info: { format: format === 'original' ? 'original (unchanged)' : format, quality: format === 'original' ? 'original (unchanged)' : quality, filename: data[0].name, size: data[0].size, mime: data[0].mime }, usage_guide: { file_id: data[0].id, url: data[0].url, how_to_use: { rest_api: "Use the file ID in your content type's media field", graphql: "Use the file ID in your GraphQL mutations", examples: { rest: "PUT /api/content-type/1 with body: { data: { image: " + data[0].id + " } }", graphql: "mutation { updateContentType(id: 1, data: { image: " + data[0].id + " }) { data { id } } }" } } } }; result = { content: [ { type: "text", text: JSON.stringify(response, null, 2) } ] }; } else {
• src/index.ts:573-618 (schema)

  Zod input validation schema for the strapi_upload_media tool, defining parameters like server, url, format, quality, metadata, and requiring userAuthorized for security.
  const UploadMediaSchema = z.object({ server: z.string().min(1, "Server name is required and cannot be empty"), url: z.string().url("Must be a valid URL"), format: z.enum(["jpeg", "png", "webp", "original"], { errorMap: () => ({ message: "Format must be one of: jpeg, png, webp, original" }) }).optional().default("original"), quality: z.union([ z.number().int().min(1, "Quality must be between 1 and 100").max(100, "Quality must be between 1 and 100"), z.string().transform((str, ctx) => { const num = parseInt(str); if (isNaN(num) || num < 1 || num > 100) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Quality must be between 1 and 100" }); return z.NEVER; } return num; }) ]).optional().default(80), metadata: MediaMetadataSchema.optional(), userAuthorized: z.union([ z.boolean(), z.string().transform((str, ctx) => { if (str === "true") return true; if (str === "false") return false; ctx.addIssue({ code: z.ZodIssueCode.custom, message: "userAuthorized must be boolean true/false or string 'true'/'false'" }); return z.NEVER; }) ]).optional().default(false) }).strict().refine( (data) => { // Media upload requires explicit user authorization if (!data.userAuthorized) { return false; } return true; }, { message: "Media upload operations require explicit user authorization (userAuthorized: true)", path: ["userAuthorized"] } );
• src/index.ts:1347-1400 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the name, description, and JSON input schema for strapi_upload_media.
  name: "strapi_upload_media", description: "Upload media to Strapi's media library from a URL with format conversion, quality control, and metadata options. IMPORTANT: This is a write operation that REQUIRES explicit user authorization via the userAuthorized parameter.", inputSchema: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media), properties: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media).properties, server: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media).properties.server, description: "The name of the server to connect to" }, url: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media).properties.url, description: "URL of the image to upload" }, format: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media).properties.format, description: "Target format for the image. Use 'original' to keep the source format.", default: "original" }, quality: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media).properties.quality, description: "Image quality (1-100). Only applies when converting formats.", default: 80 }, metadata: { type: "object", properties: { name: { type: "string", description: "Name of the file" }, caption: { type: "string", description: "Caption for the image" }, alternativeText: { type: "string", description: "Alternative text for accessibility" }, description: { type: "string", description: "Detailed description of the image" } }, additionalProperties: false }, userAuthorized: { ...zodToJsonSchema(ToolSchemas.strapi_upload_media).properties.userAuthorized, description: "REQUIRED for media upload operations. Client MUST obtain explicit user authorization before setting this to true.", default: false } } } }
• src/index.ts:1170-1238 (helper)

  Key helper function that handles the actual FormData-based POST upload to Strapi's /api/upload endpoint, including authorization enforcement, filename adjustment, metadata attachment, logging, and error handling.
  async function uploadMedia(serverName: string, imageBuffer: Buffer, fileName: string, format: string, metadata?: Record<string, any>, userAuthorized: boolean = false, requestId?: string): Promise<any> { // Check for explicit user authorization for this upload operation if (!userAuthorized) { throw new McpError( ErrorCode.InvalidParams, `AUTHORIZATION REQUIRED: Media upload operations require explicit user authorization.\n\n` + `IMPORTANT: The client MUST:\n` + `1. Ask the user for explicit permission before uploading this media\n` + `2. Show the user what media will be uploaded\n` + `3. Receive clear confirmation from the user\n` + `4. Set userAuthorized=true when making the request\n\n` + `This is a security measure to prevent unauthorized uploads.` ); } const serverConfig = getServerConfig(serverName); const formData = new FormData(); // Update filename extension if format is changed if (format !== 'original') { fileName = fileName.replace(/\.[^/.]+$/, '') + '.' + format; } // Add the file formData.append('files', imageBuffer, { filename: fileName, contentType: `image/${format === 'original' ? 'jpeg' : format}` // Default to jpeg for original }); // Add metadata if provided if (metadata) { formData.append('fileInfo', JSON.stringify(metadata)); } const url = `${serverConfig.API_URL}/api/upload`; const startTime = Date.now(); logger.debug(`Uploading media to Strapi`, { requestId, server: serverName, fileName, format, hasMetadata: !!metadata, bufferSize: imageBuffer.length, userAuthorized }); const response = await fetch(url, { method: 'POST', headers: { 'Authorization': `Bearer ${serverConfig.JWT}`, ...formData.getHeaders() }, body: formData }); const duration = Date.now() - startTime; logger.logApiCall( requestId || 'unknown', 'POST', '/api/upload', duration, response.status, serverName ); return handleStrapiError(response, 'Media upload', requestId); }
• src/index.ts:1146-1167 (helper)

  Helper function using Sharp library to process image buffer: convert format (jpeg/png/webp) and apply quality settings, or pass original.
  async function processImage(buffer: Buffer, format: string, quality: number): Promise<Buffer> { let sharpInstance = sharp(buffer); if (format !== 'original') { switch (format) { case 'jpeg': sharpInstance = sharpInstance.jpeg({ quality }); break; case 'png': // PNG quality is 0-100 for zlib compression level sharpInstance = sharpInstance.png({ compressionLevel: Math.floor((100 - quality) / 100 * 9) }); break; case 'webp': sharpInstance = sharpInstance.webp({ quality }); break; } } return sharpInstance.toBuffer(); }