Project Health Auditor

A comprehensive MCP (Model Context Protocol) server for auditing project health for Next.js and Node.js projects. This package provides an MCP server that runs health assessments through Cursor AI integration.

Features

• 🔍 Comprehensive Health Assessment: Automated scoring across multiple categories (233 points total for Node.js, 228 for Next.js)
• 📊 Detailed Reports: JSON output with category breakdowns and actionable recommendations
• 🎯 MCP Server Integration: Use via Cursor AI with seamless integration
• 🔧 Framework Support: Next.js and Node.js projects
• ✅ Actionable Feedback: Clear, detailed feedback on what needs improvement

Installation

Recommended: Global Installation (Most Reliable)

npm install -g project-health-tracker

Alternative: Using npx (May have cache issues)

If you prefer using npx, see TROUBLESHOOTING.md for common issues.

Quick Start

1. Configure MCP Server in Cursor

Add the MCP server to your Cursor configuration:

For Cursor (Global Settings):

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

Option A: Global Installation (Recommended)

{
  "mcpServers": {
    "project-health-tracker": {
      "command": "project-health-tracker-mcp",
      "args": [],
      "env": {}
    }
  }
}

Option B: Using npx (Alternative)

{
  "mcpServers": {
    "project-health-tracker": {
      "command": "npx",
      "args": [
        "-y",
        "project-health-tracker"
      ],
      "env": {}
    }
  }
}

Note: If you encounter graceful-fs errors with npx, use Option A (global installation) or see TROUBLESHOOTING.md.

2. Use in Cursor

Once configured, you can use the MCP tool directly in Cursor:

@mcp review_project projectPath="." projectType="nextjs"

Or for Node.js projects:

@mcp review_project projectPath="." projectType="node"

The MCP server will automatically run comprehensive health assessments.

MCP Tool

The package provides one MCP tool for health assessment:

review_project

Run comprehensive project health assessment and get detailed health metrics.

Parameters:

• projectPath (string, required) - Path to the project root directory
• projectType (string, enum: nextjs|node, default: nextjs) - Project type for assessment
• outputFormat (string, enum: json|summary|detailed, default: detailed) - Output format for the assessment results

Usage in Cursor:

@mcp review_project projectPath="./my-project" projectType="nextjs" outputFormat="detailed"

Example for Node.js:

@mcp review_project projectPath="./my-api" projectType="node" outputFormat="json"

Assessment Categories

Next.js Projects (228 points total)

1. PROJECT_STRUCTURE (20 points)

   • App Router structure
   • Component organization
   • Utils/hooks/lib separation
   • Type definitions
   • Redux store organization

2. CODE_QUALITY (30 points)

   • ESLint configuration
   • Husky pre-commit hooks
   • TypeScript strict mode
   • Prettier setup
   • Gitignore

3. DEVELOPMENT_ENVIRONMENT (15 points)

   • IDE configuration
   • Auto-fix on save
   • Format on save
   • Cursor rules

4. TECH_STACK (20 points)

   • App Router usage
   • Server Components
   • Image optimization
   • API routes/RTK Query
   • Performance optimization

5. SECURITY_API (15 points)

   • Input validation
   • Security headers
   • Error handling
   • Authentication
   • Token storage

6. PERFORMANCE_MONITORING (10 points)

   • Sentry integration
   • API performance tracking
   • Error tracking

7. DEPENDENCY_HEALTH (10 points)

   • Security vulnerabilities
   • Lock file consistency
   • Deprecated packages

8. TESTING_COVERAGE (10 points)

   • Playwright configuration
   • Test coverage
   • Test organization

9. REDUX_RTK (10 points)

   • RTK Query services
   • Redux slices
   • Store configuration

10. ACCESSIBILITY (5 points)

    • ARIA attributes
    • Semantic HTML
    • Keyboard navigation

11. BUSINESS_DOCUMENTATION (5 points)

    • README quality
    • Code documentation
    • Business rules

12. CURSOR_WORKFLOW (78 points) ⚡ CRITICAL - ~34% of total score

    • Tech Stack Rule File - Provides reference guidelines (7 points)
    • Prompt Review Rule File - Reviews and validates prompts (7 points)
    • Self Improve Rule File - Improves prompts over time (7 points)
    • Create PRD Rule File - Clarifies user stories and confirms steps (7 points)
    • Generate Tasks Rule File - Generates tasks sequentially (7 points)
    • Process Task List Rule File - Processes sub-tasks (7 points)
    • Review Changes Rule File - Reviews code changes (7 points)
    • Business Rules Rule File - Project workflow reference (7 points)
    • MCP Configuration - Relevant MCPs configured (UI, ShadCN, Tailwind, Prisma, Playwright) (10 points)
    • MCP Versions - MCP server versions detected and reported (3 points) ✨ NEW
    • Cursor Version - Using latest Cursor version (4 points)
    • Workspace Structure - FE and BE in common workspace (5 points)

    Note: This category is weighted heavily (34% of total score) as AI tools are critical in modern development workflows. The MCP Versions check reports which versions of MCP servers are in use (e.g., @latest, @1.0.0, or local installations).

Node.js Projects (233 points total)

Similar categories to Next.js but with Node.js-specific checks:

