VineGuard MCP Server v2.0 🍇🔒

Enterprise-grade AI testing partner with comprehensive security features for Claude Code, Cursor, and MCP-compatible IDEs

VineGuard MCP Server v2.0 provides AI-powered testing capabilities with enterprise security features directly within your IDE. Complete workflow from PRD analysis to automated fixes with zero vulnerabilities.

🚀 What's New in v2.0.0

🔒 Enterprise Security

• 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

• 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

🌐 Cloud & Deployment

• 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

🚀 Quick Installation

For Claude Code Users

# Add via Claude Code CLI
claude mcp add vineguard-mcp-server-standalone

# Or manually install
npm install -g vineguard-mcp-server-standalone

IDE Configuration

Claude Code - Add to .claude/claude_project_config.json:

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

Cursor - Add to MCP settings:

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

HTTP Mode (Cloud/Server):

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

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

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

🛠️ All 12 Available Tools

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

🔄 Workflow Tools (Complete Testing Pipeline)

analyze_prd

Analyze Product Requirements Document and extract user stories

Ask Claude: "analyze my PRD and extract test scenarios"

Features:

• Extracts user stories and acceptance criteria
• Identifies test scenarios automatically
• Risk assessment for testing priorities
• Natural language requirement parsing

create_test_plan

Generate comprehensive test plans based on PRD and code analysis

Ask Claude: "create a comprehensive test plan for my project"

Features:

• Risk-based test prioritization
• Multi-framework test strategy
• Coverage target recommendations
• Execution timeline planning

generate_vineguard_prd

Create normalized VineGuard PRD from user requirements

Ask Claude: "generate a standardized PRD from my requirements"

Features:

• Standardized requirement format
• Test strategy integration
• Quality gate definitions
• Traceability matrix

detect_bugs

Proactive bug detection using static analysis and pattern recognition

Ask Claude: "scan my code for bugs and security vulnerabilities"

Features:

• Static code analysis
• Security vulnerability detection
• Performance issue identification
• Pattern-based bug detection

generate_fixes

Generate automated fixes for detected issues with regression tests

Ask Claude: "generate fixes for the security issues you found"

Features:

• Automated fix generation
• Regression test creation
• Safe application with backup
• Change impact analysis

⚡ Core Tools (Essential Operations)

scan_project

Analyze project structure, detect frameworks, and assess testing setup

Ask Claude: "scan my project and analyze my testing setup"

Features:

• Framework detection (React, Vue, Angular, Next.js, etc.)
• Testing infrastructure analysis
• Dependency scanning
• Coverage assessment

run_tests

Execute tests using detected or specified test framework

Ask Claude: "run my tests with coverage reporting"

Supported Frameworks:

• Jest: Unit and integration tests
• Vitest: Fast Vite-native testing
• Playwright: Cross-browser E2E testing
• Cypress: Developer-friendly E2E tests

Features:

• Multi-framework execution
• Coverage reporting
• Watch mode support
• Parallel test execution

generate_test

Generate comprehensive test files for components or functions

Ask Claude: "generate comprehensive tests for src/utils/auth.js"

Test Types:

• Unit Tests: Individual function testing
• Integration Tests: Module interaction testing
• E2E Tests: Full user workflow testing

Templates:

• Basic: Simple test structure
• Comprehensive: Full coverage with edge cases
• Component: Framework-specific component tests

analyze_code

Analyze code for common issues, anti-patterns, and improvements

Ask Claude: "analyze my authentication code for security issues"

Analysis Patterns:

• Security: XSS, injection vulnerabilities, eval() usage
• Performance: Expensive operations, memory leaks
• Accessibility: WCAG compliance, keyboard navigation
• React Patterns: Hook optimization, performance patterns
• Async Errors: Promise handling, error boundaries

setup_testing

Initialize testing setup for the project with recommended configurations

Ask Claude: "setup Jest testing for my React project"

Supported Setups:

• Jest: React, Node.js, TypeScript configurations
• Vitest: Vite-based project setup
• Playwright: Cross-browser E2E setup
• Cypress: Component and E2E setup

🔒 Security & Component Tools (v2.0 New Features)

security_audit 🆕

Comprehensive security audit and vulnerability scanning with CVSS scoring

Ask Claude: "perform a complete security audit of my project"

Security Checks:

• 50+ Vulnerability Patterns: SQL injection, XSS, command injection
• CVSS Scoring: Industry-standard vulnerability ratings
• Dependency Scanning: npm audit integration
• Hardcoded Secret Detection: API keys, passwords, tokens
• Security Score: 0-100 project security rating

