Add KanbanGit MCP v0.1

app/Mcp/Servers/KanbanGitServer.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Mcp\Servers;
+
+use App\Mcp\Tools\GetTicket;
+use App\Mcp\Tools\ListMyAssignedTickets;
+use App\Mcp\Tools\ListTicketsByStatus;
+use App\Mcp\Tools\MoveTicketStatus;
+use App\Mcp\Tools\UpdateTicketAssignee;
+use App\Mcp\Tools\UpdateTicketDescription;
+use Laravel\Mcp\Server;
+use Laravel\Mcp\Server\Attributes\Instructions;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Attributes\Version;
+
+#[Name('KanbanGit MCP')]
+#[Version('0.1.0')]
+#[Instructions('Use these tools to read and update KanbanGit tickets with the authenticated application key owner permissions. Prefer stable IDs when available, especially ticket_id and ticket_status_id.')]
+class KanbanGitServer extends Server
+{
+    protected array $tools = [
+        ListMyAssignedTickets::class,
+        ListTicketsByStatus::class,
+        GetTicket::class,
+        UpdateTicketDescription::class,
+        UpdateTicketAssignee::class,
+        MoveTicketStatus::class,
+    ];
+
+    protected array $resources = [
+        //
+    ];
+
+    protected array $prompts = [
+        //
+    ];
+}

app/Mcp/Support/KanbanGitMcp.php

