Add Support for Azure DevOps Work Item Artifact Links

[cgsg10]

Summary

Add artifact link management capabilities to Azure DevOps MCP tools to enable automated repository linking for work items, specifically supporting GitHub Copilot integration.

Tools

Develop the following tools with full parameter support, including optional ones:

mcp_ado_wit_add_artifact_link: Add artifact links (repository, branch, commit) to work items.

Parameters:

• workItemId (required): The ID of the work item to add the artifact link to
• project (required): The name or ID of the Azure DevOps project
• artifactUri (required): The URI of the artifact to link (e.g., vstfs:///Git/Ref/{projectId}%2F{repositoryId}%2FGB{branchName} for branches)
• linkType (optional): Type of artifact link, defaults to "Branch"
• comment (optional): Comment to include with the artifact link

Endpoint: PATCH https://dev.azure.com/{organization}/_apis/wit/workitems/{id}?api-version=7.2-preview.3

Request Body Format: JSON Patch array with Content-Type: application/json-patch+json

Request Body:

[
  {
    "op": "add",
    "path": "/relations/-",
    "value": {
      "rel": "ArtifactLink",
      "url": "{artifactUri}",
      "attributes": {
        "name": "{linkType}",
        "comment": "{comment}"
      }
    }
  }
]

Implementation Notes:

• The rel property must always be "ArtifactLink"
• The url property contains the vstfs URI for the artifact
• The attributes.name property should match the linkType parameter
• The attributes.comment property is optional

mcp_ado_wit_remove_artifact_link: Remove artifact links from work items.

Parameters:

• workItemId (required): The ID of the work item to remove the artifact link from
• project (required): The name or ID of the Azure DevOps project
• artifactUri (required): The URI of the artifact to unlink
• linkType (optional): Type of artifact link to remove, defaults to "Branch"

Endpoint: PATCH https://dev.azure.com/{organization}/_apis/wit/workitems/{id}?api-version=7.2-preview.3

Request Body Format: JSON Patch array with Content-Type: application/json-patch+json

Request Body:

[
  {
    "op": "remove",
    "path": "/relations/{relationIndex}"
  }
]

Implementation Notes:

• First retrieve the work item with $expand=relations to get current relations
• Find the index of the relation to remove by matching the artifactUri in the url property
• Use the found index in the path property (e.g., /relations/0 for the first relation)
• The operation will fail if the specified index doesn't exist

mcp_ado_wit_list_artifact_links: List all artifact links associated with a work item.

Parameters:

• workItemId (required): The ID of the work item to retrieve artifact links for
• project (required): The name or ID of the Azure DevOps project
• artifactType (optional): Filter by artifact type (e.g., "Branch", "Commit", "PullRequest")

Endpoint: GET https://dev.azure.com/{organization}/_apis/wit/workitems/{id}?$expand=relations&api-version=7.2-preview.3

Request Body: None (GET request)

Response Format:

{
  "id": 206223,
  "fields": { ... },
  "relations": [
    {
      "rel": "ArtifactLink",
      "url": "vstfs:///Git/Ref/{projectId}%2F{repositoryId}%2FGB{branchName}",
      "attributes": {
        "name": "Branch",
        "comment": "Optional comment"
      }
    }
  ]
}

Implementation Notes:

• Use $expand=relations query parameter to include relations in the response
• Filter relations where rel === "ArtifactLink"
• Parse the url property to determine artifact type from vstfs URI format
• The attributes.name property indicates the artifact type (Branch, Commit, etc.)

Rules

1. Adhere strictly to existing project standards and coding conventions.
2. Ensure each tool exposes all API parameters (required and optional).
3. Use the official Azure DevOps Node API to interact with the APIs.
4. Follow the existing MCP tool naming pattern (mcp_ado_wit_*) for consistency.
5. Implement proper error handling for invalid artifact URIs and missing work items.
6. Support the vstfs URI format for different artifact types:
   • Branch: vstfs:///Git/Ref/{projectId}%2F{repositoryId}%2FGB{branchName}
   • Commit: vstfs:///Git/Commit/{projectId}%2F{repositoryId}%2F{commitId}
   • Pull Request: vstfs:///Git/PullRequestId/{projectId}%2F{repositoryId}%2F{pullRequestId}

Special treat

If you follow the rules, you'll get candy! 🍭

Context

This enhancement addresses a gap in the current MCP Azure DevOps tooling that prevents automated artifact link creation. Currently, users must manually add repository/branch links through the Azure DevOps web UI before GitHub Copilot can work on work items. These tools will enable full automation of the work item creation and assignment process, including the artifact links that GitHub Copilot requires for repository context.

The implementation should handle the complex vstfs URI format and provide clear error messages when artifact links cannot be created (e.g., invalid repository references, insufficient permissions, or malformed URIs).

Use Case Example

// Example usage for adding a branch artifact link
await mcp_ado_wit_add_artifact_link({
  workItemId: 1234,
  project: "OneFuzz",
  artifactUri: "vstfs:///Git/Ref/12341234-1234-1234-1234-123412341234%2F12341234-1234-1234-1234-123412341234%2FGBmain",
  linkType: "Branch",
  comment: "Linked to main branch for GitHub Copilot integration"
});

[danhellem]

Actually, I like this idea. Will add into the queue

[danhellem]

Couple of things to deal with

mcp_ado_wit_add_artifact_link

How are you going to figure out what the artifact link is? Depending on the link, the url is in different formats. How is the LLM going to know?

examples:

• Branch: - vstfs:///Git/Ref/dee68f12-9d28-4aba-83bf-e3470f2af8f0%2F5bb63655-a9d3-4a81-bb40-a840c589e48b%2FGBtest-1
• Fixed in Commit - vstfs:///Git/Commit/dee68f12-9d28-4aba-83bf-e3470f2af8f0%2F5bb63655-a9d3-4a81-bb40-a840c589e48b%2F5169aa1069478dc3c374eecc557763125b5cd43a
• Pull Request - vstfs:///Git/PullRequestId/SampleProject2%2F5bb63655-a9d3-4a81-bb40-a840c589e48b%2F411

mcp_ado_wit_remove_artifact_link

we should be able to accomplish this in #132

mcp_ado_wit_list_artifact_links

This is already done in get_work_item

[danhellem]

I am dropping this for now. If we get some other folks who request it, we can pick it back up