### Workspace Configuration Example

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Illustrates the structure of a response when a workspace is configured, including workspace details and code insights. This helps users understand the additional information provided by the tool.

```json
{
  "workspace_info": {
    "workspace_configured": true,
    "workspace_path": "/Users/you/project",
    "files_loaded": 3,
    "files_analyzed": [
      "src/auth.ts",
      "src/user.ts",
      "src/api.ts"
    ],
    "total_context_size": 15234
  },
  "code_insights": [
    "Potential issue in src/auth.ts at line 45: TODO: Add rate limiting",
    "Potential issue in src/api.ts at line 123: FIXME: Handle timeout"
  ]
}
```

--------------------------------

### Support Information

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Provides guidance on how to get support for issues, directing users to troubleshooting sections, server logs, and issue reporting.

```APIDOC
Support:
For issues or questions:
1. Check the [troubleshooting section](#troubleshooting)
2. Review [server logs](#) for detailed error messages
3. Open an issue with workspace configuration details (excluding sensitive paths)
```

--------------------------------

### Basic Vibe Check Mentor Usage

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

A simple example of using the vibe_check_mentor function without specifying any file paths, allowing the mentor to auto-discover relevant files based on the query.

```python
# Let the mentor auto-discover files
vibe_check_mentor(
    query="Should I use Redis or in-memory caching for the session store?"
)
```

--------------------------------

### Vibe CLI Setup and Usage

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Shell alias setup and command-line examples for using the vibe CLI for fast and deep analysis of issues and pull requests.

```bash
# Add to your ~/.bashrc, ~/.zshrc, or ~/.fish_config
alias vibe='python -m vibe_check.cli'

# Fast analysis
vibe quick check issue 31
vibe fast PR 44

# Deep analysis  
vibe deep issue 31
vibe comprehensive PR 44
```

--------------------------------

### Docker HTTP Deployment Quick Start

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Instructions for building and starting the vibe-check-mcp service using Docker Compose and verifying the HTTP endpoint.

```bash
# Build and start
docker-compose up --build

# Verify HTTP endpoint
curl -H "Accept: text/event-stream" http://localhost:8001/mcp/
```

--------------------------------

### MCP Configuration for Claude Desktop (Windows)

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Example MCP server configuration for Claude Desktop on Windows, including setting the WORKSPACE and PYTHONPATH environment variables for the vibe-check-mcp server.

```json
{
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "python",
      "args": ["-m", "vibe_check"],
      "env": {
        "WORKSPACE": "C:\\Users\\yourname\\projects\\my-app",
        "PYTHONPATH": "C:\\path\\to\\vibe-check-mcp\\src"
      }
    }
  }
}
```

--------------------------------

### Enhanced Vibe Check Mentor Usage

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Shows how to use the vibe_check_mentor function with workspace awareness. It includes examples of asking context-specific questions and explicitly providing file paths for analysis.

```python
# The mentor will now read actual TypeScript files
vibe_check_mentor(
    query="Should I refactor the UserAuthService.ts to use dependency injection?",
    reasoning_depth="comprehensive"
)

# Explicitly specify files to analyze
vibe_check_mentor(
    query="Review the error handling approach",
    file_paths=["src/services/api.py", "src/utils/errors.py"]
)
```

--------------------------------

### Native Host Deployment - One-Command Setup

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Installs the Vibe Check MCP server on a native host using a curl command to download and execute an installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/kesslerio/vibe-check-mcp/main/install.sh | bash
```

--------------------------------

### Project Setup (Example)

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/README.md

A basic example of how one might interact with the `analyze_code` tool, assuming a Python environment where the Vibe Check MCP library is installed.

```python
from vibe_check_mcp import analyze_code

code_snippet = """
def greet(name):
    print(f"Hello, {name}!")
"""

analysis_result = analyze_code(code_snippet, mode='Deep')
print(analysis_result)
```

--------------------------------

### Native Host Deployment - Manual Installation

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Steps for manually installing the Vibe Check MCP server by cloning the repository and installing Python dependencies.

```bash
# Clone and install
git clone https://github.com/kesslerio/vibe-check-mcp.git
cd vibe-check-mcp
pip install -r requirements.txt

