npx @j0kz/mcp-agents@latest           # Auto-detect
npx @j0kz/mcp-agents@latest claude    # Claude Code
npx @j0kz/mcp-agents@latest cursor    # Cursor
npx @j0kz/mcp-agents@latest windsurf  # Windsurf
npx @j0kz/mcp-agents@latest qoder     # Qoder
npx @j0kz/mcp-agents@latest vscode    # VS Code
npx @j0kz/mcp-agents@latest roo       # Roo Code

Common Issues & Solutions

❌ Tools not appearing in chat?

• Solution: Restart your editor completely (close all windows)
• If still not working: Clear npm cache and reinstall

  npm cache clean --force
  npx @j0kz/mcp-agents@latest
  

❌ Commands not recognized?

• Try both English and Spanish variants
• Use natural language: "Review this file" instead of technical syntax
• Ask: "What MCP tools are available?" to see loaded tools

❌ Installation failed?

• Check you're on Node.js 18+ (node --version)
• Try with sudo/admin if permission issues
• Check your editor's config file was updated correctly

❌ "Module not found" errors?

• Run: npm cache clean --force
• Reinstall: npx @j0kz/mcp-agents@latest
• Restart editor

Still stuck? Open an issue or check the Wiki

Installation

# Install skills in any project
npx @j0kz/claude-skills

# Or install with MCP tools
npx @j0kz/mcp-agents install

Available Skills

Usage Examples

"Apply the debug-detective skill to find this bug"
"Use quick-pr-review before creating my PR"
"Follow zero-to-hero to understand this codebase"

Each skill includes:

• ✅ Quick start (30-second value)
• ✅ WITH MCP approach (automated)
• ✅ WITHOUT MCP approach (manual)
• ✅ Language-specific examples
• ✅ Pro tips and metrics

📖 Full Skills Documentation

Prerequisites

• Docker Desktop 4.50+ installed

Start the Gateway

# Clone and start
git clone https://github.com/j0KZ/mcp-agents.git
cd mcp-agents
docker compose -f docker-compose.mcp.yml up -d

Token Savings

How It Works

Instead of loading all 50 tool definitions (~10,000 tokens), the gateway provides:

• mcp-find - Search tools by keyword (no loading)
• mcp-add - Load specific tools on-demand
• code-mode - Execute workflows in sandbox (only results return)

Configure Your Editor

Copy the config for your editor from examples/client-configs/:

# Claude Desktop (macOS)
cp examples/client-configs/claude-desktop.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json

# VS Code
cp examples/client-configs/vscode-mcp.json .vscode/mcp.json

📖 Full Docker MCP Documentation

How to Use

Just ask Claude naturally - the tool understands both languages:

English Examples

"Review my auth.js file"
"Check this file for code smells"
"What issues are in src/utils/validator.js?"
"Review this code and suggest improvements"
"Analyze code quality in my components"

Spanish Examples (Ejemplos en Español)

"Revisar mi archivo auth.js"
"Revisar este archivo"
"Qué problemas hay en src/utils/validator.js?"
"Analizar calidad del código en mis componentes"
"Chequear este código"

What You Get

✓ Code Quality Report:

📊 Metrics:
  - Complexity: 42 (moderate)
  - Maintainability: 72/100
  - Lines of Code: 234
  - Duplicate blocks: 2

⚠️ Issues Found (5):
  1. Unused variable 'temp' on line 42
  2. Missing error handling in async function (line 56)
  3. Potential memory leak in event listener (line 89)
  4. Magic number should be a constant (line 112)
  5. Function too complex (18 branches) - line 145

✅ Auto-fixes available for 3 issues
  - Run "Apply auto-fixes to auth.js" to fix automatically

Features

• Quality metrics (complexity, maintainability, LOC)
• Auto-fix generation using Pareto principle (80/20 rule)
• Pattern detection and best practices
• Performance bottleneck identification
• Safe auto-apply mode

How to Use

English Examples

