# 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

```bash
cd mcp-github-validator
npm install
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file or set the environment variable:

```bash
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):

```json
{
  "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`:

```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`:

```typescript
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

```bash
# 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
```