mcp-gif 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# mcp-gif
+
+MCP server for GIF animation analysis. Provides metadata extraction, individual frame export, and per-frame timing information.
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add -s user gif npx mcp-gif
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gif": {
+      "command": "npx",
+      "args": ["mcp-gif"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `gif_info`
+
+Get GIF metadata: dimensions, frame count, delays, loop count, and average FPS.
+
+**Input**: `path` — path to a GIF file
+
+**Output**:
+```json
+{
+  "width": 320,
+  "height": 240,
+  "frames": 12,
+  "delays": [100, 100, 100],
+  "loop": 0,
+  "avgFps": 10
+}
+```
+
+### `gif_frame`
+
+Extract a single frame as a PNG image.
+
+**Input**: `path` — path to a GIF file, `frame` — 0-based frame index
+
+**Output**: PNG image (base64)
+
+### `gif_frames_list`
+
+List all frames with their index, delay (ms), and FPS.
+
+**Input**: `path` — path to a GIF file
+
+**Output**:
+```json
+[
+  { "index": 0, "delay": 100, "fps": 10 },
+  { "index": 1, "delay": 200, "fps": 5 }
+]
+```
+
+## License
+
+BSD-2-Clause

package/build/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import sharp from "sharp";
+import { z } from "zod";
+const server = new McpServer({
+    name: "mcp-gif",
+    version: "1.0.0",
+});
+server.tool("gif_info", "Get metadata of a GIF file: dimensions, frame count, delays, loop count, and average FPS", { path: z.string().describe("Path to the GIF file") }, async ({ path }) => {
+    const metadata = await sharp(path, { animated: true }).metadata();
+    const width = metadata.width ?? 0;
+    const height = metadata.pageHeight ?? metadata.height ?? 0;
+    const frames = metadata.pages ?? 1;
+    const delays = metadata.delay ?? [];
+    const loop = metadata.loop ?? 0;
+    const avgDelay = delays.length > 0
+        ? delays.reduce((a, b) => a + b, 0) / delays.length
+        : 100;
+    const avgFps = avgDelay > 0 ? Math.round((1000 / avgDelay) * 100) / 100 : 0;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ width, height, frames, delays, loop, avgFps }, null, 2),
+            },
+        ],
+    };
+});
+server.tool("gif_frame", "Extract a single frame from a GIF as a PNG image", {
+    path: z.string().describe("Path to the GIF file"),
+    frame: z.number().int().min(0).describe("Frame index (0-based)"),
+}, async ({ path, frame }) => {
+    const metadata = await sharp(path, { animated: true }).metadata();
+    const totalFrames = metadata.pages ?? 1;
+    if (frame >= totalFrames) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: frame index ${frame} out of range (0-${totalFrames - 1})`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const buffer = await sharp(path, { page: frame }).png().toBuffer();
+    return {
+        content: [
+            {
+                type: "image",
+                data: buffer.toString("base64"),
+                mimeType: "image/png",
+            },
+        ],
+    };
+});
+server.tool("gif_frames_list", "List all frames of a GIF with their index, delay (ms), and FPS", { path: z.string().describe("Path to the GIF file") }, async ({ path }) => {
+    const metadata = await sharp(path, { animated: true }).metadata();
+    const frames = metadata.pages ?? 1;
+    const delays = metadata.delay ?? [];
+    const list = Array.from({ length: frames }, (_, i) => {
+        const delay = delays[i] ?? 100;
+        const fps = delay > 0 ? Math.round((1000 / delay) * 100) / 100 : 0;
+        return { index: i, delay, fps };
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(list, null, 2),
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "mcp-gif",
+  "version": "1.0.0",
+  "description": "MCP server for GIF animation analysis — metadata, frame extraction, and frame listing",
+  "type": "module",
+  "bin": {
+    "mcp-gif": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node build/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "gif",
+    "animation",
+    "sharp",
+    "model-context-protocol"
+  ],
+  "license": "BSD-2-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signal-slot/mcp-gif.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "sharp": "^0.33.5",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}