"Generate tests for calculatePrice function"
"Create tests for UserService class"
"Add tests to src/utils/helpers.js"
"Generate integration tests for the API"
"Write tests with edge cases for validateEmail"

Spanish Examples (Ejemplos en Español)

"Generar pruebas para la función calculatePrice"
"Generar tests para calculatePrice"
"Crear pruebas para la clase UserService"
"Agregar tests a src/utils/helpers.js"
"Escribir pruebas con casos extremos para validateEmail"

What You Get

✓ Test Suite Generated for calculatePrice()

📝 24 tests created:

Happy Path (8 tests):
  ✓ should calculate price with valid inputs
  ✓ should apply discount correctly
  ✓ should handle zero quantity
  ...

Edge Cases (6 tests):
  ✓ should handle negative prices
  ✓ should handle very large quantities
  ✓ should handle decimal precision
  ...

Error Handling (5 tests):
  ✓ should throw on null input
  ✓ should handle missing parameters
  ✓ should validate price range
  ...

Boundary Conditions (5 tests):
  ✓ should handle min/max values
  ✓ should handle boundary prices
  ...

📊 Estimated Coverage: 94%

Features

• Multiple framework support (Jest, Mocha, Vitest, AVA)
• Edge case detection
• Mock generation
• Coverage optimization
• Batch generation for multiple files

How to Use

English Examples

"Analyze project architecture"
"Find circular dependencies"
"Check for layer violations"
"Generate dependency graph"
"Show module info for src/services/auth.js"

Spanish Examples (Ejemplos en Español)

"Analizar arquitectura del proyecto"
"Analizar estructura del proyecto"
"Encontrar dependencias circulares"
"Buscar violaciones de capas"
"Generar gráfico de dependencias"
"Mostrar info del módulo src/services/auth.js"

What You Get

✓ Architecture Analysis Complete

🔍 Project Structure:
  - Total modules: 142
  - Max depth: 5 levels
  - Entry points: 3

⚠️ Issues Detected:

Circular Dependencies (2):
  1. auth.js → user.js → permissions.js → auth.js
  2. api.js → routes.js → api.js

Layer Violations (3):
  1. Presentation layer accessing Data layer directly
     src/components/UserList.jsx → src/db/queries.js

  2. Business layer bypassing abstraction
     src/services/order.js → src/db/connection.js

📊 Dependency Graph:
```mermaid
graph TD
    A[auth.js] --> B[user.js]
    B --> C[permissions.js]
    C --> A
    ...

💡 Suggestions:

• Break circular dependency in auth module
• Add abstraction layer for data access
• Consider splitting large modules

### Features
- Circular dependency detection
- Layer violation analysis
- Dependency graphs (Mermaid format)
- Module complexity metrics
- Configurable layer rules

</details>

<details>
<summary><b>🛡️ Security Scanner</b> - Vulnerability detection (Click to expand)</summary>

### How to Use

#### English Examples

"Scan for security vulnerabilities" "Check for SQL injection" "Find hardcoded secrets" "Scan the entire project for security issues" "Check auth.js for XSS vulnerabilities"

#### Spanish Examples (Ejemplos en Español)

"Escanear vulnerabilidades" "Escanear seguridad" "Buscar secretos hardcodeados" "Revisar inyección SQL" "Escanear todo el proyecto por problemas de seguridad" "Revisar auth.js por vulnerabilidades XSS"

### What You Get

```javascript
✓ Security Scan Complete

🔒 Vulnerabilities Found: 6

CRITICAL (2):
  1. SQL Injection Risk
     File: src/db/query.js:45
     Code: `SELECT * FROM users WHERE id = ${userId}`
     Fix: Use parameterized queries

  2. Hardcoded API Key
     File: src/config.js:8
     Code: const API_KEY = "sk-1234567890abcdef"
     Fix: Move to environment variables

