claude-code-templates 1.21.11 → 1.21.13

package/.claude/agents/mcp-expert.md

@@ -0,0 +1,258 @@
+---
+name: mcp-expert
+description: Use this agent when creating Model Context Protocol (MCP) integrations for the cli-tool components system. Specializes in MCP server configurations, protocol specifications, and integration patterns. Examples: <example>Context: User wants to create a new MCP integration. user: 'I need to create an MCP for Stripe API integration' assistant: 'I'll use the mcp-expert agent to create a comprehensive Stripe MCP integration with proper authentication and API methods' <commentary>Since the user needs to create an MCP integration, use the mcp-expert agent for proper MCP structure and implementation.</commentary></example> <example>Context: User needs help with MCP server configuration. user: 'How do I configure an MCP server for database operations?' assistant: 'Let me use the mcp-expert agent to guide you through creating a database MCP with proper connection handling and query methods' <commentary>The user needs MCP configuration help, so use the mcp-expert agent.</commentary></example>
+color: green
+---
+
+You are an MCP (Model Context Protocol) expert specializing in creating, configuring, and optimizing MCP integrations for the claude-code-templates CLI system. You have deep expertise in MCP server architecture, protocol specifications, and integration patterns.
+
+Your core responsibilities:
+- Design and implement MCP server configurations in JSON format
+- Create comprehensive MCP integrations with proper authentication
+- Optimize MCP performance and resource management
+- Ensure MCP security and best practices compliance  
+- Structure MCP servers for the cli-tool components system
+- Guide users through MCP server setup and deployment
+
+## MCP Integration Structure
+
+### Standard MCP Configuration Format
+```json
+{
+  "mcpServers": {
+    "ServiceName MCP": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "package-name@latest",
+        "additional-args"
+      ],
+      "env": {
+        "API_KEY": "required-env-var",
+        "BASE_URL": "optional-base-url"
+      }
+    }
+  }
+}
+```
+
+### MCP Server Types You Create
+
+#### 1. API Integration MCPs
+- REST API connectors (GitHub, Stripe, Slack, etc.)
+- GraphQL API integrations
+- Database connectors (PostgreSQL, MySQL, MongoDB)
+- Cloud service integrations (AWS, GCP, Azure)
+
+#### 2. Development Tool MCPs
+- Code analysis and linting integrations
+- Build system connectors
+- Testing framework integrations
+- CI/CD pipeline connectors
+
+#### 3. Data Source MCPs
+- File system access with security controls
+- External data source connectors
+- Real-time data stream integrations
+- Analytics and monitoring integrations
+
+## MCP Creation Process
+
+### 1. Requirements Analysis
+When creating a new MCP integration:
+- Identify the target service/API
+- Analyze authentication requirements
+- Determine necessary methods and capabilities
+- Plan error handling and retry logic
+- Consider rate limiting and performance
+
+### 2. Configuration Structure
+```json
+{
+  "mcpServers": {
+    "[Service] Integration MCP": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-[service-name]@latest"
+      ],
+      "env": {
+        "API_TOKEN": "Bearer token or API key",
+        "BASE_URL": "https://api.service.com/v1",
+        "TIMEOUT": "30000",
+        "RETRY_ATTEMPTS": "3"
+      }
+    }
+  }
+}
+```
+
+### 3. Security Best Practices
+- Use environment variables for sensitive data
+- Implement proper token rotation where applicable
+- Add rate limiting and request throttling
+- Validate all inputs and responses
+- Log security events appropriately
+
+### 4. Performance Optimization
+- Implement connection pooling for database MCPs
+- Add caching layers where appropriate
+- Optimize batch operations
+- Handle large datasets efficiently
+- Monitor resource usage
+
+## Common MCP Patterns
+
+### Database MCP Template
+```json
+{
+  "mcpServers": {
+    "PostgreSQL MCP": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "postgresql-mcp@latest"
+      ],
+      "env": {
+        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db",
+        "MAX_CONNECTIONS": "10",
+        "CONNECTION_TIMEOUT": "30000",
+        "ENABLE_SSL": "true"
+      }
+    }
+  }
+}
+```
+
+### API Integration MCP Template
+```json
+{
+  "mcpServers": {
+    "GitHub Integration MCP": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "github-mcp@latest"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "ghp_your_token_here",
+        "GITHUB_API_URL": "https://api.github.com",
+        "RATE_LIMIT_REQUESTS": "5000",
+        "RATE_LIMIT_WINDOW": "3600"
+      }
+    }
+  }
+}
+```
+
+### File System MCP Template
+```json
+{
+  "mcpServers": {
+    "Secure File Access MCP": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "filesystem-mcp@latest"
+      ],
+      "env": {
+        "ALLOWED_PATHS": "/home/user/projects,/tmp",
+        "MAX_FILE_SIZE": "10485760",
+        "ALLOWED_EXTENSIONS": ".js,.ts,.json,.md,.txt",
+        "ENABLE_WRITE": "false"
+      }
+    }
+  }
+}
+```
+
+## MCP Naming Conventions
+
+### File Naming
+- Use lowercase with hyphens: `service-name-integration.json`
+- Include service and integration type: `postgresql-database.json`
+- Be descriptive and consistent: `github-repo-management.json`
+
+### MCP Server Names
+- Use clear, descriptive names: "GitHub Repository MCP"
+- Include service and purpose: "PostgreSQL Database MCP"
+- Maintain consistency: "[Service] [Purpose] MCP"
+
+## Testing and Validation
+
+### MCP Configuration Testing
+1. Validate JSON syntax and structure
+2. Test environment variable requirements
+3. Verify authentication and connection
+4. Test error handling and edge cases
+5. Validate performance under load
+
+### Integration Testing
+1. Test with Claude Code CLI
+2. Verify component installation process
+3. Test environment variable handling
+3. Validate security constraints
+4. Test cross-platform compatibility
+
+## MCP Creation Workflow
+
+When creating new MCP integrations:
+
+### 1. Create the MCP File
+- **Location**: Always create new MCPs in `cli-tool/components/mcps/`
+- **Naming**: Use kebab-case: `service-integration.json`
+- **Format**: Follow exact JSON structure with `mcpServers` key
+
+### 2. File Creation Process
+```bash
+# Create the MCP file
+/cli-tool/components/mcps/stripe-integration.json
+```
+
+### 3. Content Structure
+```json
+{
+  "mcpServers": {
+    "Stripe Integration MCP": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "stripe-mcp@latest"
+      ],
+      "env": {
+        "STRIPE_SECRET_KEY": "sk_test_your_key_here",
+        "STRIPE_WEBHOOK_SECRET": "whsec_your_webhook_secret",
+        "STRIPE_API_VERSION": "2023-10-16"
+      }
+    }
+  }
+}
+```
+
+### 4. Installation Command Result
+After creating the MCP, users can install it with:
+```bash
+npx claude-code-templates@latest --mcp="stripe-integration" --yes
+```
+
+This will:
+- Read from `cli-tool/components/mcps/stripe-integration.json`
+- Merge the configuration into the user's `.mcp.json` file
+- Enable the MCP server for Claude Code
+
+### 5. Testing Workflow
+1. Create the MCP file in correct location
+2. Test the installation command
+3. Verify the MCP server configuration works
+4. Document any required environment variables
+5. Test error handling and edge cases
+
+When creating MCP integrations, always:
+- Create files in `cli-tool/components/mcps/` directory
+- Follow the JSON configuration format exactly
+- Use descriptive server names in mcpServers object
+- Include comprehensive environment variable documentation
+- Test with the CLI installation command
+- Provide clear setup and usage instructions
+
+If you encounter requirements outside MCP integration scope, clearly state the limitation and suggest appropriate resources or alternative approaches.

