framefetch-mcp 0.2.0

package/README.md

@@ -0,0 +1,13 @@
+# framefetch-mcp
+
+Local **stdio MCP bridge** for [FrameFetch](https://framefetch.net) — any social-video URL → metadata, insights, Whisper transcript, and parametric frames across YouTube/Shorts, TikTok, Reddit, Instagram, Pinterest.
+
+```bash
+npx framefetch-mcp
+```
+
+```json
+{ "mcpServers": { "framefetch": { "command": "npx", "args": ["-y", "framefetch-mcp"], "env": { "FRAMEFETCH_API_KEY": "<key>" } } } }
+```
+
+`tools/list` works with no key; tool calls use `FRAMEFETCH_API_KEY` (or x402). Override with `FRAMEFETCH_MCP_URL`. Proxies to `framefetch.net/mcp`. Full client: [framefetch-client](https://github.com/MarvinRey7879/framefetch-client).

package/mcp-tools.json

@@ -0,0 +1,92 @@
+[
+  {
+    "name": "framefetch_extract",
+    "description": "Extract structured data from ONE public social-video URL (YouTube incl. Shorts, TikTok, Instagram Reels, Pinterest, Reddit). Purpose: turn a video link into metadata (title, author, duration, date), insights (views/likes/comments), a transcript (captions, or Whisper when there are none — works on TikTok/Reddit too), and/or parametrically-sampled video frames. When to use: you have a video URL and need its text, stats, or frames for analysis, summarization, or grounding a model. When NOT to use: non-video pages, private/login-walled content, or bulk crawling (one URL per call). Returns: one JSON object containing only the requested fields plus a `cost` block (micro-USD). Frames come back as time-limited signed image URLs. Cost/latency: metadata is sub-cent and fast; transcript is billed per audio-minute and frames per frame (both also incur bandwidth) — request only the fields you need and downscale frames via `width` to control cost. Billing: a free tier covers light use; agents can also pay per call with x402 (USDC) with no account. Example: { \"url\": \"https://www.youtube.com/watch?v=...\", \"fields\": [\"metadata\",\"transcript\"], \"frames\": { \"mode\": \"fps\", \"fps\": 1, \"width\": 480 } }",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "Public video URL from a supported platform."
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "metadata",
+              "insights",
+              "transcript",
+              "frames"
+            ]
+          },
+          "description": "Which data to return. Default [\"metadata\"]. Request the minimum you need."
+        },
+        "frames": {
+          "type": "object",
+          "description": "Frame-sampling spec; required when \"frames\" is requested.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "all",
+                "every_n",
+                "fps",
+                "range"
+              ]
+            },
+            "n": {
+              "type": "number",
+              "description": "every_n: take every Nth source frame"
+            },
+            "fps": {
+              "type": "number",
+              "description": "fps/range: frames per second (max 60)"
+            },
+            "from": {
+              "type": "number",
+              "description": "range: start second"
+            },
+            "to": {
+              "type": "number",
+              "description": "range: end second"
+            },
+            "format": {
+              "type": "string",
+              "enum": [
+                "jpg",
+                "png",
+                "webp"
+              ]
+            },
+            "width": {
+              "type": "number",
+              "description": "downscale width in px (16–7680)"
+            }
+          },
+          "required": [
+            "mode"
+          ]
+        },
+        "verbosity": {
+          "type": "string",
+          "enum": [
+            "concise",
+            "detailed"
+          ]
+        }
+      },
+      "required": [
+        "url"
+      ]
+    }
+  },
+  {
+    "name": "framefetch_platform_capabilities",
+    "description": "Return a JSON matrix of which data types (metadata, insights, transcript, frames) each supported platform provides — YouTube, YouTube Shorts, TikTok, Instagram Reels, Pinterest, Reddit. Purpose: check what is available for a platform BEFORE calling framefetch_extract, so you only request supported fields. No input required.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+]

package/mcp.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// framefetch — zero-dependency stdio MCP bridge.
+// Proxies Model Context Protocol calls to the hosted FrameFetch MCP server.
+// tools/list is served from an embedded snapshot (mcp-tools.json) so introspection
+// always succeeds, even before the first network round-trip; tool calls are
+// forwarded to the remote endpoint.
+//
+// Env:
+//   FRAMEFETCH_MCP_URL   override the remote MCP endpoint (default https://framefetch.net/mcp)
+//   FRAMEFETCH_API_KEY   optional bearer key for authenticated (non-x402) calls
+import { stdin, stdout, env, exit } from "node:process";
+import { readFileSync } from "node:fs";
+
+const REMOTE = env.FRAMEFETCH_MCP_URL || "https://framefetch.net/mcp";
+const API_KEY = env.FRAMEFETCH_API_KEY || "";
+const PROTOCOL = "2025-06-18";
+const SERVER_INFO = { name: "framefetch", version: "1.0.0" };
+
+let STATIC_TOOLS = [];
+try {
+  STATIC_TOOLS = JSON.parse(readFileSync(new URL("./mcp-tools.json", import.meta.url), "utf8"));
+} catch { /* snapshot optional; remote tools/list still works */ }
+
+stdout.on("error", () => {}); // ignore EPIPE if the client closes the pipe early
+
+function send(msg) {
+  stdout.write(JSON.stringify(msg) + "\n");
+}
+
+// Remote may answer with plain JSON or an SSE frame ("event: message\ndata: {...}").
+function parseRpc(text) {
+  const s = text.trim();
+  if (s.startsWith("{")) {
+    try { return JSON.parse(s); } catch { /* fall through to SSE parse */ }
+  }
+  for (const line of s.split(/\r?\n/)) {
+    const m = line.match(/^data:\s*(.*)$/);
+    if (m) {
+      try { return JSON.parse(m[1]); } catch { /* ignore non-JSON data lines */ }
+    }
+  }
+  return null;
+}
+
+async function remoteRpc(method, params) {
+  const res = await fetch(REMOTE, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "accept": "application/json, text/event-stream",
+      ...(API_KEY ? { authorization: `Bearer ${API_KEY}` } : {}),
+    },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+  });
+  const j = parseRpc(await res.text());
+  if (!j) throw new Error("invalid response from remote MCP");
+  if (j.error) throw new Error(j.error.message || "remote MCP error");
+  return j.result;
+}
+
+async function listTools() {
+  try {
+    const r = await remoteRpc("tools/list", {});
+    if (r && Array.isArray(r.tools) && r.tools.length) return r.tools;
+  } catch { /* remote unreachable — fall back to embedded snapshot */ }
+  return STATIC_TOOLS;
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize")
+    return send({ jsonrpc: "2.0", id, result: { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: SERVER_INFO } });
+  if (method === "ping")
+    return send({ jsonrpc: "2.0", id, result: {} });
+  if (typeof method === "string" && method.startsWith("notifications/"))
+    return; // notifications carry no id and need no reply
+  if (method === "tools/list")
+    return send({ jsonrpc: "2.0", id, result: { tools: await listTools() } });
+  if (method === "tools/call") {
+    try {
+      return send({ jsonrpc: "2.0", id, result: await remoteRpc("tools/call", params) });
+    } catch (e) {
+      return send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true } });
+    }
+  }
+  if (id !== undefined)
+    return send({ jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } });
+}
+
+let buf = "";
+let pending = 0;
+let ended = false;
+const tryExit = () => { if (ended && pending === 0) setImmediate(() => exit(0)); };
+stdin.setEncoding("utf8");
+stdin.on("data", (chunk) => {
+  buf += chunk;
+  let i;
+  while ((i = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, i).trim();
+    buf = buf.slice(i + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    pending++;
+    Promise.resolve(handle(msg)).catch(() => {}).finally(() => { pending--; tryExit(); });
+  }
+});
+// Exit only once stdin is closed AND every in-flight response has been flushed.
+stdin.on("end", () => { ended = true; tryExit(); });

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "framefetch-mcp",
+  "version": "0.2.0",
+  "description": "Local stdio MCP bridge for FrameFetch — any social-video URL to metadata, transcript, insights & parametric frames across YouTube/Shorts, TikTok, Reddit, Instagram, Pinterest. Proxies to the hosted FrameFetch MCP server.",
+  "type": "module",
+  "bin": { "framefetch-mcp": "mcp.js" },
+  "files": ["mcp.js", "mcp-tools.json", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["framefetch", "mcp", "video", "transcript", "youtube", "tiktok", "ai-agent", "stdio", "x402", "whisper"],
+  "homepage": "https://framefetch.net",
+  "repository": { "type": "git", "url": "git+https://github.com/MarvinRey7879/framefetch-client.git" },
+  "license": "MIT",
+  "author": "FrameFetch"
+}