image-tiler-mcp-server 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Keiver Hernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+# image-tiler-mcp-server
+
+Split large images into optimally-sized tiles so LLM vision models see every detail — no downscaling, no lost text.
+
+<p align="center">
+  <img src="assets/preview.webp" alt="Preview of image tiling grid for veguitas.com" width="100%" />
+</p>
+
+## Why tiling matters
+
+LLM vision systems have a **maximum input resolution**. When you send an image larger than that limit, the model silently downscales it before processing. A 3600×22810 full-page screenshot gets shrunk to ~247×1568 by Claude — text becomes unreadable, UI details disappear, and the model can't analyze what it can't see.
+
+**Tiling solves this.** This MCP server:
+
+1. Reads the image dimensions and the target model's vision config
+2. Calculates an optimal grid that keeps every tile within the model's sweet spot
+3. Extracts tiles as individual PNGs and saves them to disk
+4. Returns metadata (grid layout, file paths, estimated token cost)
+5. Serves tiles back as base64 in paginated batches for the LLM to analyze
+
+Each tile is processed at **full resolution** — no downscaling — preserving text, UI elements, and fine detail across the entire image.
+
+See [sample of generated tiles here.](https://github.com/keiver/image-tiler-mcp-server/tree/main/assets/tiles/)
+
+### Supported Models
+
+| Model | Default tile | Tokens/tile | Max tile | ID |
+|-------|-------------|-------------|----------|-----|
+| Claude (default) | 1092px | 1590 | 1568px | `claude` |
+| OpenAI (GPT-4o/o-series) | 768px | 765 | 2048px | `openai` |
+| Gemini | 768px | 258 | 768px | `gemini` |
+| Gemini 3 | 1536px | 1120 | 3072px | `gemini3` |
+
+> **OpenAI note:** The `openai` config targets the GPT-4o / o-series vision pipeline (512px tile patches). GPT-4.1 uses a fundamentally different pipeline (32x32 pixel patches) and is not currently supported — it would require a separate model config with a different calculation approach.
+
+> **Gemini 3 note:** Gemini 3 uses a fixed token budget per image (1120 tokens regardless of dimensions). Tiling increases total token cost but preserves fine detail. For cases where detail isn't critical, consider sending a single image instead.
+
+## Tools
+
+### `tiler_tile_image`
+
+Splits a large image into tiles and saves them to disk.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `filePath` | string | yes | — | Absolute or relative path to the image file |
+| `model` | string | no | `"claude"` | Target vision model: `"claude"`, `"openai"`, `"gemini"`, `"gemini3"` |
+| `tileSize` | number | no | Model default | Tile size in pixels. Clamped to model min/max with a warning if out of bounds. |
+| `outputDir` | string | no | `tiles/{name}` subfolder next to source | Directory to save tiles |
+
+Returns JSON metadata with grid dimensions, tile count, model used, estimated token cost, and per-tile file paths.
+
+### `tiler_get_tiles`
+
+Returns tile images as base64 in batches of 5 for the LLM to see directly.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `tilesDir` | string | yes | — | Path to tiles directory (from `tiler_tile_image`) |
+| `start` | number | no | 0 | Start tile index (0-based, inclusive) |
+| `end` | number | no | start + 4 | End tile index (0-based, inclusive) |
+
+Returns text labels + image content blocks. Includes pagination hint for the next batch.
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add image-tiler -- npx -y image-tiler-mcp-server
+```
+
+> `image-tiler` is a local alias — you can name it anything you like. `image-tiler-mcp-server` is the npm package that gets downloaded and run.
+
+See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
+
+### Claude Desktop
+
+Add to your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "image-tiler": {
+      "command": "npx",
+      "args": ["-y", "image-tiler-mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+### VS Code (Cline / Continue)
+
+Add to your VS Code MCP settings:
+
+```json
+{
+  "image-tiler": {
+    "command": "npx",
+    "args": ["-y", "image-tiler-mcp-server"]
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "image-tiler": {
+      "command": "npx",
+      "args": ["-y", "image-tiler-mcp-server"]
+    }
+  }
+}
+```
+
+### Global Install (faster startup)
+
+```bash
+npm install -g image-tiler-mcp-server
+```
+
+Then use the simpler config in any client:
+
+```json
+{
+  "command": "image-tiler-mcp-server"
+}
+```
+
+### From Source
+
+```bash
+git clone https://github.com/keiver/image-tiler-mcp-server.git
+cd image-tiler-mcp-server
+npm install
+npm run build
+```
+
+Then point your MCP config to the built file:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/image-tiler-mcp-server/dist/index.js"]
+}
+```
+
+## Usage
+
+### In Claude Code
+
+```
+> Tile the screenshot at ./screenshots/full-page.png and analyze the layout
+
+Claude will:
+1. Call tiler_tile_image(filePath="./screenshots/full-page.png")
+2. See: "Tiled 3600x22810 image → 4x21 grid = 84 tiles"
+3. Call tiler_get_tiles(tilesDir="./screenshots/tiles/full-page", start=0, end=4)
+4. Analyze tiles 0-4, then continue with start=5...
+```
+
+### With Other Models
+
+```
+> Tile this image for GPT-4o analysis
+
+Claude will:
+1. Call tiler_tile_image(filePath="./image.png", model="openai")
+2. Tiles sized at 768px for OpenAI's vision pipeline
+```
+
+### Typical Workflow
+
+1. Capture full-page screenshot with your browser extension
+2. Ask Claude: _"Tile `/path/to/screencapture-localhost-3000.png` and review all sections"_
+3. Claude pages through tiles automatically, analyzing each batch
+
+## Tile Output Structure
+
+Example: `assets/landscape.png` (7680x4032) tiled with the default Claude config (1092px tiles) produces an 8x4 grid of 32 tiles (~50,880 tokens).
+
+**Grid layout** — tiles are numbered `tile_ROW_COL.png`, extracted left-to-right, top-to-bottom:
+
+```
+ 7680px
+┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬────────┐
+│ 000_000  │ 000_001  │ 000_002  │ 000_003  │ 000_004  │ 000_005  │ 000_006  │ 000_007│
+│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 36x1092│ 4032px
+├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼────────┤
+│ 001_000  │ 001_001  │ 001_002  │ 001_003  │ 001_004  │ 001_005  │ 001_006  │ 001_007│
+│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 36x1092│
+├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼────────┤
+│ 002_000  │ 002_001  │ 002_002  │ 002_003  │ 002_004  │ 002_005  │ 002_006  │ 002_007│
+│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 1092x1092│ 36x1092│
+├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼────────┤
+│ 003_000  │ 003_001  │ 003_002  │ 003_003  │ 003_004  │ 003_005  │ 003_006  │ 003_007│
+│ 1092x756 │ 1092x756 │ 1092x756 │ 1092x756 │ 1092x756 │ 1092x756 │ 1092x756 │ 36x756 │
+└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴────────┘
+```
+
+Edge tiles are smaller: the rightmost column is 36px wide (7680 - 7×1092 = 36), and the bottom row is 756px tall (4032 - 3×1092 = 756).
+
+**Output directory:**
+
+```
+assets/tiles/landscape/
+├── tile_000_000.png    # Row 0, Col 0 — 1092x1092
+├── tile_000_001.png    # Row 0, Col 1 — 1092x1092
+├── tile_000_002.png    # ...
+├── ...
+├── tile_000_007.png    # Row 0, Col 7 — 36x1092 (right edge)
+├── tile_001_000.png    # Row 1, Col 0
+├── ...
+├── tile_003_006.png    # Row 3, Col 6 — 1092x756 (bottom edge)
+└── tile_003_007.png    # Row 3, Col 7 — 36x756 (corner)
+```
+
+**JSON metadata** returned by `tiler_tile_image`:
+
+```json
+{
+  "model": "claude",
+  "sourceImage": {
+    "width": 7680,
+    "height": 4032,
+    "format": "png",
+    "fileSize": 12345678,
+    "channels": 4
+  },
+  "grid": {
+    "cols": 8,
+    "rows": 4,
+    "totalTiles": 32,
+    "tileSize": 1092,
+    "estimatedTokens": 50880
+  },
+  "outputDir": "/path/to/assets/tiles/landscape",
+  "tiles": [
+    { "index": 0, "row": 0, "col": 0, "position": "0,0", "dimensions": "1092×1092", "filePath": "/path/to/assets/tiles/landscape/tile_000_000.png" },
+    { "index": 1, "row": 0, "col": 1, "position": "1092,0", "dimensions": "1092×1092", "filePath": "/path/to/assets/tiles/landscape/tile_000_001.png" },
+    "... 30 more tiles"
+  ],
+  "previewPath": "/path/to/assets/tiles/landscape/preview.html"
+}
+```
+
+### Portrait example
+
+`assets/portrait.png` (3600x22810) tiled with Claude defaults produces a 4x21 grid of 84 tiles (~133,560 tokens).
+
+**Grid layout:**
+
+```
+ 3600px
+┌──────────┬──────────┬──────────┬─────────┐
+│ 000_000  │ 000_001  │ 000_002  │ 000_003 │
+│ 1092x1092│ 1092x1092│ 1092x1092│ 324x1092│
+├──────────┼──────────┼──────────┼─────────┤
+│ 001_000  │ 001_001  │ 001_002  │ 001_003 │
+│ 1092x1092│ 1092x1092│ 1092x1092│ 324x1092│ 22810px
+├──────────┼──────────┼──────────┼─────────┤
+│   ...    │   ...    │   ...    │   ...   │ (21 rows)
+├──────────┼──────────┼──────────┼─────────┤
+│ 020_000  │ 020_001  │ 020_002  │ 020_003 │
+│ 1092x970 │ 1092x970 │ 1092x970 │ 324x970 │
+└──────────┴──────────┴──────────┴─────────┘
+```
+
+Edge tiles: rightmost column is 324px wide (3600 - 3×1092 = 324), bottom row is 970px tall (22810 - 20×1092 = 970).
+
+## Token Cost Reference
+
+Costs vary by model. Formula: `tokens = totalTiles x tokensPerTile`
+
+### Claude (1092px tiles, 1590 tokens/tile)
+
+| Image Dimensions | Tiles | Estimated Tokens |
+|---|---|---|
+| 1440x3000 | 6 | ~9,540 |
+| 3600x5000 | 20 | ~31,800 |
+| 3600x22810 | 84 | ~133,560 |
+
+### OpenAI — GPT-4o/o-series (768px tiles, 765 tokens/tile)
+
+| Image Dimensions | Tiles | Estimated Tokens |
+|---|---|---|
+| 1440x3000 | 8 | ~6,120 |
+| 3600x5000 | 35 | ~26,775 |
+| 3600x22810 | 150 | ~114,750 |
+
+### Gemini (768px tiles, 258 tokens/tile)
+
+| Image Dimensions | Tiles | Estimated Tokens |
+|---|---|---|
+| 1440x3000 | 8 | ~2,064 |
+| 3600x5000 | 35 | ~9,030 |
+| 3600x22810 | 150 | ~38,700 |
+
+### Gemini 3 (1536px tiles, 1120 tokens/tile)
+
+| Image Dimensions | Tiles | Estimated Tokens |
+|---|---|---|
+| 1440x3000 | 2 | ~2,240 |
+| 3600x5000 | 12 | ~13,440 |
+| 3600x22810 | 45 | ~50,400 |
+
+> **Note:** Gemini 3 uses a fixed 1120 tokens per image regardless of dimensions. More tiles = more total tokens but better detail preservation.
+
+## Supported Formats
+
+PNG, JPEG, WebP, TIFF, GIF
+
+## Technical Details
+
+- **Image processing:** Sharp (libvips) — demand-driven pipeline, streams tiles without full decompression
+- **Memory usage:** ~350-400MB peak for 30MB+ PNGs
+- **Transport:** stdio (local, single-session)
+- **Tile naming:** `tile_ROW_COL.png` (zero-padded, e.g., `tile_000_003.png`)
+- **Grid order:** Left-to-right, top-to-bottom
+- **Batch limit:** 5 tiles per `tiler_get_tiles` call to stay within MCP response limits
+
+## Troubleshooting
+
+**"Command not found"** — Make sure Node.js 18+ is installed: `node --version`
+
+**"File not found"** — Use absolute paths. Relative paths resolve from the MCP server's working directory.
+
+**"MCP tools not available"** — Restart your MCP client after config changes. In Claude Code, run `/mcp` to check server status.
+
+## Security
+
+This is a **local MCP server** that runs on your machine via stdio. It operates with the same filesystem permissions as the MCP client process that spawns it. File paths provided to the tools are resolved and accessed directly — there is no sandboxing or path restriction beyond your OS-level permissions.
+
+This is by design: MCP tools run in the user's security context, same as any CLI tool. No network access, no remote connections, no data sent externally.
+
+## Requirements
+
+- Node.js 18+
+- Compatible MCP client (Claude Code, Claude Desktop, Cursor, VS Code with MCP extension)
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub Repository](https://github.com/keiver/image-tiler-mcp-server)
+- [NPM Package](https://www.npmjs.com/package/image-tiler-mcp-server)
+- [Report Issues](https://github.com/keiver/image-tiler-mcp-server/issues)

package/dist/constants.d.ts

@@ -0,0 +1,21 @@
+export declare const VISION_MODELS: readonly ["claude", "openai", "gemini", "gemini3"];
+export type VisionModel = (typeof VISION_MODELS)[number];
+export interface ModelVisionConfig {
+    defaultTileSize: number;
+    minTileSize: number;
+    maxTileSize: number;
+    tokensPerTile: number;
+    label: string;
+}
+export declare const MODEL_CONFIGS: Record<VisionModel, ModelVisionConfig>;
+export declare const DEFAULT_MODEL: VisionModel;
+export declare const DEFAULT_TILE_SIZE: number;
+export declare const MAX_TILE_SIZE: number;
+export declare const MIN_TILE_SIZE: number;
+export declare const TOKENS_PER_TILE: number;
+export declare const MAX_IMAGE_DIMENSION = 65536;
+export declare const MAX_TOTAL_TILES = 10000;
+export declare const MAX_TILES_PER_BATCH = 5;
+export declare const SUPPORTED_FORMATS: readonly ["png", "jpeg", "jpg", "webp", "tiff", "gif"];
+export declare const PNG_COMPRESSION_LEVEL = 6;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,oDAAqD,CAAC;AAChF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,WAAW,EAAE,iBAAiB,CA6BhE,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAAsB,CAAC;AAGnD,eAAO,MAAM,iBAAiB,QAAuC,CAAC;AACtE,eAAO,MAAM,aAAa,QAAmC,CAAC;AAC9D,eAAO,MAAM,aAAa,QAAmC,CAAC;AAC9D,eAAO,MAAM,eAAe,QAAqC,CAAC;AAElE,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AACzC,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,iBAAiB,wDAAyD,CAAC;AACxF,eAAO,MAAM,qBAAqB,IAAI,CAAC"}

package/dist/constants.js

@@ -0,0 +1,43 @@
+export const VISION_MODELS = ["claude", "openai", "gemini", "gemini3"];
+export const MODEL_CONFIGS = {
+    claude: {
+        defaultTileSize: 1092,
+        minTileSize: 256,
+        maxTileSize: 1568,
+        tokensPerTile: 1590,
+        label: "Claude",
+    },
+    openai: {
+        defaultTileSize: 768,
+        minTileSize: 256,
+        maxTileSize: 2048,
+        tokensPerTile: 765,
+        label: "OpenAI",
+    },
+    gemini: {
+        defaultTileSize: 768,
+        minTileSize: 256,
+        maxTileSize: 768,
+        tokensPerTile: 258,
+        label: "Gemini",
+    },
+    gemini3: {
+        defaultTileSize: 1536,
+        minTileSize: 384,
+        maxTileSize: 3072,
+        tokensPerTile: 1120,
+        label: "Gemini 3",
+    },
+};
+export const DEFAULT_MODEL = "claude";
+// Backward-compatible aliases (point to Claude config)
+export const DEFAULT_TILE_SIZE = MODEL_CONFIGS.claude.defaultTileSize;
+export const MAX_TILE_SIZE = MODEL_CONFIGS.claude.maxTileSize;
+export const MIN_TILE_SIZE = MODEL_CONFIGS.claude.minTileSize;
+export const TOKENS_PER_TILE = MODEL_CONFIGS.claude.tokensPerTile;
+export const MAX_IMAGE_DIMENSION = 65536;
+export const MAX_TOTAL_TILES = 10000;
+export const MAX_TILES_PER_BATCH = 5;
+export const SUPPORTED_FORMATS = ["png", "jpeg", "jpg", "webp", "tiff", "gif"];
+export const PNG_COMPRESSION_LEVEL = 6;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAWhF,MAAM,CAAC,MAAM,aAAa,GAA2C;IACnE,MAAM,EAAE;QACN,eAAe,EAAE,IAAI;QACrB,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,IAAI;QACnB,KAAK,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE;QACN,eAAe,EAAE,GAAG;QACpB,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,GAAG;QAClB,KAAK,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE;QACN,eAAe,EAAE,GAAG;QACpB,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,GAAG;QAChB,aAAa,EAAE,GAAG;QAClB,KAAK,EAAE,QAAQ;KAChB;IACD,OAAO,EAAE;QACP,eAAe,EAAE,IAAI;QACrB,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,IAAI;QACnB,KAAK,EAAE,UAAU;KAClB;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAgB,QAAQ,CAAC;AAEnD,uDAAuD;AACvD,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC,eAAe,CAAC;AACtE,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC;AAElE,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAU,CAAC;AACxF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTileImageTool } from "./tools/tile-image.js";
+import { registerGetTilesTool } from "./tools/get-tiles.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const server = new McpServer({
+    name: "image-tiler-mcp-server",
+    version,
+});
+registerTileImageTool(server);
+registerGetTilesTool(server);
+async function runStdio() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("image-tiler-mcp-server running on stdio");
+}
+async function shutdown() {
+    await server.close();
+    process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+runStdio().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,wBAAwB;IAC9B,OAAO;CACR,CAAC,CAAC;AAEH,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAE7B,KAAK,UAAU,QAAQ;IACrB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC3D,CAAC;AAED,KAAK,UAAU,QAAQ;IACrB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEhC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAClC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/schemas/index.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const TileImageInputSchema: {
+    filePath: z.ZodString;
+    model: z.ZodDefault<z.ZodEnum<["claude", "openai", "gemini", "gemini3"]>>;
+    tileSize: z.ZodOptional<z.ZodNumber>;
+    outputDir: z.ZodOptional<z.ZodString>;
+};
+export declare const GetTilesInputSchema: {
+    tilesDir: z.ZodString;
+    start: z.ZodDefault<z.ZodNumber>;
+    end: z.ZodOptional<z.ZodNumber>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB,eAAO,MAAM,oBAAoB;;;;;CA6BhC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;CAqB/B,CAAC"}

package/dist/schemas/index.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { MAX_IMAGE_DIMENSION, MAX_TILES_PER_BATCH, VISION_MODELS, DEFAULT_MODEL, MODEL_CONFIGS, } from "../constants.js";
+const modelDescriptions = VISION_MODELS.map((m) => `"${m}" (${MODEL_CONFIGS[m].defaultTileSize}px tiles, ~${MODEL_CONFIGS[m].tokensPerTile} tokens/tile)`).join(", ");
+const defaultDescriptions = VISION_MODELS.map((m) => `${MODEL_CONFIGS[m].label}: ${MODEL_CONFIGS[m].defaultTileSize}`).join(", ");
+export const TileImageInputSchema = {
+    filePath: z
+        .string()
+        .min(1, "File path cannot be empty")
+        .describe("Absolute or relative path to the image file to tile"),
+    model: z
+        .enum(VISION_MODELS)
+        .default(DEFAULT_MODEL)
+        .describe(`Target vision model: ${modelDescriptions}. Default: "${DEFAULT_MODEL}"`),
+    tileSize: z
+        .number()
+        .int()
+        .min(1, "Tile size must be a positive integer")
+        .max(MAX_IMAGE_DIMENSION, `Tile size must not exceed ${MAX_IMAGE_DIMENSION}px`)
+        .optional()
+        .describe(`Tile size in pixels. If omitted, uses the model's optimal default (${defaultDescriptions}). Values outside the model's supported range are automatically clamped with a warning.`),
+    outputDir: z
+        .string()
+        .optional()
+        .describe("Directory to save tiles. Defaults to a 'tiles' subfolder next to the source image"),
+};
+export const GetTilesInputSchema = {
+    tilesDir: z
+        .string()
+        .min(1, "Tiles directory path cannot be empty")
+        .describe("Path to the tiles directory (returned by tiler_tile_image as outputDir)"),
+    start: z
+        .number()
+        .int()
+        .min(0, "Start index must be >= 0")
+        .default(0)
+        .describe("Start tile index (0-based, inclusive)"),
+    end: z
+        .number()
+        .int()
+        .min(0, "End index must be >= 0")
+        .optional()
+        .describe(`End tile index (0-based, inclusive). Defaults to start + ${MAX_TILES_PER_BATCH - 1}. Max ${MAX_TILES_PER_BATCH} tiles per batch to stay within MCP response limits`),
+};
+//# sourceMappingURL=index.js.map

package/dist/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,MAAM,iBAAiB,GAAG,aAAa,CAAC,GAAG,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC,eAAe,cAAc,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,eAAe,CAC9G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,mBAAmB,GAAG,aAAa,CAAC,GAAG,CAC3C,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CACxE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,2BAA2B,CAAC;SACnC,QAAQ,CAAC,qDAAqD,CAAC;IAClE,KAAK,EAAE,CAAC;SACL,IAAI,CAAC,aAAa,CAAC;SACnB,OAAO,CAAC,aAAa,CAAC;SACtB,QAAQ,CACP,wBAAwB,iBAAiB,eAAe,aAAa,GAAG,CACzE;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,EAAE,sCAAsC,CAAC;SAC9C,GAAG,CACF,mBAAmB,EACnB,6BAA6B,mBAAmB,IAAI,CACrD;SACA,QAAQ,EAAE;SACV,QAAQ,CACP,sEAAsE,mBAAmB,yFAAyF,CACnL;IACH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,mFAAmF,CACpF;CACJ,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,sCAAsC,CAAC;SAC9C,QAAQ,CACP,yEAAyE,CAC1E;IACH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,EAAE,0BAA0B,CAAC;SAClC,OAAO,CAAC,CAAC,CAAC;SACV,QAAQ,CAAC,uCAAuC,CAAC;IACpD,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,EAAE,wBAAwB,CAAC;SAChC,QAAQ,EAAE;SACV,QAAQ,CACP,4DAA4D,mBAAmB,GAAG,CAAC,SAAS,mBAAmB,qDAAqD,CACrK;CACJ,CAAC"}

package/dist/services/image-processor.d.ts

@@ -0,0 +1,7 @@
+import type { ImageMetadata, TileGridInfo, TileImageResult } from "../types.js";
+export declare function getImageMetadata(filePath: string): Promise<ImageMetadata>;
+export declare function calculateGrid(width: number, height: number, tileSize: number, tokensPerTile?: number): TileGridInfo;
+export declare function tileImage(filePath: string, tileSize: number, outputDir: string, tokensPerTile?: number): Promise<TileImageResult>;
+export declare function readTileAsBase64(tilePath: string): Promise<string>;
+export declare function listTilesInDirectory(tilesDir: string): Promise<string[]>;
+//# sourceMappingURL=image-processor.d.ts.map

package/dist/services/image-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-processor.d.ts","sourceRoot":"","sources":["../../src/services/image-processor.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAY,eAAe,EAAE,MAAM,aAAa,CAAC;AAK1F,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,aAAa,GAAE,MAAwB,GACtC,YAAY,CAYd;AAED,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAwB,GACtC,OAAO,CAAC,eAAe,CAAC,CA4E1B;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxE;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB"}