# Verify installation
PYTHONPATH=src python -m vibe_check server --help
```

--------------------------------

### CLI Command Help Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/VIBE_LANGUAGE_STYLE_GUIDE.md

Shows examples of how CLI help messages can be adapted for Professional, Casual, and Playful vibe levels.

```bash
# Professional
claude analyze-issue 42 --comprehensive

# Casual  
vibe check issue 42

# Playful
deep vibe check issue 42 - let's see what's up!
```

--------------------------------

### Development Setup and Execution

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/CONTRIBUTING.md

Steps to set up the development environment, install dependencies, configure environment variables, and run the Vibe Check MCP server.

```bash
# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/vibe-check-mcp.git
cd vibe-check-mcp

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment variables
export GITHUB_TOKEN="your_github_token"  # For GitHub integration testing
export VIBE_CHECK_DEV_MODE="true"       # Enable dev tools

# 5. Run tests to verify setup
pytest

# 6. Start the MCP server for testing
PYTHONPATH=src python -m vibe_check server
```

--------------------------------

### MCP Configuration for Claude Desktop (macOS)

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Example MCP server configuration for Claude Desktop on macOS, including setting the WORKSPACE and PYTHONPATH environment variables for the vibe-check-mcp server.

```json
{
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "python",
      "args": ["-m", "vibe_check"],
      "env": {
        "WORKSPACE": "/Users/yourname/projects/my-app",
        "PYTHONPATH": "/path/to/vibe-check-mcp/src"
      }
    }
  }
}
```

--------------------------------

### MCP Configuration for VS Code with Continue.dev

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Example MCP server configuration for VS Code using the Continue.dev extension, utilizing the ${workspaceFolder} variable to dynamically set the WORKSPACE environment variable.

```json
{
  "models": [...],
  "mcpServers": {
    "vibe-check-mcp": {
      "command": "python",
      "args": ["-m", "vibe_check"],
      "env": {
        "WORKSPACE": "${workspaceFolder}"  // Uses current VS Code workspace
      }
    }
  }
}
```

--------------------------------

### Advanced Configuration: Multiple Workspaces

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Demonstrates how to switch between different projects by updating the WORKSPACE environment variable and restarting the MCP server.

```bash
# Project A
export WORKSPACE="/path/to/project-a"

# Project B  
export WORKSPACE="/path/to/project-b"
```

--------------------------------

### Advanced Configuration: Project Registry (Future)

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Outlines the upcoming feature for a project registry, enabling quick switching between projects and auto-discovery based on context.

```python
# Register projects
register_project("frontend", "/Users/you/projects/web-app")
register_project("backend", "/Users/you/projects/api-server")

# Mentor auto-discovers based on context
vibe_check_mentor(query="Review the React components")  # Uses frontend
vibe_check_mentor(query="Check the database models")    # Uses backend
```

--------------------------------

### Troubleshooting Permission Errors

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Guides users on how to resolve 'permission denied' errors. This involves checking read access for the MCP server process and file permissions.

```APIDOC
Troubleshooting: Permission Errors

If you get permission denied errors:
1. Verify the MCP server process has read access
2. Check file permissions: `ls -la /path/to/file`
3. On Windows, check if files are locked by another process
```

--------------------------------

### Validation Output Example

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

An example of the configuration validation results, showing critical, warning, and informational messages with corresponding suggestions.

```text
Configuration Validation Results:
========================================

CRITICAL:
  ❌ Missing critical dependencies: fastmcp
     💡 Install missing dependencies: pip install fastmcp

WARNING:
  ⚠️ Claude CLI not found in PATH
     💡 Install Claude CLI or add it to your PATH for full functionality
  ⚠️ No MCP configuration files found
     💡 Create MCP configuration file for Claude CLI integration

INFO:
  ✅ Environment setup looks good
  ✅ Python path configuration detected