@@ -0,0 +1,239 @@
+<?php
+
+namespace App\Mcp\Support;
+
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Http\Resources\ProjectResource;
+use App\Http\Resources\TicketResource;
+use App\Models\Project;
+use App\Models\Ticket;
+use App\Models\TicketStatus;
+use App\Models\User;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Auth\AuthenticationException;
+use Illuminate\Support\Collection;
+use Illuminate\Validation\ValidationException;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+
+class KanbanGitMcp
+{
+    public function __construct(
+        private readonly PermissionService $permissionService,
+    ) {}
+
+    /**
+     * @throws AuthenticationException
+     */
+    public function user(Request $request): User
+    {
+        $user = $request->user();
+
+        if (! $user instanceof User) {
+            throw new AuthenticationException('Authentication required.');
+        }
+
+        return $user;
+    }
+
+    /**
+     * @throws AuthorizationException
+     */
+    public function ensureCanRead(User $user, Project $project): void
+    {
+        if (! $this->permissionService->allows($user, Permission::ProjectRead, $project)) {
+            throw new AuthorizationException('You cannot view this project.');
+        }
+    }
+
+    /**
+     * @throws AuthorizationException
+     */
+    public function ensureCanWrite(User $user, Project $project): void
+    {
+        if (! $this->permissionService->allows($user, Permission::ProjectWrite, $project)) {
+            throw new AuthorizationException('You cannot update tickets in this project.');
+        }
+    }
+
+    /**
+     * @throws AuthorizationException
+     */
+    public function ticketForRead(User $user, int $ticketId): Ticket
+    {
+        $ticket = Ticket::query()
+            ->with('project')
+            ->find($ticketId);
+
+        if ($ticket === null) {
+            throw ValidationException::withMessages([
+                'ticket_id' => 'Ticket was not found.',
+            ]);
+        }
+
+        $this->ensureCanRead($user, $ticket->project);
+
+        return $ticket;
+    }
+
+    /**
+     * @throws AuthorizationException
+     */
+    public function ticketForWrite(User $user, int $ticketId): Ticket
+    {
+        $ticket = Ticket::query()
+            ->with('project')
+            ->find($ticketId);
+
+        if ($ticket === null) {
+            throw ValidationException::withMessages([
+                'ticket_id' => 'Ticket was not found.',
+            ]);
+        }
+
+        $this->ensureCanWrite($user, $ticket->project);
+
+        return $ticket;
+    }
+
+    /**
+     * @throws AuthorizationException
+     */
+    public function projectForRead(User $user, ?int $projectId): ?Project
+    {
+        if ($projectId === null) {
+            return null;
+        }
+
+        $project = Project::query()->find($projectId);
+
+        if ($project === null) {
+            throw ValidationException::withMessages([
+                'project_id' => 'Project was not found.',
+            ]);
+        }
+
+        $this->ensureCanRead($user, $project);
+
+        return $project;
+    }
+
+    /**
+     * @param  array<string, mixed>  $validated
+     * @return Collection<int, TicketStatus>|Response
+     */
+    public function resolveTicketStatuses(User $user, array $validated, ?Project $project = null): Collection|Response
+    {
+        $projectIds = $project === null
+            ? $this->permissionService->viewableProjectIds($user)
+            : [$project->id];
+
+        if ($projectIds === []) {
+            return collect();
+        }
+
+        $ticketStatusId = $validated['ticket_status_id'] ?? null;
+        if ($ticketStatusId !== null) {
+            $ticketStatus = TicketStatus::query()
+                ->whereIn('project_id', $projectIds)
+                ->with('boardColumn')
+                ->find((int) $ticketStatusId);
+
+            return $ticketStatus === null
+                ? Response::error('Ticket status was not found in a visible project.')
+                : collect([$ticketStatus]);
+        }
+
+        $query = TicketStatus::query()
+            ->whereIn('project_id', $projectIds)
+            ->with(['boardColumn', 'project'])
+            ->orderBy('project_id')
+            ->orderBy('position');
+
+        if (($statusSlug = $validated['status_slug'] ?? null) !== null) {
+            $query->where('slug', $statusSlug);
+        } elseif (($statusName = $validated['status_name'] ?? null) !== null) {
+            $query->where('name', $statusName);
+        } else {
+            return Response::error('Provide ticket_status_id, status_slug, or status_name.');
+        }
+
+        $ticketStatuses = $query->get();
+
+        if ($ticketStatuses->count() <= 1) {
+            return $ticketStatuses;
+        }
+
+        $matches = $ticketStatuses
+            ->map(fn (TicketStatus $ticketStatus): array => [
+                'id' => $ticketStatus->id,
+                'name' => $ticketStatus->name,
+                'project_id' => $ticketStatus->project_id,
+                'project_name' => $ticketStatus->project?->name,
+                'slug' => $ticketStatus->slug,
+            ])
+            ->values()
+            ->all();
+
+        return Response::error(sprintf(
+            'Status lookup is ambiguous. Provide ticket_status_id or project_id. Matches: %s',
+            json_encode($matches, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES),
+        ));
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function ticketPayload(Ticket $ticket): array
+    {
+        $ticket->load([
+            'assignee',
+            'author',
+            'fieldValues.ticketFieldDefinition',
+            'fieldValues.userValue',
+            'project',
+            'ticketPriority',
+            'ticketStatus.boardColumn',
+            'ticketType',
+            'worklogEntries.actor',
+        ]);
+
+        return [
+            'project' => ProjectResource::make($ticket->project)->resolve(),
+            'ticket' => TicketResource::make($ticket)->resolve(),
+        ];
+    }
+
+    /**
+     * @return array{
+     *     acceptance_criteria: string|null,
+     *     assignee_user_id: int|null,
+     *     author_user_id: int|null,
+     *     blocked_comment: string|null,
+     *     description: string|null,
+     *     is_blocked: bool,
+     *     parent_ticket_id: int|null,
+     *     story_points: int|null,
+     *     ticket_priority_id: int,
+     *     ticket_type_id: int,
+     *     title: string
+     * }
+     */
+    public function updatePayload(Ticket $ticket): array
+    {
+        return [
+            'acceptance_criteria' => $ticket->acceptance_criteria,
+            'assignee_user_id' => $ticket->assignee_user_id,
+            'author_user_id' => $ticket->author_user_id,
+            'blocked_comment' => $ticket->blocked_comment,
+            'description' => $ticket->description,
+            'is_blocked' => $ticket->is_blocked,
+            'parent_ticket_id' => $ticket->parent_ticket_id,
+            'story_points' => $ticket->story_points,
+            'ticket_priority_id' => $ticket->ticket_priority_id,
+            'ticket_type_id' => $ticket->ticket_type_id,
+            'title' => $ticket->title,
+        ];
+    }
+}

app/Mcp/Tools/GetTicket.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Mcp\Support\KanbanGitMcp;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Name('get_ticket')]
+#[Description('Get a visible ticket with project, status, type, priority, assignee, author, field values, and worklog data.')]
+#[IsReadOnly]
+class GetTicket extends Tool
+{
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $validated = $request->validate([
+            'ticket_id' => ['required', 'integer'],
+        ]);
+
+        $user = $this->kanbanGitMcp->user($request);
+        $ticket = $this->kanbanGitMcp->ticketForRead($user, (int) $validated['ticket_id']);
+
+        return Response::structured([
+            'data' => $this->kanbanGitMcp->ticketPayload($ticket),
+        ]);
+    }
+
+    /**
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'ticket_id' => $schema->integer()
+                ->description('Ticket ID.')
+                ->required(),
+        ];
+    }
+}

app/Mcp/Tools/ListMyAssignedTickets.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Tickets\ListAssignedTicketsByVisibleProject;
+use App\Http\Resources\UserResource;
+use App\Mcp\Support\KanbanGitMcp;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Name('list_my_assigned_tickets')]
+#[Description('List tickets assigned to the authenticated application key owner, grouped by visible project. Optionally filter to one project.')]
+#[IsReadOnly]
+class ListMyAssignedTickets extends Tool
+{
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+        private readonly ListAssignedTicketsByVisibleProject $listAssignedTicketsByVisibleProject,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $validated = $request->validate([
+            'project_id' => ['nullable', 'integer'],
+        ]);
+
+        $user = $this->kanbanGitMcp->user($request);
+        $project = $this->kanbanGitMcp->projectForRead($user, $validated['project_id'] ?? null);
+
+        return Response::structured([
+            'data' => $this->listAssignedTicketsByVisibleProject->handle($user, $user, $project),
+            'meta' => [
+                'assignee' => UserResource::make($user)->resolve(),
+            ],
+        ]);
+    }
+
+    /**
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'project_id' => $schema->integer()
+                ->nullable()
+                ->description('Optional project ID. When omitted, tickets from all visible projects are returned.'),
+        ];
+    }
+}

app/Mcp/Tools/ListTicketsByStatus.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Tickets\ListTicketsByStatusByVisibleProject;
+use App\Http\Resources\TicketStatusResource;
+use App\Mcp\Support\KanbanGitMcp;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Name('list_tickets_by_status')]
+#[Description('List tickets in a status, grouped by visible project. Use ticket_status_id when possible; status_slug or status_name are convenience lookups and must be unambiguous.')]
+#[IsReadOnly]
+class ListTicketsByStatus extends Tool
+{
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+        private readonly ListTicketsByStatusByVisibleProject $listTicketsByStatusByVisibleProject,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $validated = $request->validate([
+            'project_id' => ['nullable', 'integer'],
+            'status_name' => ['nullable', 'string'],
+            'status_slug' => ['nullable', 'string'],
+            'ticket_status_id' => ['nullable', 'integer'],
+        ]);
+
+        $user = $this->kanbanGitMcp->user($request);
+        $project = $this->kanbanGitMcp->projectForRead($user, $validated['project_id'] ?? null);
+        $ticketStatuses = $this->kanbanGitMcp->resolveTicketStatuses($user, $validated, $project);
+
+        if ($ticketStatuses instanceof Response) {
+            return $ticketStatuses;
+        }
+
+        return Response::structured([
+            'data' => $this->listTicketsByStatusByVisibleProject->handle($user, $ticketStatuses, $project),
+            'meta' => [
+                'statuses' => TicketStatusResource::collection($ticketStatuses)->resolve(),
+            ],
+        ]);
+    }
+
+    /**
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'project_id' => $schema->integer()
+                ->nullable()
+                ->description('Optional project ID. Use it to scope status_name or status_slug and avoid ambiguity.'),
+            'status_name' => $schema->string()
+                ->nullable()
+                ->description('Exact ticket status name. Must match exactly and be unambiguous.'),
+            'status_slug' => $schema->string()
+                ->nullable()
+                ->description('Ticket status slug. Must be unambiguous unless project_id is provided.'),
+            'ticket_status_id' => $schema->integer()
+                ->nullable()
+                ->description('Stable ticket status ID. Preferred when available.'),
+        ];
+    }
+}

app/Mcp/Tools/MoveTicketStatus.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Tickets\MoveProjectTicket;
+use App\Mcp\Support\KanbanGitMcp;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
+
+#[Name('move_ticket_status')]
+#[Description('Move a ticket to an allowed target status. Use ticket_status_id when possible; status_slug or status_name are convenience lookups and must resolve to one status in the ticket project.')]
+#[IsDestructive(false)]
+class MoveTicketStatus extends Tool
+{
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+        private readonly MoveProjectTicket $moveProjectTicket,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $validated = $request->validate([
+            'status_name' => ['nullable', 'string'],
+            'status_slug' => ['nullable', 'string'],
+            'ticket_id' => ['required', 'integer'],
+            'ticket_status_id' => ['nullable', 'integer'],
+        ]);
+
+        $user = $this->kanbanGitMcp->user($request);
+        $ticket = $this->kanbanGitMcp->ticketForWrite($user, (int) $validated['ticket_id']);
+        $ticketStatuses = $this->kanbanGitMcp->resolveTicketStatuses($user, $validated, $ticket->project);
+
+        if ($ticketStatuses instanceof Response) {
+            return $ticketStatuses;
+        }
+
+        if ($ticketStatuses->isEmpty()) {
+            return Response::error('Ticket status was not found in this ticket project.');
+        }
+
+        $destinationStatus = $ticketStatuses->first();
+
+        if ($destinationStatus->project_id !== $ticket->project_id) {
+            return Response::error('Ticket status must belong to the same project as the ticket.');
+        }
+
+        $ticket->loadMissing('ticketStatus');
+
+        if (
+            $ticket->ticket_status_id !== $destinationStatus->id
+            && ! ($ticket->ticketStatus?->allowedTargetStatuses()->whereKey($destinationStatus->id)->exists() ?? false)
+        ) {
+            return Response::error('Choose a status this ticket is allowed to move to.');
+        }
+
+        $result = $this->moveProjectTicket->handle($ticket->project, $ticket, $user, [
+            'ticket_status_id' => $destinationStatus->id,
+        ]);
+
+        return Response::structured([
+            'data' => $this->kanbanGitMcp->ticketPayload($ticket->fresh()),
+            'meta' => [
+                'destination_label' => $result['destination_label'],
+                'message' => $result['moved']
+                    ? "{$ticket->ticket_key} moved to {$result['destination_label']}."
+                    : "{$ticket->ticket_key} already belongs to {$result['destination_label']}.",
+                'moved' => $result['moved'],
+            ],
+        ]);
+    }
+
+    /**
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'status_name' => $schema->string()
+                ->nullable()
+                ->description('Exact target status name. Must resolve to one status in the ticket project.'),
+            'status_slug' => $schema->string()
+                ->nullable()
+                ->description('Target status slug. Must resolve to one status in the ticket project.'),
+            'ticket_id' => $schema->integer()
+                ->description('Ticket ID.')
+                ->required(),
+            'ticket_status_id' => $schema->integer()
+                ->nullable()
+                ->description('Stable target status ID. Preferred when available.'),
+        ];
+    }
+}

app/Mcp/Tools/UpdateTicketAssignee.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Tickets\UpdateProjectTicket;
+use App\Mcp\Support\KanbanGitMcp;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
+
+#[Name('update_ticket_assignee')]
+#[Description('Assign or unassign a ticket while preserving all other ticket fields. Requires project write permission.')]
+#[IsDestructive(false)]
+class UpdateTicketAssignee extends Tool
+{
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+        private readonly UpdateProjectTicket $updateProjectTicket,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $validated = $request->validate([
+            'assignee_user_id' => ['present', 'nullable', 'integer', 'exists:users,id'],
+            'ticket_id' => ['required', 'integer'],
+        ]);
+
+        $user = $this->kanbanGitMcp->user($request);
+        $ticket = $this->kanbanGitMcp->ticketForWrite($user, (int) $validated['ticket_id']);
+        $payload = [
+            ...$this->kanbanGitMcp->updatePayload($ticket),
+            'assignee_user_id' => $validated['assignee_user_id'] ?? null,
+        ];
+
+        $wasUpdated = $this->updateProjectTicket->handle($ticket, $user, $payload);
+
+        return Response::structured([
+            'data' => $this->kanbanGitMcp->ticketPayload($ticket->fresh()),
+            'meta' => [
+                'message' => $wasUpdated
+                    ? "{$ticket->ticket_key} assignee was updated."
+                    : 'No ticket changes were detected.',
+            ],
+        ]);
+    }
+
+    /**
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'assignee_user_id' => $schema->integer()
+                ->nullable()
+                ->description('User ID to assign. Pass null to unassign.')
+                ->required(),
+            'ticket_id' => $schema->integer()
+                ->description('Ticket ID.')
+                ->required(),
+        ];
+    }
+}

app/Mcp/Tools/UpdateTicketDescription.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use App\Actions\Tickets\UpdateProjectTicket;
+use App\Mcp\Support\KanbanGitMcp;
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
+
+#[Name('update_ticket_description')]
+#[Description('Update only a ticket description while preserving all other ticket fields. Requires project write permission.')]
+#[IsDestructive(false)]
+class UpdateTicketDescription extends Tool
+{
+    public function __construct(
+        private readonly KanbanGitMcp $kanbanGitMcp,
+        private readonly UpdateProjectTicket $updateProjectTicket,
+    ) {}
+
+    public function handle(Request $request): Response|ResponseFactory
+    {
+        $validated = $request->validate([
+            'description' => ['nullable', 'string'],
+            'ticket_id' => ['required', 'integer'],
+        ]);
+
+        $user = $this->kanbanGitMcp->user($request);
+        $ticket = $this->kanbanGitMcp->ticketForWrite($user, (int) $validated['ticket_id']);
+        $payload = [
+            ...$this->kanbanGitMcp->updatePayload($ticket),
+            'description' => $validated['description'] ?? null,
+        ];
+
+        $wasUpdated = $this->updateProjectTicket->handle($ticket, $user, $payload);
+
+        return Response::structured([
+            'data' => $this->kanbanGitMcp->ticketPayload($ticket->fresh()),
+            'meta' => [
+                'message' => $wasUpdated
+                    ? "{$ticket->ticket_key} description was updated."
+                    : 'No ticket changes were detected.',
+            ],
+        ]);
+    }
+
+    /**
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'description' => $schema->string()
+                ->nullable()
+                ->description('New ticket description. Pass null to clear it.'),
+            'ticket_id' => $schema->integer()
+                ->description('Ticket ID.')
+                ->required(),
+        ];
+    }
+}