manage_work_item_link
Add, remove, or update links between Azure DevOps work items to establish relationships and track dependencies.
Instructions
Add or remove links between work items
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sourceWorkItemId | Yes | The ID of the source work item | |
| targetWorkItemId | Yes | The ID of the target work item | |
| projectId | No | The ID or name of the project (Default: MyProject) | |
| organizationId | No | The ID or name of the organization (Default: mycompany) | |
| operation | Yes | The operation to perform on the link | |
| relationType | Yes | The reference name of the relation type (e.g., "System.LinkTypes.Hierarchy-Forward") | |
| newRelationType | No | The new relation type to use when updating a link | |
| comment | No | Optional comment explaining the link |
Implementation Reference
- The core handler function that manages (adds, removes, updates) links between two work items using Azure DevOps WorkItemTrackingApi. Handles input validation, constructs JSON patch documents for relations, and updates the source work item.export async function manageWorkItemLink( connection: WebApi, projectId: string, options: ManageWorkItemLinkOptions, ): Promise<WorkItem> { try { const { sourceWorkItemId, targetWorkItemId, operation, relationType, newRelationType, comment, } = options; // Input validation if (!sourceWorkItemId) { throw new Error('Source work item ID is required'); } if (!targetWorkItemId) { throw new Error('Target work item ID is required'); } if (!relationType) { throw new Error('Relation type is required'); } if (operation === 'update' && !newRelationType) { throw new Error('New relation type is required for update operation'); } const witApi = await connection.getWorkItemTrackingApi(); // Create the JSON patch document const document = []; // Construct the relationship URL const relationshipUrl = `${connection.serverUrl}/_apis/wit/workItems/${targetWorkItemId}`; if (operation === 'add' || operation === 'update') { // For 'update', we'll first remove the old link, then add the new one if (operation === 'update') { document.push({ op: 'remove', path: `/relations/+[rel=${relationType};url=${relationshipUrl}]`, }); } // Add the new relationship document.push({ op: 'add', path: '/relations/-', value: { rel: operation === 'update' ? newRelationType : relationType, url: relationshipUrl, ...(comment ? { attributes: { comment } } : {}), }, }); } else if (operation === 'remove') { // Remove the relationship document.push({ op: 'remove', path: `/relations/+[rel=${relationType};url=${relationshipUrl}]`, }); } // Update the work item with the new relationship const updatedWorkItem = await witApi.updateWorkItem( {}, // customHeaders document, sourceWorkItemId, projectId, ); if (!updatedWorkItem) { throw new AzureDevOpsResourceNotFoundError( `Work item '${sourceWorkItemId}' not found`, ); } return updatedWorkItem; } catch (error) { if (error instanceof AzureDevOpsError) { throw error; } throw new Error( `Failed to manage work item link: ${error instanceof Error ? error.message : String(error)}`, ); } }
- Zod schema defining the input parameters for the manage_work_item_link tool, including source/target IDs, operation (add/remove/update), relation types, and optional fields.export const ManageWorkItemLinkSchema = z.object({ sourceWorkItemId: z.number().describe('The ID of the source work item'), targetWorkItemId: z.number().describe('The ID of the target work item'), projectId: z .string() .optional() .describe(`The ID or name of the project (Default: ${defaultProject})`), organizationId: z .string() .optional() .describe(`The ID or name of the organization (Default: ${defaultOrg})`), operation: z .enum(['add', 'remove', 'update']) .describe('The operation to perform on the link'), relationType: z .string() .describe( 'The reference name of the relation type (e.g., "System.LinkTypes.Hierarchy-Forward")', ), newRelationType: z .string() .optional() .describe('The new relation type to use when updating a link'), comment: z .string() .optional() .describe('Optional comment explaining the link'), });
- src/features/work-items/tool-definitions.ts:36-39 (registration)MCP tool registration definition, specifying name, description, and input JSON schema derived from Zod schema.name: 'manage_work_item_link', description: 'Add or remove links between work items', inputSchema: zodToJsonSchema(ManageWorkItemLinkSchema), },
- src/features/work-items/index.ts:127-144 (registration)Runtime dispatch handler in the main work-items request handler that parses arguments with the schema and invokes the manageWorkItemLink function.case 'manage_work_item_link': { const args = ManageWorkItemLinkSchema.parse(request.params.arguments); const result = await manageWorkItemLink( connection, args.projectId ?? defaultProject, { sourceWorkItemId: args.sourceWorkItemId, targetWorkItemId: args.targetWorkItemId, operation: args.operation, relationType: args.relationType, newRelationType: args.newRelationType, comment: args.comment, }, ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }