Skip to content

tools.md

Latest commit

 

History

History
444 lines (318 loc) · 13 KB

tools.md

File metadata and controls

444 lines (318 loc) · 13 KB

Tool Reference

Complete documentation for all 13 Azure DevOps MCP tools.

Overview

The Azure DevOps MCP server provides 13 tools organized into 4 categories:

  • Pull Requests (3 tools): Manage pull requests
  • Work Items (3 tools): Query and create work items
  • Pipelines (4 tools): Run and monitor pipelines
  • Variable Groups (3 tools): Manage variable groups

All tools return either:

  • Concise format: Human-readable markdown for list/read operations
  • JSON format: Full structured data for create/update operations

Pull Requests

create_pull_request

Creates a new pull request in Azure DevOps.

Parameters:

Parameter Type Required Default Description
repository string Yes - Name or ID of repository
source_branch string Yes - Source branch name
title string Yes - Pull request title
target_branch string No null Target branch (defaults to repo default branch)
description string No null Pull request description
reviewers list[string] No null List of reviewer usernames or emails
work_items list[int] No null Work item IDs to link to this PR
auto_complete boolean No false Enable auto-complete when all policies are met
squash boolean No false Squash commits when merging
delete_source_branch boolean No false Delete source branch after merge

Returns: Full JSON with created pull request details including:

  • pullRequestId - Unique PR identifier
  • title, description - PR details
  • sourceRefName, targetRefName - Branch references
  • status - PR status (active, abandoned, completed)
  • createdBy - Creator information
  • url - Direct link to PR

Example usage:

Create a pull request from feature/new-ui to main in my-repo with title "Add new UI components"

list_pull_requests

List pull requests with filtering options.

Parameters:

Parameter Type Required Default Description
repository string No null Filter by repository name or ID
creator string No null Filter by creator username
reviewer string No null Filter by reviewer username
source_branch string No null Filter by source branch name
target_branch string No null Filter by target branch name
status string No "active" Filter by status: active, abandoned, completed, all
top int No 25 Maximum results to return (1-100)
skip int No 0 Number of results to skip (pagination)

Returns: Concise markdown format with:

  • PR ID and title
  • Creator name and relative timestamp
  • Branch mapping (target ← source)
  • Total count and pagination info

Example usage:

List all active pull requests targeting the main branch

get_pull_request_details

Get detailed information about a specific pull request.

Parameters:

Parameter Type Required Default Description
pull_request_id int Yes - Pull request ID
include_work_items boolean No false Include linked work items (makes additional API call)

Returns: Full JSON with comprehensive PR details including:

  • All fields from create_pull_request
  • Commit information
  • Review status and votes
  • Merge status and conflicts
  • Related work items (if include_work_items=true)

Example usage:

Get details for pull request 123 including linked work items

Work Items

list_work_items

Query work items using WIQL or filter parameters.

Parameters:

Parameter Type Required Default Description
wiql string No null WIQL query string (takes precedence over filters)
type list[string] No null Filter by types: Bug, Task, User Story, Feature, Epic, etc.
state list[string] No null Filter by states: New, Active, Resolved, Closed, etc.
assigned_to string No null Filter by assigned user
area_path string No null Filter by area path
iteration_path string No null Filter by iteration path
top int No 50 Maximum results to return (1-200)

Behavior:

  • If wiql is provided, it's used directly and all other filters are ignored
  • Otherwise, filters are combined to build a WIQL query automatically
  • Multiple values in type or state are OR'd together
  • Different filter categories are AND'd together

Returns: Concise markdown format with:

  • Work item ID, type badge, and title
  • State and assigned user
  • Total count

Example usage:

List all active bugs assigned to john@contoso.com

List work items using WIQL: "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'"

get_work_item

Get detailed information about a specific work item.

Parameters:

Parameter Type Required Default Description
work_item_id int Yes - Work item ID
expand string No "all" What to expand: all, relations, fields, links, none

Returns: Full JSON with all work item details including:

  • id, rev - Identification and revision
  • fields - All system and custom fields
  • relations - Related work items, links, attachments
  • url - Direct link to work item

Example usage:

Get full details for work item 456

create_work_item

Create a new work item.

Parameters:

Parameter Type Required Default Description
type string Yes - Work item type: Bug, Task, User Story, Feature, Epic, etc.
title string Yes - Work item title
description string No null Work item description (supports HTML/markdown)
assigned_to string No null Username or email to assign to
area_path string No null Area path
iteration_path string No null Iteration path
state string No null Initial state (e.g., New, Active)
fields dict No null Additional custom fields as key-value pairs

Returns: Full JSON with created work item details.

Example usage:

Create a bug with title "Login fails on mobile" assigned to jane@contoso.com

Pipelines