1. PROJECT_STRUCTURE (20 points)

   • Source structure and module organization
   • Route/controller organization
   • Service layer separation
   • Type definitions
   • Middleware organization
   • Module system (ESM/CommonJS)

2. CODE_QUALITY (30 points)

   • ESLint configuration
   • Husky pre-commit hooks
   • TypeScript strict mode
   • Prettier setup
   • Gitignore

3. DEVELOPMENT_ENVIRONMENT (15 points)

   • IDE configuration
   • Auto-fix on save
   • Format on save
   • Cursor rules
   • Debugging configuration

4. TECH_STACK (20 points)

   • Framework patterns (Express, Fastify, etc.)
   • Middleware implementation
   • API route organization
   • Environment variable management
   • Service layer architecture
   • Async/await patterns

5. SECURITY_API (15 points)

   • Security headers (helmet, CORS)
   • Input validation
   • Error handling
   • Authentication
   • Token storage

6. DATABASE_DATA_LAYER (10 points)

   • ORM/Query builder configuration
   • Migration management
   • Connection pooling
   • Transaction handling

7. PERFORMANCE_MONITORING (10 points)

   • Error tracking integration
   • Structured logging
   • Health check endpoints

8. DEPENDENCY_HEALTH (10 points)

   • Security vulnerabilities
   • Lock file consistency
   • Deprecated packages

9. TESTING_COVERAGE (10 points)

   • Test framework configuration
   • Test coverage for API endpoints
   • Test organization and fixtures

10. API_DESIGN (10 points)

    • RESTful conventions
    • API versioning
    • Request/response validation
    • API documentation (Swagger/OpenAPI)
    • Error response format consistency

11. BUSINESS_DOCUMENTATION (5 points)

    • README quality
    • Code documentation (JSDoc)
    • API documentation
    • Business logic separation

12. CURSOR_WORKFLOW (78 points) ⚡ CRITICAL - ~34% of total score

    • Tech Stack Rule File - Provides reference guidelines (7 points)
    • Prompt Review Rule File - Reviews and validates prompts (7 points)
    • Self Improve Rule File - Improves prompts over time (7 points)
    • Create PRD Rule File - Clarifies user stories and confirms steps (7 points)
    • Generate Tasks Rule File - Generates tasks sequentially (7 points)
    • Process Task List Rule File - Processes sub-tasks (7 points)
    • Review Changes Rule File - Reviews code changes (7 points)
    • Business Rules Rule File - Project workflow reference (7 points)
    • MCP Configuration - Relevant MCPs configured (UI, ShadCN, Tailwind, Prisma, Playwright) (10 points)
    • MCP Versions - MCP server versions detected and reported (3 points) ✨ NEW
    • Cursor Version - Using latest Cursor version (4 points)
    • Workspace Structure - FE and BE in common workspace (5 points)

    Note: This category is weighted heavily (34% of total score) as AI tools are critical in modern development workflows. The MCP Versions check reports which versions of MCP servers are in use (e.g., @latest, @1.0.0, or local installations).

Score Ratings

• EXCELLENT: 90-100% - All tools working + standards followed + best practices
• GOOD: 75-89% - Tools working + most standards followed
• FAIR: 60-74% - Tools configured + some standards followed
• POOR: <60% - Tools missing or not working

Output Format

The assessment returns a JSON object with:

{
  "projectScore": 105,
  "maxScore": 155,
  "percentage": 67.7,
  "complianceRating": "FAIR",
  "categoryBreakdown": [
    {
      "category": "PROJECT_STRUCTURE",
      "score": 16,
      "maxScore": 20,
      "percentage": 80,
      "complianceStatus": "GOOD",
      "details": "PROJECT_STRUCTURE: Some project structure improvements recommended",
      "gaps": ["Consider organizing middleware in dedicated directory"],
      "recommendations": ["Configure PROJECT_STRUCTURE properly"]
    }
  ],
  "complianceGaps": [...],
  "priorityActions": [
    {
      "priority": "CRITICAL",
      "action": "TypeScript: Found 5 type error(s). Run 'npx tsc --noEmit' to see details.",
      "impact": "Improves CODE_QUALITY compliance (currently POOR)"
    }
  ],
  "cursorEffectiveness": "Fair compatibility. Cursor will work but may need more guidance."
}

Output Formats

The tool supports three output formats:

• detailed (default): Human-readable formatted report with category breakdown and priority actions
• summary: Concise summary with top issues
• json: Complete JSON object with all assessment data

What's Assessed

The auditor provides detailed feedback on:

• Project Structure: Organization, folder structure, module system
• Code Quality: ESLint, TypeScript, Husky, Prettier configuration
• Development Environment: VS Code settings, auto-fix, format on save
• Tech Stack: Framework patterns, middleware, API routes
• Security & API: Input validation, security headers, authentication
• Database/Data Layer: ORM usage, migrations, connection pooling (Node.js only)
• Performance Monitoring: Error tracking, logging, health checks
• Dependency Health: Security vulnerabilities, deprecated packages
• Testing Coverage: Test framework, test coverage, test organization
• API Design: RESTful conventions, versioning, documentation (Node.js only)
• Business Documentation: README, code documentation, API docs

Development

Building the Package

npm run build

Running Locally

npm run mcp

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues and feature requests, please use the GitHub issue tracker.