Output Example:

{
  "securityScore": 85,
  "totalIssues": 12,
  "issuesBySeverity": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 5
  },
  "recommendations": [
    "Update vulnerable dependencies",
    "Remove hardcoded secrets",
    "Add input validation"
  ]
}

test_component 🆕

Generate specialized tests for React/Vue/Angular/Svelte components

Ask Claude: "generate comprehensive tests for my Button component with accessibility checks"

Framework Support:

• React: Hooks, context, lifecycle testing
• Vue: Composition API, props, events
• Angular: Services, dependency injection, lifecycle
• Svelte: Stores, reactive statements, events

Test Features:

• Component Analysis: Props, state, events, lifecycle
• Visual Testing: Snapshot and visual regression tests
• Accessibility Testing: WCAG compliance, keyboard navigation
• Interaction Testing: User events, form handling
• Performance Testing: Render optimization

Generated Test Example:

describe('Button Component', () => {
  it('renders without crashing', () => {
    render(<Button />);
    expect(screen.getByRole('button')).toBeInTheDocument();
  });

  it('handles click events correctly', async () => {
    const mockClick = jest.fn();
    const user = userEvent.setup();
    render(<Button onClick={mockClick} />);

    await user.click(screen.getByRole('button'));
    expect(mockClick).toHaveBeenCalled();
  });

  it('has no accessibility violations', async () => {
    const { container } = render(<Button />);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

🔒 Security Features

Input Validation & Sanitization

Every tool input is validated before execution:

• Path Validation: Prevents path traversal attacks
• Type Checking: Ensures correct parameter types
• Command Injection Prevention: Sanitizes all string inputs
• File Extension Validation: Only allows safe file types
• Bounds Checking: Validates file paths within project root

Rate Limiting

Tool-specific rate limits prevent abuse:

# Resource-intensive tools (slower limits)
run_tests: 10 requests/minute
detect_bugs: 5 requests/minute
security_audit: 5 requests/minute
generate_fixes: 3 requests/minute

# Analysis tools (moderate limits)
scan_project: 20 requests/minute
analyze_code: 30 requests/minute
generate_test: 25 requests/minute

# Light tools (higher limits)
analyze_prd: 50 requests/minute
create_test_plan: 40 requests/minute

Security Audit Deep Dive

Comprehensive vulnerability detection patterns:

1. Code Injection

   • eval() usage detection
   • Function() constructor usage
   • Dynamic code execution patterns

2. Cross-Site Scripting (XSS)

   • innerHTML assignments
   • document.write() usage
   • Unsanitized user input

3. SQL Injection

   • String concatenation in queries
   • Unsanitized database inputs

4. Information Disclosure

   • Console logging in production
   • Hardcoded secrets and API keys
   • Debug information exposure

5. Cryptographic Issues

   • Weak random number generation
   • Deprecated hash functions (MD5, SHA1)

🌐 HTTP Transport & Cloud Deployment

Environment Variables

# Transport Configuration
VINEGUARD_TRANSPORT=stdio              # stdio (default) or http
VINEGUARD_HTTP_PORT=3001              # Port for HTTP mode
VINEGUARD_MODE=orchestrator           # Server mode
VINEGUARD_DEFAULT=intelligent         # Default behavior
VINEGUARD_PROJECT_ROOT=.              # Project root path
VINEGUARD_ENABLE_MCP_ORCHESTRATION=true  # Enable orchestration

# Security Configuration
VINEGUARD_RATE_LIMIT_WINDOW=60000     # Rate limit window (ms)
VINEGUARD_MAX_FILE_SIZE=1048576       # Max file size for scanning

Docker Deployment

FROM node:20-alpine

# Install VineGuard
RUN npm install -g vineguard-mcp-server-standalone

# Security: Create non-root user
RUN addgroup -g 1001 -S vineguard && \
    adduser -S vineguard -u 1001

# Switch to non-root user
USER vineguard

# Expose HTTP port
EXPOSE 3001

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3001/health || exit 1

# Start HTTP server
CMD ["sh", "-c", "VINEGUARD_TRANSPORT=http VINEGUARD_HTTP_PORT=3001 vineguard-mcp-server-standalone"]

AWS Lambda Deployment

// lambda.js
const { HttpTransport } = require('vineguard-mcp-server-standalone/dist/transport/http');
const { Server } = require('@modelcontextprotocol/sdk/server/index');

const server = new Server({ name: 'vineguard', version: '2.0.0' });
const transport = new HttpTransport(server);

exports.handler = async (event, context) => {
  // Process HTTP requests through VineGuard
  return await transport.handleRequest(event);
};

Health & Metrics Endpoints

# Health Check
curl http://localhost:3001/health
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "uptime": 12345,
  "version": "2.0.0",
  "metrics": {
    "totalRequests": 150,
    "errorCount": 2,
    "averageResponseTime": 245
  }
}

# Detailed Metrics
curl http://localhost:3001/metrics
{
  "totalRequests": 150,
  "requestsByTool": {
    "scan_project": 50,
    "generate_test": 30,
    "security_audit": 20,
    "run_tests": 15
  },
  "errorCount": 2,
  "averageResponseTime": 245,
  "memory": {
    "rss": 52428800,
    "heapTotal": 29696000,
    "heapUsed": 25487360
  },
  "rateLimitStats": [
    {
      "key": "default-client:security_audit",
      "count": 3,
      "resetTime": 1642248600000
    }
  ]
}

🧪 Testing VineGuard with MCP Jest

VineGuard includes comprehensive MCP testing framework:

# Install MCP Jest testing
npm install -D mcp-jest

# Run MCP server tests
npm run test:mcp

# Run with coverage
npm run test:mcp:coverage

# Watch mode
npm run test:mcp:watch

Test Results Example:

🚀 Testing MCP server: node packages/mcp-server-standalone/dist/index.js

MCP Test Results
================

Tests: 14 passed, 0 failed, 0 skipped, 14 total
Pass rate: 100%
Duration: 70ms

CONNECTION TESTS
----------------
✅ Server Connection (58ms)
   Successfully connected to MCP server (ping successful)

CAPABILITY TESTS
----------------
✅ Capability Discovery (1ms)
   Found 12 tools, 4 resources, 0 prompts

TOOL TESTS
----------
✅ Tool 'scan_project' execution (3ms)
✅ Tool 'analyze_prd' execution (3ms)
✅ Tool 'security_audit' execution (5ms)
✅ Tool 'test_component' execution (4ms)

🔧 Migration Guide: v1.x → v2.0

Breaking Changes

• None: v2.0 is fully backward compatible
• All existing tools work exactly the same
• New security features are transparent

New Features to Use

1. Security Auditing

   # Before v2.0: Manual security checks
   # After v2.0: Automated security auditing
   "audit my project for security vulnerabilities"

2. Component Testing

   # Before v2.0: Generic test generation
   # After v2.0: Framework-specific component testing
   "generate React component tests with accessibility checks"

3. HTTP Transport

   # Before v2.0: stdio only
   # After v2.0: HTTP mode for cloud deployment
   VINEGUARD_TRANSPORT=http vineguard-mcp-server-standalone

Enhanced Security (Automatic)

All existing tools now automatically include:

• Input validation and sanitization
• Rate limiting protection
• Path traversal prevention
• Enhanced error handling

🚨 Troubleshooting

Common Issues

1. Rate Limit Exceeded

Error: Rate limit exceeded for run_tests. Try again in 45 seconds.

Solution: Wait for rate limit to reset or adjust VINEGUARD_RATE_LIMIT_WINDOW

2. Path Validation Failed

Error: Input validation failed: Path is outside project root

Solution: Use relative paths within your project directory

3. HTTP Mode Connection Issues

Error: ECONNREFUSED connecting to http://localhost:3001

Solution: Ensure HTTP mode is started: VINEGUARD_TRANSPORT=http vineguard-mcp-server-standalone

4. Security Audit Large Project

Error: Security audit failed: Request Too Large

Solution: Set VINEGUARD_MAX_FILE_SIZE or use includeNodeModules: false

Debug Mode

# Enable debug logging
DEBUG=vineguard* vineguard-mcp-server-standalone

# Verbose security audit
VINEGUARD_DEBUG=security vineguard-mcp-server-standalone

📊 Performance Benchmarks

🤝 Contributing

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

Development Setup

# Clone repository
git clone https://github.com/idvd20/vineguard.git
cd vineguard

# Install dependencies
pnpm install

# Build packages
pnpm build

# Run tests
pnpm test
pnpm test:mcp

# Start development server
cd packages/mcp-server-standalone
pnpm dev

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• NPM Package: vineguard-mcp-server-standalone
• GitHub Repository: VineGuard
• Documentation: VineGuard Docs
• Security Policy: SECURITY.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions

VineGuard MCP Server v2.0 - Enterprise-grade AI testing with comprehensive security features 🍇🔒

Built with ❤️ for the developer community