shadcn-svelte-mcp

<!-- .github/copilot-instructions.md - guidance for AI coding agents -->

# 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](https://tmcp.io)-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, `src/worker.ts` for the Cloudflare Worker 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/`.

2. 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).
- Deploy Worker: `bun run deploy:worker` (wrangler; requires `TMCP_KV` binding — see `wrangler.jsonc`).

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.

3. Big-picture architecture (quick map)

- MCP Server (`src/mcp/server.ts`): exports `server` (tmcp `McpServer`) and `serverVersion`. Registers 5 tools + 4 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.
  - `src/worker.ts` — Cloudflare Worker: `HttpTransport` at `/mcp`, optional KV-backed cache (`TMCP_KV`).
- 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/component-discovery.ts` + `bits-ui-discovery.ts` (dynamic discovery), `src/services/cache-manager.ts` (memory + optional KV + optional disk tiers, 3-day TTL).

4. 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 is runtime-agnostic: disk tier uses dynamic `node:fs` import and auto-degrades to memory/KV only on Workers. Do not add static `node:*` imports to shared services used by `src/worker.ts`.
- **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.

Important runtime smoke-test: when running AI-driven tests or validations, always use the MCP testing channel `#test-mcp` rather than executing repository test scripts directly. Do NOT start or run `bun run dev` from within AI tests — the development server is expected to already be running. If a local manual smoke-test is required by a developer, run `bun run dev` locally for 10–15s, but AI agents must not start it.

IMPORTANT (strict): DO NOT run local test scripts (files under `test/`) from within AI-driven workflows. This rule prevents accidental process execution, environment changes, or side effects caused by automated agents.

If you need to validate tools programmatically, use the `#test-mcp` MCP channel (or instrumented CI jobs that call tools via the MCP protocol). Reserve direct execution of `test/*.ts` scripts for manual local debugging only.

**MCP Tool Testing Rule**: When testing or validating MCP tools, ALWAYS use the dedicated MCP test tools (e.g., `#mcp_test-mcp_shadcnSvelteGetTool`) instead of running JavaScript test files directly. The MCP test tools provide proper integration testing through the MCP protocol and ensure tools work correctly in the actual MCP environment.

Caching: tools use the shared cache-manager (3-day TTL; memory + `.cache/` disk on Node/Bun, KV on Workers). Expect stale cached results when iterating; clear `.cache/` or restart the process during development if necessary.

5. Common edit patterns and examples (concrete references)

To add a new tool, mirror `src/mcp/tools/shadcn-svelte-get.ts`:

```ts
import { defineTool } from "tmcp/tool";
import { tool } from "tmcp/utils";
import * as v from "valibot";

export const myTool = defineTool(
  {
    name: "my-tool",
    description: "What it does",
    schema: v.object({
      param: v.pipe(v.string(), v.description("What param is")),
    }),
  },
  async ({ param }) => tool.text(`Received: ${param}`),
);
```

Then register it in `src/mcp/server.ts` via `server.tools([...])`. Prompts follow the same shape with `definePrompt` + `server.prompts([...])`.

- To examine how components are discovered, inspect `src/mcp/tools/shadcn-svelte-get.ts` and `src/services/component-discovery.ts`.
- To test changes quickly: use the `#test-mcp` MCP channel to run tests and validations. Do not invoke repo test scripts or start `bun run dev` from AI-driven runs.

6. Integration & external deps

- Key runtime deps (see `package.json`): tmcp, @tmcp/adapter-valibot, @tmcp/transport-http, @tmcp/transport-stdio, valibot, srvx, cheerio, turndown, fuse.js. Respect the pinned major versions when adding features unless requested.
- No database. Cache persistence is optional: disk (`./.cache`) on Node/Bun, KV binding `TMCP_KV` on Cloudflare Workers.

7. Debugging tips for AI agents

- If a tool returns "not found", check the web scraping services in `src/services/` and verify the component exists on shadcn-svelte.com.
- Verify protocol behavior with curl: `curl -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'`.
- For runtime discovery iterate: change code and run `bun run dev` for 10–15s to surface issues; focus on reproducing the failing scenario in that window.

8. What not to change without confirmation

- The `McpServer` assembly in `src/mcp/server.ts` (server info, adapter, capabilities) — changes affect all transports.
- The registry format and field names used by tools (`items[].name`, `items[].files[].path`, `items[].type`).
- The version-sync tooling (`.releaserc.json`, `.github/workflows/version-and-release.yml`, `scripts/sync-versions*.js`) — they anchor on `src/mcp/server.ts`.