tools

package
v0.0.0-...-9c0f5be Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2025 License: MIT Imports: 19 Imported by: 0

README

Azure DevOps Tools

This package contains a set of high-level, focused tools for an AI agent to interact with Azure DevOps.

Tools

The tools come in a few different categories that indicate certain parts of a standard workflow.

Sprint Management

For sprint management, the model should be able to either provide a specific sprint to operate on, or it can use @CurrentIteration to operate on the current sprint.

  • get_sprints: Get all sprints in Azure DevOps, useful for the model to understand which sprints exist, especially when creating new sprints.
  • create_sprint: Create a new sprint in Azure DevOps.
  • sprint_items: Get the items in a sprint in Azure DevOps.
  • sprint_overview: Get the overview of a sprint in Azure DevOps.
Work Item Management

To keep the amount of tools manageable, for the most part each tool will default to bulk operations. The model could just provide a list of one item to operate on, or it can provide a list of items to operate on.

We also want to maximize the amount of information that can be provided to the model to make decisions.

This includes returning related work items, as well as the ability to add related work items to a work item.

This also includes returning comments from work items, as well as the ability to add comments to work items.

  • create_work_items: Create a new work item in Azure DevOps.
  • get_work_items: Get the details of a work item in Azure DevOps.
  • update_work_items: Update a work item in Azure DevOps. This should be capable of dealing with the full range of work item fields, including assignment, status, custom fields, sprint, relationships, comments, etc.
Miscellaneous
  • search_work_items: Search for work items in Azure DevOps by keywords, abstracting away the WIQL query.
  • execute_wiql: Execute a WIQL query on Azure DevOps, returning the results.
REVIEW

If you consider the tools you have available now for azure, assuming for the moment they would all be working, is there anything missing for you to effectively manage azure boards and work items?

Edit Looking at the Azure DevOps tools available, you have a pretty comprehensive set for work item management. Let me analyze what's there and what might be missing for truly effective Azure Boards management:

Current Tool Coverage ✅ Core CRUD Operations:

✅ Create work items (azure_create_work_items) ✅ Read/Get work items (azure_get_work_items) ✅ Update work items (azure_update_work_items) ✅ Search/Query work items (azure_execute_wiql, azure_search_work_items) Sprint Management:

✅ Get sprints (azure_get_sprints) ✅ Create sprints (azure_create_sprint) ✅ Sprint overview (azure_sprint_overview) ✅ Sprint work items (azure_sprint_items)

Notable Gaps for Advanced Management 🔍

  1. Work Item Deletion & State Management:

No bulk state transitions (moving multiple items from "Doing" to "Done")

  1. Advanced Relationship Management:

Can add/remove relations in updates, but no dedicated relationship visualization

No dependency mapping or critical path analysis No bulk relationship operations

  1. Team & Capacity Management:

No workload distribution analysis No team velocity metrics

  1. Board Configuration:

No board customization (columns, swimlanes, card fields) No board rules management No custom field definitions

  1. Advanced Analytics & Reporting:

No burndown chart data No cycle time analysis No work item history/audit trails No bulk export capabilities 6. Process Template Management:

No work item type customization No workflow state customization No field rule management 7. Integration & Automation:

No webhook management No automated rule creation No integration with external tools (GitHub, etc.) Most Critical Missing Pieces for Your Use Case 🎯 Given your development background and need for out-of-the-box solutions, I'd prioritize these missing capabilities:

  1. Bulk Operations Tool:

javascript // Conceptual tool for bulk state changes azure_bulk_update({ query: "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'DOING'", updates: { state: "DONE", resolved_date: "today" } }) 2. Advanced Analytics Tool:

javascript // Sprint metrics and team performance azure_get_analytics({ sprint_id: "current", metrics: ["velocity", "burndown", "cycle_time", "blocked_items"] }) 3. Work Item Templates:

javascript // Standardized work item creation azure_create_from_template({ template: "bug_template", values: { severity: "high", component: "api" } }) 4. Dependency Analysis:

