blip-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Krämer
+
+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,53 @@
+<p align="center">
+  <img src="logo.png" alt="Blip" width="200" />
+</p>
+
+<p align="center">
+  Visual annotation MCP server for Claude Code.<br>
+  Draw on your preview. Claude sees what you mean.
+</p>
+
+---
+
+## How it works
+
+1. Tell Claude: **"annotate"** (or **"annotate http://localhost:3000"**)
+2. A browser opens with drawing tools on your page
+3. Draw circles, arrows, highlights, text labels
+4. Click **Send to Claude** -- the annotated screenshot goes back to your chat
+5. Claude updates the code based on what you drew
+
+No more describing UI changes with words. Just draw on them.
+
+## Install
+
+```bash
+claude mcp add blip -- npx blip-mcp
+```
+
+That's it. Requires [Claude Code](https://claude.com/claude-code) and Node.js 18+.
+
+## Two modes
+
+**CLI (Terminal)** -- The `annotate` MCP tool opens your page in a browser with the overlay injected. Draw, hit send, the screenshot goes straight back to Claude.
+
+**Desktop (Claude Code app)** -- The overlay works with Claude Code's built-in preview. Click the pencil button to activate drawing, then press Ctrl+P to add the screenshot to chat.
+
+## Development
+
+```bash
+git clone https://github.com/nebenzu/Blip.git
+cd Blip
+npm install
+npm run build
+```
+
+```bash
+npm run dev     # Watch mode
+npm run serve   # Dev server on port 4460
+npm start       # Run MCP server directly
+```
+
+## License
+
+MIT

package/dist/annotation-server.d.ts

@@ -0,0 +1,7 @@
+export interface AnnotationResult {
+    imagePath: string;
+}
+export declare function startAnnotationServer(port?: number): Promise<number>;
+export declare function waitForAnnotation(): Promise<AnnotationResult>;
+export declare function getServerPort(): number;
+export declare function stopAnnotationServer(): void;

package/dist/annotation-server.js

