How jpisnice/shadcn-ui-mcp-server works
Project type and purpose
• This is a full-stack CLI-based MCP (Model Context Protocol) server written in TypeScript/Node.js.
• It exposes a suite of “tools” over the MCP JSON-RPC interface, letting AI-powered editors and IDEs (VS Code, Claude Desktop, Continue.dev, Cursor) query and fetch shadcn/ui v4 component source, demos, metadata, blocks, and repository structure via the GitHub API.
File structure
• Top-level:
• package.json / tsconfig.json → Node.js/TypeScript CLI project
• src/index.ts → entrypoint for “npx @jpisnice/shadcn-ui-mcp-server”
• src/handler.ts → request dispatcher binding MCP messages to tool handlers
• src/tools/… → domain logic organized into “blocks”, “components”, “repository” subdirectories
• src/utils/… → infrastructure helpers (API client, caching, circuit breaker, logging, validation)
• src/prompts.ts, src/resource-templates.ts → templates for constructing responses
• Helpers: .github/workflows, docs/, examples.sh, test-package.sh for CI, docs and examples.
README for architecture insights
• Describes key features (component source, demos, blocks, metadata, directory browsing)
• Lists provided tools and how they map to commands (get_component, list_blocks, get_directory_structure, etc.)
• Calls out GitHub API integration with caching and rate-limit handling
Main components
a. Clients
• Editor/IDE Extensions (VS Code Continue, Claude, Cursor, etc.)
• CLI wrapper (“npx @jpisnice/shadcn-ui-mcp-server”)
b. MCP Server Process
• Entrypoint (index.ts) — parses CLI args, configures GitHub token, starts MCP server over STDIO
• Handler (handler.ts) — routes incoming MCP JSON-RPC requests to the appropriate tool
• Tool Registry (src/tools/index.ts) — enumerates domain tools
• Domain Tools
– Components: get_component, list_components, get_component_demo, get_component_metadata
– Blocks: get_block, list_blocks
– Repository: get_directory_structure
• Resource Layer (prompts.ts, resource-templates.ts, resources.ts) — transforms raw data into templated responses
• Schemas (src/schemas) — type definitions for components/blocks
c. Infrastructure & Integrations
• Utilities (src/utils)
– api.ts & axios.ts — HTTP client to GitHub API
– cache.ts — in-memory or file caching layer
– circuit-breaker.ts — retry/backoff on API errors
– logger.ts — structured logging to console or file (mcp-server.log)
– validation.ts — input/output validation
• External Services
– GitHub REST API (rate-limited, authenticated)
d. Configuration & CI
• GitHub Actions workflows (.github/workflows)
• Documentation and examples (docs/, examples.sh)
Relationships and interactions
• Editor/IDE spawns the CLI via “npx …”
• CLI initializes the MCP server over STDIO
• Incoming JSON-RPC requests → Handler → Tool Registry → Specific Tool Function
• Tool Function → calls GitHub API via axios (through cache + circuit-breaker) → raw JSON
• Logger records each step; cache persists frequent GitHub lookups; circuit-breaker prevents API overuse
Architectural patterns and principles
• Layered architecture: Presentation (CLI/MCP), Application (Handler/Registry), Domain (Tools), Infrastructure (Utilities), Integration (GitHub)
• Separation of concerns: each tool has its own folder and well-defined interface
• Resiliency patterns: caching, circuit breaker for external API calls
• Template/Strategy pattern: resource-templates for uniform responses
• Plugin-style tool registration: dynamic registry in src/tools/index.ts
Technologies, frameworks, libraries
• Node.js, TypeScript, npx
• MCP JSON-RPC protocol (Model Context Protocol)
• axios (HTTP client)
• In-memory/file cache, circuit breaker implementation
• GitHub REST API
• GitHub Actions for CI