javascript // Critical path and blocking analysis
azure_analyze_dependencies({ root_item_id: 1964, depth: 3, include_blocked: true }) The current toolset covers about 70-80% of typical Azure Boards management needs. The gaps are mainly in advanced analytics, bulk operations, and process automation - areas where you'd typically want more sophisticated tooling for enterprise-level project management.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var FieldMap = map[string]string{
	"Title":       "System.Title",
	"Description": "System.Description",
	"State":       "System.State",
	"Priority":    "Microsoft.VSTS.Common.Priority",
}

Field name mapping

View Source 
var RelationTypeMap = map[string]string{
	"parent":   "System.LinkTypes.Hierarchy-Reverse",
	"child":    "System.LinkTypes.Hierarchy-Forward",
	"children": "System.LinkTypes.Hierarchy-Forward",
	"related":  "System.LinkTypes.Related",
}

Relation type mapping

Functions

func AddOperation 

func AddOperation(field string, value any) webapi.JsonPatchOperation

Helper function to add an operation

func ExtractWorkItemIDFromURL 

func ExtractWorkItemIDFromURL(itemURL string) (int, error)

ExtractWorkItemIDFromURL extracts the work item ID from a standard Azure DevOps work item URL. Example URL: https://dev.azure.com/org/project/_apis/wit/workItems/123 or https://org.visualstudio.com/project/_apis/wit/workItems/123

func FormatStringList 

func FormatStringList(items []string) string

Format a list of strings for WIQL queries

func GetCurrentSprint 

func GetCurrentSprint(ctx context.Context, workClient work.Client, project string, team string) (map[string]any, error)

GetCurrentSprint uses the Azure DevOps SDK to get current sprint information.

func GetFloat64Arg 

func GetFloat64Arg(req mcp.CallToolRequest, key string) (float64, error)

Helper to extract a float64 argument.

func GetIntArg 

func GetIntArg(req mcp.CallToolRequest, key string) (int, error)

Helper to extract an int argument from a float64.

func GetOptionalStringParamWithFallback 

func GetOptionalStringParamWithFallback(req mcp.CallToolRequest, key string, fallbackValue string) string

GetOptionalStringParamWithFallback is a helper function. It tries to get a string parameter from the request. If not found or empty, it returns the fallbackValue.

func GetStringArg 

func GetStringArg(req mcp.CallToolRequest, key string) (string, error)

Helper to extract a string argument.

func GetWorkItemURL 

func GetWorkItemURL(orgURL string, workItemID int) string

GetWorkItemURL constructs the UI URL for a work item.

func HandleError 

func HandleError(err error, message string) *mcp.CallToolResult

Helper for common error formatting

func Min 

func Min(a, b int) int

Helper function for min value

func NewAzureCreateSprintTool 

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

NewAzureCreateSprintTool creates a new tool instance for creating sprints.

func NewAzureCreateWorkItemsTool 

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

NewAzureCreateWorkItemsTool creates a new tool instance for creating work items.

func NewAzureEnrichWorkItemTool 

func NewAzureEnrichWorkItemTool(conn *azuredevops.Connection, globalConfig AzureDevOpsConfig) core.Tool

NewAzureEnrichWorkItemTool creates a new tool instance for enriching work items.

func NewAzureExecuteWiqlTool 

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

NewAzureExecuteWiqlTool creates a new tool instance for executing WIQL queries.

func NewAzureFindItemsByStatusTool 

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

NewAzureFindItemsByStatusTool creates a new tool instance for finding items by status

func NewAzureGetGitHubFileContentTool 

func NewAzureGetGitHubFileContentTool() core.Tool

NewAzureGetGitHubFileContentTool creates a new tool instance for retrieving GitHub file content.

func NewAzureGetSprintsTool 

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

NewAzureGetSprintsTool creates a new tool instance for listing sprints.

func NewAzureGetWorkItemsTool 

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

NewAzureGetWorkItemsTool creates a new tool instance for getting work item details

