michaelschiemer/docs/claude/mcp-integration.md

# MCP Integration

**Model Context Protocol (MCP) Server Integration** für das Custom PHP Framework.

## Server Status

**✅ FULLY FUNCTIONAL**
- Server getestet und funktionsfähig mit JSON-RPC Protokoll
- Tools und Ressourcen bereit für AI-Integration
- Automatische Erkennung von Framework-Komponenten
- Sichere, sandbox-basierte Dateisystem-Zugriffe

## Quick Access Commands

```bash
# MCP Server starten
docker exec -i php php console.php mcp:server

# MCP Server testen
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | docker exec -i php php console.php mcp:server
```

## Verfügbare MCP Tools

### Framework Analysis Tools
| Tool | Beschreibung | Verwendung |
|------|--------------|------------|
| `analyze_routes` | Alle registrierten Routen abrufen | Framework-Routing-Analyse |
| `analyze_container_bindings` | DI Container Bindings analysieren | Dependency Injection Debugging |
| `discover_attributes` | Attribute nach Typ entdecken | Framework-Pattern-Erkennung |
| `framework_health_check` | Health Check der Framework-Komponenten | System-Status-Überprüfung |
| `list_framework_modules` | Alle Framework-Module auflisten | Architektur-Übersicht |

### Codebase Analysis Tools (NEW ✨)
| Tool | Beschreibung | Verwendung |
|------|--------------|------------|
| `analyze_codebase` | Intelligente Codebase-Analyse mit semantischer Suche | Umfassende Code-Analyse |
| `find_controllers` | Alle Controller-Klassen finden | Controller-Discovery |
| `find_services` | Alle Services, Manager, Repositories finden | Service-Layer-Analyse |
| `find_value_objects` | Alle Value Object Klassen finden | Domain-Model-Analyse |
| `find_initializers` | Alle DI Container Initializers finden | Dependency-Injection-Analyse |
| `find_mcp_tools` | Alle MCP Tool Methoden finden | MCP-Integration-Übersicht |
| `find_commands` | Alle Console Commands finden | CLI-Kommando-Analyse |
| `search_by_pattern` | Suche nach Klassennamen-Pattern | Pattern-basierte Suche |

### File System Tools
| Tool | Beschreibung | Verwendung |
|------|--------------|------------|
| `list_directory` | Verzeichnisinhalte auflisten (projekt-beschränkt) | Dateisystem-Navigation |
| `read_file` | Dateiinhalte mit Zeilenlimits lesen | Code-Analyse |
| `find_files` | Dateien nach Pattern finden | Pattern-basierte Suche |

### Git Version Control Tools (NEW ✨)
| Tool | Beschreibung | Verwendung |
|------|--------------|------------|
| `git_status` | Git Status mit staged/unstaged/untracked Änderungen | Änderungs-Übersicht |
| `git_diff` | Diff für staged oder unstaged Änderungen | Code-Review |
| `git_add` | Dateien für Commit stagen | Staging-Operationen |
| `git_commit` | Commit mit Message erstellen | Commit-Erstellung |
| `git_generate_commit_message` | AI-gestützte Commit-Message-Generierung | Intelligente Commits |
| `git_log` | Commit-Historie abrufen | Verlaufs-Analyse |
| `git_branch_info` | Branch-Informationen | Branch-Management |
| `git_changed_files` | Liste geänderter Dateien mit Typen | Änderungs-Tracking |
| `git_stash` | Änderungen stashen | Temporäre Speicherung |
| `git_stash_list` | Stash-Liste anzeigen | Stash-Verwaltung |

## MCP Resources

- `framework://config`: Framework-Konfiguration und Umgebung

## Claude Desktop Konfiguration

```json
{
  "mcpServers": {
    "custom-php-framework": {
      "command": "docker",
      "args": ["exec", "-i", "php", "php", "console.php", "mcp:server"],
      "cwd": "/home/michael/dev/michaelschiemer"
    }
  }
}
```

## Framework-Analyse-Capabilities

### Core Framework Analysis
- **Route Discovery**: Automatische Erkennung aller registrierten Routen
- **Container Binding Inspection**: Analyse der Dependency Injection Bindings
- **Modul- und Komponenten-Discovery**: Erkennung aller Framework-Module
- **Health Monitoring**: Überwachung des Framework-Status
- **File System Operations**: Projekt-beschränkte Dateisystem-Operationen

