✨ 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/City/UpdateCityTool.php

@@ -4,7 +4,9 @@ namespace App\Mcp\Tools\City;
 
 use App\Http\Requests\Api\UpdateCityRequest;
 use App\Http\Resources\CityResource;
+use App\Mcp\Tools\Concerns\ResolvesEntities;
 use App\Models\City;
+use App\Models\Country;
 use Illuminate\Contracts\JsonSchema\JsonSchema;
 use Illuminate\JsonSchema\Types\Type;
 use Illuminate\Support\Facades\Gate;
@@ -13,15 +15,17 @@ use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Attributes\Description;
 use Laravel\Mcp\Server\Tool;
 
-#[Description('Aktualisiert eine bestehende Stadt. Nur der Ersteller oder ein Super-Admin darf sie ändern.')]
+#[Description('Aktualisiert eine deiner Städte (per Name angegeben). Nur der Ersteller oder ein Super-Admin darf sie ändern.')]
 class UpdateCityTool extends Tool
 {
+    use ResolvesEntities;
+
     public function handle(Request $request): Response
     {
-        $city = City::find($request->get('id'));
+        $city = $this->resolveOwnedByName($request, City::class, 'Städte', 'city');
 
-        if (! $city) {
-            return Response::error('Stadt nicht gefunden.');
+        if ($city instanceof Response) {
+            return $city;
         }
 
         $user = $request->user();
@@ -30,6 +34,10 @@ class UpdateCityTool extends Tool
             return Response::error('Nur der Ersteller oder ein Super-Admin darf diese Stadt ändern.');
         }
 
+        if ($error = $this->mergeForeignKey($request, 'country', 'country_id', Country::query(), 'Land', false)) {
+            return $error;
+        }
+
         $validated = $request->validate((new UpdateCityRequest)->rules());
 
         $city->update($validated);
@@ -43,9 +51,11 @@ class UpdateCityTool extends Tool
     public function schema(JsonSchema $schema): array
     {
         return [
-            'id' => $schema->integer()->description('ID der zu aktualisierenden Stadt.')->required(),
-            'country_id' => $schema->integer()->description('ID des zugehörigen Landes.'),
-            'name' => $schema->string()->description('Name der Stadt.'),
+            'city' => $schema->string()->description('Name der zu ändernden Stadt (aus deinen Städten, siehe list-my-cities).'),
+            'id' => $schema->integer()->description('Optional: ID der Stadt, falls bereits bekannt (Alternative zu "city").'),
+            'country' => $schema->string()->description('Name des zugehörigen Landes (wird automatisch aufgelöst).'),
+            'country_id' => $schema->integer()->description('Optional: ID des Landes (Alternative zu "country").'),
+            'name' => $schema->string()->description('Neuer Name der Stadt.'),
             'longitude' => $schema->number()->description('Längengrad der Stadt.'),
             'latitude' => $schema->number()->description('Breitengrad der Stadt.'),
             'population' => $schema->integer()->description('Einwohnerzahl der Stadt.'),