VineGuard MCP - IDE Integration Server 🔧

Enterprise-grade MCP server for AI-powered testing directly in your IDE

VineGuard MCP v2.1.4 provides AI-powered testing capabilities with enterprise security features directly within your IDE. Perfect for Claude Code, Cursor, VS Code, and any MCP-compatible development environment.

🎯 What is VineGuard MCP?

VineGuard MCP is the Model Context Protocol server that brings VineGuard's AI testing capabilities directly into your IDE. It's designed for:

• ✅ IDE Integration: Seamless testing within your development environment
• ✅ Interactive AI: Natural language commands and real-time assistance
• ✅ Component Testing: Specialized React/Vue/Angular testing capabilities
• ✅ Enterprise Security: Advanced security features and audit trails

Looking for command-line automation? Check out VineGuard CLI for CI/CD pipelines and terminal workflows.

🚀 Quick Installation

For Claude Code Users

# Install the MCP server globally
npm install -g vineguard-mcp

# Add via Claude Code CLI (if available)
claude mcp add vineguard-mcp

For Other IDE Users

# Install globally
npm install -g vineguard-mcp

# Configure in your IDE (see configuration examples below)

⚙️ IDE Configuration

Claude Code

Add to .claude/claude_project_config.json:

{
  "mcpServers": {
    "vineguard": {
      "command": "npx",
      "args": ["vineguard-mcp"],
      "env": {
        "VINEGUARD_PROJECT_ROOT": ".",
        "VINEGUARD_MODE": "orchestrator",
        "VINEGUARD_DEFAULT": "intelligent"
      }
    }
  }
}

Cursor

Add to your MCP settings:

{
  "mcpServers": {
    "vineguard": {
      "command": "npx",
      "args": ["vineguard-mcp"],
      "env": {
        "VINEGUARD_PROJECT_ROOT": ".",
        "VINEGUARD_MODE": "orchestrator"
      }
    }
  }
}

VS Code (with MCP Extension)

Configure in your VS Code MCP settings:

{
  "mcp.servers": {
    "vineguard": {
      "command": "npx",
      "args": ["vineguard-mcp"],
      "env": {
        "VINEGUARD_PROJECT_ROOT": ".",
        "VINEGUARD_MODE": "orchestrator"
      }
    }
  }
}

HTTP Mode (Cloud/Server Deployment)

# Start HTTP server
VINEGUARD_TRANSPORT=http VINEGUARD_HTTP_PORT=3001 npx vineguard-mcp

# Health check
curl http://localhost:3001/health

# Metrics
curl http://localhost:3001/metrics

🛠️ Available MCP Tools

When VineGuard MCP server is running, these 12 tools become available in your IDE:

🔄 Workflow Tools (Complete Testing Pipeline)

analyze_prd

Reads your PRD, extracts test scenarios, and creates comprehensive test strategies.

"analyze my PRD and extract test scenarios"
"read this requirements document and create a test strategy"

create_test_plan

Generates detailed test plans based on your code and requirements.

"create a comprehensive test plan for my user authentication system"
"generate test scenarios for this React component"

generate_vineguard_prd

Creates a normalized VineGuard PRD from your existing codebase and requirements.

"analyze my codebase and generate a comprehensive PRD"
"create technical requirements from my existing implementation"

detect_bugs

Scans your code for potential issues, bugs, and security vulnerabilities.

"scan my code for potential bugs and security issues"
"analyze this component for common React anti-patterns"

generate_fixes

Creates fixes for detected issues with regression test coverage.

"fix the issues you found and add tests to prevent regression"
"generate solutions for the security vulnerabilities"

⚡ Core Tools (Essential Testing Operations)

scan_project

Comprehensive project analysis including structure, patterns, and technology detection.

"scan my project and understand its architecture"
"analyze the project structure and dependencies"

run_tests

Execute tests with enhanced debugging context and intelligent failure analysis.

"run my tests and analyze any failures"
"execute the test suite with detailed debugging"

generate_test

Create comprehensive test suites with framework-specific optimizations.

"generate comprehensive tests for my authentication service"
"create React Testing Library tests for this component"

analyze_code

Deep code analysis with quality metrics and improvement recommendations.

"analyze this code for quality and performance issues"
"review my implementation and suggest improvements"

setup_testing

Initialize testing infrastructure with best practices and configurations.

"set up testing infrastructure for my React project"
"configure Jest and Testing Library with best practices"

🔒 Security Tools (Enterprise-Grade Protection)

