build_get_builds
Fetch and filter build data from Azure DevOps projects using criteria like build ID, status, branch, or requester. Ideal for tracking and analyzing build history.
Instructions
Retrieves a list of builds for a given project.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| branchName | No | Branch name to filter builds | |
| buildIds | No | Array of build IDs to retrieve | |
| buildNumber | No | Build number to filter builds | |
| continuationToken | No | Token for continuing paged results | |
| definitions | No | Array of build definition IDs to filter builds | |
| deletedFilter | No | Filter for deleted builds (see QueryDeletedOption enum) | |
| maxBuildsPerDefinition | No | Maximum number of builds per definition | |
| maxTime | No | Maximum finish time to filter builds | |
| minTime | No | Minimum finish time to filter builds | |
| project | Yes | Project ID or name to get builds for | |
| properties | No | Array of property names to include in the results | |
| queryOrder | No | Order in which builds are returned | QueueTimeDescending |
| queues | No | Array of queue IDs to filter builds | |
| reasonFilter | No | Reason filter for the build (see BuildReason enum) | |
| repositoryId | No | Repository ID to filter builds | |
| repositoryType | No | Type of repository to filter builds | |
| requestedFor | No | User ID or name who requested the build | |
| resultFilter | No | Result filter for the build (see BuildResult enum) | |
| statusFilter | No | Status filter for the build (see BuildStatus enum) | |
| tagFilters | No | Array of tags to filter builds | |
| top | No | Maximum number of builds to return |
Implementation Reference
- src/tools/builds.ts:145-197 (handler)Handler function that fetches builds from Azure DevOps using the Build API based on provided filters and returns JSON-formatted results.
async ({ project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType, }) => { const connection = await connectionProvider(); const buildApi = await connection.getBuildApi(); const builds = await buildApi.getBuilds( project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType ); return { content: [{ type: "text", text: JSON.stringify(builds, null, 2) }], }; } - src/tools/builds.ts:119-144 (schema)Zod input schema defining all parameters for querying builds, including project, filters, pagination, and ordering options.
project: z.string().describe("Project ID or name to get builds for"), definitions: z.array(z.number()).optional().describe("Array of build definition IDs to filter builds"), queues: z.array(z.number()).optional().describe("Array of queue IDs to filter builds"), buildNumber: z.string().optional().describe("Build number to filter builds"), minTime: z.coerce.date().optional().describe("Minimum finish time to filter builds"), maxTime: z.coerce.date().optional().describe("Maximum finish time to filter builds"), requestedFor: z.string().optional().describe("User ID or name who requested the build"), reasonFilter: z.number().optional().describe("Reason filter for the build (see BuildReason enum)"), statusFilter: z.number().optional().describe("Status filter for the build (see BuildStatus enum)"), resultFilter: z.number().optional().describe("Result filter for the build (see BuildResult enum)"), tagFilters: z.array(z.string()).optional().describe("Array of tags to filter builds"), properties: z.array(z.string()).optional().describe("Array of property names to include in the results"), top: z.number().optional().describe("Maximum number of builds to return"), continuationToken: z.string().optional().describe("Token for continuing paged results"), maxBuildsPerDefinition: z.number().optional().describe("Maximum number of builds per definition"), deletedFilter: z.number().optional().describe("Filter for deleted builds (see QueryDeletedOption enum)"), queryOrder: z .enum(getEnumKeys(BuildQueryOrder) as [string, ...string[]]) .default("QueueTimeDescending") .optional() .describe("Order in which builds are returned"), branchName: z.string().optional().describe("Branch name to filter builds"), buildIds: z.array(z.number()).optional().describe("Array of build IDs to retrieve"), repositoryId: z.string().optional().describe("Repository ID to filter builds"), repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter builds"), }, - src/tools/builds.ts:115-198 (registration)MCP server.tool registration call that registers the 'build_get_builds' tool with its description, input schema, and handler function.
server.tool( BUILD_TOOLS.get_builds, "Retrieves a list of builds for a given project.", { project: z.string().describe("Project ID or name to get builds for"), definitions: z.array(z.number()).optional().describe("Array of build definition IDs to filter builds"), queues: z.array(z.number()).optional().describe("Array of queue IDs to filter builds"), buildNumber: z.string().optional().describe("Build number to filter builds"), minTime: z.coerce.date().optional().describe("Minimum finish time to filter builds"), maxTime: z.coerce.date().optional().describe("Maximum finish time to filter builds"), requestedFor: z.string().optional().describe("User ID or name who requested the build"), reasonFilter: z.number().optional().describe("Reason filter for the build (see BuildReason enum)"), statusFilter: z.number().optional().describe("Status filter for the build (see BuildStatus enum)"), resultFilter: z.number().optional().describe("Result filter for the build (see BuildResult enum)"), tagFilters: z.array(z.string()).optional().describe("Array of tags to filter builds"), properties: z.array(z.string()).optional().describe("Array of property names to include in the results"), top: z.number().optional().describe("Maximum number of builds to return"), continuationToken: z.string().optional().describe("Token for continuing paged results"), maxBuildsPerDefinition: z.number().optional().describe("Maximum number of builds per definition"), deletedFilter: z.number().optional().describe("Filter for deleted builds (see QueryDeletedOption enum)"), queryOrder: z .enum(getEnumKeys(BuildQueryOrder) as [string, ...string[]]) .default("QueueTimeDescending") .optional() .describe("Order in which builds are returned"), branchName: z.string().optional().describe("Branch name to filter builds"), buildIds: z.array(z.number()).optional().describe("Array of build IDs to retrieve"), repositoryId: z.string().optional().describe("Repository ID to filter builds"), repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter builds"), }, async ({ project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType, }) => { const connection = await connectionProvider(); const buildApi = await connection.getBuildApi(); const builds = await buildApi.getBuilds( project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType ); return { content: [{ type: "text", text: JSON.stringify(builds, null, 2) }], }; } ); - src/tools/builds.ts:12-22 (helper)Constant object mapping tool names to their string identifiers, including 'get_builds: "build_get_builds"'.
const BUILD_TOOLS = { get_definitions: "build_get_definitions", get_definition_revisions: "build_get_definition_revisions", get_builds: "build_get_builds", get_log: "build_get_log", get_log_by_id: "build_get_log_by_id", get_changes: "build_get_changes", run_build: "build_run_build", get_status: "build_get_status", update_build_stage: "build_update_build_stage", }; - src/tools.ts:19-30 (registration)Top-level function that configures all tools by calling configureBuildTools among others, which indirectly registers the build tools.
function configureAllTools(server: McpServer, tokenProvider: () => Promise<AccessToken>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string) { configureCoreTools(server, tokenProvider, connectionProvider, userAgentProvider); configureWorkTools(server, tokenProvider, connectionProvider); configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider); configureRepoTools(server, tokenProvider, connectionProvider, userAgentProvider); configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider); configureReleaseTools(server, tokenProvider, connectionProvider); configureWikiTools(server, tokenProvider, connectionProvider); configureTestPlanTools(server, tokenProvider, connectionProvider); configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider); configureAdvSecTools(server, tokenProvider, connectionProvider); }