Azure DevOps Multi-Organization MCP Server

Instructions

Implementation Reference

• src/tools/pipelines.ts:127-194 (handler)

  The asynchronous handler function implementing the core logic of the 'pipelines_get_builds' tool. It connects to Azure DevOps, queries builds with provided filters using the Build API, simplifies the response data, and returns it as JSON text.
  async ({ organization, project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType }) => { const connection = await connectionManager.getConnection(organization); const buildApi = await connection.getBuildApi(); // Default to a summary view if properties are not specified to avoid hitting token limits // We select key fields that are most useful for status checks const defaultProperties = [ "id", "buildNumber", "status", "result", "queueTime", "startTime", "finishTime", "url", "definition", "project", "sourceBranch", "requestedFor" ]; const selectedProperties = properties || defaultProperties; // Default top to 20 if not specified to prevent massive responses const limit = top || 20; const builds = await buildApi.getBuilds( project, definitions, queues, buildNumber, minTime ? new Date(minTime) : undefined, maxTime ? new Date(maxTime) : undefined, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, selectedProperties, limit, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType ); // Simplify the output to reduce token usage const simplifiedBuilds = builds.map(b => ({ id: b.id, buildNumber: b.buildNumber, status: b.status, result: b.result, queueTime: b.queueTime, startTime: b.startTime, finishTime: b.finishTime, definition: b.definition ? { id: b.definition.id, name: b.definition.name } : undefined, sourceBranch: b.sourceBranch, requestedFor: b.requestedFor ? { displayName: b.requestedFor.displayName } : undefined, url: b.url })); return { content: [{ type: "text", text: JSON.stringify(simplifiedBuilds, null, 2) }], }; }
• src/tools/pipelines.ts:99-126 (schema)

  Zod schema defining the input parameters for the 'pipelines_get_builds' tool, including organization, project, various filters, and pagination options.
  { organization: z.string().describe("The name of the Azure DevOps organization"), 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.string().optional().describe("Minimum finish time to filter builds (ISO 8601 string)"), maxTime: z.string().optional().describe("Maximum finish time to filter builds (ISO 8601 string)"), 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)) .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/pipelines.ts:96-195 (registration)

  The server.tool() call that registers the 'pipelines_get_builds' tool, including its name, description, input schema, and handler function within the registerPipelineTools function.
  server.tool( "pipelines_get_builds", "Gets a list of builds (pipeline runs) with filtering options", { organization: z.string().describe("The name of the Azure DevOps organization"), 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.string().optional().describe("Minimum finish time to filter builds (ISO 8601 string)"), maxTime: z.string().optional().describe("Maximum finish time to filter builds (ISO 8601 string)"), 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)) .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 ({ organization, project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType }) => { const connection = await connectionManager.getConnection(organization); const buildApi = await connection.getBuildApi(); // Default to a summary view if properties are not specified to avoid hitting token limits // We select key fields that are most useful for status checks const defaultProperties = [ "id", "buildNumber", "status", "result", "queueTime", "startTime", "finishTime", "url", "definition", "project", "sourceBranch", "requestedFor" ]; const selectedProperties = properties || defaultProperties; // Default top to 20 if not specified to prevent massive responses const limit = top || 20; const builds = await buildApi.getBuilds( project, definitions, queues, buildNumber, minTime ? new Date(minTime) : undefined, maxTime ? new Date(maxTime) : undefined, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, selectedProperties, limit, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType ); // Simplify the output to reduce token usage const simplifiedBuilds = builds.map(b => ({ id: b.id, buildNumber: b.buildNumber, status: b.status, result: b.result, queueTime: b.queueTime, startTime: b.startTime, finishTime: b.finishTime, definition: b.definition ? { id: b.definition.id, name: b.definition.name } : undefined, sourceBranch: b.sourceBranch, requestedFor: b.requestedFor ? { displayName: b.requestedFor.displayName } : undefined, url: b.url })); return { content: [{ type: "text", text: JSON.stringify(simplifiedBuilds, null, 2) }], }; } );