Azure DevOps Multi-Organization MCP Server

Instructions

Implementation Reference

• src/tools/pipelines.ts:34-75 (handler)

  The main handler logic that connects to Azure DevOps, calls getDefinitions API with filtered parameters, simplifies the build definitions list, and returns formatted JSON response.

  async ({ organization, project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename }) => {
      const connection = await connectionManager.getConnection(organization);
      const buildApi = await connection.getBuildApi();
      
      // Default top to 50 to prevent massive responses
      const limit = top || 50;
  
      const buildDefinitions = await buildApi.getDefinitions(
          project, 
          name, 
          repositoryId, 
          repositoryType, 
          safeEnumConvert(DefinitionQueryOrder, queryOrder), 
          limit, 
          continuationToken, 
          minMetricsTime ? new Date(minMetricsTime) : undefined, 
          definitionIds, 
          path, 
          builtAfter ? new Date(builtAfter) : undefined, 
          notBuiltAfter ? new Date(notBuiltAfter) : undefined, 
          includeAllProperties, 
          includeLatestBuilds, 
          taskIdFilter, 
          processType, 
          yamlFilename
      );
  
      // Simplify the output
      const simplifiedDefinitions = buildDefinitions.map(d => ({
          id: d.id,
          name: d.name,
          path: d.path,
          type: d.type,
          queueStatus: d.queueStatus,
          revision: d.revision,
          url: d.url
      }));
  
      return {
          content: [{ type: "text", text: JSON.stringify(simplifiedDefinitions, null, 2) }],
      };
  }

• src/tools/pipelines.ts:11-33 (schema)

  Zod schema for tool input parameters, including all filters and pagination options for querying build definitions.

  {
      organization: z.string().describe("The name of the Azure DevOps organization"),
      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))
          .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.string().optional().describe("Minimum metrics time to filter build definitions (ISO 8601 string)"),
      definitionIds: z.array(z.number()).optional().describe("Array of build definition IDs to filter"),
      builtAfter: z.string().optional().describe("Return definitions that have builds after this date (ISO 8601 string)"),
      notBuiltAfter: z.string().optional().describe("Return definitions that do not have builds after this date (ISO 8601 string)"),
      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/pipelines.ts:8-76 (registration)

  MCP server tool registration call that associates the name, description, input schema, and handler function.

  server.tool(
    "pipelines_get_build_definitions",
    "Gets a list of build definitions (pipeline configurations) in a project",
    {
        organization: z.string().describe("The name of the Azure DevOps organization"),
        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))
            .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.string().optional().describe("Minimum metrics time to filter build definitions (ISO 8601 string)"),
        definitionIds: z.array(z.number()).optional().describe("Array of build definition IDs to filter"),
        builtAfter: z.string().optional().describe("Return definitions that have builds after this date (ISO 8601 string)"),
        notBuiltAfter: z.string().optional().describe("Return definitions that do not have builds after this date (ISO 8601 string)"),
        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 ({ organization, project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename }) => {
        const connection = await connectionManager.getConnection(organization);
        const buildApi = await connection.getBuildApi();
        
        // Default top to 50 to prevent massive responses
        const limit = top || 50;
  
        const buildDefinitions = await buildApi.getDefinitions(
            project, 
            name, 
            repositoryId, 
            repositoryType, 
            safeEnumConvert(DefinitionQueryOrder, queryOrder), 
            limit, 
            continuationToken, 
            minMetricsTime ? new Date(minMetricsTime) : undefined, 
            definitionIds, 
            path, 
            builtAfter ? new Date(builtAfter) : undefined, 
            notBuiltAfter ? new Date(notBuiltAfter) : undefined, 
            includeAllProperties, 
            includeLatestBuilds, 
            taskIdFilter, 
            processType, 
            yamlFilename
        );
  
        // Simplify the output
        const simplifiedDefinitions = buildDefinitions.map(d => ({
            id: d.id,
            name: d.name,
            path: d.path,
            type: d.type,
            queueStatus: d.queueStatus,
            revision: d.revision,
            url: d.url
        }));
  
        return {
            content: [{ type: "text", text: JSON.stringify(simplifiedDefinitions, null, 2) }],
        };
    }
  );

• src/tools/common.ts:1-7 (helper)

  Helper utility to extract string enum keys, used in the schema for queryOrder parameter.

  export function getEnumKeys(enumObject: any): [string, ...string[]] {
      const keys = Object.keys(enumObject).filter((key) => isNaN(Number(key)));
      if (keys.length === 0) {
          return ["Values"]; 
      }
      return [keys[0], ...keys.slice(1)];
  }

• src/tools/common.ts:9-12 (helper)

  Helper utility for safe enum value lookup, used in the handler for queryOrder conversion.

  export function safeEnumConvert<T>(enumObject: any, key?: string): T | undefined {
      if (!key) return undefined;
      return enumObject[key];
  }