func NewAzureSearchWorkItemsTool 

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

NewAzureSearchWorkItemsTool creates a new tool instance for searching work items.

func NewAzureSprintItemsTool 

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

NewAzureSprintItemsTool creates a new tool instance for finding items in the current sprint

func NewAzureSprintOverviewTool 

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

NewAzureSprintOverviewTool creates a new tool instance.

func NewAzureUpdateWorkItemsTool 

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

NewAzureUpdateWorkItemsTool creates a new tool instance for updating work items.

func NewAzureWorkItemCommentsTool 

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

NewAzureWorkItemCommentsTool creates a new tool instance for managing work item comments

func ParseIDs 

func ParseIDs(idsStr string) ([]int, error)

Helper to parse a comma-separated list of IDs

func SafeString 

func SafeString(s *string) string

SafeString dereferences a string pointer and returns its value, or an empty string if nil.

func StringPtr 

func StringPtr(s string) *string

Helper function to create a string pointer

Types

type AzureCreateSprintTool 

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

AzureCreateSprintTool provides functionality to create new sprints (iterations).

func (*AzureCreateSprintTool) Handle 

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

func (*AzureCreateSprintTool) Handler 

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

type AzureCreateWorkItemsTool 

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

AzureCreateWorkItemsTool provides functionality to create new work items in bulk with custom fields.

func (*AzureCreateWorkItemsTool) Handle 

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

func (*AzureCreateWorkItemsTool) Handler 

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

type AzureDevOpsConfig 

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

AzureDevOpsConfig contains configuration for Azure DevOps integration

type AzureEnrichWorkItemTool 

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

AzureEnrichWorkItemTool provides functionality to search across platforms for information related to a work item.

func (*AzureEnrichWorkItemTool) Handle 

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

Handle returns the MCP tool handle.

func (*AzureEnrichWorkItemTool) Handler 

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

Handler is the main execution function for the enrich work item tool.

type AzureExecuteWiqlTool 

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

AzureExecuteWiqlTool provides functionality to execute WIQL queries.

func (*AzureExecuteWiqlTool) Handle 

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

func (*AzureExecuteWiqlTool) Handler 

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

Handler executes the WIQL query.

type AzureFindItemsByStatusTool 

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

AzureFindItemsByStatusTool provides functionality to find work items by status

func (*AzureFindItemsByStatusTool) Handle 

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

func (*AzureFindItemsByStatusTool) Handler 

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

type AzureGetGitHubFileContentTool 

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

AzureGetGitHubFileContentTool provides functionality to retrieve the content of a file from GitHub.

func (*AzureGetGitHubFileContentTool) Handle 

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

Handle returns the MCP tool handle.

func (*AzureGetGitHubFileContentTool) Handler 

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

Handler is the main execution function for the get GitHub file content tool.

type AzureGetSprintsTool 

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

AzureGetSprintsTool provides functionality to list sprints (iterations).

func (*AzureGetSprintsTool) Handle 

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

func (*AzureGetSprintsTool) Handler 

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

type AzureGetWorkItemsTool 

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

AzureGetWorkItemsTool provides functionality to get work item details

func (*AzureGetWorkItemsTool) Handle 

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

func (*AzureGetWorkItemsTool) Handler 

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

type AzureSearchWorkItemsTool 

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

AzureSearchWorkItemsTool provides functionality to search for work items.

func (*AzureSearchWorkItemsTool) Handle 

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

func (*AzureSearchWorkItemsTool) Handler 

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

type AzureSprintItemsTool 

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

AzureSprintItemsTool provides functionality to find work items in the current sprint

func (*AzureSprintItemsTool) Handle 

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

func (*AzureSprintItemsTool) Handler 

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

type AzureSprintOverviewTool 

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

AzureSprintOverviewTool provides functionality to get an overview of a sprint.

func (*AzureSprintOverviewTool) Handle 

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

func (*AzureSprintOverviewTool) Handler 

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