@@ -0,0 +1,230 @@
+import express from 'express';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { exec } from 'node:child_process';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = resolve(__dirname, '..');
+const PUBLIC_DIR = join(PROJECT_ROOT, 'public');
+const SCREENSHOTS_DIR = join(PROJECT_ROOT, 'screenshots');
+const LANDING_DIR = join(PROJECT_ROOT, 'landing');
+let pendingResolve = null;
+let server = null;
+let serverPort = 0;
+let proxyTarget = null;
+export async function startAnnotationServer(port = 4461) {
+    if (server)
+        return serverPort;
+    await mkdir(SCREENSHOTS_DIR, { recursive: true });
+    const app = express();
+    // Serve landing page at root
+    app.get('/', (_req, res) => {
+        const landingIndex = join(LANDING_DIR, 'index.html');
+        if (existsSync(landingIndex)) {
+            res.sendFile(landingIndex);
+        }
+        else {
+            res.redirect('/annotate');
+        }
+    });
+    // Serve landing page static files
+    app.use('/landing', express.static(LANDING_DIR));
+    // Proxy route: fetch any URL and inject the overlay script
+    app.get('/proxy', async (req, res) => {
+        const targetUrl = req.query.url;
+        if (!targetUrl) {
+            res.status(400).send('Missing ?url= parameter');
+            return;
+        }
+        try {
+            // Store target origin for catch-all proxy
+            const parsedTarget = new URL(targetUrl);
+            proxyTarget = parsedTarget.origin;
+            const response = await fetch(targetUrl);
+            let html = await response.text();
+            const contentType = response.headers.get('content-type') || 'text/html';
+            if (contentType.includes('text/html')) {
+                // Inject overlay script before </body> (use absolute URL to avoid <base> tag redirect)
+                const overlayScript = `<script src="http://localhost:${serverPort}/overlay.js?v=${Date.now()}"></script>`;
+                if (html.includes('</body>')) {
+                    html = html.replace('</body>', `${overlayScript}\n</body>`);
+                }
+                else {
+                    html += overlayScript;
+                }
+                // Add <base> so the app's own assets and API calls resolve to the target origin
+                const url = new URL(targetUrl);
+                const base = `<base href="${url.origin}/">`;
+                if (html.includes('<head>')) {
+                    html = html.replace('<head>', `<head>\n${base}`);
+                }
+                else if (html.includes('<html')) {
+                    html = html.replace(/<html[^>]*>/, `$&\n<head>${base}</head>`);
+                }
+            }
+            res.type('text/html').send(html);
+        }
+        catch (err) {
+            res.status(500).send(`Failed to fetch ${targetUrl}`);
+        }
+    });
+    // Annotation app at /annotate
+    app.get('/annotate', (_req, res) => {
+        res.sendFile(join(PUBLIC_DIR, 'index.html'));
+    });
+    // Static files for annotation app
+    app.use(express.static(PUBLIC_DIR, { etag: false, lastModified: false, maxAge: 0 }));
+    // Serve an image by path (restricted to screenshots directory)
+    app.get('/api/image', (req, res) => {
+        const imgPath = req.query.path;
+        if (!imgPath)
+            return res.status(400).json({ error: 'No path provided' });
+        const resolved = resolve(imgPath);
+        if (!resolved.startsWith(SCREENSHOTS_DIR)) {
+            return res.status(403).json({ error: 'Access denied' });
+        }
+        if (!existsSync(resolved))
+            return res.status(404).json({ error: 'Image not found' });
+        res.sendFile(resolved);
+    });
+    // Save annotated image
+    app.post('/api/save', async (req, res) => {
+        try {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            await new Promise((resolve) => req.on('end', resolve));
+            const body = Buffer.concat(chunks);
+            const boundary = req.headers['content-type']?.split('boundary=')[1];
+            let imageBuffer;
+            if (boundary) {
+                const bodyStr = body.toString('latin1');
+                const parts = bodyStr.split('--' + boundary);
+                const imagePart = parts.find(p => p.includes('filename='));
+                if (!imagePart) {
+                    res.status(400).json({ error: 'No image in request' });
+                    return;
+                }
+                const headerEnd = imagePart.indexOf('\r\n\r\n');
+                const dataStart = headerEnd + 4;
+                const dataEnd = imagePart.lastIndexOf('\r\n');
+                imageBuffer = Buffer.from(imagePart.slice(dataStart, dataEnd), 'latin1');
+            }
+            else {
+                imageBuffer = body;
+            }
+            const filename = `annotated-${Date.now()}.png`;
+            const filepath = join(SCREENSHOTS_DIR, filename);
+            await writeFile(filepath, imageBuffer);
+            if (pendingResolve) {
+                pendingResolve({ imagePath: filepath });
+                pendingResolve = null;
+            }
+            res.json({ success: true, path: filepath });
+        }
+        catch (err) {
+            // Save error
+            res.status(500).json({ error: 'Failed to save' });
+        }
+    });
+    // Save annotated image from base64 JSON
+    app.post('/api/save-base64', express.json({ limit: '50mb' }), async (req, res) => {
+        try {
+            const { image, ...metadata } = req.body;
+            if (!image) {
+                res.status(400).json({ error: 'No image data' });
+                return;
+            }
+            const imageBuffer = Buffer.from(image, 'base64');
+            const filename = `annotated-${Date.now()}.png`;
+            const filepath = join(SCREENSHOTS_DIR, filename);
+            await writeFile(filepath, imageBuffer);
+            // Write all metadata alongside
+            const metaPath = filepath.replace('.png', '.json');
+            await writeFile(metaPath, JSON.stringify({
+                ...metadata,
+                timestamp: new Date().toISOString()
+            }, null, 2));
+            // Copy image to clipboard on macOS so user can Cmd+V in chat
+            if (process.platform === 'darwin') {
+                const safePath = filepath.replace(/'/g, "'\\''");
+                exec(`osascript -e 'set the clipboard to (read (POSIX file "${safePath}") as «class PNGf»)'`, (err) => {
+                    if (err)
+                        console.error('Clipboard copy failed:', err);
+                });
+            }
+            if (pendingResolve) {
+                pendingResolve({ imagePath: filepath });
+                pendingResolve = null;
+            }
+            res.json({ success: true, path: filepath });
+        }
+        catch (err) {
+            // Save error
+            res.status(500).json({ error: 'Failed to save' });
+        }
+    });
+    // Catch-all: proxy unknown requests to the target server
+    app.use(async (req, res) => {
+        if (!proxyTarget) {
+            res.status(404).send('Not found');
+            return;
+        }
+        try {
+            const targetUrl = `${proxyTarget}${req.originalUrl}`;
+            const headers = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (typeof value === 'string' && key !== 'host')
+                    headers[key] = value;
+            }
+            const fetchRes = await fetch(targetUrl, {
+                method: req.method,
+                headers,
+                body: ['GET', 'HEAD'].includes(req.method) ? undefined : req.body,
+            });
+            res.status(fetchRes.status);
+            fetchRes.headers.forEach((value, key) => {
+                if (!['transfer-encoding', 'content-encoding', 'connection'].includes(key.toLowerCase())) {
+                    res.setHeader(key, value);
+                }
+            });
+            const buffer = Buffer.from(await fetchRes.arrayBuffer());
+            res.send(buffer);
+        }
+        catch {
+            res.status(502).send('Proxy error');
+        }
+    });
+    return new Promise((resolve) => {
+        server = createServer(app);
+        server.listen(port, () => {
+            serverPort = port;
+            resolve(port);
+        });
+        server.on('error', () => {
+            server = createServer(app);
+            server.listen(0, () => {
+                const addr = server.address();
+                serverPort = typeof addr === 'object' && addr ? addr.port : port;
+                resolve(serverPort);
+            });
+        });
+    });
+}
+export function waitForAnnotation() {
+    return new Promise((resolve) => {
+        pendingResolve = resolve;
+    });
+}
+export function getServerPort() {
+    return serverPort;
+}
+export function stopAnnotationServer() {
+    if (server) {
+        server.close();
+        server = null;
+        serverPort = 0;
+    }
+}

