@vm3jack/mcp-server-azure-devops 1.0.0

package/docs/tools/pipelines.md

@@ -0,0 +1,532 @@
+# Pipeline Tools
+
+This document describes the tools available for working with Azure DevOps pipelines.
+
+## Table of Contents
+
+- [`list_pipelines`](#list_pipelines) - List pipelines in a project
+- [`get_pipeline`](#get_pipeline) - Get details of a specific pipeline
+- [`list_pipeline_runs`](#list_pipeline_runs) - List recent runs for a pipeline
+- [`get_pipeline_run`](#get_pipeline_run) - Get details of a specific run (plus artifacts)
+- [`download_pipeline_artifact`](#download_pipeline_artifact) - Download an artifact file as text
+- [`pipeline_timeline`](#pipeline_timeline) - Retrieve the stage and job timeline for a run
+- [`get_pipeline_log`](#get_pipeline_log) - Retrieve raw or JSON-formatted log content
+- [`trigger_pipeline`](#trigger_pipeline) - Trigger a pipeline run
+
+## list_pipelines
+
+Lists pipelines in a project.
+
+### Parameters
+
+| Parameter   | Type   | Required | Description                                               |
+| ----------- | ------ | -------- | --------------------------------------------------------- |
+| `projectId` | string | No       | The ID or name of the project (Default: from environment) |
+| `orderBy`   | string | No       | Order by field and direction (e.g., "createdDate desc")   |
+| `top`       | number | No       | Maximum number of pipelines to return                     |
+
+### Response
+
+Returns an array of pipeline objects:
+
+```json
+{
+  "count": 2,
+  "value": [
+    {
+      "id": 4,
+      "revision": 2,
+      "name": "Node.js build pipeline",
+      "folder": "\\",
+      "url": "https://dev.azure.com/organization/project/_apis/pipelines/4"
+    },
+    {
+      "id": 1,
+      "revision": 1,
+      "name": "Sample Pipeline",
+      "folder": "\\",
+      "url": "https://dev.azure.com/organization/project/_apis/pipelines/1"
+    }
+  ]
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the project does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Using default project from environment
+const result = await callTool('list_pipelines', {});
+
+// Specifying project and limiting results
+const limitedResult = await callTool('list_pipelines', {
+  projectId: 'my-project',
+  top: 10,
+  orderBy: 'name asc',
+});
+```
+
+## get_pipeline
+
+Gets details of a specific pipeline.
+
+### Parameters
+
+| Parameter         | Type   | Required | Description                                                       |
+| ----------------- | ------ | -------- | ----------------------------------------------------------------- |
+| `projectId`       | string | No       | The ID or name of the project (Default: from environment)         |
+| `pipelineId`      | number | Yes      | The numeric ID of the pipeline to retrieve                        |
+| `pipelineVersion` | number | No       | The version of the pipeline to retrieve (latest if not specified) |
+
+### Response
+
+Returns a pipeline object with the following structure:
+
+```json
+{
+  "id": 4,
+  "revision": 2,
+  "name": "Node.js build pipeline",
+  "folder": "\\",
+  "url": "https://dev.azure.com/organization/project/_apis/pipelines/4",
+  "_links": {
+    "self": {
+      "href": "https://dev.azure.com/organization/project/_apis/pipelines/4"
+    },
+    "web": {
+      "href": "https://dev.azure.com/organization/project/_build/definition?definitionId=4"
+    }
+  },
+  "configuration": {
+    "path": "azure-pipelines.yml",
+    "repository": {
+      "id": "bd0e8130-7fba-4f3b-8559-54760b6e7248",
+      "type": "azureReposGit"
+    },
+    "type": "yaml"
+  }
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the pipeline or project does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Get latest version of a pipeline
+const result = await callTool('get_pipeline', {
+  pipelineId: 4,
+});
+
+// Get specific version of a pipeline
+const versionResult = await callTool('get_pipeline', {
+  projectId: 'my-project',
+  pipelineId: 4,
+  pipelineVersion: 2,
+});
+```
+
+## list_pipeline_runs
+
+Lists recent runs for a given pipeline with optional filtering by branch, state, result, or time window.
+
+### Parameters
+
+| Parameter           | Type         | Required | Description                                                                 |
+| ------------------- | ------------ | -------- | --------------------------------------------------------------------------- |
+| `projectId`         | string       | No       | The ID or name of the project (Default: from environment)                   |
+| `pipelineId`        | number       | Yes      | Numeric ID of the pipeline whose runs should be returned                    |
+| `top`               | number       | No       | Maximum rows to return (1-100, default 50)                                  |
+| `continuationToken` | string       | No       | Continuation token for paging through long histories                         |
+| `branch`            | string       | No       | Filter runs by branch (accepts `main` or full ref like `refs/heads/main`)   |
+| `state`             | string       | No       | Filter by current run state (`notStarted`, `inProgress`, `completed`, etc.) |
+| `result`            | string       | No       | Filter by final run result (`succeeded`, `failed`, `canceled`, etc.)        |
+| `createdFrom`       | string (ISO) | No       | Restrict runs created on or after this timestamp                            |
+| `createdTo`         | string (ISO) | No       | Restrict runs created on or before this timestamp                           |
+| `orderBy`           | string       | No       | Sort order for creation date (`createdDate desc` by default)                |
+
+### Response
+
+Returns the runs plus a continuation token when more pages are available:
+
+```json
+{
+  "runs": [
+    {
+      "id": 13590799,
+      "name": "20251001.2",
+      "createdDate": "2025-10-01T08:59:27.343Z",
+      "state": "completed",
+      "result": "succeeded",
+      "pipeline": { "id": 69847, "name": "embed-confluence-content" },
+      "_links": {
+        "web": {
+          "href": "https://dev.azure.com/org/project/_build/results?buildId=13590799"
+        }
+      }
+    }
+  ],
+  "continuationToken": "eyJwYWdlIjoxfQ=="
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the pipeline or project does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Fetch the latest 10 runs on the main branch
+const runs = await callTool('list_pipeline_runs', {
+  pipelineId: 69847,
+  top: 10,
+  branch: 'main',
+});
+
+// Continue from a previous page
+const nextPage = await callTool('list_pipeline_runs', {
+  pipelineId: 69847,
+  continuationToken: runs.continuationToken,
+});
+```
+
+## get_pipeline_run
+
+Gets detailed information about a single pipeline run, including artifact listings when available.
+
+### Parameters
+
+| Parameter    | Type   | Required | Description                                                                 |
+| ------------ | ------ | -------- | --------------------------------------------------------------------------- |
+| `projectId`  | string | No       | The ID or name of the project (Default: from environment)                   |
+| `runId`      | number | Yes      | Numeric ID of the pipeline run                                              |
+| `pipelineId` | number | No       | Optional guard to validate the run belongs to the specified pipeline        |
+
+### Response
+
+Returns the pipeline run enriched with artifact metadata:
+
+```json
+{
+  "id": 13590799,
+  "name": "20251001.2",
+  "state": "completed",
+  "result": "succeeded",
+  "pipeline": { "id": 69847, "name": "embed-confluence-content" },
+  "createdDate": "2025-10-01T08:59:27.343Z",
+  "artifacts": [
+    {
+      "name": "embedding-batch",
+      "type": "PipelineArtifact",
+      "downloadUrl": "https://.../embedding-batch.zip",
+      "signedContentUrl": "https://.../signedContent",
+      "items": [
+        { "path": "logs", "itemType": "folder" },
+        { "path": "logs/summary.json", "itemType": "file" }
+      ]
+    },
+    {
+      "name": "embedding-metrics",
+      "type": "Container",
+      "containerId": 39106000,
+      "rootPath": "embedding-metrics",
+      "items": [
+        { "path": "embedding_metrics.json", "itemType": "file", "size": 2048 }
+      ]
+    }
+  ]
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the run or project does not exist
+- Returns `AzureDevOpsResourceNotFoundError` if `pipelineId` is provided and does not match the run
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Inspect a run and the files it produced
+const run = await callTool('get_pipeline_run', {
+  runId: 13590799,
+});
+
+// Guard against a run from another pipeline
+await callTool('get_pipeline_run', {
+  pipelineId: 69847,
+  runId: 13590799,
+});
+```
+
+## download_pipeline_artifact
+
+Downloads a single file from a pipeline run artifact (container or pipeline artifact) and returns its textual content.
+
+### Parameters
+
+| Parameter      | Type   | Required | Description                                                                 |
+| -------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| `projectId`    | string | No       | The ID or name of the project (Default: from environment)                   |
+| `runId`        | number | Yes      | Numeric ID of the pipeline run                                              |
+| `artifactPath` | string | Yes      | Artifact name and file path (e.g., `artifact-name/path/to/file.json`)       |
+| `pipelineId`   | number | No       | Optional guard to disambiguate runs triggered by different pipelines        |
+
+### Response
+
+Returns the file content along with artifact metadata:
+
+```json
+{
+  "artifact": "embedding-metrics",
+  "path": "embedding-metrics/embedding_metrics.json",
+  "content": "{\n  \"status\": \"ok\"\n}"
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the artifact or requested file is missing
+- Returns `AzureDevOpsAuthenticationError` if the artifact storage cannot be accessed
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Download a JSON summary generated by the run
+const artifact = await callTool('download_pipeline_artifact', {
+  runId: 13590799,
+  artifactPath: 'embedding-metrics/embedding_metrics.json',
+});
+console.log(JSON.parse(artifact.content));
+```
+
+## pipeline_timeline
+
+Retrieves the timeline of stages, jobs, and tasks for a pipeline run with optional filtering by state and result.
+
+### Parameters
+
+| Parameter    | Type                   | Required | Description                                                                     |
+| ------------ | ---------------------- | -------- | ------------------------------------------------------------------------------- |
+| `projectId`  | string                 | No       | The ID or name of the project (Default: from environment)                       |
+| `runId`      | number                 | Yes      | Numeric ID of the pipeline run                                                  |
+| `timelineId` | string                 | No       | Fetch a specific timeline record (otherwise returns the default timeline)       |
+| `pipelineId` | number                 | No       | Optional reference to the pipeline for documentation purposes                   |
+| `state`      | string or string array | No       | Filter returned records by state (`pending`, `inProgress`, `completed`)         |
+| `result`     | string or string array | No       | Filter returned records by result (`succeeded`, `failed`, `canceled`, etc.)     |
+
+### Response
+
+Returns the timeline records (filtered when requested):
+
+```json
+{
+  "id": "f9d9c210-06c7-4e53-b45f-6b661341fa7f",
+  "records": [
+    {
+      "id": "Stage_1",
+      "name": "Build",
+      "type": "Stage",
+      "state": "completed",
+      "result": "succeeded",
+      "startTime": "2025-10-01T08:59:30.123Z",
+      "finishTime": "2025-10-01T09:02:10.456Z"
+    },
+    {
+      "id": "Job_1",
+      "name": "Agent job",
+      "type": "Job",
+      "parentId": "Stage_1",
+      "state": "completed",
+      "result": "succeeded"
+    }
+  ]
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the timeline or project does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Fetch the full timeline
+const timeline = await callTool('pipeline_timeline', {
+  runId: 13590799,
+});
+
+// Only keep completed records
+const completed = await callTool('pipeline_timeline', {
+  runId: 13590799,
+  state: 'completed',
+});
+```
+
+## get_pipeline_log
+
+Retrieves log content for a specific timeline log. Supports plain text or JSON (structured lines) formats.
+
+### Parameters
+
+| Parameter    | Type   | Required | Description                                                                  |
+| ------------ | ------ | -------- | ---------------------------------------------------------------------------- |
+| `projectId`  | string | No       | The ID or name of the project (Default: from environment)                    |
+| `runId`      | number | Yes      | Numeric ID of the pipeline run                                               |
+| `logId`      | number | Yes      | Log identifier from the timeline records                                    |
+| `format`     | string | No       | `plain` (default) or `json`                                                  |
+| `startLine`  | number | No       | First line to include (useful for large logs)                                |
+| `endLine`    | number | No       | Last line to include (exclusive, when paired with `startLine`)               |
+| `pipelineId` | number | No       | Optional reference to help locate the log when working across many pipelines |
+
+### Response
+
+- When `format` is omitted or set to `plain`, returns a newline-delimited string:
+
+```text
+Queueing build...
+Starting: Build
+##[section]Starting: Initialize job
+```
+
+- When `format` is set to `json`, returns the structured log payload from Azure DevOps:
+
+```json
+[
+  {
+    "line": 1,
+    "stepRecordId": "Job_1",
+    "content": "##[section]Starting: Initialize job"
+  }
+]
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the log or project does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Grab the first 200 lines of plain text
+const logText = await callTool('get_pipeline_log', {
+  runId: 13590799,
+  logId: 12,
+  startLine: 0,
+  endLine: 200,
+});
+
+// Fetch the same lines as structured JSON
+const logJson = await callTool('get_pipeline_log', {
+  runId: 13590799,
+  logId: 12,
+  format: 'json',
+  startLine: 0,
+  endLine: 200,
+});
+```
+
+## trigger_pipeline
+
+Triggers a run of a specific pipeline. Allows specifying the branch to run on and passing variables to customize the pipeline execution.
+
+### Parameters
+
+| Parameter            | Type   | Required | Description                                                           |
+| -------------------- | ------ | -------- | --------------------------------------------------------------------- |
+| `projectId`          | string | No       | The ID or name of the project (Default: from environment)             |
+| `pipelineId`         | number | Yes      | The numeric ID of the pipeline to trigger                             |
+| `branch`             | string | No       | The branch to run the pipeline on (e.g., "main", "feature/my-branch") |
+| `variables`          | object | No       | Variables to pass to the pipeline run                                 |
+| `templateParameters` | object | No       | Parameters for template-based pipelines                               |
+| `stagesToSkip`       | array  | No       | Stages to skip in the pipeline run                                    |
+
+#### Variables Format
+
+```json
+{
+  "myVariable": {
+    "value": "my-value",
+    "isSecret": false
+  },
+  "secretVariable": {
+    "value": "secret-value",
+    "isSecret": true
+  }
+}
+```
+
+### Response
+
+Returns a run object with details about the triggered pipeline run:
+
+```json
+{
+  "id": 12345,
+  "name": "20230215.1",
+  "createdDate": "2023-02-15T10:30:00Z",
+  "url": "https://dev.azure.com/organization/project/_apis/pipelines/runs/12345",
+  "_links": {
+    "self": {
+      "href": "https://dev.azure.com/organization/project/_apis/pipelines/runs/12345"
+    },
+    "web": {
+      "href": "https://dev.azure.com/organization/project/_build/results?buildId=12345"
+    }
+  },
+  "state": 1,
+  "result": null,
+  "variables": {
+    "myVariable": {
+      "value": "my-value"
+    }
+  }
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the pipeline or project does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Trigger a pipeline on the default branch
+// In this case, use default project from environment variables
+const result = await callTool('trigger_pipeline', {
+  pipelineId: 4,
+});
+
+// Trigger a pipeline on a specific branch with variables
+const runWithOptions = await callTool('trigger_pipeline', {
+  projectId: 'my-project',
+  pipelineId: 4,
+  branch: 'feature/my-branch',
+  variables: {
+    deployEnvironment: {
+      value: 'staging',
+      isSecret: false,
+    },
+  },
+});
+```

package/docs/tools/projects.md

@@ -0,0 +1,114 @@
+# Azure DevOps Projects Tools
+
+This document describes the tools available for working with Azure DevOps projects.
+
+## list_projects
+
+Lists all projects in the Azure DevOps organization.
+
+### Description
+
+The `list_projects` tool retrieves all projects that the authenticated user has access to within the configured Azure DevOps organization. This is useful for discovering which projects are available before working with repositories, work items, or other project-specific resources.
+
+This tool uses the Azure DevOps WebApi client to interact with the Core API.
+
+### Parameters
+
+All parameters are optional:
+
+```json
+{
+  "stateFilter": 1, // Optional: Filter on team project state
+  "top": 100, // Optional: Maximum number of projects to return
+  "skip": 0, // Optional: Number of projects to skip
+  "continuationToken": 123 // Optional: Gets projects after the continuation token provided
+}
+```
+
+| Parameter           | Type   | Required | Description                                                                             |
+| ------------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
+| `stateFilter`       | number | No       | Filter on team project state (0: all, 1: well-formed, 2: creating, 3: deleting, 4: new) |
+| `top`               | number | No       | Maximum number of projects to return in a single request                                |
+| `skip`              | number | No       | Number of projects to skip, useful for pagination                                       |
+| `continuationToken` | number | No       | Gets the projects after the continuation token provided                                 |
+
+### Response
+
+The tool returns an array of `TeamProject` objects, each containing:
+
+- `id`: The unique identifier of the project
+- `name`: The name of the project
+- `description`: The project description (if available)
+- `url`: The URL of the project
+- `state`: The state of the project (e.g., "wellFormed")
+- `revision`: The revision of the project
+- `visibility`: The visibility of the project (e.g., "private" or "public")
+- `lastUpdateTime`: The timestamp when the project was last updated
+- ... and potentially other project properties
+
+Example response:
+
+```json
+[
+  {
+    "id": "project-guid-1",
+    "name": "Project One",
+    "description": "This is the first project",
+    "url": "https://dev.azure.com/organization/Project%20One",
+    "state": "wellFormed",
+    "revision": 123,
+    "visibility": "private",
+    "lastUpdateTime": "2023-01-01T12:00:00.000Z"
+  },
+  {
+    "id": "project-guid-2",
+    "name": "Project Two",
+    "description": "This is the second project",
+    "url": "https://dev.azure.com/organization/Project%20Two",
+    "state": "wellFormed",
+    "revision": 456,
+    "visibility": "public",
+    "lastUpdateTime": "2023-02-15T14:30:00.000Z"
+  }
+]
+```
+
+### Error Handling
+
+The tool may throw the following errors:
+
+- General errors: If the API call fails or other unexpected errors occur
+- Authentication errors: If the authentication credentials are invalid or expired
+- Permission errors: If the authenticated user doesn't have permission to list projects
+
+Error messages will be formatted as text and provide details about what went wrong.
+
+### Example Usage
+
+```typescript
+// Example with no parameters (returns all projects)
+const allProjects = await mcpClient.callTool('list_projects', {});
+console.log(allProjects);
+
+// Example with pagination parameters
+const paginatedProjects = await mcpClient.callTool('list_projects', {
+  top: 10,
+  skip: 20,
+});
+console.log(paginatedProjects);
+
+// Example with state filter (only well-formed projects)
+const wellFormedProjects = await mcpClient.callTool('list_projects', {
+  stateFilter: 1,
+});
+console.log(wellFormedProjects);
+```
+
+### Implementation Details
+
+This tool uses the Azure DevOps Node API's Core API to retrieve projects:
+
+1. It gets a connection to the Azure DevOps WebApi client
+2. It calls the `getCoreApi()` method to get a handle to the Core API
+3. It then calls `getProjects()` with any provided parameters to retrieve the list of projects
+4. The results are returned directly to the caller