MCP GitHub Validator

An MCP (Model Context Protocol) server that validates GitHub repositories against configurable rules. Designed for React applications with support for domain pattern checking, code structure validation, and dependency analysis.

Features

• 🔍 List React Repos - Discover all React applications in your GitHub account
• 📁 Inspect Structure - View file trees and project organization
• ✅ Validate Repos - Run configurable rules against repositories
• 📊 Batch Validation - Validate multiple repos at once with summary reports

Available Tools

Tool	Description
list_react_repos	List all React repositories from your GitHub account
get_repo_structure	Get file/folder structure of a repository
validate_repo	Validate a single repo against best practices
validate_all_repos	Batch validate multiple repositories
list_rules	List all available validation rules

Validation Rules

Structure Rules

• structure/has-src-folder - Project should have a src/ folder
• structure/has-components-folder - React apps need a components folder
• structure/has-domain-folder - Domain-driven apps should have domain/features/modules
• structure/has-hooks-folder - Custom hooks should be in a hooks folder
• structure/has-services-folder - API layer should be organized

Configuration Rules

• config/has-typescript - Project should use TypeScript
• config/has-eslint - Project should have ESLint configured
• config/has-prettier - Project should have Prettier configured

Dependency Rules

• dependencies/has-state-management - Check for state management libraries
• dependencies/has-testing - Check for testing libraries
• dependencies/react-version - Ensure React 18+

Naming Rules

• naming/component-files - Component files should use PascalCase

Installation

cd mcp-github-validator
npm install
npm run build

Configuration

Environment Variables

Create a .env file or set the environment variable:

GITHUB_TOKEN=your_github_personal_access_token

A GitHub token is recommended to avoid rate limits. Create one at: https://github.com/settings/tokens

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "github-validator": {
      "command": "node",
      "args": ["/path/to/mcp-github-validator/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

VS Code with Copilot

Add to your VS Code settings or workspace .vscode/mcp.json:

{
  "servers": {
    "github-validator": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/../mcp-github-validator/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude or Copilot:

• "List all my React repositories"
• "Show me the structure of the mapland repo"
• "Validate the films repository"
• "Validate all my React repos and show me a summary"
• "What validation rules are available?"
• "Check if user-lens follows domain patterns"

Adding Custom Rules

Create a new rule in src/rules/index.ts:

const myCustomRule: RuleDefinition = {
  id: "custom/my-rule",
  name: "My Custom Rule",
  description: "Description of what this rule checks",
  severity: "warning", // 'error' | 'warning' | 'info'
  category: "structure", // or 'config', 'dependencies', 'naming', 'domain-pattern'
  async validate(ctx: ValidationContext): Promise<RuleResult> {
    // Your validation logic here
    const passed = pathExists(ctx.fileTree, "some/path");
    
    return {
      ruleId: this.id,
      passed,
      severity: this.severity,
      message: passed ? "Check passed" : "Check failed",
      suggestions: passed ? undefined : ["How to fix this"],
    };
  },
};

// Add to allRules array
export const allRules: RuleDefinition[] = [
  // ... existing rules
  myCustomRule,
];

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run typecheck

Project Structure

mcp-github-validator/
├── src/
│   ├── index.ts        # MCP server entry point
│   ├── github.ts       # GitHub API utilities
│   ├── types.ts        # TypeScript type definitions
│   ├── tools.ts        # MCP tool implementations
│   ├── validator.ts    # Validation engine
│   └── rules/
│       └── index.ts    # Validation rule definitions
├── package.json
├── tsconfig.json
└── README.md