type AzureUpdateWorkItemsTool 

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

AzureUpdateWorkItemsTool provides functionality to update multiple work items in Azure DevOps.

func (*AzureUpdateWorkItemsTool) Handle 

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

func (*AzureUpdateWorkItemsTool) Handler 

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

type AzureWorkItemCommentsTool 

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

AzureWorkItemCommentsTool provides functionality to manage comments on work items

func (*AzureWorkItemCommentsTool) Handle 

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

func (*AzureWorkItemCommentsTool) Handler 

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

type CommentOutput 

type CommentOutput struct {
	ID           int    `json:"id"`
	Text         string `json:"text"`
	CreatedBy    string `json:"created_by"`
	CreatedDate  string `json:"created_date"`
	ModifiedBy   string `json:"modified_by,omitempty"`
	ModifiedDate string `json:"modified_date,omitempty"`
}

CommentOutput defines the structure for a single comment's output.

type DetailedWorkItemOutput 

type DetailedWorkItemOutput struct {
	ID        int                             `json:"id"`
	URL       string                          `json:"url"`
	Fields    map[string]any                  `json:"fields"` // All raw fields, includes Tags if fetched
	Relations *DetailedWorkItemRelationOutput `json:"relations,omitempty"`
	Comments  []string                        `json:"comments,omitempty"`
	Tags      string                          `json:"tags,omitempty"` // Extracted for convenience

	// Specific, commonly used fields for text formatting, can be extracted from Fields
	Title         string `json:"-"`
	Type          string `json:"-"`
	State         string `json:"-"`
	AssignedTo    string `json:"-"`
	IterationPath string `json:"-"`
	AreaPath      string `json:"-"`
	Description   string `json:"-"`
}

DetailedWorkItemOutput defines the structure for detailed work item information for output.

type DetailedWorkItemRelationOutput 

type DetailedWorkItemRelationOutput struct {
	Parents  []int `json:"parents,omitempty"`
	Children []int `json:"children,omitempty"`
	Related  []int `json:"related,omitempty"`
}

DetailedWorkItemRelationOutput defines the structure for work item relations for output.

type EnrichmentResults 

type EnrichmentResults struct {
	GitHubIssuesPRs   []GitHubIssueResult  `json:"github_issues_prs,omitempty"`
	GitHubCodeResults []GitHubCodeResult   `json:"github_code_results,omitempty"`
	SlackMessages     []SlackMessageResult `json:"slack_messages,omitempty"`
	SentryIssues      []SentryIssueResult  `json:"sentry_issues,omitempty"`
}

type GitHubCodeResult 

type GitHubCodeResult struct {
	File           string `json:"file"`
	URL            string `json:"url"`
	Repo           string `json:"repo"`
	SnippetPreview string `json:"snippet_preview,omitempty"` // Might not always be available or easy to get
}

type GitHubIssueResult 

type GitHubIssueResult struct {
	Title   string  `json:"title"`
	URL     string  `json:"url"`
	Repo    string  `json:"repo"`
	State   string  `json:"state"`
	Body    *string `json:"body,omitempty"`
	DiffURL *string `json:"diff_url,omitempty"`
}

SearchResult structures 

type RelationLink struct {
	RelType        string            `json:"rel_type"` // e.g., "System.LinkTypes.Hierarchy-Forward"
	TargetURL      string            `json:"target_url"`
	LinkAttributes map[string]string `json:"attributes,omitempty"`
}

RelationLink defines structure for adding a work item relation

type RelationLinkArgs 

type RelationLinkArgs struct {
	RelType     string `json:"rel_type"`               // e.g., "System.LinkTypes.Hierarchy-Forward", optional if removing by ref
	TargetURL   string `json:"target_url,omitempty"`   // URL of the related work item
	RelationRef string `json:"relation_ref,omitempty"` // Internal reference of the link itself (e.g. from get_work_item)
}

RelationLinkArgs is used for identifying relations to remove, can be by target URL or by relation reference

