✨ 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/CourseEvent/CreateCourseEventTool.php

@@ -2,8 +2,11 @@
 
 namespace App\Mcp\Tools\CourseEvent;
 
+use App\Mcp\Tools\Concerns\ResolvesEntities;
+use App\Models\Course;
 use App\Models\CourseEvent;
 use App\Models\User;
+use App\Models\Venue;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
 use Laravel\Mcp\Request;
@@ -11,9 +14,11 @@ use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Attributes\Description;
 use Laravel\Mcp\Server\Tool;
 
-#[Description('Legt ein neues Kurs-Event für den authentifizierten Referenten an. Der Ersteller (created_by) wird automatisch gesetzt.')]
+#[Description('Legt ein neues Kurs-Event für den authentifizierten Referenten an. Kurs und Veranstaltungsort werden über ihre Namen angegeben; der Ersteller (created_by) wird automatisch gesetzt.')]
 class CreateCourseEventTool extends Tool
 {
+    use ResolvesEntities;
+
     public function handle(Request $request): Response
     {
         $user = $request->user();
@@ -22,6 +27,20 @@ class CreateCourseEventTool extends Tool
             return Response::error('Nur Referenten (is_lecturer) dürfen Kurs-Events anlegen.');
         }
 
+        if (! $this->present($request->get('course_id'))) {
+            $course = $this->resolveOwnedByName($request, Course::class, 'Kurse', 'course');
+
+            if ($course instanceof Response) {
+                return $course;
+            }
+
+            $request->merge(['course_id' => $course->id]);
+        }
+
+        if ($error = $this->mergeForeignKey($request, 'venue', 'venue_id', Venue::query(), 'Veranstaltungsorte')) {
+            return $error;
+        }
+
         $validated = $request->validate([
             'course_id' => ['required', 'integer', 'exists:courses,id'],
             'venue_id' => ['required', 'integer', 'exists:venues,id'],
@@ -41,8 +60,10 @@ class CreateCourseEventTool extends Tool
     public function schema(JsonSchema $schema): array
     {
         return [
-            'course_id' => $schema->integer()->description('ID des zugehörigen Kurses (vorher per search-courses auflösen).')->required(),
-            'venue_id' => $schema->integer()->description('ID des Veranstaltungsorts (vorher per search-venues auflösen).')->required(),
+            'course' => $schema->string()->description('Name deines Kurses, zu dem das Event gehört. Wird automatisch aufgelöst – sonst zuerst search-courses aufrufen.'),
+            'course_id' => $schema->integer()->description('Optional: ID des Kurses, falls bereits bekannt (Alternative zu "course").'),
+            'venue' => $schema->string()->description('Name des Veranstaltungsorts. Wird automatisch aufgelöst – bei Bedarf per search-venues den genauen Namen ermitteln.'),
+            'venue_id' => $schema->integer()->description('Optional: ID des Veranstaltungsorts, falls bereits bekannt (Alternative zu "venue").'),
             'from' => $schema->string()->description('Startzeitpunkt (Datum/Uhrzeit).')->required(),
             'to' => $schema->string()->description('Endzeitpunkt (Datum/Uhrzeit), gleich oder nach dem Start.')->required(),
             'link' => $schema->string()->description('URL mit weiteren Informationen zum Kurs-Event.')->required(),