✨ 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/Venue/CreateVenueTool.php

@@ -4,6 +4,8 @@ namespace App\Mcp\Tools\Venue;
 
 use App\Http\Requests\Api\StoreVenueRequest;
 use App\Http\Resources\VenueResource;
+use App\Mcp\Tools\Concerns\ResolvesEntities;
+use App\Models\City;
 use App\Models\Venue;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
@@ -13,9 +15,11 @@ use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Attributes\Description;
 use Laravel\Mcp\Server\Tool;
 
-#[Description('Legt einen neuen Veranstaltungsort (Venue) für den authentifizierten Nutzer an. Der Ersteller (created_by) wird automatisch gesetzt.')]
+#[Description('Legt einen neuen Veranstaltungsort (Venue) für den authentifizierten Nutzer an. Die Stadt wird über ihren Namen angegeben; der Ersteller (created_by) wird automatisch gesetzt.')]
 class CreateVenueTool extends Tool
 {
+    use ResolvesEntities;
+
     public function handle(Request $request): Response
     {
         $user = $request->user();
@@ -24,6 +28,10 @@ class CreateVenueTool extends Tool
             return Response::error('Nicht berechtigt, einen Veranstaltungsort anzulegen.');
         }
 
+        if ($error = $this->mergeForeignKey($request, 'city', 'city_id', City::query(), 'Stadt')) {
+            return $error;
+        }
+
         $storeRequest = new StoreVenueRequest;
 
         $validated = $request->validate(
@@ -42,7 +50,8 @@ class CreateVenueTool extends Tool
     public function schema(JsonSchema $schema): array
     {
         return [
-            'city_id' => $schema->integer()->description('ID der zugehörigen Stadt (vorher per search-cities auflösen).')->required(),
+            'city' => $schema->string()->description('Name der zugehörigen Stadt (z. B. "Ansbach"). Wird automatisch aufgelöst – bei Bedarf per search-cities den genauen Namen ermitteln.'),
+            'city_id' => $schema->integer()->description('Optional: ID der Stadt, falls bereits bekannt (Alternative zu "city").'),
             'name' => $schema->string()->description('Name des Veranstaltungsorts.')->required(),
             'street' => $schema->string()->description('Straße und Hausnummer des Veranstaltungsorts.')->required(),
         ];

app/Mcp/Tools/Venue/ShowMyVenueTool.php

@@ -3,6 +3,7 @@
 namespace App\Mcp\Tools\Venue;
 
 use App\Http\Resources\VenueResource;
+use App\Mcp\Tools\Concerns\ResolvesEntities;
 use App\Models\Venue;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
@@ -14,15 +15,17 @@ use Laravel\Mcp\Server\Tool;
 use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
 
 #[IsReadOnly]
-#[Description('Zeigt einen einzelnen, vom authentifizierten Nutzer erstellten Veranstaltungsort.')]
+#[Description('Zeigt einen deiner Veranstaltungsorte (per Name angegeben).')]
 class ShowMyVenueTool extends Tool
 {
+    use ResolvesEntities;
+
     public function handle(Request $request): Response
     {
-        $venue = Venue::find($request->get('id'));
+        $venue = $this->resolveOwnedByName($request, Venue::class, 'Veranstaltungsorte', 'venue');
 
-        if (! $venue) {
-            return Response::error('Veranstaltungsort nicht gefunden.');
+        if ($venue instanceof Response) {
+            return $venue;
         }
 
         $user = $request->user();
@@ -40,7 +43,8 @@ class ShowMyVenueTool extends Tool
     public function schema(JsonSchema $schema): array
     {
         return [
-            'id' => $schema->integer()->description('ID des Veranstaltungsorts.')->required(),
+            'venue' => $schema->string()->description('Name des Veranstaltungsorts (aus deinen Orten, siehe list-my-venues).'),
+            'id' => $schema->integer()->description('Optional: ID des Veranstaltungsorts, falls bereits bekannt (Alternative zu "venue").'),
         ];
     }
 }

app/Mcp/Tools/Venue/UpdateVenueTool.php

@@ -4,6 +4,8 @@ namespace App\Mcp\Tools\Venue;
 
 use App\Http\Requests\Api\UpdateVenueRequest;
 use App\Http\Resources\VenueResource;
+use App\Mcp\Tools\Concerns\ResolvesEntities;
+use App\Models\City;
 use App\Models\Venue;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
@@ -13,15 +15,17 @@ use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Attributes\Description;
 use Laravel\Mcp\Server\Tool;
 
-#[Description('Aktualisiert einen bestehenden Veranstaltungsort (Venue). Nur der Ersteller oder ein Super-Admin darf ihn ändern.')]
+#[Description('Aktualisiert einen deiner Veranstaltungsorte (per Name angegeben). Nur der Ersteller oder ein Super-Admin darf ihn ändern.')]
 class UpdateVenueTool extends Tool
 {
+    use ResolvesEntities;
+
     public function handle(Request $request): Response
     {
-        $venue = Venue::find($request->get('id'));
+        $venue = $this->resolveOwnedByName($request, Venue::class, 'Veranstaltungsorte', 'venue');
 
-        if (! $venue) {
-            return Response::error('Veranstaltungsort nicht gefunden.');
+        if ($venue instanceof Response) {
+            return $venue;
         }
 
         $user = $request->user();
@@ -30,6 +34,10 @@ class UpdateVenueTool extends Tool
             return Response::error('Nur der Ersteller oder ein Super-Admin darf diesen Veranstaltungsort ändern.');
         }
 
+        if ($error = $this->mergeForeignKey($request, 'city', 'city_id', City::query(), 'Stadt', false)) {
+            return $error;
+        }
+
         $validated = $request->validate((new UpdateVenueRequest)->rules());
 
         $venue->update($validated);
@@ -43,9 +51,11 @@ class UpdateVenueTool extends Tool
     public function schema(JsonSchema $schema): array
     {
         return [
-            'id' => $schema->integer()->description('ID des zu aktualisierenden Veranstaltungsorts.')->required(),
-            'city_id' => $schema->integer()->description('ID der zugehörigen Stadt.'),
-            'name' => $schema->string()->description('Name des Veranstaltungsorts.'),
+            'venue' => $schema->string()->description('Name des zu ändernden Veranstaltungsorts (aus deinen Orten, siehe list-my-venues).'),
+            'id' => $schema->integer()->description('Optional: ID des Veranstaltungsorts, falls bereits bekannt (Alternative zu "venue").'),
+            'city' => $schema->string()->description('Name der zugehörigen Stadt (wird automatisch aufgelöst).'),
+            'city_id' => $schema->integer()->description('Optional: ID der Stadt (Alternative zu "city").'),
+            'name' => $schema->string()->description('Neuer Name des Veranstaltungsorts.'),
             'street' => $schema->string()->description('Straße und Hausnummer des Veranstaltungsorts.'),
         ];
     }