stackblitz-mcp 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2026-PRESENT Kevin Deng (https://github.com/sxzz)
+
+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,119 @@
+# stackblitz-mcp
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![Unit Test][unit-test-src]][unit-test-href]
+
+[MCP](https://modelcontextprotocol.io/) server for reading files from [StackBlitz](https://stackblitz.com/) projects. Enables AI to access file contents and project structure from StackBlitz reproduction repositories.
+
+## Install
+
+```bash
+npm i -g stackblitz-mcp
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stackblitz": {
+      "command": "npx",
+      "args": ["-y", "stackblitz-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add stackblitz -- npx -y stackblitz-mcp
+```
+
+### Cursor
+
+Add to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "stackblitz": {
+      "command": "npx",
+      "args": ["-y", "stackblitz-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `resolve_project`
+
+Resolve a StackBlitz project URL or ID and return project metadata (title, description, preset, visibility, file count).
+
+**Input:**
+
+- `projectRef` (string) — Project ID or StackBlitz URL (e.g. `stackblitz-starters-rf7brvcm` or `https://stackblitz.com/edit/stackblitz-starters-rf7brvcm`)
+
+### `list_files`
+
+List files in a StackBlitz project as an ASCII tree, optionally filtered by path prefix.
+
+**Input:**
+
+- `projectRef` (string) — Project ID or URL
+- `path` (string, optional) — Filter files by path prefix
+
+### `read_file`
+
+Read the contents of a file from a StackBlitz project.
+
+**Input:**
+
+- `projectRef` (string) — Project ID or URL
+- `path` (string) — File path within the project
+
+### `search_files`
+
+Search for content within files of a StackBlitz project.
+
+**Input:**
+
+- `projectRef` (string) — Project ID or URL
+- `query` (string) — Search query
+- `regex` (boolean, default: `false`) — Treat query as regex
+- `caseSensitive` (boolean, default: `false`) — Case-sensitive search
+- `maxResults` (number, default: `50`) — Maximum number of results
+
+## Resources
+
+| URI Pattern | Description |
+|---|---|
+| `stackblitz://{projectId}/tree` | File tree of a project |
+| `stackblitz://{projectId}/files/{path}` | Contents of a specific file |
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/sxzz/sponsors/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/sxzz/sponsors/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+[MIT](./LICENSE) License © 2026-PRESENT [Kevin Deng](https://github.com/sxzz)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/stackblitz-mcp.svg
+[npm-version-href]: https://npmjs.com/package/stackblitz-mcp
+[npm-downloads-src]: https://img.shields.io/npm/dm/stackblitz-mcp
+[npm-downloads-href]: https://www.npmcharts.com/compare/stackblitz-mcp?interval=30
+[unit-test-src]: https://github.com/sxzz/stackblitz-mcp/actions/workflows/unit-test.yml/badge.svg
+[unit-test-href]: https://github.com/sxzz/stackblitz-mcp/actions/workflows/unit-test.yml

package/dist/index.d.mts

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

package/dist/index.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+//#region src/stackblitz.ts
+const cache = /* @__PURE__ */ new Map();
+const CACHE_TTL = 300 * 1e3;
+const CACHE_MAX_SIZE = 50;
+const KNOWN_PATH_SEGMENTS = new Set([
+	"edit",
+	"fork",
+	"github",
+	"~"
+]);
+function resolveProjectId(ref) {
+	let url;
+	try {
+		url = new URL(ref);
+	} catch {
+		return ref;
+	}
+	if (url.hostname !== "stackblitz.com") throw new Error(`Unsupported URL: only stackblitz.com URLs are supported, got ${url.hostname}`);
+	const parts = url.pathname.split("/").filter(Boolean);
+	if (parts[0] === "edit" && parts[1]) return parts[1];
+	if (parts.length === 1 && !KNOWN_PATH_SEGMENTS.has(parts[0])) return parts[0];
+	throw new Error(`Could not extract project ID from URL: ${ref}`);
+}
+async function fetchProject(projectId) {
+	const cached = cache.get(projectId);
+	if (cached && cached.expiry > Date.now()) return cached.data;
+	const response = await fetch(`https://stackblitz.com/api/projects/${encodeURIComponent(projectId)}?include_files=true`);
+	if (!response.ok) throw new Error(`Failed to fetch project ${projectId}: ${response.status} ${response.statusText}`);
+	const data = await response.json();
+	if (cache.size >= CACHE_MAX_SIZE) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== void 0) cache.delete(oldest);
+	}
+	cache.set(projectId, {
+		data,
+		expiry: Date.now() + CACHE_TTL
+	});
+	return data;
+}
+function getFileList(project) {
+	return Object.values(project.appFiles).map((f) => f.fullPath).toSorted();
+}
+function getFileContents(project, path) {
+	return Object.values(project.appFiles).find((f) => f.fullPath === path);
+}
+
+//#endregion
+//#region src/tree.ts
+function buildTree(paths) {
+	const root = {
+		path: "",
+		name: "",
+		type: "directory",
+		children: []
+	};
+	for (const filePath of paths.toSorted()) {
+		const parts = filePath.split("/");
+		let current = root;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			const isFile = i === parts.length - 1;
+			const currentPath = parts.slice(0, i + 1).join("/");
+			if (!current.children) current.children = [];
+			if (isFile) current.children.push({
+				path: currentPath,
+				name: part,
+				type: "file"
+			});
+			else {
+				let dir = current.children.find((c) => c.name === part && c.type === "directory");
+				if (!dir) {
+					dir = {
+						path: currentPath,
+						name: part,
+						type: "directory",
+						children: []
+					};
+					current.children.push(dir);
+				}
+				current = dir;
+			}
+		}
+	}
+	return root;
+}
+function formatTree(node) {
+	if (!node.children || node.children.length === 0) return "";
+	const sorted = sortChildren(node.children);
+	const lines = [];
+	for (let i = 0; i < sorted.length; i++) formatNode(sorted[i], "", i === sorted.length - 1, lines);
+	return lines.join("\n");
+}
+function sortChildren(children) {
+	return children.toSorted((a, b) => {
+		if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
+		return a.name.localeCompare(b.name);
+	});
+}
+function formatNode(node, prefix, isLast, lines) {
+	const connector = isLast ? "└── " : "├── ";
+	const suffix = node.type === "directory" ? "/" : "";
+	lines.push(`${prefix}${connector}${node.name}${suffix}`);
+	if (node.children && node.children.length > 0) {
+		const childPrefix = prefix + (isLast ? "    " : "│   ");
+		const sorted = sortChildren(node.children);
+		for (let i = 0; i < sorted.length; i++) formatNode(sorted[i], childPrefix, i === sorted.length - 1, lines);
+	}
+}
+
+//#endregion
+//#region src/index.ts
+const server = new McpServer({
+	name: "stackblitz-mcp",
+	version: "0.1.0"
+});
+server.registerResource("project_tree", new ResourceTemplate("stackblitz://{projectId}/tree", { list: void 0 }), {
+	description: "File tree of a StackBlitz project",
+	mimeType: "text/plain"
+}, async (uri, variables) => {
+	const { project } = await fetchProject(resolveProjectId(String(variables.projectId)));
+	const tree = buildTree(getFileList(project));
+	return { contents: [{
+		uri: uri.href,
+		mimeType: "text/plain",
+		text: formatTree(tree)
+	}] };
+});
+server.registerResource("project_file", new ResourceTemplate("stackblitz://{projectId}/files/{+path}", { list: void 0 }), { description: "Contents of a file in a StackBlitz project" }, async (uri, variables) => {
+	const projectId = resolveProjectId(String(variables.projectId));
+	const path = String(variables.path);
+	const { project } = await fetchProject(projectId);
+	const file = getFileContents(project, path);
+	if (!file) throw new Error(`File not found: ${path}`);
+	return { contents: [{
+		uri: uri.href,
+		mimeType: guessMimeType(path),
+		text: file.contents
+	}] };
+});
+server.registerTool("resolve_project", {
+	description: "Resolve a StackBlitz project URL or ID and return project metadata",
+	inputSchema: { projectRef: z.string().min(1).describe("StackBlitz project ID or URL") }
+}, async ({ projectRef }) => {
+	const projectId = resolveProjectId(projectRef);
+	const { project } = await fetchProject(projectId);
+	const files = getFileList(project);
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			projectId,
+			title: project.title,
+			description: project.description,
+			preset: project.preset,
+			visibility: project.visibility,
+			fileCount: files.length
+		}, null, 2)
+	}, {
+		type: "resource_link",
+		uri: `stackblitz://${projectId}/tree`,
+		name: `${projectId} file tree`,
+		mimeType: "text/plain"
+	}] };
+});
+server.registerTool("list_files", {
+	description: "List files in a StackBlitz project, optionally filtered by path prefix",
+	inputSchema: {
+		projectRef: z.string().min(1).describe("StackBlitz project ID or URL"),
+		path: z.string().optional().describe("Filter files by path prefix")
+	}
+}, async ({ projectRef, path }) => {
+	const { project } = await fetchProject(resolveProjectId(projectRef));
+	let files = getFileList(project);
+	if (path) {
+		const prefix = path.endsWith("/") ? path : `${path}/`;
+		files = files.filter((f) => f.startsWith(prefix) || f === path);
+	}
+	return { content: [{
+		type: "text",
+		text: formatTree(buildTree(files))
+	}] };
+});
+server.registerTool("read_file", {
+	description: "Read the contents of a file from a StackBlitz project",
+	inputSchema: {
+		projectRef: z.string().min(1).describe("StackBlitz project ID or URL"),
+		path: z.string().min(1).describe("File path within the project")
+	}
+}, async ({ projectRef, path }) => {
+	const projectId = resolveProjectId(projectRef);
+	const { project } = await fetchProject(projectId);
+	const file = getFileContents(project, path);
+	if (!file) {
+		const files = getFileList(project);
+		const basename = path.split("/").pop() || "";
+		const suggestions = files.filter((f) => f.includes(basename)).slice(0, 5);
+		return {
+			content: [{
+				type: "text",
+				text: `File not found: ${path}${suggestions.length ? `\n\nDid you mean:\n${suggestions.map((s) => `  - ${s}`).join("\n")}` : ""}`
+			}],
+			isError: true
+		};
+	}
+	return { content: [{
+		type: "text",
+		text: file.contents
+	}, {
+		type: "resource_link",
+		uri: `stackblitz://${projectId}/files/${path}`,
+		name: path,
+		mimeType: guessMimeType(path)
+	}] };
+});
+server.registerTool("search_files", {
+	description: "Search for content within files of a StackBlitz project",
+	inputSchema: {
+		projectRef: z.string().min(1).describe("StackBlitz project ID or URL"),
+		query: z.string().min(1).describe("Search query string"),
+		regex: z.boolean().default(false).describe("Treat query as regex"),
+		caseSensitive: z.boolean().default(false).describe("Case-sensitive search"),
+		maxResults: z.number().int().positive().default(50).describe("Maximum number of results")
+	}
+}, async ({ projectRef, query, regex, caseSensitive, maxResults }) => {
+	const { project } = await fetchProject(resolveProjectId(projectRef));
+	let pattern;
+	if (regex) try {
+		pattern = new RegExp(query, caseSensitive ? "g" : "gi");
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: `Invalid regex: ${error instanceof Error ? error.message : String(error)}`
+			}],
+			isError: true
+		};
+	}
+	const searchQuery = caseSensitive ? query : query.toLowerCase();
+	const matches = [];
+	for (const file of Object.values(project.appFiles)) {
+		if (matches.length >= maxResults) break;
+		const lines = file.contents.split("\n");
+		for (const [i, line] of lines.entries()) {
+			if (matches.length >= maxResults) break;
+			let found;
+			if (pattern) {
+				found = pattern.test(line);
+				pattern.lastIndex = 0;
+			} else found = (caseSensitive ? line : line.toLowerCase()).includes(searchQuery);
+			if (found) matches.push({
+				file: file.fullPath,
+				line: i + 1,
+				text: line.trimEnd()
+			});
+		}
+	}
+	if (matches.length === 0) return { content: [{
+		type: "text",
+		text: `No matches found for "${query}"`
+	}] };
+	const grouped = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		const group = grouped.get(match.file) || [];
+		group.push(match);
+		grouped.set(match.file, group);
+	}
+	let output = `Found ${matches.length} match${matches.length === 1 ? "" : "es"} in ${grouped.size} file${grouped.size === 1 ? "" : "s"}:\n\n`;
+	for (const [file, fileMatches] of grouped) {
+		output += `## ${file}\n`;
+		for (const m of fileMatches) output += `  L${m.line}: ${m.text}\n`;
+		output += "\n";
+	}
+	return { content: [{
+		type: "text",
+		text: output.trimEnd()
+	}] };
+});
+const MIME_TYPES = {
+	ts: "text/typescript",
+	tsx: "text/typescript",
+	js: "text/javascript",
+	jsx: "text/javascript",
+	json: "application/json",
+	md: "text/markdown",
+	html: "text/html",
+	css: "text/css",
+	scss: "text/scss",
+	less: "text/less",
+	svg: "image/svg+xml",
+	yaml: "text/yaml",
+	yml: "text/yaml",
+	xml: "text/xml",
+	txt: "text/plain",
+	vue: "text/x-vue",
+	svelte: "text/x-svelte"
+};
+function guessMimeType(path) {
+	return MIME_TYPES[path.split(".").pop()?.toLowerCase() || ""] || "text/plain";
+}
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error("StackBlitz MCP server running on stdio");
+}
+main().catch((error) => {
+	console.error("Fatal error:", error);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "stackblitz-mcp",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "MCP server for reading files from StackBlitz projects",
+  "author": "Kevin Deng <sxzz@sxzz.moe>",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/sxzz",
+  "homepage": "https://github.com/sxzz/stackblitz-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sxzz/stackblitz-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sxzz/stackblitz-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "stackblitz",
+    "ai",
+    "llm"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "stackblitz-mcp": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.23"
+  },
+  "devDependencies": {
+    "@sxzz/eslint-config": "^7.5.1",
+    "@sxzz/prettier-config": "^2.2.6",
+    "@types/node": "^25.0.10",
+    "@typescript/native-preview": "7.0.0-dev.20260124.1",
+    "bumpp": "^10.4.0",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "tsdown": "^0.20.1",
+    "tsdown-preset-sxzz": "^0.3.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "prettier": "@sxzz/prettier-config",
+  "scripts": {
+    "lint": "eslint --cache .",
+    "lint:fix": "pnpm run lint --fix",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsgo --noEmit",
+    "format": "prettier --cache --write .",
+    "release": "bumpp"
+  }
+}