```

--------------------------------

### Migration: Generic Mentor to Workspace

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Explains the migration path from using the mentor without workspace configuration to adopting workspace features, emphasizing backward compatibility.

```APIDOC
Migration from Generic Mentor:
If you've been using the mentor without workspace configuration:
1. No breaking changes: Existing usage continues to work
2. Gradual adoption: Add WORKSPACE when ready for enhanced features
3. Backwards compatible: All existing parameters still supported
4. Same API: No code changes required
```

--------------------------------

### Performance: File and Size Limits

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Details the performance considerations, including the maximum number of files per request and the size limits for individual files and the total request.

```APIDOC
Performance Considerations:
- File limit: Maximum 10 files per request
- Size limit: 1MB per file, 5MB total
```

--------------------------------

### Claude Code Configuration - Legacy Manual Installation

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Configuration for Claude Code using a legacy manual installation of Vibe Check MCP. Not recommended due to complexity.

```bash
claude mcp add-json vibe-check '{
  "type": "stdio",
  "command": "python", 
  "args": ["-m", "vibe_check.server"],
  "env": {
    "PYTHONPATH": "'"$(pwd)"' /src",
    "GITHUB_TOKEN": "your_github_token_here"
  }
}'
```

--------------------------------

### Pattern Detection Message Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/VIBE_LANGUAGE_STYLE_GUIDE.md

Provides examples of rephrasing technical pattern detection messages into friendly coaching for developers.

```text
❌ "Infrastructure-Without-Implementation pattern detected"
✅ "Vibe killer spotted: building infrastructure before testing basics"

❌ "High severity anti-pattern"
✅ "Major vibe disruption - this could cause real headaches"

❌ "Immediate remediation required"
✅ "Let's fix this vibe before it spreads"
```

--------------------------------

### Vibe-Check Server Startup Commands

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Provides various command-line methods to start the vibe-check server, including auto-detection, explicit stdio transport, and direct module execution.

```bash
# Auto-detect transport (stdio for Claude clients)
python -m vibe_check server

# Explicit stdio transport
python -m vibe_check server --stdio

# Direct module execution
python -m vibe_check.server --stdio
```

--------------------------------

### Best Practice: Leverage Auto-discovery

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Encourages users to mention file names naturally within their questions to leverage the tool's auto-discovery capabilities.

```APIDOC
Best Practices:
3. Leverage auto-discovery: Mention file names naturally in questions
```

--------------------------------

### Pre-commit Hooks Setup and Execution

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/tests/README.md

Provides bash commands for installing and managing pre-commit hooks. This includes installing the pre-commit package, setting up the hooks for the repository, and manually running all hooks on the project files.

```bash
# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run hooks manually
pre-commit run --all-files

