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

# 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

{
  "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

# 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

# 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

SuperClaude /git Command Integration

High-Level Workflow Automation via /sc:git command:

# Smart Commit (AI-powered, recommended)
/sc:git commit --smart
→ Analyzes changes, generates conventional commit, executes commit workflow

# Feature Branch Workflow
/sc:git feature user-authentication
→ Creates feature branch, sets up development workflow

# Code Review & Merge
/sc:git merge feature/login --review
→ AI-assisted code review, safe merge with conflict detection

# Release Preparation
/sc:git release v2.1.0 --changelog
→ Generates changelog, creates tag, prepares GitHub release

# Emergency Hotfix
/sc:git hotfix critical-bug --from production
→ Fast hotfix branch creation and deployment workflow

# Interactive Rebase
/sc:git rebase --interactive main
→ Guided commit history cleanup before merge

See /home/michael/.claude/commands/sc/git.md for complete workflow documentation.

Response Format

Alle Codebase-Analysis-Tools liefern strukturierte Ergebnisse:

{
  "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

Framework Analysis

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

Git Workflow Automation (NEW ✨)

Individual MCP Tools (Low-Level):

• 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

SuperClaude /git Command (High-Level, Recommended):

• Prefer /sc:git commit --smart über manuelle Commits für AI-gestützte Conventional Commits
• Use /sc:git feature [name] für standardisierte Feature Branch Creation
• Use /sc:git merge [branch] --review für AI-unterstützte Code Review vor Merge
• Use /sc:git release [version] für automatisierte Release-Vorbereitung mit Changelog
• Use /sc:git hotfix [issue] für schnelle Hotfix-Workflows mit automatischem Branch Management

Workflow Integration Benefits:

• Automatic validation and error handling
• AI-assisted decision making for commits and merges
• Consistent branch naming conventions
• Integrated code review and conflict resolution
• TodoWrite tracking for multi-step workflows
• Graceful fallback to Bash if MCP server unavailable

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