security_audit

Comprehensive security scanning with CVSS vulnerability scoring.

"perform a security audit of my application"
"scan for vulnerabilities and provide CVSS scores"

test_component

Specialized testing for React/Vue/Angular components with accessibility checks.

"test this React component for accessibility and functionality"
"generate comprehensive Vue component tests"

🚀 What's New in v2.1.4

🔒 Enterprise Security Features

• Input Validation & Sanitization: Protection against all injection attacks
• Rate Limiting: Tool-specific abuse prevention (configurable)
• Path Traversal Protection: Secure file access with bounds checking
• Security Audit Tool: Comprehensive vulnerability scanner with CVSS scoring
• Zero Security Issues: No eval() usage, proper sanitization

🧪 Enhanced Testing Capabilities

• Component Testing: React/Vue/Angular specialized test generation
• Visual Regression: Automated visual testing integration
• Accessibility Testing: WCAG compliance testing built-in
• 12 Total Tools: Expanded from 10 comprehensive tools

🌐 Transport & Deployment Options

• HTTP Transport: REST API mode alongside stdio transport
• Metrics API: /health and /metrics endpoints
• Docker Ready: Production containerization
• Serverless: AWS Lambda, Google Cloud Run configurations
• CORS Support: Configurable cross-origin resource sharing

🔄 Latest Updates

• Enhanced Claude Code Integration: Improved MCP configuration for seamless setup
• Dependency Optimization: Updated to use npm versions instead of workspace dependencies
• Performance Improvements: Optimized response handling and token management

💬 Natural Language Examples

Here are examples of how you can interact with VineGuard MCP in your IDE:

Project Analysis

"scan my project for security vulnerabilities"
"analyze my React components for testing coverage"
"understand my project structure and suggest improvements"

Test Generation

"generate comprehensive tests for my authentication module"
"create Jest tests for this user service with edge cases"
"write Playwright tests for my checkout flow"

Component Testing

"test this React component for accessibility compliance"
"generate Vue component tests with user interaction scenarios"
"create Angular component tests with dependency injection"

Security & Quality

"audit my code for security vulnerabilities"
"scan for potential performance bottlenecks"
"review this implementation for code quality issues"

Workflow Operations

"analyze my PRD and create a complete test strategy"
"generate a technical requirements document from my code"
"create fixes for the issues you found with regression tests"

🔧 Configuration Options

Environment Variables

# Project settings
export VINEGUARD_PROJECT_ROOT="."
export VINEGUARD_MODE="orchestrator"
export VINEGUARD_DEFAULT="intelligent"

# Transport settings
export VINEGUARD_TRANSPORT="stdio"  # or "http"
export VINEGUARD_HTTP_PORT="3001"

# Security settings
export VINEGUARD_RATE_LIMIT="100"
export VINEGUARD_ENABLE_SECURITY_AUDIT="true"

# Performance settings
export VINEGUARD_MAX_TOKENS="16000"          # AI token limit (default: 16000)
export VINEGUARD_MAX_RESPONSE_LENGTH="400000" # Response size limit in chars (default: 400KB)

# Feature toggles
export VINEGUARD_ENABLE_MCP_ORCHESTRATION="true"
export VINEGUARD_COMPONENT_TESTING="true"

Advanced Configuration

Create a vineguard-mcp.config.js file:

export default {
  // MCP server settings
  transport: 'stdio', // or 'http'
  httpPort: 3001,

  // Security settings
  security: {
    rateLimit: 100,
    enableAudit: true,
    validateInputs: true
  },

  // Testing preferences
  testing: {
    frameworks: ['jest', 'playwright', 'cypress'],
    componentTesting: true,
    accessibilityTesting: true
  },

  // AI settings
  ai: {
    mode: 'orchestrator',
    default: 'intelligent',
    enableOrchestration: true,
    maxTokens: 16000,              // AI token limit
    maxResponseLength: 100000      // Response size limit in characters
  }
};

🐳 Docker Deployment

Quick Start with Docker

# Pull the image
docker pull vineguard/mcp-server

# Run with environment variables
docker run -d \
  -p 3001:3001 \
  -e VINEGUARD_TRANSPORT=http \
  -e VINEGUARD_MODE=orchestrator \
  vineguard/mcp-server

Docker Compose

