✨ Add ResolvesEntities concern for name-based ID resolution

- 🤖 Introduced `ResolvesEntities` trait to simplify entity resolution by name or ID across MCP tools.
- 📚 Updated tools (Meetups, Cities, Venues, Courses, Lecturers) to use the concern for resolving related entities (e.g., courses, venues, lecturers).
- 🎯 Enhanced tool descriptions and schemas for better name-based parameter handling with fallback support for IDs.
- ✅ Added dedicated feature tests for name resolution logic, partial matches, and error handling scenarios.

app/Mcp/Tools/Course/CreateCourseTool.php

@@ -2,7 +2,9 @@
 
 namespace App\Mcp\Tools\Course;
 
+use App\Mcp\Tools\Concerns\ResolvesEntities;
 use App\Models\Course;
+use App\Models\Lecturer;
 use App\Models\User;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
@@ -11,9 +13,11 @@ use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Attributes\Description;
 use Laravel\Mcp\Server\Tool;
 
-#[Description('Legt einen neuen Kurs für den authentifizierten Referenten an. Der Ersteller (created_by) wird automatisch gesetzt.')]
+#[Description('Legt einen neuen Kurs für den authentifizierten Referenten an. Der Referent wird über seinen Namen angegeben; der Ersteller (created_by) wird automatisch gesetzt.')]
 class CreateCourseTool extends Tool
 {
+    use ResolvesEntities;
+
     public function handle(Request $request): Response
     {
         $user = $request->user();
@@ -22,6 +26,10 @@ class CreateCourseTool extends Tool
             return Response::error('Nur Referenten (is_lecturer) dürfen Kurse anlegen.');
         }
 
+        if ($error = $this->mergeForeignKey($request, 'lecturer', 'lecturer_id', Lecturer::query(), 'Referenten')) {
+            return $error;
+        }
+
         $validated = $request->validate([
             'name' => ['required', 'string', 'max:255'],
             'lecturer_id' => ['required', 'exists:lecturers,id'],
@@ -40,7 +48,8 @@ class CreateCourseTool extends Tool
     {
         return [
             'name' => $schema->string()->description('Name des Kurses.')->required(),
-            'lecturer_id' => $schema->integer()->description('ID des zugehörigen Referenten (vorher per search-lecturers auflösen).')->required(),
+            'lecturer' => $schema->string()->description('Name des zugehörigen Referenten. Wird automatisch aufgelöst – bei Bedarf per search-lecturers den genauen Namen ermitteln.'),
+            'lecturer_id' => $schema->integer()->description('Optional: ID des Referenten, falls bereits bekannt (Alternative zu "lecturer").'),
             'description' => $schema->string()->description('Beschreibung des Kurses.'),
         ];
     }