snapforge-mcp 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# snapforge-mcp
+
+MCP server for [SnapForge](https://snapforge.org) — gives AI agents two tools:
+
+- **`snapforge_screenshot`** — capture a URL or HTML as PNG/JPEG (returned inline as an image)
+- **`snapforge_pdf`** — render a URL or HTML to a PDF (saved to a temp file, path returned)
+
+## Setup
+
+Get a free API key at <https://snapforge.org> (POST your email to `/signup`), then:
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "snapforge": {
+      "command": "npx",
+      "args": ["-y", "snapforge-mcp"],
+      "env": { "SNAPFORGE_API_KEY": "sf_your_key_here" }
+    }
+  }
+}
+```
+
+### Any MCP client
+
+```bash
+SNAPFORGE_API_KEY=sf_your_key npx -y snapforge-mcp
+```
+
+## Environment
+
+- `SNAPFORGE_API_KEY` (required) — your SnapForge API key
+- `SNAPFORGE_BASE_URL` (optional) — defaults to `https://snapforge.org`
+
+## Tool parameters
+
+Both tools accept `url` **or** `html`, plus `waitUntil` (`load`|`networkidle`) and `delay` (ms).
+- `snapforge_screenshot`: `fullPage`, `width`, `height`, `scale`, `format` (`png`|`jpeg`), `quality`
+- `snapforge_pdf`: `pageFormat` (`A4`, `Letter`, …), `landscape`, `printBackground`, `margin`
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,91 @@
+#!/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 { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const BASE = (process.env.SNAPFORGE_BASE_URL || 'https://snapforge.org').replace(/\/$/, '');
+const API_KEY = process.env.SNAPFORGE_API_KEY || '';
+
+// Call a SnapForge render endpoint and return the raw bytes + content type.
+async function render(endpoint, body) {
+  if (!API_KEY) {
+    throw new Error('Set the SNAPFORGE_API_KEY environment variable (get one at https://snapforge.org).');
+  }
+  const res = await fetch(`${BASE}${endpoint}`, {
+    method: 'POST',
+    headers: { 'x-api-key': API_KEY, 'content-type': 'application/json' },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    let detail = '';
+    try { detail = JSON.stringify(await res.json()); } catch { detail = await res.text().catch(() => ''); }
+    throw new Error(`SnapForge ${endpoint} failed (HTTP ${res.status}): ${detail}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  return { buf, contentType: res.headers.get('content-type') || 'application/octet-stream' };
+}
+
+const server = new McpServer({ name: 'snapforge', version: '1.0.0' });
+
+const common = {
+  url: z.string().url().optional().describe('Public http/https URL to render'),
+  html: z.string().optional().describe('Raw HTML to render instead of a URL (max 2MB)'),
+  waitUntil: z.enum(['load', 'networkidle']).optional().describe('When to consider the page ready'),
+  delay: z.number().int().min(0).max(10000).optional().describe('Extra wait in ms before capture')
+};
+
+server.registerTool(
+  'snapforge_screenshot',
+  {
+    title: 'SnapForge screenshot',
+    description: 'Capture a screenshot of a public URL or raw HTML and return it as an image (PNG/JPEG).',
+    inputSchema: {
+      ...common,
+      fullPage: z.boolean().optional().describe('Capture the full scrollable page'),
+      width: z.number().int().min(100).max(3840).optional(),
+      height: z.number().int().min(100).max(2160).optional(),
+      scale: z.number().int().min(1).max(3).optional().describe('Device pixel ratio (high-DPI)'),
+      format: z.enum(['png', 'jpeg']).optional(),
+      quality: z.number().int().min(1).max(100).optional().describe('JPEG quality')
+    }
+  },
+  async (args) => {
+    try {
+      const { buf, contentType } = await render('/v1/screenshot', args);
+      return { content: [{ type: 'image', data: buf.toString('base64'), mimeType: contentType }] };
+    } catch (e) {
+      return { isError: true, content: [{ type: 'text', text: String(e.message || e) }] };
+    }
+  }
+);
+
+server.registerTool(
+  'snapforge_pdf',
+  {
+    title: 'SnapForge PDF',
+    description: 'Render a public URL or raw HTML to a PDF. The PDF is written to a temp file and its path is returned.',
+    inputSchema: {
+      ...common,
+      pageFormat: z.enum(['Letter', 'Legal', 'Tabloid', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6']).optional(),
+      landscape: z.boolean().optional(),
+      printBackground: z.boolean().optional(),
+      margin: z.string().optional().describe('CSS size for all margins, e.g. "1cm"')
+    }
+  },
+  async (args) => {
+    try {
+      const { buf } = await render('/v1/pdf', args);
+      const file = path.join(tmpdir(), `snapforge-${Date.now()}.pdf`);
+      await writeFile(file, buf);
+      return { content: [{ type: 'text', text: `PDF saved to ${file} (${buf.length} bytes).` }] };
+    } catch (e) {
+      return { isError: true, content: [{ type: 'text', text: String(e.message || e) }] };
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "snapforge-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for SnapForge — screenshot & HTML-to-PDF API as agent tools",
+  "type": "module",
+  "bin": { "snapforge-mcp": "index.js" },
+  "files": ["index.js", "README.md"],
+  "keywords": ["mcp", "model-context-protocol", "screenshot", "pdf", "snapforge", "playwright"],
+  "homepage": "https://snapforge.org",
+  "repository": { "type": "git", "url": "git+https://github.com/sporty303/snapforge-mcp.git" },
+  "author": "Gerome Sportelli",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  }
+}