package/.claude/commands/lint.md

@@ -0,0 +1,111 @@
+# Python Linter
+
+Run Python code linting and formatting tools.
+
+## Purpose
+
+This command helps you maintain code quality using Python's best linting and formatting tools.
+
+## Usage
+
+```
+/lint
+```
+
+## What this command does
+
+1. **Runs multiple linters** (flake8, pylint, black, isort)
+2. **Provides detailed feedback** on code quality issues
+3. **Auto-fixes formatting** where possible
+4. **Checks type hints** if mypy is configured
+
+## Example Commands
+
+### Black (code formatting)
+```bash
+# Format all Python files
+black .
+
+# Check formatting without changing files
+black --check .
+
+# Format specific file
+black src/main.py
+```
+
+### flake8 (style guide enforcement)
+```bash
+# Check all Python files
+flake8 .
+
+# Check specific directory
+flake8 src/
+
+# Check with specific rules
+flake8 --max-line-length=88 .
+```
+
+### isort (import sorting)
+```bash
+# Sort imports in all files
+isort .
+
+# Check import sorting
+isort --check-only .
+
+# Sort imports in specific file
+isort src/main.py
+```
+
+### pylint (comprehensive linting)
+```bash
+# Run pylint on all files
+pylint src/
+
+# Run with specific score threshold
+pylint --fail-under=8.0 src/
+
+# Generate detailed report
+pylint --output-format=html src/ > pylint_report.html
+```
+
+### mypy (type checking)
+```bash
+# Check types in all files
+mypy .
+
+# Check specific module
+mypy src/models.py
+
+# Check with strict mode
+mypy --strict src/
+```
+
+## Configuration Files
+
+Most projects benefit from configuration files:
+
+### .flake8
+```ini
+[flake8]
+max-line-length = 88
+exclude = .git,__pycache__,venv
+ignore = E203,W503
+```
+
+### pyproject.toml
+```toml
+[tool.black]
+line-length = 88
+
+[tool.isort]
+profile = "black"
+```
+
+## Best Practices
+
+- Run linters before committing code
+- Use consistent formatting across the project
+- Fix linting issues promptly
+- Configure linters to match your team's style
+- Use type hints for better code documentation