package/dist/dev-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dev-server.js

@@ -0,0 +1,10 @@
+// Standalone dev server for previewing the annotation UI
+import { startAnnotationServer } from './annotation-server.js';
+const port = parseInt(process.argv[2] || '4460');
+startAnnotationServer(port).then((actualPort) => {
+    console.log(`Blip server running at http://localhost:${actualPort}`);
+    console.log(`  Annotation editor: http://localhost:${actualPort}/annotate`);
+}).catch((err) => {
+    console.error('Failed to start server:', err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { startAnnotationServer, waitForAnnotation } from './annotation-server.js';
+import { exec } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = import.meta.dirname ?? join(__filename, '..');
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' :
+        process.platform === 'win32' ? 'start' : 'xdg-open';
+    const child = exec(`${cmd} "${url}"`);
+    // Prevent child process output from corrupting MCP stdio transport
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+}
+// Read image + metadata, return MCP content array with inline image
+async function buildAnnotationResponse(imagePath, extra = {}) {
+    const imageData = await readFile(imagePath);
+    const base64 = imageData.toString('base64');
+    let metadata = {};
+    const metaPath = imagePath.replace('.png', '.json');
+    try {
+        if (existsSync(metaPath)) {
+            metadata = JSON.parse(await readFile(metaPath, 'utf-8'));
+        }
+    }
+    catch { }
+    return {
+        content: [
+            {
+                type: 'image',
+                data: base64,
+                mimeType: 'image/png',
+            },
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    annotated_image_path: imagePath,
+                    metadata,
+                    ...extra,
+                }),
+            },
+        ],
+    };
+}
+const server = new McpServer({
+    name: 'blip',
+    version: '0.1.0',
+});
+// Single tool: annotate a live page or open the standalone editor
+server.tool('annotate', 'Open a visual annotation editor. The user can draw circles, arrows, highlights, and text on a screenshot. Returns the annotated image directly.', {
+    url: z.string().optional().describe('URL of a live page to annotate (e.g., http://localhost:3000). If omitted, opens the standalone editor where you can paste or drop a screenshot.'),
+}, async ({ url: targetUrl }) => {
+    const port = await startAnnotationServer();
+    let browserUrl;
+    if (targetUrl) {
+        // Proxy mode: inject overlay on the live page
+        browserUrl = `http://localhost:${port}/proxy?url=${encodeURIComponent(targetUrl)}`;
+    }
+    else {
+        // Standalone editor mode
+        browserUrl = `http://localhost:${port}/annotate`;
+    }
+    openBrowser(browserUrl);
+    const result = await waitForAnnotation();
+    return buildAnnotationResponse(result.imagePath, targetUrl ? { source_url: targetUrl } : {});
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "blip-mcp",
+  "version": "0.1.0",
+  "description": "Visual annotation MCP server for Claude Code - draw on preview screenshots to communicate UI changes",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "blip": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "serve": "node dist/dev-server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "blip",
+    "claude",
+    "claude-code",
+    "annotation",
+    "screenshot",
+    "visual-feedback",
+    "model-context-protocol",
+    "ai-coding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nebenzu/Blip"
+  },
+  "files": [
+    "dist",
+    "public",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.2",
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}