build_get_timeline tool (Issue 345) (#443)

Implement `build_get_timeline` tool with tests.

## GitHub issue number
Fixes #345 

## **Associated Risks**


## ✅ **PR Checklist**

- [x] **I have read the [contribution
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CONTRIBUTING.md)**
- [x] **I have read the [code of conduct
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CODE_OF_CONDUCT.md)**
- [x] Title of the pull request is clear and informative.
- [x] 👌 Code hygiene
- [x] 🔭 Telemetry added, updated, or N/A
- [x] 📄 Documentation added, updated, or N/A
- [x] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**
Added tests. Tested via the following prompt:

```
Get the timeline for the buildid 6 in the project ABC
```

Author: nikolapeja6

README.md

@@ -120,6 +120,7 @@ Interact with these Azure DevOps services:
 - **build_get_log**: Retrieve the logs for a specific build.
 - **build_get_log_by_id**: Get a specific build log by log ID.
 - **build_get_changes**: Get the changes associated with a specific build.
+- **build_get_timeline**: Retrieve the timeline for a specific build, showing detailed information about steps and tasks.
 - **build_run_build**: Trigger a new build for a specified definition.
 - **build_get_status**: Fetch the status of a specific build.
 - **build_update_build_stage**: Update the stage of a specific build.

src/tools/builds.ts

@@ -19,6 +19,7 @@ const BUILD_TOOLS = {
   run_build: "build_run_build",
   get_status: "build_get_status",
   update_build_stage: "build_update_build_stage",
+  get_timeline: "build_get_timeline",
 };
 
 function configureBuildTools(server: McpServer, tokenProvider: () => Promise<AccessToken>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string) {
@@ -357,6 +358,27 @@ function configureBuildTools(server: McpServer, tokenProvider: () => Promise<Acc
       };
     }
   );
+
+  server.tool(
+    BUILD_TOOLS.get_timeline,
+    "Retrieves the timeline for a specific build, showing detailed information about steps and tasks.",
+    {
+      project: z.string().describe("Project ID or name to get the build timeline for"),
+      buildId: z.number().describe("ID of the build to get the timeline for"),
+      timelineId: z.string().optional().describe("The ID of a specific timeline to retrieve. If not specified, the primary timeline is returned."),
+      changeId: z.number().optional().describe("If specified, only includes timeline records that changed after this watermark."),
+      planId: z.string().optional().describe("The ID of the plan to retrieve the timeline for."),
+    },
+    async ({ project, buildId, timelineId, changeId, planId }) => {
+      const connection = await connectionProvider();
+      const buildApi = await connection.getBuildApi();
+      const timeline = await buildApi.getBuildTimeline(project, buildId, timelineId, changeId, planId);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(timeline, null, 2) }],
+      };
+    }
+  );
 }
 
 export { BUILD_TOOLS, configureBuildTools };

test/src/tools/builds.test.ts

@@ -871,4 +871,104 @@ describe("configureBuildTools", () => {
       await expect(handler(params)).rejects.toThrow("Build not found");
     });
   });
+
+  describe("get_timeline tool", () => {
+    it("should retrieve the timeline for a build", async () => {
+      configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider);
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "build_get_timeline");
+      if (!call) throw new Error("build_get_timeline tool not registered");
+      const [, , , handler] = call;
+
+      const mockTimeline = {
+        id: "timeline-123",
+        records: [
+          {
+            id: "record-1",
+            name: "Initialize job",
+            type: "Task",
+            startTime: "2024-08-19T10:00:00.000Z",
+            finishTime: "2024-08-19T10:01:00.000Z",
+            state: "Completed",
+            result: "Succeeded",
+          },
+          {
+            id: "record-2",
+            name: "Checkout",
+            type: "Task",
+            startTime: "2024-08-19T10:01:00.000Z",
+            finishTime: "2024-08-19T10:02:00.000Z",
+            state: "Completed",
+            result: "Succeeded",
+          },
+        ],
+      };
+
+      const mockBuildApi = {
+        getBuildTimeline: jest.fn().mockResolvedValue(mockTimeline),
+      };
+      mockConnection.getBuildApi.mockResolvedValue(mockBuildApi);
+
+      const params = {
+        project: "test-project",
+        buildId: 123,
+        timelineId: "timeline-123",
+        changeId: 456,
+        planId: "plan-789",
+      };
+
+      const result = await handler(params);
+
+      expect(mockBuildApi.getBuildTimeline).toHaveBeenCalledWith("test-project", 123, "timeline-123", 456, "plan-789");
+      expect(result.content[0].text).toBe(JSON.stringify(mockTimeline, null, 2));
+    });
+
+    it("should handle minimal parameters for get_timeline", async () => {
+      configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider);
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "build_get_timeline");
+      if (!call) throw new Error("build_get_timeline tool not registered");
+      const [, , , handler] = call;
+
+      const mockTimeline = {
+        id: "timeline-123",
+        records: [
+          { id: "record-1", name: "Task 1", state: "Completed" },
+          { id: "record-2", name: "Task 2", state: "Completed" },
+        ],
+      };
+
+      const mockBuildApi = {
+        getBuildTimeline: jest.fn().mockResolvedValue(mockTimeline),
+      };
+      mockConnection.getBuildApi.mockResolvedValue(mockBuildApi);
+
+      const params = {
+        project: "test-project",
+        buildId: 123,
+      };
+
+      const result = await handler(params);
+
+      expect(mockBuildApi.getBuildTimeline).toHaveBeenCalledWith("test-project", 123, undefined, undefined, undefined);
+      expect(result.content[0].text).toBe(JSON.stringify(mockTimeline, null, 2));
+    });
+
+    it("should handle API errors for get_timeline", async () => {
+      configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider);
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "build_get_timeline");
+      if (!call) throw new Error("build_get_timeline tool not registered");
+      const [, , , handler] = call;
+
+      const mockBuildApi = {
+        getBuildTimeline: jest.fn().mockRejectedValue(new Error("Timeline not found")),
+      };
+      mockConnection.getBuildApi.mockResolvedValue(mockBuildApi);
+
+      const params = {
+        project: "test-project",
+        buildId: 999,
+      };
+
+      await expect(handler(params)).rejects.toThrow("Timeline not found");
+    });
+  });
 });