stackblitz-mcp: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An MCP (Model Context Protocol) server that provides read-only access to StackBlitz project files. It fetches project data from the StackBlitz API (https://stackblitz.com/api/projects/{id}?include_files=true) and exposes it via MCP tools and resources over stdio transport.

Commands

pnpm run build          # Build with tsdown → dist/index.mjs
pnpm run dev            # Watch mode build
pnpm run test           # Run tests (vitest, watch mode)
pnpm run test -- --run  # Run tests once
pnpm run lint           # ESLint check
pnpm run lint:fix       # ESLint auto-fix
pnpm run typecheck      # Type check with tsgo (native TS)
pnpm run format         # Prettier format

Architecture

The server has three modules:

• src/index.ts — MCP server entry point. Registers 2 resources and 4 tools on McpServer, then connects via StdioServerTransport. Use registerResource/registerTool (not the deprecated resource/tool methods).
• src/stackblitz.ts — StackBlitz API client. resolveProjectId() extracts project IDs from URLs or passes plain IDs through. fetchProject() calls the API with a TTL cache (5 min, max 50 entries).
• src/tree.ts — Builds a FileNode tree from flat file paths and formats it as ASCII art with ├──/└── connectors.

Key Conventions

• ESM only ("type": "module"). Use .js extensions in imports (e.g., ./stackblitz.js).
• verbatimModuleSyntax is enabled — use import type for type-only imports.
• Type checking uses tsgo (native TypeScript preview), which has stricter overload resolution than tsc.
• ESLint uses @sxzz/eslint-config which enforces: toSorted() over sort(), for-of over index loops, node: prefix for Node.js builtins, no duplicate imports.
• Prettier uses @sxzz/prettier-config.
• Tool results use type: 'text' as const and type: 'resource_link' as const for content items. resource_link fields (uri, name, mimeType) are at top level, not nested in a resource object.