image-tiler-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server that splits large images into optimally-sized tiles for LLM vision systems (Claude, OpenAI, Gemini, Gemini 3). Prevents automatic downscaling by keeping each tile within each model's sweet spot. Also captures full-page screenshots from URLs via Chrome DevTools Protocol, with scroll-stitching for pages exceeding Chrome's 16,384px capture limit. Built with the MCP SDK, Sharp (libvips), ws (WebSocket for CDP), and Zod.

Published as image-tiler-mcp-server on npm. Requires Node >= 20. This is a library/tool (not an app): inputs come from MCP clients, not untrusted end users.

Model configs available via tiler://models resource. See docs/architecture.md for full module and test inventory.

Commands

npm run build        # Compile TypeScript -> dist/
npm run dev          # Watch mode (tsc --watch)
npm start            # Run the compiled server (node dist/index.js)
npm run inspect      # Launch MCP Inspector for interactive testing
npm test             # Run test suite (vitest)
npm run test:watch   # Run tests in watch mode
npx vitest run src/__tests__/schemas.test.ts  # Single test file

No linter is configured.

Architecture

Transport: stdio only (single-session, local). Entry point is src/index.ts.

One unified MCP tool: tiler (src/tools/tiler.ts). Mode is auto-detected from params:

• Tile-image mode (has filePath/sourceUrl/dataUrl/imageBase64): Splits image into grid tiles saved to tiles/{name}/. Returns JSON metadata + up to 5 tile images inline with pagination.
• Capture-and-tile mode (has url or screenshotPath): Captures URL screenshot via Chrome CDP, tiles it, returns first batch inline. Stop after Phase 1 for screenshot-only use.
• Get-tiles mode (has tilesDir): Reads tiles from disk, returns base64 images in batches of 5 with pagination via start/end.