type SearchWorkItemOutput 

type SearchWorkItemOutput struct {
	ID    int    `json:"id"`
	Title string `json:"title"`
	Type  string `json:"type"`
	State string `json:"state"`
	URL   string `json:"url"`
}

SearchWorkItemOutput defines the structure for a single work item in search results.

type SentryIssueResult 

type SentryIssueResult struct {
	ID        string `json:"id"`
	Title     string `json:"title"`
	Permalink string `json:"permalink"`
	Project   string `json:"project"`
}

type SlackMessageResult 

type SlackMessageResult struct {
	Permalink   string `json:"permalink"`
	User        string `json:"user"`
	Channel     string `json:"channel"`
	TextPreview string `json:"text_preview"`
}

type SprintOutput 

type SprintOutput struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	IterationPath string `json:"iteration_path"`
	StartDate     string `json:"start_date,omitempty"`
	EndDate       string `json:"end_date,omitempty"`
	TimeFrame     string `json:"time_frame,omitempty"`
	URL           string `json:"url,omitempty"`
}

SprintOutput defines the structure for a single sprint's details for output. This structure is adapted from the previous pkg/tools/azure/sprint.go

type SprintOverviewOutput 

type SprintOverviewOutput struct {
	ID                   string         `json:"id,omitempty"`
	Name                 string         `json:"name"`
	IterationPath        string         `json:"iteration_path"`
	StartDate            string         `json:"start_date,omitempty"`
	EndDate              string         `json:"end_date,omitempty"`
	TimeFrame            string         `json:"time_frame,omitempty"`
	URL                  string         `json:"url,omitempty"`
	Goal                 string         `json:"goal,omitempty"` // Sprint Goal, if available
	TotalWorkItems       int            `json:"total_work_items"`
	WorkItemsByState     map[string]int `json:"work_items_by_state"`
	WorkItemsByType      map[string]int `json:"work_items_by_type"`
	UniqueAssignees      []string       `json:"unique_assignees,omitempty"`
	SampleWorkItemTitles []string       `json:"sample_work_item_titles,omitempty"` // A few titles for context
}

SprintOverviewOutput defines the structure for the sprint overview.

type SprintWorkItemOutput 

type SprintWorkItemOutput struct {
	ID            int    `json:"id"`
	Title         string `json:"title"`
	State         string `json:"state"`
	Type          string `json:"type"`
	URL           string `json:"url"`
	AssignedTo    string `json:"assigned_to,omitempty"`
	IterationPath string `json:"iteration_path,omitempty"`
	ParentIDs     []int  `json:"parent_ids,omitempty"`
}

SprintWorkItemOutput defines the structure for work item details for output.

type WorkItemDefinition 

type WorkItemDefinition struct {
	Type         string            `json:"type"`
	Title        string            `json:"title"`
	Description  string            `json:"description,omitempty"`
	State        string            `json:"state,omitempty"`
	Priority     string            `json:"priority,omitempty"`
	ParentID     string            `json:"parent_id,omitempty"`
	AssignedTo   string            `json:"assigned_to,omitempty"`
	Iteration    string            `json:"iteration,omitempty"`
	Area         string            `json:"area,omitempty"`
	Tags         string            `json:"tags,omitempty"`
	CustomFields map[string]string `json:"custom_fields,omitempty"`
}

WorkItemDefinition is used to parse the JSON input for each work item to be created.

type WorkItemUpdateDefinition 

type WorkItemUpdateDefinition struct {
	ID              int                `json:"id"`
	FieldsToUpdate  map[string]any     `json:"fields_to_update"`           // Flexible map for all field types
	Comment         string             `json:"comment,omitempty"`          // For adding a new comment
	AddRelations    []RelationLink     `json:"add_relations,omitempty"`    // For adding new relations
	RemoveRelations []RelationLinkArgs `json:"remove_relations,omitempty"` // For removing relations by URL or Ref
}

WorkItemUpdateDefinition defines the structure for updating a single work item.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.