@vm3jack/mcp-server-azure-devops 1.0.0

package/docs/tools/work-items.md

@@ -0,0 +1,182 @@
+# Work Item Tools
+
+This document describes the tools available for working with Azure DevOps work items.
+
+## Table of Contents
+
+- [`get_work_item`](#get_work_item) - Retrieve a specific work item by ID
+- [`create_work_item`](#create_work_item) - Create a new work item
+- [`list_work_items`](#list_work_items) - List work items in a project
+
+## get_work_item
+
+Retrieves a work item by its ID.
+
+### Parameters
+
+| Parameter    | Type   | Required | Description                                                                       |
+| ------------ | ------ | -------- | --------------------------------------------------------------------------------- |
+| `workItemId` | number | Yes      | The ID of the work item to retrieve                                               |
+| `expand`     | string | No       | Controls the level of detail in the response. Defaults to "All" if not specified. Other values: "Relations", "Fields", "None" |
+
+### Response
+
+Returns a work item object with the following structure:
+
+```json
+{
+  "id": 123,
+  "fields": {
+    "System.Title": "Sample Work Item",
+    "System.State": "Active",
+    "System.AssignedTo": "user@example.com",
+    "System.Description": "Description of the work item"
+  },
+  "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/123"
+}
+```
+
+### Error Handling
+
+- Returns `AzureDevOpsResourceNotFoundError` if the work item does not exist
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+// Using default expand="All"
+const result = await callTool('get_work_item', {
+  workItemId: 123,
+});
+
+// Explicitly specifying expand
+const minimalResult = await callTool('get_work_item', {
+  workItemId: 123,
+  expand: 'None'
+});
+```
+
+## create_work_item
+
+Creates a new work item in a specified project.
+
+### Parameters
+
+| Parameter          | Type   | Required | Description                                                         |
+| ------------------ | ------ | -------- | ------------------------------------------------------------------- |
+| `projectId`        | string | Yes      | The ID or name of the project where the work item will be created   |
+| `workItemType`     | string | Yes      | The type of work item to create (e.g., "Task", "Bug", "User Story") |
+| `title`            | string | Yes      | The title of the work item                                          |
+| `description`      | string | No       | The description of the work item                                    |
+| `assignedTo`       | string | No       | The email or name of the user to assign the work item to            |
+| `areaPath`         | string | No       | The area path for the work item                                     |
+| `iterationPath`    | string | No       | The iteration path for the work item                                |
+| `priority`         | number | No       | The priority of the work item                                       |
+| `additionalFields` | object | No       | Additional fields to set on the work item (key-value pairs)         |
+
+### Response
+
+Returns the newly created work item object:
+
+```json
+{
+  "id": 124,
+  "fields": {
+    "System.Title": "New Work Item",
+    "System.State": "New",
+    "System.Description": "Description of the new work item",
+    "System.AssignedTo": "user@example.com",
+    "System.AreaPath": "Project\\Team",
+    "System.IterationPath": "Project\\Sprint 1",
+    "Microsoft.VSTS.Common.Priority": 2
+  },
+  "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/124"
+}
+```
+
+### Error Handling
+
+- Returns validation error if required fields are missing
+- Returns `AzureDevOpsAuthenticationError` if authentication fails
+- Returns `AzureDevOpsResourceNotFoundError` if the project does not exist
+- Returns generic error messages for other failures
+
+### Example Usage
+
+```javascript
+const result = await callTool('create_work_item', {
+  projectId: 'my-project',
+  workItemType: 'User Story',
+  title: 'Implement login functionality',
+  description:
+    'Create a secure login system with email and password authentication',
+  assignedTo: 'developer@example.com',
+  priority: 1,
+  additionalFields: {
+    'Custom.Field': 'Custom Value',
+  },
+});
+```
+
+### Implementation Details
+
+The tool creates a JSON patch document to define the fields of the work item, then calls the Azure DevOps API to create the work item. Each field is added to the document with an 'add' operation, and the document is submitted to the API.
+
+## list_work_items
+
+Lists work items in a specified project.
+
+### Parameters
+
+| Parameter   | Type   | Required | Description                                           |
+| ----------- | ------ | -------- | ----------------------------------------------------- |
+| `projectId` | string | Yes      | The ID or name of the project to list work items from |
+| `teamId`    | string | No       | The ID of the team to list work items for             |
+| `queryId`   | string | No       | ID of a saved work item query                         |
+| `wiql`      | string | No       | Work Item Query Language (WIQL) query                 |
+| `top`       | number | No       | Maximum number of work items to return                |
+| `skip`      | number | No       | Number of work items to skip                          |
+
+### Response
+
+Returns an array of work item objects:
+
+```json
+[
+  {
+    "id": 123,
+    "fields": {
+      "System.Title": "Sample Work Item",
+      "System.State": "Active",
+      "System.AssignedTo": "user@example.com"
+    },
+    "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/123"
+  },
+  {
+    "id": 124,
+    "fields": {
+      "System.Title": "Another Work Item",
+      "System.State": "New",
+      "System.AssignedTo": "user2@example.com"
+    },
+    "url": "https://dev.azure.com/organization/project/_apis/wit/workItems/124"
+  }
+]
+```
+
+### 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
+const result = await callTool('list_work_items', {
+  projectId: 'my-project',
+  wiql: "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Task' ORDER BY [System.CreatedDate] DESC",
+  top: 10,
+});
+```

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@vm3jack/mcp-server-azure-devops",
+  "version": "1.0.0",
+  "description": "Azure DevOps reference server for the Model Context Protocol (MCP)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vm3jack/mcp-server-azure-devops"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-server-azure-devops": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "lint-staged": {
+    "*.ts": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "release-please": {
+    "release-type": "node",
+    "changelog-types": [
+      {
+        "type": "feat",
+        "section": "Features",
+        "hidden": false
+      },
+      {
+        "type": "fix",
+        "section": "Bug Fixes",
+        "hidden": false
+      },
+      {
+        "type": "chore",
+        "section": "Miscellaneous",
+        "hidden": false
+      },
+      {
+        "type": "docs",
+        "section": "Documentation",
+        "hidden": false
+      },
+      {
+        "type": "perf",
+        "section": "Performance Improvements",
+        "hidden": false
+      },
+      {
+        "type": "refactor",
+        "section": "Code Refactoring",
+        "hidden": false
+      }
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build && chmod +x dist/index.js",
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "start": "node dist/index.js",
+    "inspector": "npm run build && npx @modelcontextprotocol/inspector@0.9.0 node dist/index.js",
+    "test": "npm run test:unit && npm run test:int && npm run test:e2e",
+    "test:unit": "jest --config jest.unit.config.js",
+    "test:int": "jest --config jest.int.config.js",
+    "test:e2e": "jest --config jest.e2e.config.js",
+    "test:watch": "jest --watch",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "prepare": "husky install",
+    "commit": "cz"
+  },
+  "keywords": [
+    "azure-devops",
+    "mcp",
+    "ai",
+    "automation"
+  ],
+  "author": "vm3jack",
+  "license": "MIT",
+  "dependencies": {
+    "@azure/identity": "^4.8.0",
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "axios": "^1.8.3",
+    "azure-devops-node-api": "^13.0.0",
+    "diff": "^8.0.2",
+    "dotenv": "^16.3.1",
+    "jszip": "^3.10.1",
+    "minimatch": "^10.0.1",
+    "zod": "^3.24.2",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "@types/diff": "^7.0.2",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.27.0",
+    "@typescript-eslint/parser": "^8.27.0",
+    "commitizen": "^4.3.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^8.0.0",
+    "husky": "^8.0.3",
+    "jest": "^29.0.0",
+    "lint-staged": "^15.5.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.8.2"
+  }
+}