v1.2.0

.claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(npm test)",
+      "Bash(npm run build:*)",
+      "Bash(rm:*)",
+      "Bash(chmod:*)",
+      "Bash(./build/index.js --help)",
+      "Bash(./build/index.js --version)",
+      "Bash(sed:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(timeout 5s npm run start)",
+      "Bash(node:*)",
+      "Bash(git push:*)",
+      "Bash(npm run test:*)",
+      "Bash(awk:*)",
+      "Bash(npm run start:*)",
+      "Bash(git rm:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)"
+    ],
+    "deny": []
+  }
+}

ASSISTANTS.md

@@ -0,0 +1,165 @@
+## Project Overview
+
+This is a **Model Context Protocol (MCP) server** for shadcn/ui v4 components. It provides AI assistants with access to shadcn/ui component source code, demos, blocks, and metadata through the MCP protocol.
+
+- **Package**: `@shelldandy/shadcn-ui-mcp-server`
+- **Runtime**: Node.js 18+ (ESM modules)
+- **Language**: TypeScript with strict mode
+- **Architecture**: MCP server using [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
+
+## Development Commands
+
+```bash
+# Build the project
+npm run build
+
+# Clean build artifacts
+npm run clean
+
+# Development build and run
+npm run dev
+
+# Start the server (requires build first)
+npm run start
+
+# Test the package (validates build and CLI)
+npm run test
+
+# Run examples
+npm run examples
+```
+
+## Project Architecture
+
+### Core Components
+
+1. **Entry Point** (`src/index.ts`)
+
+   - CLI argument parsing (`--github-api-key`, `--help`, `--version`)
+   - MCP server initialization with stdio transport
+   - GitHub API key configuration
+
+2. **Handler System** (`src/handler.ts`)
+
+   - Sets up MCP request handlers for resources, tools, and prompts
+   - Validates tool parameters using Zod schemas
+   - Global error handling and response formatting
+
+3. **Tools Layer** (`src/tools.ts`)
+
+   - Defines MCP tools available to AI clients
+   - Tools: `get_component`, `get_component_demo`, `list_components`, `get_component_metadata`, `get_directory_structure`, `get_block`, `list_blocks`
+   - Uses new MCP server approach with backward compatibility exports
+
+4. **API Layer** (`src/utils/axios.ts`)
+   - GitHub API integration with rate limiting
+   - Caching system for API responses
+   - Direct access to shadcn/ui v4 registry paths
+
+### MCP Protocol Implementation
+
+The server implements the Model Context Protocol to provide:
+
+- **Tools**: Callable functions that fetch shadcn/ui data
+- **Resources**: Static or dynamic content accessible via URI
+- **Prompts**: Reusable prompt templates with parameters
+
+### Data Sources
+
+- **Primary**: GitHub API access to [shadcn-ui/ui](https://github.com/shadcn-ui/ui) repository
+- **Registry Path**: `/apps/www/registry/new-york/` (v4 components)
+- **Blocks Path**: `/apps/www/registry/new-york/blocks/` (v4 blocks)
+
+## File Structure
+
+```
+src/
+├── index.ts              # CLI entry point and server initialization
+├── handler.ts            # MCP request handlers and validation
+├── tools.ts              # Tool definitions and implementations
+├── resources.ts          # Static MCP resources
+├── prompts.ts            # MCP prompt templates
+├── resource-templates.ts # Dynamic resource templates
+├── schemas/
+│   └── component.ts      # Zod schemas for validation
+└── utils/
+    ├── axios.ts          # GitHub API client with caching
+    ├── api.ts            # Legacy API types (deprecated)
+    └── cache.ts          # Response caching utilities
+```
+
+## Testing
+
+- **Test Script**: `./test-package.sh` - Validates build, CLI, and package structure
+- **No Unit Tests**: The project focuses on integration testing through the test script
+- **Manual Testing**: Use `npm run examples` to test tool functionality
+
+## Building and Publishing
+
+```bash
+# Prepare for publishing
+npm run prepublishOnly
+
+# This runs: clean → build → chmod +x build/index.js
+```
+
+The build process:
+
+1. TypeScript compilation to `build/` directory
+2. Makes the main entry point executable
+3. Validates package structure for npm publishing
+
+## Configuration
+
+### GitHub API Integration
+
+The server requires a GitHub API token for optimal performance:
+
+- **Without token**: 60 requests/hour
+- **With token**: 5,000 requests/hour
+
+Configuration methods:
+
+```bash
+# Command line
+--github-api-key ghp_your_token
+
+# Environment variable (either option works)
+export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token
+# Or using the common GITHUB_TOKEN variable
+export GITHUB_TOKEN=ghp_your_token
+```
+
+### MCP Client Configuration
+
+For Claude Desktop (`~/.config/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "shadcn-ui": {
+      "command": "npx",
+      "args": ["@shelldandy/shadcn-ui-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
+        // Or using GITHUB_TOKEN:
+        "GITHUB_TOKEN": "ghp_your_token"
+      }
+    }
+  }
+}
+```
+
+## Key Dependencies
+
+- `@modelcontextprotocol/sdk`: MCP protocol implementation
+- `axios`: HTTP client for GitHub API
+- `cheerio`: HTML parsing (legacy, minimal usage)
+- `zod`: Runtime type validation and schema definition
+
+## Notes
+
+- The project uses ESM modules (`"type": "module"` in package.json)
+- All TypeScript compilation targets ES2022 with Node16 module resolution
+- The `src/utils/api.ts` file contains legacy code that's deprecated in favor of direct GitHub API access
+- Error handling follows MCP protocol standards with proper error codes and messages

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Read @ASSISTANTS.md

PUBLISHING.md

@@ -109,6 +109,8 @@ npx shadcn-ui-mcp-server --github-api-key YOUR_TOKEN
     "command": "npx",
     "args": ["shadcn-ui-mcp-server"],
     "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"}
+    // Or using GITHUB_TOKEN:
+    "env": {"GITHUB_TOKEN": "YOUR_TOKEN"}
   }]
 }
 ```