### Intelligente Codebase-Analyse (NEW ✨)
- **Semantic Search**: AST-basierte Code-Analyse statt nur Text-Pattern-Matching
- **Attribute Discovery**: Finde Klassen basierend auf Attributen (#[Route], #[McpTool], etc.)
- **Interface Implementation Search**: Finde alle Implementierungen eines Interfaces
- **Pattern-Based Class Discovery**: Wildcard-Patterns wie `*Controller`, `*Service`
- **Component Categorization**: Automatische Kategorisierung (Controllers, Services, VOs, etc.)
- **Performance Optimiert**: Nutzt Framework's Discovery System und Caching
- **Batch Operations**: Mehrere Suchtypen in einer Query kombinierbar

## Verwendungsbeispiele

### Codebase Analysis Queries

```bash
# Find all controllers and their routes
find_controllers

# Find all services (Services, Managers, Repositories)
find_services

# Find all value objects
find_value_objects

# Search by pattern
search_by_pattern "*Repository"
search_by_pattern "*Handler"

# Complex query with multiple filters
analyze_codebase {
  "attribute_types": ["App\\Framework\\Attributes\\Route", "App\\Framework\\Attributes\\Initializer"],
  "class_name_patterns": ["*Controller", "*Service"],
  "max_results": 100
}
```

### Git Workflow Examples

```bash
# Intelligenter Commit-Workflow
# 1. Status prüfen
git_status

# 2. Änderungen analysieren
git_changed_files

# 3. AI-gestützte Commit-Message generieren
git_generate_commit_message

# 4. Dateien stagen
git_add { "files": ["."] }

# 5. Commit erstellen
git_commit { "message": "feat(Mcp): add Git version control tools for automated workflows" }

# Branch-Workflow
git_branch_info                 # Aktuellen Branch prüfen
git_stash                       # Temporäre Änderungen speichern
git_log { "limit": 10 }        # Letzte 10 Commits anzeigen

# Diff-Analyse
git_diff { "staged": true }    # Staged changes diff
git_diff { "file": "src/Framework/Mcp/Tools/GitTools.php" }  # File-specific diff
```

### Response Format

Alle Codebase-Analysis-Tools liefern strukturierte Ergebnisse:

```json
{
  "controllers": [
    {
      "class_name": "App\\Application\\Api\\UserController",
      "file_path": "/var/www/html/src/Application/Api/UserController.php",
      "namespace": "App\\Application\\Api",
      "is_readonly": true,
      "is_final": true,
      "methods": ["getUsers", "getUser", "createUser"]
    }
  ],
  "routes": [
    {
      "path": "/api/users",
      "http_method": "GET",
      "controller": "App\\Application\\Api\\UserController",
      "action": "getUsers"
    }
  ],
  "statistics": {
    "total_components": 150,
    "total_routes": 45
  },
  "execution_time_ms": 42.5
}
```

## Best Practices für AI-Interaktion

1. **MCP Tools verwenden**: Nutze MCP Tools für Framework-Analyse anstatt manueller Datei-Lesung oder Bash-Grep
2. **Codebase Analysis bevorzugen**: Nutze intelligente `find_*` Tools statt Pattern-Matching für Framework-Komponenten
3. **Attribute Discovery nutzen**: Verwende Attribute-Discovery zum Verstehen der Framework-Patterns
4. **Health Checks**: Führe Framework Health Checks vor Änderungen durch
5. **Projekt-Scope beachten**: Respektiere projekt-beschränkte Dateizugriff-Limitierungen
6. **Batch Queries**: Kombiniere mehrere Suchkriterien in einer `analyze_codebase` Query für bessere Performance
7. **Git Automation** (NEW):
   - Nutze `git_generate_commit_message` für konsistente Conventional Commits
   - Prüfe `git_status` vor Änderungen für sauberen Working Tree
   - Verwende `git_changed_files` für Scope-Analyse vor Commits
   - Nutze `git_diff` für Code-Review vor dem Stagen
   - Führe `git_log` aus für Commit-Message-Konsistenz

## Sicherheitsfeatures

- **Sandboxed File Access**: Alle Dateizugriffe sind auf das Projekt beschränkt
- **Safe Operations**: Nur lesende Operationen für Framework-Analyse
- **Validation**: Eingabe-Validierung für alle MCP-Tool-Parameter
- **Error Handling**: Robuste Fehlerbehandlung mit aussagekräftigen Meldungen