HIGH (3):
  3. XSS Vulnerability
     File: src/templates/user.html:12
     Code: <div>{{{ userInput }}}</div>
     Fix: Use HTML escaping

  4. Path Traversal Risk
     File: src/files/handler.js:23
     Code: fs.readFile(`uploads/${filename}`)
     Fix: Validate and sanitize file paths

  5. Weak Cryptography
     File: src/auth/crypto.js:15
     Code: crypto.createHash('md5')
     Fix: Use SHA-256 or bcrypt

MEDIUM (1):
  6. Outdated Dependency
     Package: express@4.16.0 (CVE-2022-24999)
     Fix: Update to express@^4.18.0

📊 Summary:
  - Critical: 2
  - High: 3
  - Medium: 1
  - Low: 0

Features

• OWASP Top 10 detection
• Secret scanning (20+ patterns: API keys, passwords, tokens)
• SQL injection & XSS detection
• Dependency vulnerability checks (CVE scanning)
• Path traversal and command injection detection
• Customizable severity levels

How to Use

English Examples

"Design REST API for users and posts"
"Create GraphQL schema for a blog"
"Generate OpenAPI spec for my endpoints"
"Design API with OAuth2 authentication"
"Create REST endpoints for e-commerce"

Spanish Examples (Ejemplos en Español)

"Diseñar API REST para usuarios y posts"
"Diseñar API para usuarios"
"Crear esquema GraphQL para un blog"
"Generar especificación OpenAPI para mis endpoints"
"Diseñar API con autenticación OAuth2"

What You Get

✓ REST API Design Generated

📋 Endpoints Created (12):

Users Resource:
  GET    /api/v1/users          - List users (paginated)
  GET    /api/v1/users/:id      - Get user by ID
  POST   /api/v1/users          - Create user
  PUT    /api/v1/users/:id      - Update user
  DELETE /api/v1/users/:id      - Delete user

Posts Resource:
  GET    /api/v1/posts          - List posts
  GET    /api/v1/posts/:id      - Get post
  POST   /api/v1/posts          - Create post
  PUT    /api/v1/posts/:id      - Update post
  DELETE /api/v1/posts/:id      - Delete post

  GET    /api/v1/users/:id/posts - Get user's posts
  POST   /api/v1/users/:id/posts - Create post for user

🔒 Authentication: Bearer Token (JWT)
📄 Documentation: OpenAPI 3.0 spec generated
🧪 Mock Server: Ready to generate

Features

• REST & GraphQL API design
• OpenAPI 3.0 specification generation
• Client SDK generation (TypeScript, Python, Java, etc.)
• Mock server creation
• Multiple auth types (API Key, OAuth2, JWT)
• Automatic validation rules

How to Use

English Examples

"Design database schema for a blog"
"Create schema for users, posts, and comments"
"Design MongoDB schema for e-commerce"
"Generate migration for PostgreSQL"
"Create ER diagram for my schema"

Spanish Examples (Ejemplos en Español)

"Diseñar esquema de base de datos para un blog"
"Diseñar schema para blog"
"Crear esquema para usuarios, posts y comentarios"
"Diseñar esquema MongoDB para e-commerce"
"Generar migración para PostgreSQL"

What You Get

✓ Database Schema Generated (PostgreSQL)