version: '3.8'
services:
  vineguard-mcp:
    image: vineguard/mcp-server
    ports:
      - "3001:3001"
    environment:
      - VINEGUARD_TRANSPORT=http
      - VINEGUARD_MODE=orchestrator
      - VINEGUARD_ENABLE_SECURITY_AUDIT=true
    volumes:
      - ./project:/workspace
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
      interval: 30s
      timeout: 10s
      retries: 3

☁️ Cloud Deployment

AWS Lambda

// lambda-handler.js
import { McpServer } from 'vineguard-mcp';

export const handler = async (event, context) => {
  const server = new McpServer({
    transport: 'http',
    mode: 'orchestrator'
  });

  return await server.handleRequest(event, context);
};

Google Cloud Run

FROM node:20-alpine
WORKDIR /app
RUN npm install -g vineguard-mcp
EXPOSE 3001
ENV VINEGUARD_TRANSPORT=http
ENV VINEGUARD_HTTP_PORT=3001
CMD ["vineguard-mcp"]

🤔 MCP vs CLI: Which Should I Use?

Use VineGuard MCP when:

• ✅ Working interactively in Claude Code, Cursor, or VS Code
• ✅ Want natural language commands while coding
• ✅ Need real-time AI assistance during development
• ✅ Prefer IDE-integrated testing workflows
• ✅ Building enterprise applications requiring security audits

Use VineGuard CLI when:

• ✅ Building CI/CD pipelines that need automated testing
• ✅ Working primarily in the terminal/command line
• ✅ Need to batch process multiple projects
• ✅ Creating automation scripts that integrate testing

Use Both when:

• ✅ Your team uses different workflows (some prefer CLI, others IDE)
• ✅ You want MCP for development + CLI for automation
• ✅ Building comprehensive testing strategies

🔒 Enterprise Security Features

Input Validation & Sanitization

• Path Traversal Protection: Prevents access outside project boundaries
• Command Injection Prevention: Sanitizes all user inputs
• XSS Protection: Escapes outputs appropriately

Rate Limiting

• Tool-specific Limits: Configurable limits per tool
• Request Throttling: Prevents abuse and resource exhaustion
• Graceful Degradation: Maintains service under load

Security Auditing

• CVSS Scoring: Industry-standard vulnerability scoring
• Dependency Scanning: Checks for known vulnerabilities
• Code Pattern Analysis: Identifies security anti-patterns

⚡ Performance & Troubleshooting

Token Limits

VineGuard MCP automatically handles token limits for AI operations:

• Default Token Limit: 16,000 tokens per AI request
• Configurable: Set via VINEGUARD_MAX_TOKENS environment variable
• Auto-scaling: Automatically manages request size based on available tokens

Response Size Management

Large responses are automatically handled:

• Default Response Limit: 400KB (400,000 characters)
• Auto-truncation: Large responses are safely truncated with metadata
• Configurable: Set via VINEGUARD_MAX_RESPONSE_LENGTH environment variable

Example truncated response:

{
  "analysis": {
    "files": [...],
    "summary": "..."
  }
}

... [RESPONSE TRUNCATED] ...

Original response was 250000 characters (244.1KB).
Showing first 99800 characters.
To see full response, increase VINEGUARD_MAX_RESPONSE_LENGTH environment variable.

Common Issues

"Response too large" errors:

# Increase response size limit (from default 400KB)
export VINEGUARD_MAX_RESPONSE_LENGTH="800000"  # 800KB

# Or reduce scope of analysis
vineguard-mcp scan_project --path=./src --deep=false --includeFileContents=false

"Token limit exceeded" errors:

# Increase token limit
export VINEGUARD_MAX_TOKENS="32000"

# Or break requests into smaller chunks

Performance optimization:

# Enable parallel processing (if supported)
export VINEGUARD_ENABLE_PARALLEL="true"

# Reduce analysis depth for faster responses
export VINEGUARD_DEFAULT_DEPTH="2"

📊 Monitoring & Metrics

Health Checks

# Basic health check
curl http://localhost:3001/health

# Detailed metrics
curl http://localhost:3001/metrics

Metrics Collected

• Request Count: Total number of tool requests
• Response Times: Latency metrics per tool
• Error Rates: Success/failure ratios
• Security Events: Audit trail of security-related events

🔗 Related Packages

• VineGuard CLI: Command-line automation tool
• VineGuard Core: Core functionality
• VineGuard Utils: Shared utilities

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Main Project: VineGuard Monorepo
• MCP Package: vineguard-mcp
• CLI Package: vineguard
• Issues: Report Issues
• Documentation: Full Docs