tnishanth94/ADO-MCP-Server

ADO MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to Azure DevOps (ADO) work items, enabling seamless integration between AI assistants and Azure DevOps services.

Features

• Work Item Management: Fetch, create, and update user stories, tasks, and test cases
• Test Case Support: Create and retrieve test cases with detailed test steps
• Task Creation: Create tasks linked to parent user stories
• Area Path Queries: Retrieve all work items under specific area paths
• Comprehensive Work Item Operations: Support for all major work item fields including priority, story points, acceptance criteria, and assignments

Tools Available

Work Item Operations

• getUserStory - Fetch a user story by ID with complete details
• createUserStory - Create new user stories with custom fields
• updateWorkItem - Update existing work items with new values
• getWorkItemsByAreaPath - Query work items by area path with optional type filtering

Task Management

• createTask - Create tasks linked to parent user stories with activity tracking

Test Case Management

• getTestCase - Retrieve test cases with detailed test steps
• createTestCase - Create test cases with structured test steps

Prerequisites

• Node.js (v14 or higher)
• Azure DevOps account with appropriate permissions
• Personal Access Token (PAT) for Azure DevOps

Installation

1. Clone the repository:

   git clone https://github.com/tnishanth94/ADO-MCP-Server.git
   cd ADO-MCP-Server
   

2. Install dependencies:

   npm install
   

3. Set up environment variables: Create a .env file in the root directory and configure the following variables:

   ADO_ORG=your-organization-name
   ADO_PROJECT=your-project-name
   ADO_PAT=your-personal-access-token
   GIT_USER_NAME=Your Name
   GIT_USER_EMAIL=your.email@example.com
   

Configuration

Azure DevOps Setup

1. Generate a Personal Access Token (PAT):

   • Go to Azure DevOps → User Settings → Personal Access Tokens
   • Create a new token with the following scopes:
     • Work Items (Read & Write)
     • Project and Team (Read)

2. Organization and Project Setup:

   • Identify your Azure DevOps organization name (from the URL: https://dev.azure.com/{org-name})
   • Identify your project name within the organization (from the URL: https://dev.azure.com/{org-name}/{project-name})

Environment Variables

Usage

Running the Server

node server.js

The server will start and listen for MCP protocol messages via stdio.

Integration with MCP Clients

This server is designed to work with MCP-compatible clients like Claude Desktop, Github Copilot, or custom applications that support the Model Context Protocol.

Example Client Configuration

For Github Copilot, add to your mcp.json: or create one inside your user profile inside Code (%APPDATA%\Code\User)

{
  "servers": {
    "ado-mcp-server": {
			"type": "stdio",
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "ADO_ORG": "your-org",
        "ADO_PROJECT": "your-project",
        "ADO_PAT": "your-pat"
      }
    }
  }
}

API Reference

getUserStory

Fetch a user story by ID with complete metadata.

Parameters:

• id (number): Work item ID

Returns: Formatted user story details including title, state, assignee, description, acceptance criteria, and more.

createUserStory

Create a new user story in Azure DevOps.

Required Parameters:

• title (string): Story title
• iterationPath (string): Sprint/iteration path
• parentId (number): Parent work item ID

Optional Parameters:

• description, areaPath, priority, storyPoints, acceptanceCriteria, assignedTo

createTask

Create a task linked to a parent user story.

Required Parameters:

• title (string): Task title
• parentId (number): Parent story ID

Optional Parameters:

• description, iterationPath, areaPath, priority, assignedTo, activity, estimatedHours, state

createTestCase

Create a test case with structured test steps.

Required Parameters:

• title (string): Test case title
• steps (array): Array of test steps with action and expectedResult

Optional Parameters:

• description, iterationPath, areaPath, parentId, priority, assignedTo

getWorkItemsByAreaPath

Query work items under a specific area path.

Required Parameters:

• areaPath (string): Area path to search under

Optional Parameters:

• workItemTypes (array): Filter by work item types (e.g., ['Feature', 'User Story', 'Bug'])

Error Handling

The server includes comprehensive error handling for:

• Azure DevOps API authentication errors
• Invalid work item IDs
• Missing required fields
• Network connectivity issues

All errors are returned with descriptive messages to help with troubleshooting.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check Azure DevOps API documentation for reference
• Verify your PAT permissions and organization/project settings

Changelog

v1.0.0

• Initial release with core work item operations
• Support for user stories, tasks, and test cases
• Area path querying functionality
• Comprehensive error handling and logging

Wiki Page Management

createOrUpdateWikiPage

Create or update a wiki page in Azure DevOps.

Parameters:

• wikiName (string): Name of the wiki
• path (string): Path of the page to create or update
• content (string): Content of the wiki page
• comment (string, optional): Comment for the update, defaults to "Updated via API"

Returns: Details of the created or updated wiki page, including ID, path, URL, and ETag.

Notes:

• The function first retrieves the wiki by name to get its ID.
• It then creates or updates the page using the proper version descriptor for the wiki's repository.