codepen-mcp 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# CodePen MCP
+
+An [MCP](https://modelcontextprotocol.io) server that gives Cursor (and other MCP clients) tools to **ingest and inspect** CodePen pens: metadata, full source (HTML/CSS/JS), and embed snippet.
+
+## What’s available
+
+CodePen has **no public REST/GraphQL API** for reading pen data. This server uses:
+
+- **oEmbed (official)** – `https://codepen.io/api/oembed?format=json&url=...` for title, author, thumbnail, and embed iframe. Stable and supported by CodePen.
+- **Pen page parsing (best-effort)** – Fetches the public pen page and extracts the embedded `__item` JSON to get full source (HTML, CSS, JS), tags, resources, and preprocessors. This can break if CodePen changes their front-end.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_pen_metadata` | Fetch metadata via oEmbed: title, author, thumbnail, embed HTML. No source code. |
+| `get_pen` | Fetch full pen (source + metadata) by parsing the pen page. Use for ingest/inspect/understand. |
+| `get_pen_embed_html` | Get the iframe embed HTML via oEmbed, with optional height. |
+
+## Setup
+
+### Install and build
+
+```bash
+npm install
+npm run build
+```
+
+### Run the server (stdio)
+
+The server uses stdio transport so Cursor can spawn it as a subprocess:
+
+```bash
+node dist/index.js
+```
+
+### Configure Cursor
+
+Add the CodePen MCP server in Cursor (e.g. **Settings → MCP** or your MCP config file). Example:
+
+```json
+{
+  "mcpServers": {
+    "codepen": {
+      "command": "node",
+      "args": ["/absolute/path/to/codepen-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Use the path to your cloned repo (e.g. `/Users/you/Projects/codepen-mcp/dist/index.js`).
+
+## Optional: Agent Skill
+
+The repo includes a Cursor Agent Skill at [.cursor/skills/codepen-ingest/](.cursor/skills/codepen-ingest/) that tells the agent when and how to use the CodePen tools (e.g. when the user pastes a pen URL). It’s scoped to this project; you can copy it to `~/.cursor/skills/` for use in all projects.
+
+## Example pen
+
+Example used for design and testing: [Responsive Sidenotes V2](https://codepen.io/johndjameson/pen/DwxMqa) (`johndjameson/pen/DwxMqa`).
+
+## Limitations
+
+- **Full source** depends on parsing the public pen page; no official API. If CodePen changes their HTML/JS, `get_pen` may need updates.
+- **oEmbed and pen page** may return 403 or be rate-limited in some environments (e.g. strict Cloudflare or automated networks). In normal browser-like or Cursor usage they usually work.
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/pen-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Normalize a CodePen URL or slug to a full pen URL.
+ * Accepts: full URL, or "username/pen/slug" or "username/pen/slug/"
+ */
+export declare function normalizePenUrl(input: string): string;
+export interface OEmbedResult {
+    success: boolean;
+    type: string;
+    version: string;
+    provider_name: string;
+    provider_url: string;
+    title: string;
+    author_name: string;
+    author_url: string;
+    height: string;
+    width: string;
+    thumbnail_url?: string;
+    thumbnail_width?: string;
+    thumbnail_height?: string;
+    html: string;
+}
+/**
+ * Fetch pen metadata from CodePen oEmbed API (official, stable).
+ */
+export declare function fetchPenMetadata(penUrl: string, options?: {
+    height?: number;
+}): Promise<OEmbedResult>;
+/** Normalized pen data extracted from the pen page (best-effort scraping). */
+export interface NormalizedPen {
+    title: string;
+    description: string;
+    html: string;
+    css: string;
+    js: string;
+    tags: string[];
+    resources: Array<{
+        url: string;
+        type: string;
+        order: number;
+    }>;
+    html_pre_processor: string;
+    css_pre_processor: string;
+    js_pre_processor: string;
+    author?: {
+        username: string;
+        name: string;
+        url: string;
+    };
+    pen_url: string;
+    hashid: string;
+}
+/**
+ * Fetch the pen page and extract full source from embedded __item (best-effort).
+ * May break if CodePen changes their front-end.
+ */
+export declare function fetchPen(penUrl: string): Promise<NormalizedPen>;

package/dist/pen-utils.js

@@ -0,0 +1,148 @@
+/**
+ * Normalize a CodePen URL or slug to a full pen URL.
+ * Accepts: full URL, or "username/pen/slug" or "username/pen/slug/"
+ */
+export function normalizePenUrl(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith("https://codepen.io/")) {
+        try {
+            const u = new URL(trimmed);
+            const path = u.pathname.replace(/\/$/, "");
+            const match = path.match(/^\/([^/]+)\/pen\/([^/]+)/);
+            if (match)
+                return `https://codepen.io/${match[1]}/pen/${match[2]}`;
+        }
+        catch {
+            // fall through
+        }
+    }
+    if (trimmed.includes("/pen/")) {
+        const withoutLeadingSlash = trimmed.replace(/^\//, "");
+        if (/^[^/]+\/pen\/[^/]+/.test(withoutLeadingSlash)) {
+            return `https://codepen.io/${withoutLeadingSlash.replace(/\/$/, "")}`;
+        }
+    }
+    throw new Error(`Invalid CodePen URL or slug: ${input}. Expected format: https://codepen.io/username/pen/slug or username/pen/slug`);
+}
+const OEMBED_BASE = "https://codepen.io/api/oembed";
+/**
+ * Fetch pen metadata from CodePen oEmbed API (official, stable).
+ */
+export async function fetchPenMetadata(penUrl, options) {
+    const url = new URL(OEMBED_BASE);
+    url.searchParams.set("format", "json");
+    url.searchParams.set("url", penUrl);
+    if (options?.height != null) {
+        url.searchParams.set("height", String(options.height));
+    }
+    const res = await fetch(url.toString(), {
+        headers: { Accept: "application/json" },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`oEmbed request failed (${res.status}): ${text || res.statusText}`);
+    }
+    const data = (await res.json());
+    if (!data.success) {
+        throw new Error("CodePen oEmbed returned success: false");
+    }
+    return data;
+}
+/**
+ * Unescape a JSON string value (content only, no surrounding quotes).
+ * Handles \\, \", \n, \r, \t per JSON spec. Order matters: \\ first.
+ */
+function unescapeJsonString(s) {
+    return s
+        .replace(/\\\\/g, "\\")
+        .replace(/\\"/g, '"')
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t");
+}
+/**
+ * Extract the __item JSON string from the pen page HTML.
+ * The page embeds a script with a global object containing "__item":"{\"key\":...}".
+ */
+function extractItemJson(html) {
+    // Match "__item":"..." where the value is a JSON string (escaped quotes and backslashes inside).
+    const match = html.match(/"__item"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+    if (match) {
+        return unescapeJsonString(match[1]);
+    }
+    throw new Error("Could not find __item in pen page. CodePen may have changed their page structure.");
+}
+/**
+ * Fetch the pen page and extract full source from embedded __item (best-effort).
+ * May break if CodePen changes their front-end.
+ */
+export async function fetchPen(penUrl) {
+    const url = normalizePenUrl(penUrl);
+    const res = await fetch(url, {
+        headers: {
+            "User-Agent": "CodePen-MCP/1.0 (ingest tool)",
+            Accept: "text/html",
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch pen page (${res.status}): ${res.statusText}`);
+    }
+    const html = await res.text();
+    const itemJson = extractItemJson(html);
+    let item;
+    try {
+        item = JSON.parse(itemJson);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse pen __item JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!item || typeof item !== "object") {
+        throw new Error("Pen __item is not an object");
+    }
+    // Optional: extract __profiled for author (username, name). It may be in the same blob.
+    let author;
+    const profiledMatch = html.match(/"__profiled"\s*:\s*(\{[^}]+\})/);
+    if (profiledMatch) {
+        try {
+            const profiled = JSON.parse(profiledMatch[1]);
+            if (profiled?.username) {
+                author = {
+                    username: profiled.username,
+                    name: profiled.name ?? profiled.username,
+                    url: `https://codepen.io/${profiled.username}`,
+                };
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    const slug = url.match(/\/([^/]+)\/pen\/([^/]+)/);
+    const username = slug ? slug[1] : "";
+    if (!author && username) {
+        author = {
+            username,
+            name: username,
+            url: `https://codepen.io/${username}`,
+        };
+    }
+    return {
+        title: item.title ?? "Untitled",
+        description: item.description ?? "",
+        html: item.html ?? "",
+        css: item.css ?? "",
+        js: item.js ?? "",
+        tags: Array.isArray(item.tags) ? item.tags : [],
+        resources: (item.resources ?? []).map((r) => ({
+            url: r.url ?? "",
+            type: r.resource_type ?? "js",
+            order: typeof r.order === "number" ? r.order : 0,
+        })),
+        html_pre_processor: item.html_pre_processor ?? "none",
+        css_pre_processor: item.css_pre_processor ?? "none",
+        js_pre_processor: item.js_pre_processor ?? "none",
+        author,
+        pen_url: url,
+        hashid: item.hashid ?? "",
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,88 @@
+import * as z from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { fetchPenMetadata, fetchPen, normalizePenUrl } from "./pen-utils.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "codepen-mcp",
+        version: "1.0.0",
+        description: "Ingest and inspect CodePen pens via oEmbed and pen page parsing",
+    });
+    server.registerTool("get_pen_metadata", {
+        title: "Get Pen Metadata",
+        description: "Fetch CodePen pen metadata from the official oEmbed API. Returns title, author, thumbnail, and embed iframe HTML. Does not include source code. Use when you only need metadata or embed snippet.",
+        inputSchema: {
+            pen_url: z
+                .string()
+                .describe("Full CodePen URL (e.g. https://codepen.io/johndjameson/pen/DwxMqa) or slug (e.g. johndjameson/pen/DwxMqa)"),
+        },
+    }, async ({ pen_url }) => {
+        try {
+            const url = normalizePenUrl(pen_url);
+            const data = await fetchPenMetadata(url);
+            const out = {
+                pen_url: url,
+                title: data.title,
+                author_name: data.author_name,
+                author_url: data.author_url,
+                thumbnail_url: data.thumbnail_url,
+                height: data.height,
+                width: data.width,
+                embed_html: data.html,
+            };
+            return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
+    });
+    server.registerTool("get_pen", {
+        title: "Get Pen (Full Source)",
+        description: "Fetch a CodePen pen's full source (HTML, CSS, JS), metadata, tags, external resources, and preprocessors by parsing the public pen page. Use when you need to ingest, inspect, or understand the code. Note: This parses the pen page and may break if CodePen changes their front-end.",
+        inputSchema: {
+            pen_url: z
+                .string()
+                .describe("Full CodePen URL (e.g. https://codepen.io/johndjameson/pen/DwxMqa) or slug (e.g. johndjameson/pen/DwxMqa)"),
+        },
+    }, async ({ pen_url }) => {
+        try {
+            const pen = await fetchPen(pen_url);
+            return { content: [{ type: "text", text: JSON.stringify(pen, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
+    });
+    server.registerTool("get_pen_embed_html", {
+        title: "Get Pen Embed HTML",
+        description: "Get the iframe embed HTML for a CodePen pen via oEmbed. Optionally specify height. Use when the user wants embed code to paste into a blog or page.",
+        inputSchema: {
+            pen_url: z
+                .string()
+                .describe("Full CodePen URL or slug (e.g. johndjameson/pen/DwxMqa)"),
+            height: z
+                .number()
+                .optional()
+                .describe("Optional iframe height in pixels (default from oEmbed)"),
+        },
+    }, async ({ pen_url, height }) => {
+        try {
+            const url = normalizePenUrl(pen_url);
+            const data = await fetchPenMetadata(url, height != null ? { height } : undefined);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ pen_url: url, title: data.title, embed_html: data.html }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "codepen-mcp",
+  "version": "0.0.1",
+  "description": "MCP server for ingesting and inspecting CodePen pens",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "codepen-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "prepare": "npm run build",
+    "test": "ava",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^20.0.0",
+    "ava": "^6.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "ava": {
+    "files": [
+      "test/**/*.test.ts"
+    ],
+    "extensions": [
+      "ts"
+    ],
+    "nodeArguments": [
+      "--import=tsx/esm"
+    ],
+    "workerThreads": false
+  }
+}