sketch_html_analyze

Analyzes Sketch HTML zip files to extract design structure, page layouts, and artboard information for design review and implementation.

Instructions

Analyze sketch html files and return the design structure of corresponding pages or drawing boards

Input Schema

TableJSON Schema

Name	Required	Description
`file_path`	Yes	sketch html zip file path(required)
`page_id`	No	page id (optional)
`page_name`	No	page name (optional)
`artboard_id`	No	artboard id (optional)
`artboard_name`	No	artboard name (optional)
`rect`	No	rect [x, y, width, height] (optional)
`assets_path`	No	assets path (optional), default src/assets/sketch
`saveResult`	No	save analysis result (optional), default true

Implementation Reference

src/services/sketchHtmlAnalyze/index.ts:15-66 (handler)

The actual implementation of the sketch_html_analyze logic which processes the file, filters artboards, and assembles data.

export async function handleSketchHtmlAnalyze(args: SketchHtmlInputSchema) {
  let response = ''

  try {
    const sketchHtmlData = await openSketchHtmlFile(args.file_path)
    const targetArtboard = filterArtboards(args, sketchHtmlData.data.artboards)
    const assembledArtboard = assembleArtboard(
      targetArtboard,
      args.assets_path,
      args.rect,
      sketchHtmlData.images
    )

    const prompt = {
      meta: {
        description:
          'Design data extracted from Sketch exported HTML. All coordinates are relative to the artboard. Layers are flattened. Refer to the preview image to verify and refine the design structure.'
      },
      artboard: assembledArtboard.artboard
    }

    const parsed = path.parse(args.file_path)
    if (args.saveResult ?? true) {
      const targetPath = `${parsed.dir}/${parsed.name}/${assembledArtboard.artboard.pageName ?? assembledArtboard.artboard.pageObjectID}_${assembledArtboard.artboard.name ?? assembledArtboard.artboard.objectID}${args.rect?.length === 4 ? `[${args.rect.join(',')}]` : ''}.json`
      await writeJsonFile(targetPath, prompt)
    }

    response = `Sketch Structure JSON: ${JSON.stringify(prompt)}.`

    let previewPath = ''

    if (assembledArtboard.previewPath) {
      const imageData = sketchHtmlData.images?.find(item =>
        item.path.endsWith(assembledArtboard.previewPath)
      )?.data
      if (imageData) {
        const fileName = path.basename(assembledArtboard.previewPath)
        previewPath = `${parsed.dir}/${parsed.name}/${fileName}`
        response = `${response}\nSketch Preview Image: ${previewPath}`
        saveImage(imageData, `${parsed.dir}/${parsed.name}`, fileName).catch(
          error => {
            logger.error(`Failed to save image ${previewPath}: ${error}`)
          }
        )
      }
    }
  } catch (error) {
    response = `Sketch analyze error: ${error instanceof Error ? error.message : 'unknown error'}`
  }

  return response
}

src/tools/sketchHtmlAnalyze/index.ts:27-40 (handler)

The tool wrapper function that invokes the core logic and formats it for the MCP protocol.

async function sketchHtmlAnalyze(
  args: SketchHtmlInputSchema
): Promise<CallToolResult> {
  logger.debug(args, 'sketchHtmlAnalyze')
  const text = await handleSketchHtmlAnalyze(args)
  return {
    content: [
      {
        type: 'text',
        text
      }
    ]
  }
}

src/tools/sketchHtmlAnalyze/index.ts:42-53 (registration)

Tool registration function that exposes the sketchHtmlAnalyze handler to the MCP tool registry.

export function toolSketchHtmlAnalyze(): RegisterToolParams {
  return [
    toolName,
    {
      title: toolName,
      description:
        'Analyze sketch html files and return the design structure of corresponding pages or drawing boards',
      inputSchema: sketchHtmlInputSchema
    },
    sketchHtmlAnalyze
  ]
}

mcp-sketch