azure

README

Azure DevOps Tools

This package provides tools for interacting with Azure DevOps through the MCP (Model-Centric Programming) framework.

Environment Setup

The following environment variables must be set:

AZURE_DEVOPS_ORG=your-organization-name
AZDO_PAT=your-personal-access-token
AZURE_DEVOPS_PROJECT=your-project-name

Available Tools

Work Item Tool

The Work Item tool allows you to manage and query Azure DevOps work items (tasks, bugs, user stories, epics, etc.).

Operations

The tool supports the following operations:

• get_help: Get help and documentation about the tool
• get_examples: Get example WIQL queries and usage patterns
• find_work_items: Find work items by state and parent relationship (recommended for AI assistants)
• list_fields: List available fields without needing a work item ID
• search: Search for work items by text in titles and descriptions
• get_states: Get all available work item states
• get_work_item_types: Get all available work item types
• find_orphaned_items: Find work items without parent links
• find_blocked_items: Find work items marked as blocked
• find_overdue_items: Find work items with past due dates
• find_sprint_items: Find work items in the current sprint
• query: Search for work items using WIQL
• get_details: Get details of specific work items by IDs
• create: Create a new work item
• update: Update a work item field
• manage_relations: Add or remove relations between work items
• get_related_work_items: Get work items related to a specific item
• add_comment: Add a comment to a work item
• get_comments: Get comments for a work item
• manage_tags: Add or remove tags from a work item
• get_tags: Get tags for a work item
• get_templates: Get work item templates
• create_from_template: Create a work item from a template
• add_attachment: Add an attachment to a work item
• get_attachments: Get attachments for a work item
• remove_attachment: Remove an attachment from a work item

Example Usage

To use the Work Item tool, you must specify an operation and appropriate parameters.

Getting Help

{
  "operation": "get_help"
}

For help on a specific operation:

{
  "operation": "get_help",
  "operation": "query"
}

Finding Work Items

Find items in DOING or REVIEW states:

{
  "operation": "find_work_items",
  "states": "DOING,REVIEW"
}

Find items without Epic parents:

{
  "operation": "find_work_items",
  "states": "DOING,REVIEW",
  "has_parent": "false",
  "parent_type": "Epic"
}

Querying Work Items with WIQL

{
  "operation": "query",
  "query": "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'DOING'"
}

Getting Work Item Details

{
  "operation": "get_details",
  "ids": "123,456,789"
}

Wiki Tool

The Wiki tool allows you to manage Azure DevOps wiki pages.

Operations

• manage_wiki_page: Create or update a wiki page
• get_wiki_page: Get a wiki page's content
• list_wiki_pages: List wiki pages
• search_wiki: Search for content in the wiki

Sprint Tool

The Sprint tool allows you to manage Azure DevOps sprints/iterations.

Operations

• get_current_sprint: Get the current sprint
• get_sprints: Get all sprints

Using with AI Assistants

When using these tools with AI assistants like Claude, start with one of these approaches:

1. Use the get_help operation to understand available operations:

   {
     "operation": "get_help"
   }
   

2. Use the find_work_items operation to find relevant work items:

   {
     "operation": "find_work_items",
     "states": "DOING,REVIEW"
   }
   

3. Use the list_fields operation to understand available fields:

   {
     "operation": "list_fields"
   }
   

4. Search for work items by text:

   {
     "operation": "search",
     "search_text": "authentication issue"
   }
   

5. Find items in the current sprint:

   {
     "operation": "find_sprint_items"
   }
   

6. Create different types of work items:

   {
     "operation": "create",
     "type": "User Story",
     "title": "As a user, I want to log in securely",
     "description": "Implement secure login functionality with proper error handling"
   }
   

   {
     "operation": "create",
     "type": "Epic",
     "title": "Authentication System Overhaul",
     "description": "Redesign the entire authentication system"
   }
   

7. Get available states for proper filtering:

   {
     "operation": "get_states"
   }
   

The tools include detailed help and examples to make them easier to use with AI assistants.

Documentation

Index

• func NewSprintTool(conn *azuredevops.Connection, config AzureDevOpsConfig) core.Tool
• func NewWikiTool(conn *azuredevops.Connection, config AzureDevOpsConfig) core.Tool
• func NewWorkItemTool(conn *azuredevops.Connection, config AzureDevOpsConfig) core.Tool
• type APIIterationResponseValue
• type APIIterationsResponse
• type AzureDevOpsConfig
• type AzureProvider
  • func NewAzureProvider() *AzureProvider
• type OperationHandler
• type SprintOutput
• type SprintTool
  • func (tool *SprintTool) Handle() mcp.Tool
  • func (tool *SprintTool) Handler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)
• type WikiTool
  • func (tool *WikiTool) Handle() mcp.Tool
  • func (tool *WikiTool) Handler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)
• type WorkItemTool
  • func (tool *WorkItemTool) Handle() mcp.Tool
  • func (tool *WorkItemTool) Handler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)

Functions

func NewSprintTool

func NewSprintTool(conn *azuredevops.Connection, config AzureDevOpsConfig) core.Tool

func NewWikiTool

func NewWikiTool(conn *azuredevops.Connection, config AzureDevOpsConfig) core.Tool

func NewWorkItemTool

func NewWorkItemTool(conn *azuredevops.Connection, config AzureDevOpsConfig) core.Tool

NewWorkItemTool creates a new tool instance.

Types

type APIIterationResponseValue

type APIIterationResponseValue struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	Path       string `json:"path"` // This is the Iteration Path
	Attributes struct {
		StartDate  *time.Time `json:"startDate"`  // Use pointer to handle potential nulls if API sends that
		FinishDate *time.Time `json:"finishDate"` // Use pointer
		TimeFrame  string     `json:"timeFrame"`
	} `json:"attributes"`
}

APIIterationResponseValue defines the structure for parsing individual iteration from Azure DevOps API.

type APIIterationsResponse

type APIIterationsResponse struct {
	Count int64                       `json:"count"`
	Value []APIIterationResponseValue `json:"value"`
}

APIIterationsResponse defines the overall structure for the iterations API response.

type AzureDevOpsConfig

type AzureDevOpsConfig struct {
	OrganizationURL     string
	PersonalAccessToken string
	Project             string
	Team                string
}

type AzureProvider

type AzureProvider struct {
	Tools map[string]core.Tool
	// contains filtered or unexported fields
}

func NewAzureProvider

func NewAzureProvider() *AzureProvider

type OperationHandler

type OperationHandler func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)

OperationHandler defines a function type for handling an operation.

type SprintOutput

type SprintOutput struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	IterationPath string `json:"iteration_path"`
	StartDate     string `json:"start_date"`
	EndDate       string `json:"end_date"`
}

SprintOutput defines the structure for a single sprint's details for output.

type SprintTool

type SprintTool struct {
	// contains filtered or unexported fields
}

func (*SprintTool) Handle

func (tool *SprintTool) Handle() mcp.Tool

func (*SprintTool) Handler

func (tool *SprintTool) Handler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)

type WikiTool

type WikiTool struct {
	// contains filtered or unexported fields
}

func (*WikiTool) Handle

func (tool *WikiTool) Handle() mcp.Tool

func (*WikiTool) Handler

func (tool *WikiTool) Handler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)

type WorkItemTool

type WorkItemTool struct {
	// contains filtered or unexported fields
}

WorkItemTool manages work items.

func (*WorkItemTool) Handle

func (tool *WorkItemTool) Handle() mcp.Tool

func (*WorkItemTool) Handler

func (tool *WorkItemTool) Handler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)

Handler dispatches operations based on the "operation" argument.