shadcn-svelte-mcp: Instructions file for GitHub Copilot

AI assistant quick-start for this repository

This file gives concise, actionable instructions for an AI coding agent to be productive in this codebase.

1. What this repo is

• A Mastra-based AI tooling project that bundles: workflows, agents, MCP servers and custom tools. See src/index.ts for the Mastra bootstrap (workflows, agents, mcpServers).
• Documentation is fetched in real-time from shadcn-svelte.com using Crawlee (Playwright for JS-heavy pages) and Cheerio (fallback for simple pages) under src/services/.

1. How to run / common developer commands

• Node engine: use Node >= 20.9.0 (see package.json "engines").
• Development (app-level): bun run dev (calls mastra dev).
• Type checking: bun run check (runs tsc --noEmit to check for TypeScript errors across the entire project).
• Note: for quick smoke-tests and CI checks, we use bun run dev only (see the smoke-test guideline below). Other MCP helper scripts exist in package.json but the canonical developer workflow relies on bun run dev for early error detection.

Important: AI-generated/progress documentation and ephemeral notes

• All AI-generated progress docs, status logs, design notes, or autogenerated markdown should be created or updated only inside the ai-generated-docs/ folder at the repository root. Do not place generated progress docs in other directories.
• When moving or manipulating files as part of progress updates, prefer Git-aware operations (for example git mv) so history is preserved.

Shell command preference

• When suggesting or running commands, prefer POSIX bash commands. Provide exact, copyable bash snippets and use git for VCS operations. Wrap examples in bash code blocks and avoid platform-specific shells unless requested.

1. Big-picture architecture (quick map)

• Mastra instance (src/index.ts): central entry that composes workflows (src/mastra/workflows), agents (src/mastra/agents), and mcpServers (src/mastra/mcp-server). MCP clients are used directly in agent definitions, not registered here.
• MCP Server (src/mastra/mcp-server.*): exposes an object shadcn used by src/dev-server.ts and src/server.ts via startSSE/startHTTP/close. This SERVER exposes YOUR tools to external MCP clients.
• MCP Client (src/mastra/mcp-client.ts): connects to EXTERNAL MCP servers (like Mastra's official server at mcp.mastra.ai) to USE their tools in your agents. This CLIENT consumes tools from other servers.
• Tools (src/mastra/tools/*): each tool is created with createTool(...) from @mastra/core/tools and follows the pattern: zod input schema, execute({context}) returns result. Example tools: shadcn-svelte-get, shadcn-svelte-list, shadcn-svelte-icons.
• Web scraping services: src/services/doc-fetcher.ts handles real-time documentation fetching from shadcn-svelte.com; src/services/component-discovery.ts dynamically discovers available components.

1. Project-specific conventions and gotchas (do not invent alternatives)

• Tools follow Mastra patterns using createTool with Zod schemas for input validation (see shadcn-svelte-get.ts). When creating new tools, follow the established patterns for tool development.
• Tools use web scraping to fetch documentation in real-time from shadcn-svelte.com. The tooling parses markdown content returned from the scraping service.
• File path resolution: tools resolve docs relative to the tool file (they use file URL + join with ../docs) — prefer relative paths instead of hard-coded absolute paths.
• Web scraping approach: tools use real-time web scraping to fetch documentation from shadcn-svelte.com. Components are discovered dynamically from the live website.
• Input validation: tools MUST use zod to validate inputs. Mastra's createTool requires Zod schemas for proper type inference and runtime validation. When updating or creating tools, use zod schemas (see existing examples in src/mastra/tools/*). Follow the pattern: import { z } from "zod" and define schemas with z.object({...}).
• Test file organization: ALWAYS place test files in the test/ directory at the repository root, never in src/. Test files should be named descriptively (e.g., test-crawlee.ts, test-mcp.ts). Update package.json scripts when moving test files to reflect new paths. Use git mv when moving files to preserve version history.