Co-authored-by: Carlos Florêncio <carlosmflorencio@gmail.com> Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com>
3.8 KiB
status, system, requirements, created, owners
| status | system | requirements | created | owners | ||
|---|---|---|---|---|---|---|
| current | integrations |
|
2026-09-14 |
|
Manage task change requests through MCP System Design
Purpose and boundaries
This design gives agents one provider-neutral MCP surface for managing a task's GitHub pull request and GitLab merge request associations. The MCP tool surface and the task-facing handler are owned here; provider stores, webhook discovery, and automation handling stay owned by their existing GitHub and GitLab designs, and task identity, workspace reach authorization, and list/serialization surfaces stay owned by the task system.
Requirement mapping
| Requirement | Design section |
|---|---|
REQ-INTEGRATIONS-TASK-CHANGE-LINK-MCP-001 |
Components and responsibilities, Control flow |
Components and responsibilities
apps/backend/internal/mcp/handlers/task_change_link.govalidates the request shape, binds the caller task identity through the ordinary task reach path, and forwards one provider-neutral request to the coordinator.apps/backend/internal/backendapp/task_change_link_coordinator.goresolves the canonical repository from the task's workspace, rejects unknown or unverified provider hosts, dispatches to the provider service, and returns the resulting linked set. Replacement compensates a failed post-establishment exchange by removing the newly created association and reports both errors when compensation itself fails.apps/backend/internal/githubandapps/backend/internal/gitlabown association persistence, idempotent link/removal, and exact automation retirement scoped to one provider, repository, and change-request number. GitHub detach keeps durable tombstones; GitLab unlink publishes a workspace-scoped deletion event after persistence.apps/backend/internal/mcp/server/server.goregisterslink_task_pr_kandev,unlink_task_pr_kandev, andreplace_task_pr_kandevwith provider-aware availability.
Data and contracts
Every mutation requires explicit task_id, a provider discriminator
(github or gitlab), the canonical repository identity (repository_id),
and the change-request number. A bare number is invalid. Replacement adds the
old association triple (old_provider, old_repository_id,
old_number). Responses return the current canonical linked set for the
task.
Unlinking changes only the active association row. Conversation history and terminal receipts remain untouched, and re-linking the same identity restores an active association.
Control flow
- The MCP server receives the tool call and resolves the caller task.
- The handler authorizes workspace reach for that task.
- The handler validates provider, repository identity, and number, rejecting a bare number or unresolved repository before any store mutation.
- The coordinator loads the task's repositories, verifies the requested canonical repository belongs to the task workspace and carries a verified provider host, and dispatches link, unlink, or replace.
- The provider service applies idempotent persistence, scoped automation cleanup, and deletion-event publication.
- The coordinator assembles the resulting linked set and the handler returns it. List/query surfaces read the same stores, so no extra invalidation is required for restart-consistent state.
Examples
{
"task_id": "<task-id>",
"provider": "github",
"repository_id": "<repository-id>",
"number": 3506
}
link_task_pr_kandev and unlink_task_pr_kandev accept this shape;
replace_task_pr_kandev additionally requires the old association triple
(old_provider, old_repository_id, old_number). See
docs/public/automation-and-mcp.md
for the operator-facing contract.