Azure DevOps MCP Server with PAT Authentication

Instructions

Implementation Reference

• src/tools/work.ts:64-104 (handler)

  The asynchronous handler function that implements the logic for creating new iterations in an Azure DevOps project using the WorkItemTrackingApi. It processes an array of iterations, creates each one with optional start and finish dates, collects results, and returns them as JSON or an error message.

  async ({ project, iterations }) => {
    try {
      const connection = await connectionProvider();
      const workItemTrackingApi = await connection.getWorkItemTrackingApi();
      const results = [];
  
      for (const { iterationName, startDate, finishDate } of iterations) {
        // Step 1: Create the iteration
        const iteration = await workItemTrackingApi.createOrUpdateClassificationNode(
          {
            name: iterationName,
            attributes: {
              startDate: startDate ? new Date(startDate) : undefined,
              finishDate: finishDate ? new Date(finishDate) : undefined,
            },
          },
          project,
          TreeStructureGroup.Iterations
        );
  
        if (iteration) {
          results.push(iteration);
        }
      }
  
      if (results.length === 0) {
        return { content: [{ type: "text", text: "No iterations were created" }], isError: true };
      }
  
      return {
        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
  
      return {
        content: [{ type: "text", text: `Error creating iterations: ${errorMessage}` }],
        isError: true,
      };
    }
  }

• src/tools/work.ts:52-63 (schema)

  Zod input schema defining the parameters for the tool: 'project' (string) and 'iterations' (array of objects with 'iterationName' (required string) and optional 'startDate'/'finishDate' (ISO strings)).

  {
    project: z.string().describe("The name or ID of the Azure DevOps project."),
    iterations: z
      .array(
        z.object({
          iterationName: z.string().describe("The name of the iteration to create."),
          startDate: z.string().optional().describe("The start date of the iteration in ISO format (e.g., '2023-01-01T00:00:00Z'). Optional."),
          finishDate: z.string().optional().describe("The finish date of the iteration in ISO format (e.g., '2023-01-31T23:59:59Z'). Optional."),
        })
      )
      .describe("An array of iterations to create. Each iteration must have a name and can optionally have start and finish dates in ISO format."),
  },

• src/tools/work.ts:49-105 (registration)

  Registration of the MCP tool 'work_create_iterations' via server.tool(), specifying the tool name (from WORK_TOOLS), description, input schema, and handler function.

  server.tool(
    WORK_TOOLS.create_iterations,
    "Create new iterations in a specified Azure DevOps project.",
    {
      project: z.string().describe("The name or ID of the Azure DevOps project."),
      iterations: z
        .array(
          z.object({
            iterationName: z.string().describe("The name of the iteration to create."),
            startDate: z.string().optional().describe("The start date of the iteration in ISO format (e.g., '2023-01-01T00:00:00Z'). Optional."),
            finishDate: z.string().optional().describe("The finish date of the iteration in ISO format (e.g., '2023-01-31T23:59:59Z'). Optional."),
          })
        )
        .describe("An array of iterations to create. Each iteration must have a name and can optionally have start and finish dates in ISO format."),
    },
    async ({ project, iterations }) => {
      try {
        const connection = await connectionProvider();
        const workItemTrackingApi = await connection.getWorkItemTrackingApi();
        const results = [];
  
        for (const { iterationName, startDate, finishDate } of iterations) {
          // Step 1: Create the iteration
          const iteration = await workItemTrackingApi.createOrUpdateClassificationNode(
            {
              name: iterationName,
              attributes: {
                startDate: startDate ? new Date(startDate) : undefined,
                finishDate: finishDate ? new Date(finishDate) : undefined,
              },
            },
            project,
            TreeStructureGroup.Iterations
          );
  
          if (iteration) {
            results.push(iteration);
          }
        }
  
        if (results.length === 0) {
          return { content: [{ type: "text", text: "No iterations were created" }], isError: true };
        }
  
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
  
        return {
          content: [{ type: "text", text: `Error creating iterations: ${errorMessage}` }],
          isError: true,
        };
      }
    }
  );

• src/tools/work.ts:10-14 (registration)

  Constant object WORK_TOOLS that maps internal handler names (e.g., 'create_iterations') to the full MCP tool names (e.g., 'work_create_iterations'), used in tool registrations.

  const WORK_TOOLS = {
    list_team_iterations: "work_list_team_iterations",
    create_iterations: "work_create_iterations",
    assign_iterations: "work_assign_iterations",
  };