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 tmcp-based MCP server (lightweight, schema-agnostic MCP SDK). See src/mcp/server.ts for the McpServer assembly, src/index.ts for the Node/Bun HTTP entry, and src/stdio.ts for local MCP clients.
• Documentation is fetched in real-time from shadcn-svelte.com using Cheerio + Turndown (HTML → Markdown) and direct .md / llms.txt endpoint fetching under src/services/.

1. How to run / common developer commands

• Runtimes: Node >= 20.9.0 or Bun >= 1.1 (see package.json "engines").
• Development: bun run dev (HTTP server with watch on http://localhost:3000, MCP endpoint /mcp, health /health).
• Type checking: bun run check (runs tsc --noEmit across the project).
• Local MCP: bun run mcp (stdio transport).
• Build: bun run build (bundles src/index.ts + src/stdio.ts → dist/ for Fly.io/Render).
• Agent sync guard: bun run check:agents (fails if the per-editor agent bodies in agents/ drift apart; agents-md-snippet.md is a declared variant).
• Version guard: bun run check-versions (package.json must match src/mcp/server.ts).
• CI: .github/workflows/ci.yml runs check, check:agents, check-versions, bun test, and a report-only link check on every push and pull request. Only bun.lock exists, so CI uses bun install --frozen-lockfile — npm ci cannot work in this repo.

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)

• MCP Server (src/mcp/server.ts): exports server (tmcp McpServer) and serverVersion. Registers 5 tools + 5 prompts, uses the Valibot adapter (@tmcp/adapter-valibot) — all schemas are valibot.
• Entry points:
  • src/index.ts — srvx HTTP server (Node/Bun): Streamable HTTP at /mcp, /health endpoint.
  • src/stdio.ts — StdioTransport for local MCP clients.
• Tools (src/mcp/tools/*): each is created with defineTool(...) from tmcp/tool and follows the pattern: valibot schema, async (input) => tool.text(...) | tool.error(...). Examples: shadcn-svelte-get, shadcn-svelte-list, shadcn-svelte-icons, shadcn-svelte-search, bits-ui-get.
• Prompts (src/mcp/prompts/*): created with definePrompt(...) from tmcp/prompt, valibot schema, return { messages: [...] }.
• Web scraping services: src/services/doc-fetcher.ts (real-time doc fetching), src/services/catalog.ts (unified live catalog: llms.txt categories + descriptions merged with the component-discovery.ts registry index and bits-ui-discovery.ts), src/services/catalog-search.ts (pure multi-term search core used by the search tool), src/services/cache-manager.ts (memory + optional KV + optional disk tiers, 3-day TTL).

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

• Tools use defineTool from tmcp/tool with valibot schemas (import * as v from "valibot") for input validation. Use v.object({...}), v.string(), v.number(), v.picklist([...]) for string literals, v.optional(schema, default) for optional-with-default, and v.pipe(schema, v.description("...")) for field descriptions. Tool handlers MUST return content via tool.text(...) / tool.error(...) from tmcp/utils — never a bare string.
• Prompts use definePrompt from tmcp/prompt with the same valibot schema conventions and return { messages: [...] } (role: "user" | "assistant", content: { type: "text", text }).
• The version anchor: version: "x.y.z" in src/mcp/server.ts MUST stay in sync with package.json (see scripts/check-versions.js / sync-versions*.js; regex is version:\s*"[^"]+",).
• Web scraping approach: tools fetch documentation in real-time from shadcn-svelte.com (.md endpoints, llms.txt, Cheerio+Turndown HTML fallback). Components are discovered dynamically from the live website.
• The cache manager loads node:fs dynamically so it stays loadable on runtimes without it, degrading to memory-only. Do not add static node:* imports to shared services.
• Test file organization: ALWAYS place test files in the test/ directory at the repository root, never in src/. Use git mv when moving files to preserve version history.