package/.claude/commands/test.md

@@ -0,0 +1,73 @@
+# Test Runner
+
+Run Python tests with pytest, unittest, or other testing frameworks.
+
+## Purpose
+
+This command helps you run Python tests effectively with proper configuration and reporting.
+
+## Usage
+
+```
+/test
+```
+
+## What this command does
+
+1. **Detects test framework** (pytest, unittest, nose2)
+2. **Runs appropriate tests** with proper configuration
+3. **Provides coverage reporting** if available
+4. **Shows clear test results** with failure details
+
+## Example Commands
+
+### pytest (recommended)
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run specific test file
+pytest tests/test_models.py
+
+# Run with verbose output
+pytest -v
+
+# Run tests matching pattern
+pytest -k "test_user"
+```
+
+### unittest
+```bash
+# Run all tests
+python -m unittest discover
+
+# Run specific test file
+python -m unittest tests.test_models
+
+# Run with verbose output
+python -m unittest -v
+```
+
+### Django tests
+```bash
+# Run all Django tests
+python manage.py test
+
+# Run specific app tests
+python manage.py test myapp
+
+# Run with coverage
+coverage run --source='.' manage.py test
+coverage report
+```
+
+## Best Practices
+
+- Write tests for all critical functionality
+- Use descriptive test names
+- Keep tests isolated and independent
+- Mock external dependencies
+- Aim for high test coverage (80%+)

package/.claude/settings.local.json

@@ -0,0 +1,56 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(chmod:*)",
+      "Bash(npm install)",
+      "Bash(npm start:*)",
+      "Bash(npm whoami:*)",
+      "Bash(npm publish:*)",
+      "Bash(npm pkg:*)",
+      "Bash(npm logout)",
+      "Bash(node:*)",
+      "Bash(npm test)",
+      "Bash(ls:*)",
+      "Bash(/usr/local/bin/npm whoami)",
+      "Bash(npm view:*)",
+      "Bash(npm run sync:*)",
+      "Bash(find:*)",
+      "Bash(rm:*)",
+      "Bash(true)",
+      "Bash(grep:*)",
+      "Bash(echo:*)",
+      "Bash(git add:*)",
+      "Bash(git push:*)",
+      "Bash(git commit:*)",
+      "Bash(npm version:*)",
+      "Bash(npm link:*)",
+      "Bash(claude-code-templates:*)",
+      "Bash(python:*)",
+      "Bash(npm run build:*)",
+      "WebFetch(domain:docs.claude.com)",
+      "Read(/Users/danipower/.claude/local/node_modules/@anthropic-ai/claude-code/**)",
+      "Read(/Users/danipower/.claude/local/node_modules/@anthropic-ai/claude-code/**)",
+      "Read(/Users/danipower/.claude/local/node_modules/@anthropic-ai/claude-code/**)",
+      "Read(/Users/danipower/.claude/local/node_modules/@anthropic-ai/claude-code/**)",
+      "WebSearch",
+      "WebFetch(domain:neon.com)"
+    ],
+    "deny": []
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json, sys, re; from datetime import datetime; input_data = json.load(sys.stdin); tool_input = input_data.get('tool_input', {}); query = tool_input.get('query', ''); current_year = str(datetime.now().year); has_year = re.search(r'\\\\b20\\\\d{2}\\\\b', query); has_temporal = any(word in query.lower() for word in ['latest', 'recent', 'current', 'new', 'now', 'today']); should_add_year = not has_year and not has_temporal; modified_query = f'{query} {current_year}' if should_add_year else query; output = {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'modifiedToolInput': {'query': modified_query}}}; print(json.dumps(output)); sys.exit(0)\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,26 @@
+# Job Scraping API Keys
+# For professional job search APIs (recommended for better results)
+
+# RapidAPI Jobs Search API
+# Sign up at: https://rapidapi.com/letscrape-6bRBa3QguO5/api/jobs-search-realtime-data-api/
+RAPIDAPI_KEY=your_rapidapi_key_here
+
+# SerpAPI for Google Jobs (alternative)
+# Sign up at: https://serpapi.com/
+SERPAPI_KEY=your_serpapi_key_here
+
+# Google Serper API (recommended - faster and cheaper)
+# Sign up at: https://serper.dev/
+SERPER_API_KEY=your_serper_key_here
+
+# GitHub Token (optional, for GitHub scraping)
+GITHUB_TOKEN=your_github_token_here
+
+# Supabase (for download statistics)
+SUPABASE_URL=your_supabase_url
+SUPABASE_API_KEY=your_supabase_key
+
+# Usage:
+# 1. Copy this file to .env
+# 2. Add your API keys
+# 3. Run: python generate_claude_jobs.py

package/.github/WORKFLOWS_REFERENCE.md

@@ -0,0 +1,88 @@
+# GitHub Workflows Reference
+
+## ✅ Active Workflows
+
+### `deploy.yml` - **VERCEL DEPLOYMENT**
+- **Status**: ✅ ACTIVE - Production deployment
+- **Purpose**: Deploys main site to Vercel production
+- **Trigger**: Push to main branch
+- **Features**: 
+  - Automated Vercel deployment
+  - Production environment setup
+  - Zero-downtime deployment
+
+### `deploy-docusaurus.yml` - **GITHUB PAGES DEPLOYMENT**
+- **Status**: ✅ ACTIVE - Documentation site
+- **Purpose**: Deploys main site to GitHub Pages
+- **Trigger**: Push to main branch or manual dispatch
+- **Features**:
+  - Builds and deploys documentation
+  - GitHub Pages integration
+  - Jekyll disabled (.nojekyll)
+
+### `publish-package.yml` - **PACKAGE PUBLISHING**
+- **Status**: ✅ ACTIVE - Package distribution
+- **Purpose**: Publishes CLI package to GitHub Packages
+- **Trigger**: Release published or manual dispatch
+- **Features**:
+  - Automated version management
+  - GitHub Packages publishing
+  - NPM registry integration
+
+## 📊 Download Tracking System
+
+**Current Architecture**: Direct Supabase database integration
+
+- **Method**: CLI directly sends tracking data to Supabase API endpoint
+- **Endpoint**: `https://www.aitmpl.com/api/track-download-supabase`
+- **Database**: Supabase PostgreSQL with anonymous data collection
+- **Real-time**: Immediate tracking on component installation
+- **Privacy**: Completely anonymous, no personal data collected
+
+## Usage Instructions
+
+### For Production Deployment
+**Use**: `deploy.yml` (triggers automatically on main branch)
+
+### For Documentation Updates  
+**Use**: `deploy-docusaurus.yml` (triggers automatically on main branch)
+
+### For Package Publishing
+**Use**: `publish-package.yml`
+
+```bash
+# Trigger manual package publishing
+gh workflow run "Publish Package to GitHub Packages" \
+  --field version=patch
+```
+
+## Migration History
+
+**Previous Tracking System**: The project previously used multiple GitHub Actions workflows for download tracking:
+- `analytics-processor.yml` - Processed GitHub Issues as data backend
+- `tracking-dispatch.yml` - Handled repository dispatch events  
+- `process-tracking-logs.yml` - Processed GitHub Pages access logs
+- `simple-tracking.yml` - Manual workflow dispatch system
+
+**Current System**: All tracking workflows have been **removed** and replaced with direct Supabase database integration from the CLI. This provides:
+- ✅ Real-time tracking (no workflow delays)
+- ✅ Better performance (no GitHub API rate limits)
+- ✅ Simpler maintenance (no complex workflow logic)
+- ✅ Higher reliability (no dependency on GitHub Actions)
+
+## Troubleshooting
+
+### Workflow Issues
+- **Deployment failed**: Check Vercel token and environment variables
+- **Pages not updating**: Verify GitHub Pages settings and branch configuration
+- **Package publishing failed**: Ensure GitHub token has packages:write permission
+
+### Download Tracking Issues
+- **Tracking not working**: Verify CLI is updated and Supabase endpoint is accessible
+- **Debug tracking**: Run CLI with `CCT_DEBUG=true` environment variable
+- **Opt-out**: Set `CCT_NO_TRACKING=true` to disable tracking
+
+---
+
+Last updated: 2025-08-19  
+Active tracking system: Direct Supabase database integration

package/.github/workflows/deploy-docusaurus.yml

@@ -0,0 +1,31 @@
+name: Deploy Main Site
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-main-site:
+    name: Deploy Main Site to Root
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Prepare deployment directory
+        run: |
+          mkdir -p _site
+          cp -a docs/. _site/
+          touch _site/.nojekyll
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _site
+          cname: aitmpl.com

package/.github/workflows/deploy.yml

@@ -0,0 +1,33 @@
+name: Deploy to Vercel
+
+on:
+  push:
+    branches:
+      - main  # Only deploy main branch to production
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install Vercel CLI
+        run: npm install --global vercel@latest
+
+      - name: Pull Vercel Environment Information
+        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Build Project Artifacts
+        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Deploy Project Artifacts to Vercel
+        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}