build_get_definitions
Retrieve a filtered list of build definitions for a specific project in Azure DevOps, enabling efficient management and querying of build configurations based on criteria like repository type, name, path, or build activity.
Instructions
Retrieves a list of build definitions for a given project.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| builtAfter | No | Return definitions that have builds after this date | |
| continuationToken | No | Token for continuing paged results | |
| definitionIds | No | Array of build definition IDs to filter | |
| includeAllProperties | No | Whether to include all properties in the results | |
| includeLatestBuilds | No | Whether to include the latest builds for each definition | |
| minMetricsTime | No | Minimum metrics time to filter build definitions | |
| name | No | Name of the build definition to filter | |
| notBuiltAfter | No | Return definitions that do not have builds after this date | |
| path | No | Path of the build definition to filter | |
| processType | No | Process type to filter build definitions | |
| project | Yes | Project ID or name to get build definitions for | |
| queryOrder | No | Order in which build definitions are returned | |
| repositoryId | No | Repository ID to filter build definitions | |
| repositoryType | No | Type of repository to filter build definitions | |
| taskIdFilter | No | Task ID to filter build definitions | |
| top | No | Maximum number of build definitions to return | |
| yamlFilename | No | YAML filename to filter build definitions |
Implementation Reference
- src/tools/builds.ts:12-22 (registration)BUILD_TOOLS constant mapping internal names to MCP tool names, including 'get_definitions' to 'build_get_definitions'.
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/builds.ts:28-49 (schema)Zod input schema for the build_get_definitions tool defining parameters for querying build definitions.
{ project: z.string().describe("Project ID or name to get build definitions for"), repositoryId: z.string().optional().describe("Repository ID to filter build definitions"), repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter build definitions"), name: z.string().optional().describe("Name of the build definition to filter"), path: z.string().optional().describe("Path of the build definition to filter"), queryOrder: z .enum(getEnumKeys(DefinitionQueryOrder) as [string, ...string[]]) .optional() .describe("Order in which build definitions are returned"), top: z.number().optional().describe("Maximum number of build definitions to return"), continuationToken: z.string().optional().describe("Token for continuing paged results"), minMetricsTime: z.coerce.date().optional().describe("Minimum metrics time to filter build definitions"), definitionIds: z.array(z.number()).optional().describe("Array of build definition IDs to filter"), builtAfter: z.coerce.date().optional().describe("Return definitions that have builds after this date"), notBuiltAfter: z.coerce.date().optional().describe("Return definitions that do not have builds after this date"), includeAllProperties: z.boolean().optional().describe("Whether to include all properties in the results"), includeLatestBuilds: z.boolean().optional().describe("Whether to include the latest builds for each definition"), taskIdFilter: z.string().optional().describe("Task ID to filter build definitions"), processType: z.number().optional().describe("Process type to filter build definitions"), yamlFilename: z.string().optional().describe("YAML filename to filter build definitions"), }, - src/tools/builds.ts:50-94 (handler)Handler implementation that uses Azure DevOps Build API to fetch build definitions based on input parameters and returns JSON-formatted results.
async ({ project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename, }) => { const connection = await connectionProvider(); const buildApi = await connection.getBuildApi(); const buildDefinitions = await buildApi.getDefinitions( project, name, repositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename ); return { content: [{ type: "text", text: JSON.stringify(buildDefinitions, null, 2) }], }; } - src/tools/builds.ts:25-95 (registration)Registers the 'build_get_definitions' tool with MCP server, specifying description, input schema, and handler function.
server.tool( BUILD_TOOLS.get_definitions, "Retrieves a list of build definitions for a given project.", { project: z.string().describe("Project ID or name to get build definitions for"), repositoryId: z.string().optional().describe("Repository ID to filter build definitions"), repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter build definitions"), name: z.string().optional().describe("Name of the build definition to filter"), path: z.string().optional().describe("Path of the build definition to filter"), queryOrder: z .enum(getEnumKeys(DefinitionQueryOrder) as [string, ...string[]]) .optional() .describe("Order in which build definitions are returned"), top: z.number().optional().describe("Maximum number of build definitions to return"), continuationToken: z.string().optional().describe("Token for continuing paged results"), minMetricsTime: z.coerce.date().optional().describe("Minimum metrics time to filter build definitions"), definitionIds: z.array(z.number()).optional().describe("Array of build definition IDs to filter"), builtAfter: z.coerce.date().optional().describe("Return definitions that have builds after this date"), notBuiltAfter: z.coerce.date().optional().describe("Return definitions that do not have builds after this date"), includeAllProperties: z.boolean().optional().describe("Whether to include all properties in the results"), includeLatestBuilds: z.boolean().optional().describe("Whether to include the latest builds for each definition"), taskIdFilter: z.string().optional().describe("Task ID to filter build definitions"), processType: z.number().optional().describe("Process type to filter build definitions"), yamlFilename: z.string().optional().describe("YAML filename to filter build definitions"), }, async ({ project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename, }) => { const connection = await connectionProvider(); const buildApi = await connection.getBuildApi(); const buildDefinitions = await buildApi.getDefinitions( project, name, repositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename ); return { content: [{ type: "text", text: JSON.stringify(buildDefinitions, null, 2) }], }; } );