```

--------------------------------

### Install Vibe Check MCP via Smithery CLI

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Command to install the Vibe Check MCP server using the Smithery CLI, recommended for production and automated Claude Code integration.

```bash
npx -y @smithery/cli install vibe-check-mcp --client claude
```

--------------------------------

### Quick Test Commands in Claude Code

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Examples of commands to use within Claude Code for quick testing and analysis using the vibe-check MCP tools.

```bash
"Quick vibe check this text: I'm planning to build a custom HTTP client for the Stripe API"
```

```bash
"Show me the vibe check server status"
```

```bash
"Analyze this code for complexity patterns: [paste code]"
```

```bash
"Validate my MCP setup"
```

```bash
"Is Claude CLI working?"
```

```bash
"Check my configuration for integration issues"
```

--------------------------------

### Example Detection Flow

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Details the step-by-step process of how Vibe-Check-MCP detects integration anti-patterns and provides feedback to developers.

```text
1. Developer writes: "Building custom Cognee REST server with JWT"
2. MCP tool detects: Technology=Cognee, Red Flag=custom REST server  
3. Instant feedback: "🚨 Official cognee/cognee:main container available"
4. Next step: Test official solution before custom development
5. Outcome: Prevents unnecessary 2000+ line implementation
```

--------------------------------

### Claude Desktop Configuration - Manual Installation

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

JSON configuration for Claude Desktop to use a manually installed Vibe Check MCP server, specifying Python command and environment variables.

```json
{
  "mcpServers": {
    "vibe-check": {
      "command": "python",
      "args": ["-m", "vibe_check.server", "--stdio"],
      "env": {
        "PYTHONPATH": "/path/to/vibe-check-mcp/src",
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}
```

--------------------------------

### Best Practice: Cache Sessions

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Suggests using session IDs for related questions to improve efficiency by caching previous interactions.

```APIDOC
Best Practices:
4. Cache sessions: Use session IDs for related questions
```

--------------------------------

### Integration Pattern Detection Prompts

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Examples of prompts for fast integration pattern analysis, technology scanning, and effort-complexity assessment.

```text
"Vibe check this integration plan for anti-patterns"
"Analyze for integration over-engineering"
"Fast pattern detection on this PR description"
"Quick tech scan for known integrations"
"Scan for Cognee, Supabase, OpenAI usage"
"Instant technology detection"
"Analyze integration effort complexity"
"Check if development effort matches integration complexity"
"Effort-value analysis for this implementation"
```

--------------------------------

### Automatic File Discovery with Vibe Check Mentor

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Illustrates how the Vibe Check Mentor automatically identifies and analyzes relevant files when they are mentioned in the query, such as 'user_service.py'.

```python
# Mentioning a file name triggers automatic loading
vibe_check_mentor(
    query="The authentication in user_service.py seems complex"
)
# Automatically loads and analyzes user_service.py
```

--------------------------------

### Best Practice: Use Relative Paths

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Advises using relative paths in queries to ensure portability and consistency across different team members' environments.

```APIDOC
Best Practices:
2. Use relative paths in queries: Makes queries portable across team members
```

--------------------------------

### Performance: Cache TTL and Auto-discovery

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Covers performance aspects related to caching and auto-discovery, specifying cache duration and the depth for auto-discovery searches.

```APIDOC
Performance Considerations:
- Cache TTL: Files cached for 1 hour per session
- Auto-discovery: Searches up to 3 directory levels deep
```

--------------------------------

### Vibe Check Configuration

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Example configuration file (.vibe-check/config.json) for the Vibe Check MCP system. It details settings for context loading, library detection, and project-specific patterns.

```json
// .vibe-check/config.json
{
    "context_loading": {
        "enabled": true,
        "cache_duration_minutes": 60,
        "library_detection": {
            "languages": ["python", "javascript", "typescript"],
            "max_files_to_scan": 1000,
            "timeout_seconds": 30
        }
    },
    "libraries": {
        "fastapi": {
            "version": "0.100+",
            "patterns": ["dependency-injection", "async-preferred"],
            "architecture": "microservices"
        },
        "react": {
            "version": "18.x",
            "patterns": ["hooks-preferred", "functional-components"]
        }
    },
    "project_patterns": {
        "authentication": "supabase-required",
        "database": "postgresql-preferred"
    },
    "exceptions": [
        "custom-auth-required-for-gdpr-compliance"
    ]
}
```

--------------------------------

### Best Practice: Set Workspace to Project Root

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Recommends setting the workspace to the project's root directory to provide the mentor with the most comprehensive context for analysis.

```APIDOC
Best Practices:
1. Set workspace to project root: This gives the mentor full context
```

--------------------------------

### Analyze Doom Loops - Real-World Example

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Demonstrates a real-world usage scenario for the analyze_doom_loops function with a sample architecture discussion exhibiting analysis paralysis.

```python
# Input: Architecture discussion showing analysis paralysis
analyze_doom_loops(
    content="""
    We need to decide between microservices and monolith architecture.
    Should we use REST APIs or GraphQL for communication?
    What about message queues - RabbitMQ vs Kafka vs Redis?
    On the other hand, a monolith might be simpler to start.
    But then again, microservices give us better scalability.
    However, we could also consider a modular monolith approach.
    What if we need to handle millions of requests later?
    The pros and cons of each approach need careful evaluation.
    """,
    analysis_type="comprehensive"
)
```

--------------------------------

### GitHub Issue Analysis with Vibe CLI

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Examples of using the vibe CLI for fast and deep analysis of GitHub issues, including specifying repositories.

```bash
# Basic pattern detection
vibe quick issue 31
vibe fast check issue 42 in facebook/react

# Comprehensive Claude-powered analysis
vibe deep issue 31
vibe comprehensive issue 42 in microsoft/typescript
```

--------------------------------

### Best Practice: Limit File Count

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Recommends limiting the number of files per request to a maximum of 5 to optimize performance and focus the analysis.

```APIDOC
Best Practices:
5. Limit file count: Focus on 3-5 most relevant files for best results
```

--------------------------------

### Troubleshooting Workspace Not Found

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Provides steps to resolve the 'No workspace configured' error. This includes verifying environment variables, path existence, and file permissions.

```APIDOC
Troubleshooting: Workspace Not Found

If you see "No workspace configured":
1. Verify WORKSPACE environment variable is set
2. Check the path exists and is a directory
3. Ensure the MCP server has read permissions
```

--------------------------------

### Vibe CLI Commands

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Examples of using the Vibe CLI for various analysis tasks, including integration patterns, quick tech scans, and effort analysis.

```bash
# Development workflow examples
vibe analyze integration patterns "Building custom Cognee server"
vibe quick tech scan "PR: Add Supabase integration"
vibe effort analysis "Custom auth implementation - 1500 lines"
```

```bash
# Before starting integration work
vibe analyze integration patterns "Planning Cognee integration for knowledge management"
```

```bash
# During PR review
vibe quick tech scan "PR: Custom Supabase authentication implementation"
```

```bash
# Validating technical decisions
vibe effort analysis "2000+ line custom integration vs official SDK"
```

```bash
# Comprehensive analysis with case studies
vibe analyze integration patterns "Custom vs official approaches" --detail comprehensive
```

--------------------------------

### Verification Commands for Vibe-Check Deployment

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Includes commands to test the CLI help, startup, MCP tool availability, and version information for the vibe-check project.

```bash
# Test CLI help
PYTHONPATH=src python -m vibe_check server --help

# Test startup (Ctrl+C to exit)
PYTHONPATH=src python -m vibe_check server --stdio

# Test MCP tools are available
PYTHONPATH=src python -c "from vibe_check.server import app; print('✅ MCP server loads successfully')"

# Check version
PYTHONPATH=src python -c "from vibe_check import __version__; print(f'Version: {__version__}')"
```

--------------------------------

### Claude Desktop Configuration - NPX Setup

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

JSON configuration for Claude Desktop to use the Vibe Check MCP server via NPX, including environment variables.

```json
{
  "mcpServers": {
    "vibe-check": {
      "command": "npx",
      "args": ["vibe-check-mcp", "--stdio"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}
```

--------------------------------

### Local Development Setup and Integration

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/README.md

Guides through setting up the Vibe Check MCP project locally, including cloning, installing dependencies, testing the server, and adding the local development server to Claude Code MCP.

```bash
# 1. Clone and install dependencies
git clone https://github.com/kesslerio/vibe-check-mcp.git
cd vibe-check-mcp
pip install -r requirements.txt

# 2. Test server locally
PYTHONPATH=src python -m vibe_check.server --help

# 3. Add local development server to Claude Code (with GitHub token)
claude mcp add vibe-check-local -e PYTHONPATH="$(pwd)/src" -e GITHUB_TOKEN="your_github_token_here" -- python -m vibe_check.server --stdio

# Or without GitHub token (public repos only)
claude mcp add vibe-check-local -e PYTHONPATH="$(pwd)/src" -- python -m vibe_check.server --stdio

# 4. Restart Claude Code
```

--------------------------------

### MCP Server Configuration (NPX vs. Local)

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Demonstrates the transition from an older Python-based MCP server setup to a simpler NPX approach, highlighting removed dependencies and configurations.

```bash
# OLD - Don't use this anymore
claude mcp add-json vibe-check '{
  "type": "stdio",
  "command": "/Users/username/.venv/bin/python",
  "args": ["-m", "vibe_check.server"],
  "env": {
    "PYTHONPATH": "/Users/username/project/src",
    "GITHUB_TOKEN": "your_token"
  },
  "cwd": "/Users/username/project"
}'

# NEW - Simple NPX approach
claude mcp add-json vibe-check '{
  "type": "stdio",
  "command": "npx",
  "args": ["vibe-check-mcp", "--stdio"],
  "env": {
    "GITHUB_TOKEN": "your_token"
  }
}'
```

--------------------------------

### Vibe Check Mentor Usage with Specific Files

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Shows how to provide a list of specific file paths to the vibe_check_mentor function for targeted analysis, ensuring the mentor focuses on the designated code.

```python
# Analyze specific files
vibe_check_mentor(
    query="Is this the right abstraction level?",
    file_paths=[
        "src/core/repository.ts",
        "src/services/user_service.ts"
    ]
)
```

--------------------------------

### Install Dependencies

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Installs all necessary project dependencies listed in the requirements file. This is crucial for resolving import errors and ensuring tools function correctly.

```bash
pip install -r requirements.txt
```

--------------------------------

### Technology Selection with vibe_check_mentor

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/api/vibe_check_mentor.md

Provides an example of using `vibe_check_mentor` for technology selection, such as comparing frameworks like Vue 3 and React. It requires a query and context, and optionally a context object `ctx`.

```python
await vibe_check_mentor(
    query="Vue 3 vs React for dashboard project",
    context="Team knows React, timeline 3 months",
    ctx=ctx
)
```

--------------------------------

### Detect Project Libraries Response Example

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

An example of the expected JSON response from the `detect_project_libraries` function, detailing identified libraries, their confidence scores, scan duration, files scanned, and overall detection confidence.

```json
{
    "libraries": {
        "fastapi": 0.95,        // High confidence (found @app.get decorators)
        "react": 0.92,          // High confidence (.tsx files + useState hooks)
        "supabase": 0.87,       // High confidence (requirements.txt + imports)
        "github": 0.78,         // Medium confidence (GitHub API patterns)
        "openai": 0.85          // High confidence (OpenAI client usage)
    },
    "scan_duration_ms": 245,
    "files_scanned": 156,
    "detection_confidence": 0.91
}
```

--------------------------------

### Quick Test Execution Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/tests/IMPLEMENTATION_SUMMARY.md

Demonstrates how to execute tests using the test runner script, including options for coverage, verbosity, and specific test categories. Also shows how to run tests directly with pytest.

```bash
# Run all tests with coverage
python tests/test_runner.py --category all --coverage --verbose

# Run specific categories
python tests/test_runner.py --category unit --verbose
python tests/test_runner.py --category security --verbose
python tests/test_runner.py --category performance --verbose

# Run with pytest directly
python -m pytest tests/unit/ -v --cov=src
python -m pytest -m security -v
python -m pytest -m performance --benchmark-only
```

--------------------------------

### File Analysis Example

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/api/vibe_check_mentor.md

Demonstrates how to analyze multiple files by providing a list of file paths and a working directory. This is useful for reviewing code implementations.

```python
result = await vibe_check_mentor(
    query="Review this authentication implementation",
    file_paths=[
        "/src/auth/login.py",
        "/src/auth/middleware.py",
        "/src/models/user.py"
    ],
    working_directory="/Users/dev/project",
    ctx=ctx
)
```

--------------------------------

### MCP Configuration Validation and Troubleshooting

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Details on the automatic startup validation and specific tools for validating MCP configuration and Claude CLI integration. Includes common issues and their solutions.

```APIDOC
MCP Configuration Validation and Troubleshooting:

Automatic Startup Validation:
- Claude CLI Availability: Checks if `claude` command is available and working.
- MCP Configuration Files: Validates structure of `.claude_desktop_config.json`, `mcp.json`, etc.
- Tool Permissions: Verifies permission configurations and allowlists.
- Environment Setup: Checks `PYTHONPATH`, `GITHUB_TOKEN`, and other variables.
- Dependencies: Validates critical Python packages (fastmcp, click, etc.).

Configuration Validation Tools:

1. `validate_mcp_configuration`:
   - Comprehensive validation of your entire MCP setup.
   - Usage in Claude Code:
     - "Validate my MCP configuration"
     - "Check my setup for integration issues"
     - "Diagnose my MCP configuration"
   - Returns: Detailed validation results with overall health status, grouped results by severity (Critical/Warning/Info), actionable recommendations, and summary statistics.

2. `check_claude_cli_integration`:
   - Quick Claude CLI specific health check.
   - Usage in Claude Code:
     - "Is Claude CLI working?"
     - "Quick Claude CLI check"
     - "Test Claude CLI integration"
   - Returns: Focused Claude CLI status with availability and version information, basic integration environment check, and quick action recommendations.

Common Configuration Issues:
- Claude CLI not found: Symptoms: "claude: command not found". Solution: Install Claude CLI or add to PATH.
- MCP config missing: Symptoms: Server starts but no tools available. Solution: Create MCP configuration file.
- Invalid JSON config: Symptoms: Server fails to start. Solution: Fix JSON syntax in configuration.
- Missing PYTHONPATH: Symptoms: Import errors, module not found. Solution: Set PYTHONPATH to include src directory.
- Permission denied: Symptoms: Tool access failures. Solution: Check file permissions and access controls.
```

--------------------------------

### Message Type Guidelines Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/VIBE_LANGUAGE_STYLE_GUIDE.md

Provides examples of how different message types (Success, Error, Status, Educational) should be phrased across Professional, Casual, and Playful vibe levels. This helps in maintaining a consistent tone.

```markdown
### Success Messages

| Context | Professional | Casual | Playful |
|---------|-------------|--------|---------|
| Analysis complete | "Analysis complete" | "Vibe check complete" | "Vibe check complete - you're killing it!" |
| No issues found | "No concerning patterns detected" | "Clean vibes detected! 🎯" | "Squeaky clean vibes! No drama here! 🌟" |
| Task finished | "Task completed successfully" | "All done - looking good!" | "Nailed it! 🎉" |

### Error Messages

| Context | Professional | Casual | Playful |
|---------|-------------|--------|---------|
| Error prefix | "❌ Error:" | "😅 Oops:" | "🚨 Whoopsie:" |
| Failed action | "Failed to" | "Couldn't" | "Epic fail on" |
| Config issues | "Configuration error" | "Config vibes aren't right" | "Config vibes are totally off" |
| File not found | "File not found" | "Can't find that file" | "That file is playing hide and seek 📁" |
| API timeout | "Request timeout" | "Request took too long ⏰" | "The vibes took forever to respond ⏰" |

### Status Messages

| Context | Professional | Casual | Playful |
|---------|-------------|--------|---------|
| Starting work | "Starting analysis" | "Checking the vibes..." | "Time to check those vibes! 🔍" |
| Processing | "Processing file" | "Scanning for vibe disruptions" | "Hunting for vibe killers" |
| Pattern found | "Pattern detected" | "Vibe pattern spotted" | "Caught a vibe killer!" |

### Educational/Coaching Messages

| Context | Professional | Casual | Playful |
|---------|-------------|--------|---------|
| Recommendation | "Recommendation:" | "Vibe restoration:" | "Let's restore those good vibes:" |
| Severity high | "🚨 HIGH PRIORITY" | "🚨 Major vibe disruption" | "🚨 MASSIVE vibe killer alert!" |
| Learn more | "Review documentation" | "Dig into the learning stuff" | "Time for some vibe education!" |
```

--------------------------------

### Python Development Environment

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/CONTRIBUTING.md

Basic Python setup and dependency installation for the Vibe Check MCP project.

```python
# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

--------------------------------

### Environment Variables Configuration

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Configuration of environment variables for GitHub integration and Claude CLI setup.

```bash
# GitHub integration (optional)
export GITHUB_TOKEN="your_github_token"

# Claude CLI configuration (for _llm tools)
export CLAUDE_CLI_NAME="claude"  # Custom CLI name if needed
```

--------------------------------

### Troubleshooting Files Not Loading

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Offers solutions for issues where files are not being loaded by the tool. This covers checking file extensions, directory constraints, file size limits, and logs.

```APIDOC
Troubleshooting: Files Not Loading

If files aren't being loaded:
1. Check file extensions are supported
2. Verify files are within WORKSPACE directory
3. Ensure files are under 1MB in size
4. Check logs for specific error messages
```

--------------------------------

### Web-Enhanced Research Prompts

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Examples of prompts for performing web-enhanced research on new frameworks and deployment options.

```text
"Research new-framework with web search"
"Find official deployment options for emerging-tool"
"Web search enhanced integration analysis"
```

--------------------------------

### Review Microservices Communication

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Initiates a review of the microservices communication pattern by providing relevant file paths. This function helps in understanding how different services interact within the system.

```python
vibe_check_mentor(
    query="Review our microservices communication pattern",
    file_paths=[
        "services/auth/main.go",
        "services/user/main.go",
        "shared/messaging/broker.go"
    ],
    reasoning_depth="comprehensive"
)
```

--------------------------------

### Success Celebration Message Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/VIBE_LANGUAGE_STYLE_GUIDE.md

Illustrates how success messages can be tailored for Professional, Casual, and Playful contexts.

```text
Professional: "Analysis completed. No issues detected."
Casual: "Vibe check complete - looking good! ✨"
Playful: "Vibe check done and dusted! Your code is absolutely vibing! 🎉"
```

--------------------------------

### Educational Content Message Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/VIBE_LANGUAGE_STYLE_GUIDE.md

Illustrates how to transform academic explanations into relatable and understandable guidance for developers.

```text
❌ "This pattern leads to technical debt accumulation"
✅ "This pattern creates more work later - nobody wants that!"

❌ "Insufficient validation of external dependencies"
✅ "Didn't check if the tools actually work - classic vibe killer"

❌ "Premature optimization detected"
✅ "Building fancy stuff before proving it works - we've all been there"
```

--------------------------------

### Integration Decision Analysis Prompts

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Examples of natural language prompts for analyzing integration alternatives and decision frameworks.

```text
"Check cognee integration alternatives"
"Validate docker vs custom approach for supabase"
"Integration decision check for claude api"
"Analyze this integration plan for anti-patterns"
"Check this text for custom development red flags"
"Integration vibe check of this technical document"
"Integration decision framework for cognee vs custom"
"Structured analysis of docker vs build approach"
"Clear thought framework for supabase integration"
```

--------------------------------

### Integration Decision Framework Example

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Demonstrates how to use the integration_decision_framework function with specific technology, custom features, and analysis type.

```python
integration_decision_framework(
    technology="cognee",
    custom_features="REST API, authentication, storage",
    decision_statement="Choose between official Cognee container vs custom development",
    analysis_type="weighted-criteria"
)
```

--------------------------------

### Vibe Check Mentor Session Caching

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Demonstrates the session caching feature of the Vibe Check Mentor. The first call loads files, and subsequent calls with `continue_session=True` reuse the cached content for improved performance.

```python
# First call loads files
result1 = vibe_check_mentor(
    query="Review the API design",
    session_id="my-session-123"
)

# Subsequent calls reuse cached files
result2 = vibe_check_mentor(
    query="What about error handling?",
    session_id="my-session-123",
    continue_session=True
)
```

--------------------------------

### Configuration Error Message

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Example message indicating an invalid JSON format in the .vibe-check/config.json file, with a fallback to default settings.

```text
❌ Configuration error: Invalid JSON in .vibe-check/config.json
📋 Using default configuration settings
```

--------------------------------

### Manual Docker Commands for Vibe-Check

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/MCP_DEPLOYMENT_GUIDE.md

Provides commands for building the Docker image, running it with a custom port, and using an environment file for configuration.

```bash
# Build image
docker build -t vibe-check-mcp .

# Run with custom port
docker run -p 8002:8002 -e MCP_SERVER_PORT=8002 vibe-check-mcp

# Run with environment file
docker run --env-file .env -p 8001:8001 vibe-check-mcp
```

--------------------------------

### Error Recovery Message Examples

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/VIBE_LANGUAGE_STYLE_GUIDE.md

Demonstrates variations in error recovery messages across Professional, Casual, and Playful tones.

```text
Professional: "GitHub API authentication required. Configure token."
Casual: "Need GitHub token for full vibe powers 💫"
Playful: "GitHub wants to know who we are - time for some auth magic! 🪄"
```

--------------------------------

### Context Loading Failure Message

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Example message displayed when project context cannot be loaded, showing the fallback to generic analysis mode.

```text
⚠️ Context loading failed: Integration knowledge base not found
📋 Falling back to generic analysis mode
```

--------------------------------

### Architecture Decisions with vibe_check_mentor

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/api/vibe_check_mentor.md

Demonstrates using `vibe_check_mentor` to get advice on architectural decisions, such as choosing between serverless and containers. It requires a query and context, and optionally a context object `ctx`.

```python
await vibe_check_mentor(
    query="Choosing between serverless and containers for API",
    context="Startup, variable traffic, 3 developers",
    ctx=ctx
)
```

--------------------------------

### GitHub Pull Request Analysis with Vibe CLI

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/USAGE.md

Examples of using the vibe CLI for fast and deep analysis of GitHub pull requests.

```bash
# Quick metrics and basic patterns
vibe quick PR 44
vibe fast check PR 32

# Full Claude CLI review
vibe deep PR 44  
vibe comprehensive PR 32
```

--------------------------------

### Privacy: Type Safe File Processing

Source: https://github.com/kesslerio/vibe-check-mcp/blob/main/docs/WORKSPACE_SETUP.md

Confirms that the tool is type-safe and only processes text-based source files, ensuring data integrity.

```APIDOC
Privacy and Security:
- Type safe: Only text-based source files are processed
```