📊 Tables Created (3):

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  username VARCHAR(100) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  title VARCHAR(255) NOT NULL,
  content TEXT NOT NULL,
  published BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE comments (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  post_id UUID NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_posts_user_id ON posts(user_id);
CREATE INDEX idx_comments_post_id ON comments(post_id);
CREATE INDEX idx_posts_published ON posts(published);

✓ Normalized to 3NF
✓ 3 indexes created
✓ Migration files ready
✓ ER diagram generated

Features

• SQL (PostgreSQL, MySQL) & NoSQL (MongoDB) support
• Automatic normalization (1NF, 2NF, 3NF, BCNF)
• Migration generation (up/down)
• ER diagram creation (Mermaid, PlantUML, DBML)
• Index optimization suggestions
• Seed data generation

How to Use

English Examples

"Generate README for this project"
"Add JSDoc comments to auth.js"
"Create API documentation"
"Generate changelog from git commits"
"Document all functions in utils/"

Spanish Examples (Ejemplos en Español)

"Generar README para este proyecto"
"Generar README"
"Agregar comentarios JSDoc a auth.js"
"Crear documentación de API"
"Generar changelog desde commits de git"

What You Get

✓ Documentation Generated

📄 README.md created with:

- Project description
- Installation instructions
- Usage examples
- API reference
- Badges (build, coverage, version)
- Table of contents
- Contributing guidelines
- License info

📝 JSDoc comments added (24 functions):
/\*\*

- Authenticates a user with email and password
- @param {string} email - User's email address
- @param {string} password - User's password (plain text)
- @returns {Promise<User>} Authenticated user object
- @throws {AuthError} If credentials are invalid
  \*/
  async function authenticateUser(email, password) { ... }

📊 API Documentation generated:

- All endpoints documented
- Request/response examples
- Authentication requirements
- Error codes and messages

📜 CHANGELOG.md updated:

## [1.2.0] - 2025-01-15

### Added

- User authentication system
- Password reset functionality

### Fixed

- Memory leak in event handlers

Features

• README generation (with badges, TOC, examples)
• JSDoc/TSDoc comment generation
• API documentation (from code)
• Changelog generation (from git history)
• Multiple styles (Standard, Google, TypeScript)
• Batch documentation for entire projects

How to Use

English Examples

"Extract this code block into a function"
"Convert callbacks to async/await in api.js"
"Simplify nested conditionals in validator.js"
"Remove dead code from utils/"
"Apply singleton pattern to DatabaseConnection"

Spanish Examples (Ejemplos en Español)

"Extraer este bloque de código en una función"
"Refactorizar este código"
"Convertir callbacks a async/await en api.js"
"Simplificar condicionales anidados en validator.js"
"Eliminar código muerto de utils/"

What You Get

✓ Refactoring Complete

Before (12 lines):
  function processUser(user, callback) {
    validateUser(user, function(err, valid) {
      if (err) return callback(err);
      if (!valid) return callback(new Error('Invalid'));
      saveUser(user, function(err, saved) {
        if (err) return callback(err);
        sendEmail(saved, function(err) {
          if (err) return callback(err);
          callback(null, saved);
        });
      });
    });
  }

After (7 lines, async/await):
  async function processUser(user) {
    const valid = await validateUser(user);
    if (!valid) throw new Error('Invalid user');
    const saved = await saveUser(user);
    await sendEmail(saved);
    return saved;
  }

✅ Improvements:
  - 42% fewer lines
  - Removed callback hell
  - Added proper error handling
  - More readable code

Features

• Extract function/method/class
• Convert callbacks to async/await
• Simplify conditionals (guard clauses, ternary)
• Remove dead code (unused vars, unreachable code)
• Apply design patterns (Singleton, Factory, Observer, Strategy, etc.)
• Variable renaming (consistent across codebase)
• Code metrics calculation

How to Use

English Examples

"Review, test, and document auth.js"
"Full security audit of the project"
"Complete code quality check"
"Review all files, find issues, generate tests, and fix"
"Design API, create schema, generate docs"

Spanish Examples (Ejemplos en Español)

"Revisar, probar y documentar auth.js"
"Auditoría de seguridad completa del proyecto"
"Revisión completa de calidad de código"
"Revisar archivos, encontrar problemas, generar tests"
"Diseñar API, crear schema, generar docs"

What You Get

✓ Workflow Pipeline Executed

🔄 Step 1/4: Code Review
  ✓ Reviewed auth.js
  ⚠️ Found 5 issues

🔄 Step 2/4: Security Scan
  ✓ Scanned for vulnerabilities
  🔴 Found 2 critical issues

🔄 Step 3/4: Test Generation
  ✓ Generated 18 tests
  📊 Coverage: 92%

🔄 Step 4/4: Documentation
  ✓ Added JSDoc comments
  ✓ Updated README

✅ Pipeline Complete (4/4 steps)

📊 Summary:
  - Issues found: 5
  - Critical vulnerabilities: 2
  - Tests generated: 18
  - Documentation: Updated

💡 Next Steps:
  1. Fix critical security issues
  2. Run tests: npm test
  3. Review auto-generated docs

Features

• Chain multiple MCP tools
• Pre-built workflows (quality check, security audit, full docs)
• Conditional execution (skip steps on errors)
• CI/CD integration templates
• Batch operations (multiple files/projects)
• Custom pipeline creation

How to Use

The Laziest Way (One Command)

npx @j0kz/auto-pilot

That's it! Auto-Pilot will:

• 🔍 Detect your project type automatically
• 📦 Install git hooks for quality checks
• 👀 Start watching files (auto-fix on save)
• 🧪 Generate tests for untested code
• 🔒 Fix security issues instantly
• 🧹 Clean up code automatically

English Examples

"Start auto-pilot"
"Fix everything automatically"
"Watch my files and fix on save"
"Install automation hooks"
"Make my code perfect without me doing anything"

Spanish Examples (Ejemplos en Español)

"Iniciar auto-pilot"
"Arreglar todo automáticamente"
"Observar mis archivos y corregir al guardar"
"Instalar hooks de automatización"
"Hacer mi código perfecto sin hacer nada"

What You Get

╔═══════════════════════════════════════════╗
║        🚀 AUTO-PILOT v1.0.36              ║
║   Zero-Effort Automation for Lazy Devs     ║
╚═══════════════════════════════════════════╝

📊 Detected: TypeScript React project with 234 files
✅ Git hooks installed (pre-commit, pre-push)
👀 Watching files for auto-fix...
🔧 Fixed 47 issues automatically:
  - Removed 12 console.log statements
  - Fixed 8 == to ===
  - Replaced 15 var with let/const
  - Added JSDoc to 12 functions
  - Generated tests for 5 untested files

✅ Auto-Pilot ready! Just write code, I'll handle the rest.

Features

• Smart Detection: Automatically detects language, framework, tools
• File Watching: Auto-fixes issues as you save files
• Git Hooks: Ensures quality before commits/pushes
• Auto-Fix Engine: Safely fixes common issues (console.log, ==, var, etc.)
• Test Generation: Creates tests for untested code
• Zero Config: Works out of the box, no setup needed
• Lazy Mode: For developers who want perfect code without thinking

CLI Commands

auto-pilot              # Start everything (default)
auto-pilot fix          # Fix all issues instantly
auto-pilot watch        # Watch mode only
auto-pilot detect       # Show what was detected
auto-pilot doctor       # Health check
auto-pilot lazy         # Ultra lazy mode 🦥

Git Hooks Installed

Pre-commit:

• Auto-fixes staged files
• Removes console statements
• Runs prettier & ESLint
• Generates missing tests

Pre-push:

• Runs full test suite
• Checks coverage (>55%)
• Security audit
• Build verification

Commit-msg:

• Enforces conventional commits
• Auto-fixes commit messages

The Laziness Scale

• Level 1: You run tests manually → Amateur
• Level 2: You have CI/CD → Getting there
• Level 3: You use linters → Decent
• Level 4: You have pre-commit hooks → Good
• Level 5: You use Auto-Pilot → LEGENDARY LAZY 🦥

# Quick setup - adds MCP quality checks to your CI pipeline
curl -o .github/workflows/mcp-quality.yml \
  https://raw.githubusercontent.com/j0KZ/mcp-agents/main/templates/github-actions/mcp-basic.yml

This will run Smart Reviewer, Test Generator, and Security Scanner on every PR.

# Automatically review code before committing
npx @j0kz/mcp-hooks-generator basic

Runs checks locally before pushing, catching issues early.

include:
  - remote: 'https://raw.githubusercontent.com/j0KZ/mcp-agents/main/templates/gitlab-ci/mcp-quality-gate.gitlab-ci.yml'

Integrates MCP tools into GitLab's CI/CD pipeline.