list_pipelines

List pipelines in the project.

Parameters:

Parameter Type Required Default Description
name_filter string No null Filter by pipeline name (partial match)
folder_path string No null Filter by folder path
top int No 50 Maximum results to return (1-100)

Returns: Concise markdown format with:

  • Pipeline ID and name
  • Folder path (if not root)
  • Total count

Example usage:

List all pipelines in the /CI folder

run_pipeline

Queue and run a pipeline.

Parameters:

Parameter Type Required Default Description
pipeline_id int No null Pipeline ID (takes precedence over name)
pipeline_name string No null Pipeline name (used if ID not provided)
branch string No null Branch to run from
commit_id string No null Specific commit SHA to build
parameters dict No null Pipeline parameters as key-value pairs
variables dict No null Pipeline variables as key-value pairs

Required: Either pipeline_id or pipeline_name must be provided.

Returns: Full JSON with build details including:

  • id - Build/run ID
  • buildNumber - Build number
  • status - Current status
  • result - Final result (if completed)
  • _links.web.href - Direct link to build

Example usage:

Run pipeline 10 on the develop branch with variable environment=staging

list_pipeline_runs

List pipeline runs with filtering.

Parameters:

Parameter Type Required Default Description
pipeline_ids list[int] No null Filter by one or more pipeline IDs
branch string No null Filter by branch name
status string No "all" Filter by status: inProgress, completed, cancelling, all
result string No "all" Filter by result: succeeded, failed, canceled, all
top int No 25 Maximum results to return (1-100)
reason string No "all" Filter by trigger: manual, pullRequest, schedule, all

Returns: Concise markdown format with:

  • Run ID and pipeline name
  • Status and result
  • Started timestamp (relative)
  • Branch name

Example usage:

List last 10 failed pipeline runs

cancel_pipeline_run

Cancel a running pipeline.

Parameters:

Parameter Type Required Default Description
build_id int Yes - Build/run ID to cancel

Returns: Full JSON with cancellation confirmation including updated status.

Example usage:

Cancel pipeline run 789

Variable Groups

list_variable_groups

List variable groups in the project.

Parameters:

Parameter Type Required Default Description
group_name string No null Filter by variable group name (partial match)
action_filter string No null Filter by permission: manage, use, none
top int No 50 Maximum results to return (1-100)

Returns: Concise markdown format with:

  • Group ID and name
  • Number of variables
  • Total count

Example usage:

List all variable groups

get_variable_group

Get detailed information about a variable group.

Parameters:

Parameter Type Required Default Description
group_id int Yes - Variable group ID

Returns: Full JSON with all variable group details including:

  • id, name, description - Group metadata
  • variables - All variables with values
    • Security: Secret values are redacted as ***REDACTED***
  • type - Group type (Vsts or AzureKeyVault)
  • isShared - Whether accessible by all pipelines

Example usage:

Get variable group 42

update_variable_group_variable

Update or create a variable in a variable group.

Parameters:

Parameter Type Required Default Description
group_id int Yes - Variable group ID
variable_name string Yes - Variable name to update or create
variable_value string No null Variable value (omit to delete variable)
is_secret boolean No false Mark variable as secret

Behavior:

  • Tries to update the variable first
  • If variable doesn't exist, creates it automatically
  • If variable_value is null, deletes the variable

Returns: Full JSON with updated/created variable details.

  • Security: Secret values are redacted as ***REDACTED***

Example usage:

Update variable API_KEY in group 42 to value abc123 and mark as secret

Create variable DATABASE_URL in group 42 with value postgres://localhost

Response Formats

Concise Format

Used for list and read operations. Returns human-readable markdown with:

  • Headers with counts
  • Bullet points or numbered lists
  • Relative timestamps ("2 days ago")
  • Key information highlighted
  • Empty state messages

JSON Format

Used for create and update operations. Returns complete structured data with:

  • All resource fields
  • 2-space indentation
  • Proper type formatting
  • Secret redaction where applicable

Common Patterns

Error Handling

All tools handle errors gracefully with actionable messages:

  • Authentication Failed: Check your PAT token
  • Resource Not Found: Verify IDs are correct
  • Permission Denied: Ensure PAT has required scopes
  • Rate Limit: Wait before retrying

See Troubleshooting Guide for detailed error resolution.

Pagination

List operations support pagination:

  • top parameter limits results
  • skip parameter (PRs only) for offset-based pagination
  • Response indicates if more results available

Filtering

Most list operations support filtering:

  • String filters: partial match (case-insensitive)
  • Multiple values: OR'd together within category
  • Multiple categories: AND'd together

Security

  • PAT tokens never logged or exposed
  • Secret variable values always redacted
  • All inputs validated
  • No shell injection risk

Next Steps