@vm3jack/mcp-server-azure-devops 1.0.0

package/docs/authentication.md

@@ -0,0 +1,267 @@
+# Authentication Guide for Azure DevOps MCP Server
+
+This guide provides detailed information about the authentication methods supported by the Azure DevOps MCP Server, including setup instructions, configuration examples, and troubleshooting tips.
+
+## Supported Authentication Methods
+
+The Azure DevOps MCP Server supports three authentication methods:
+
+1. **Personal Access Token (PAT)** - Simple token-based authentication
+2. **Azure Identity (DefaultAzureCredential)** - Flexible authentication using the Azure Identity SDK
+3. **Azure CLI** - Authentication using your Azure CLI login
+
+Azure DevOps Server (on-prem) supports PAT authentication only. Azure Identity and Azure CLI are supported for Azure DevOps Services.
+
+## Method 1: Personal Access Token (PAT) Authentication
+
+PAT authentication is the simplest method and works well for personal use or testing.
+
+### Setup Instructions
+
+1. **Generate a PAT in Azure DevOps**:
+
+   - Go to https://dev.azure.com/{your-organization}/_usersSettings/tokens
+   - Or click on your profile picture > Personal access tokens
+   - Select "+ New Token"
+   - Name your token (e.g., "MCP Server Access")
+   - Set an expiration date
+   - Select the following scopes:
+     - **Code**: Read & Write
+     - **Work Items**: Read & Write
+     - **Build**: Read & Execute
+     - **Project and Team**: Read
+     - **Graph**: Read
+     - **Release**: Read & Execute
+   - Click "Create" and copy the generated token
+
+2. **Configure your `.env` file**:
+   ```
+   AZURE_DEVOPS_AUTH_METHOD=pat
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_PAT=your-personal-access-token
+   AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+   ```
+
+### Security Considerations
+
+- PATs have an expiration date and will need to be renewed
+- Store your PAT securely and never commit it to source control
+- Consider using environment variables or a secrets manager in production
+- Scope your PAT to only the permissions needed for your use case
+
+## Method 2: Azure Identity Authentication (DefaultAzureCredential)
+
+Azure Identity authentication uses the `DefaultAzureCredential` class from the `@azure/identity` package, which provides a simplified authentication experience by trying multiple credential types in sequence.
+
+> Note: Azure Identity authentication is supported for Azure DevOps Services only.
+
+### How DefaultAzureCredential Works
+
+`DefaultAzureCredential` tries the following credential types in order:
+
+1. Environment variables (EnvironmentCredential)
+2. Managed Identity (ManagedIdentityCredential)
+3. Azure CLI (AzureCliCredential)
+4. Visual Studio Code (VisualStudioCodeCredential)
+5. Azure PowerShell (AzurePowerShellCredential)
+6. Interactive Browser (InteractiveBrowserCredential) - optional, disabled by default
+
+This makes it ideal for applications that need to work in different environments (local development, Azure-hosted) without code changes.
+
+### Setup Instructions
+
+1. **Install the Azure Identity SDK**:
+   The SDK is already included as a dependency in the Azure DevOps MCP Server.
+
+2. **Configure your `.env` file**:
+
+   ```
+   AZURE_DEVOPS_AUTH_METHOD=azure-identity
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+   ```
+
+3. **Set up credentials based on your environment**:
+
+   a. **For service principals (client credentials)**:
+
+   ```
+   AZURE_TENANT_ID=your-tenant-id
+   AZURE_CLIENT_ID=your-client-id
+   AZURE_CLIENT_SECRET=your-client-secret
+   ```
+
+   b. **For managed identities in Azure**:
+   No additional configuration needed if running in Azure with a managed identity.
+
+   c. **For local development**:
+
+   - Log in with Azure CLI: `az login`
+   - Or use Visual Studio Code Azure Account extension
+
+### Security Considerations
+
+- Use managed identities in Azure for improved security
+- For service principals, rotate client secrets regularly
+- Store credentials securely using Azure Key Vault or environment variables
+- Apply the principle of least privilege when assigning roles
+
+## Method 3: Azure CLI Authentication
+
+Azure CLI authentication uses the `AzureCliCredential` class from the `@azure/identity` package, which authenticates using the Azure CLI's logged-in account.
+
+> Note: Azure CLI authentication is supported for Azure DevOps Services only.
+
+### Setup Instructions
+
+1. **Install the Azure CLI**:
+
+   - Follow the instructions at https://docs.microsoft.com/cli/azure/install-azure-cli
+
+2. **Log in to Azure**:
+
+   ```bash
+   az login
+   ```
+
+3. **Configure your `.env` file**:
+   ```
+   AZURE_DEVOPS_AUTH_METHOD=azure-cli
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+   ```
+
+### Security Considerations
+
+- Azure CLI authentication is best for local development
+- Ensure your Azure CLI session is kept secure
+- Log out when not in use: `az logout`
+
+## Configuration Reference
+
+| Variable                       | Description                                                                        | Required                     | Default          |
+| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------- | ---------------- |
+| `AZURE_DEVOPS_AUTH_METHOD`     | Authentication method (`pat`, `azure-identity`, or `azure-cli`) - case-insensitive | No                           | `azure-identity` |
+| `AZURE_DEVOPS_ORG_URL`         | Full URL to your Azure DevOps organization                                         | Yes                          | -                |
+| `AZURE_DEVOPS_PAT`             | Personal Access Token (for PAT auth)                                               | Only with PAT auth           | -                |
+| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified                                                  | No                           | -                |
+| `AZURE_DEVOPS_API_VERSION`     | API version to use                                                                 | No                           | Latest           |
+| `AZURE_TENANT_ID`              | Azure AD tenant ID (for service principals)                                        | Only with service principals | -                |
+| `AZURE_CLIENT_ID`              | Azure AD application ID (for service principals)                                   | Only with service principals | -                |
+| `AZURE_CLIENT_SECRET`          | Azure AD client secret (for service principals)                                    | Only with service principals | -                |
+| `LOG_LEVEL`                    | Logging level (debug, info, warn, error)                                           | No                           | info             |
+
+## Troubleshooting Authentication Issues
+
+### PAT Authentication Issues
+
+1. **Invalid PAT**: Ensure your PAT hasn't expired and has the required scopes
+
+   - Error: `TF400813: The user 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' is not authorized to access this resource.`
+   - Solution: Generate a new PAT with the correct scopes
+
+2. **Scope issues**: If receiving 403 errors, check if your PAT has the necessary permissions
+
+   - Error: `TF401027: You need the Git 'Read' permission to perform this action.`
+   - Solution: Update your PAT with the required scopes
+
+3. **Organization access**: Verify your PAT has access to the organization specified in the URL
+   - Error: `TF400813: Resource not found for anonymous request.`
+   - Solution: Ensure your PAT has access to the specified organization
+
+### Azure Identity Authentication Issues
+
+1. **Missing credentials**: Ensure you have the necessary credentials configured
+
+   - Error: `CredentialUnavailableError: DefaultAzureCredential failed to retrieve a token`
+   - Solution: Check that you're logged in with Azure CLI or have environment variables set
+
+2. **Permission issues**: Verify your identity has the necessary permissions
+
+   - Error: `AuthorizationFailed: The client does not have authorization to perform action`
+   - Solution: Assign the appropriate roles to your identity
+
+3. **Token acquisition errors**: Check network connectivity and Azure AD endpoint availability
+   - Error: `ClientAuthError: Interaction required`
+   - Solution: Check network connectivity or use a different credential type
+
+### Azure CLI Authentication Issues
+
+1. **CLI not installed**: Ensure Azure CLI is installed and in your PATH
+
+   - Error: `AzureCliCredential authentication failed: Azure CLI not found`
+   - Solution: Install Azure CLI
+
+2. **Not logged in**: Verify you're logged in to Azure CLI
+
+   - Error: `AzureCliCredential authentication failed: Please run 'az login'`
+   - Solution: Run `az login`
+
+3. **Permission issues**: Check if your Azure CLI account has access to Azure DevOps
+   - Error: `TF400813: The user is not authorized to access this resource`
+   - Solution: Log in with an account that has access to Azure DevOps
+
+## Best Practices
+
+1. **Choose the right authentication method for your environment**:
+
+   - For local development: Azure CLI or PAT
+   - For CI/CD pipelines: PAT or service principal
+   - For Azure-hosted applications: Managed Identity
+
+2. **Follow the principle of least privilege**:
+
+   - Only grant the permissions needed for your use case
+   - Regularly review and rotate credentials
+
+3. **Secure your credentials**:
+
+   - Use environment variables or a secrets manager
+   - Never commit credentials to source control
+   - Set appropriate expiration dates for PATs
+
+4. **Monitor and audit authentication**:
+   - Review Azure DevOps access logs
+   - Set up alerts for suspicious activity
+
+## Examples
+
+### Example 1: Local Development with PAT
+
+```bash
+# .env file
+AZURE_DEVOPS_AUTH_METHOD=pat
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
+AZURE_DEVOPS_PAT=abcdefghijklmnopqrstuvwxyz0123456789
+AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
+```
+
+### Example 2: Azure-hosted Application with Managed Identity
+
+```bash
+# .env file
+AZURE_DEVOPS_AUTH_METHOD=azure-identity
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
+AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
+```
+
+### Example 3: CI/CD Pipeline with Service Principal
+
+```bash
+# .env file
+AZURE_DEVOPS_AUTH_METHOD=azure-identity
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
+AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
+AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
+AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111
+AZURE_CLIENT_SECRET=your-client-secret
+```
+
+### Example 4: Local Development with Azure CLI
+
+```bash
+# .env file
+AZURE_DEVOPS_AUTH_METHOD=azure-cli
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
+AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
+```

package/docs/azure-identity-authentication.md

@@ -0,0 +1,187 @@
+# Azure Identity Authentication for Azure DevOps MCP Server
+
+This guide explains how to use Azure Identity authentication with the Azure DevOps MCP Server.
+
+## Overview
+
+Azure Identity authentication lets you use your existing Azure credentials to authenticate with Azure DevOps, instead of creating and managing Personal Access Tokens (PATs). This approach offers several benefits:
+
+- **Unified authentication**: Use the same credentials for Azure and Azure DevOps
+- **Enhanced security**: Support for managed identities and client certificates
+- **Flexible credential types**: Multiple options for different environments
+- **Automatic token management**: Handles token acquisition and renewal
+
+## Credential Types
+
+The Azure DevOps MCP Server supports multiple credential types through the Azure Identity SDK:
+
+### DefaultAzureCredential
+
+This credential type attempts multiple authentication methods in sequence until one succeeds:
+
+1. Environment variables (EnvironmentCredential)
+2. Managed Identity (ManagedIdentityCredential)
+3. Azure CLI (AzureCliCredential)
+4. Visual Studio Code (VisualStudioCodeCredential)
+5. Azure PowerShell (AzurePowerShellCredential)
+
+It's a great option for applications that need to work across different environments without code changes.
+
+### AzureCliCredential
+
+This credential type uses your Azure CLI login. It's perfect for local development when you're already using the Azure CLI.
+
+## Configuration
+
+### Environment Variables
+
+To use Azure Identity authentication, set the following environment variables:
+
+```bash
+# Required
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+AZURE_DEVOPS_AUTH_METHOD=azure-identity
+
+# Optional
+AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
+```
+
+For service principal authentication, add these environment variables:
+
+```bash
+AZURE_TENANT_ID=your-tenant-id
+AZURE_CLIENT_ID=your-client-id
+AZURE_CLIENT_SECRET=your-client-secret
+```
+
+### Use with Claude Desktop/Cursor AI
+
+Add the following to your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "azureDevOps": {
+      "command": "npx",
+      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
+      "env": {
+        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
+        "AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
+        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
+      }
+    }
+  }
+}
+```
+
+## Authentication Methods
+
+### Method 1: Using Azure CLI
+
+1. Install the Azure CLI from [here](https://docs.microsoft.com/cli/azure/install-azure-cli)
+2. Log in to Azure:
+   ```bash
+   az login
+   ```
+3. Set up your environment variables:
+   ```bash
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_AUTH_METHOD=azure-identity
+   ```
+
+### Method 2: Using Service Principal
+
+1. Create a service principal in Azure AD:
+   ```bash
+   az ad sp create-for-rbac --name "MyAzureDevOpsApp"
+   ```
+2. Grant the service principal access to your Azure DevOps organization
+3. Set up your environment variables:
+   ```bash
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_AUTH_METHOD=azure-identity
+   AZURE_TENANT_ID=your-tenant-id
+   AZURE_CLIENT_ID=your-client-id
+   AZURE_CLIENT_SECRET=your-client-secret
+   ```
+
+### Method 3: Using Managed Identity (for Azure-hosted applications)
+
+1. Enable managed identity for your Azure resource (VM, App Service, etc.)
+2. Grant the managed identity access to your Azure DevOps organization
+3. Set up your environment variables:
+   ```bash
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_AUTH_METHOD=azure-identity
+   ```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Failed to acquire token
+
+```
+Error: Failed to authenticate with Azure Identity: CredentialUnavailableError: DefaultAzureCredential failed to retrieve a token
+```
+
+**Possible solutions:**
+- Ensure you're logged in with `az login`
+- Check if your managed identity is correctly configured
+- Verify that service principal credentials are correct
+
+#### Permission issues
+
+```
+Error: Failed to authenticate with Azure Identity: AuthorizationFailed: The client does not have authorization to perform action
+```
+
+**Possible solutions:**
+- Ensure your identity has the necessary permissions in Azure DevOps
+- Check if you need to add your identity to specific Azure DevOps project(s)
+
+#### Network issues
+
+```
+Error: Failed to authenticate with Azure Identity: ClientAuthError: Interaction required
+```
+
+**Possible solutions:**
+- Check your network connectivity
+- Verify that your firewall allows connections to Azure services
+
+## Best Practices
+
+1. **Choose the right credential type for your environment**:
+   - For local development: Azure CLI credential
+   - For CI/CD pipelines: Service principal
+   - For Azure-hosted applications: Managed identity
+
+2. **Follow the principle of least privilege**:
+   - Only grant the permissions needed for your use case
+   - Regularly audit and review permissions
+
+3. **Rotate credentials regularly**:
+   - For service principals, rotate client secrets periodically
+   - Use certificate-based authentication when possible for enhanced security
+
+## Examples
+
+### Basic configuration with Azure CLI
+
+```bash
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
+AZURE_DEVOPS_AUTH_METHOD=azure-identity
+AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
+```
+
+### Service principal authentication
+
+```bash
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
+AZURE_DEVOPS_AUTH_METHOD=azure-identity
+AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
+AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
+AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111
+AZURE_CLIENT_SECRET=your-client-secret
+```

package/docs/ci-setup.md

@@ -0,0 +1,61 @@
+# CI Environment Setup for Integration Tests
+
+This document explains how to set up the CI environment to run integration tests with Azure DevOps.
+
+## GitHub Secrets Configuration
+
+To run integration tests in the CI environment, you need to configure the following GitHub Secrets:
+
+1. **AZURE_DEVOPS_ORG_URL**: The URL of your Azure DevOps organization (e.g., `https://dev.azure.com/your-organization`)
+2. **AZURE_DEVOPS_PAT**: A Personal Access Token with appropriate permissions
+3. **AZURE_DEVOPS_DEFAULT_PROJECT** (optional): The default project to use for tests
+
+### Setting up GitHub Secrets
+
+1. Go to your GitHub repository
+2. Click on "Settings" > "Secrets and variables" > "Actions"
+3. Click on "New repository secret"
+4. Add each of the required secrets:
+
+#### AZURE_DEVOPS_ORG_URL
+
+- Name: `AZURE_DEVOPS_ORG_URL`
+- Value: `https://dev.azure.com/your-organization`
+
+#### AZURE_DEVOPS_PAT
+
+- Name: `AZURE_DEVOPS_PAT`
+- Value: Your Personal Access Token
+
+#### AZURE_DEVOPS_DEFAULT_PROJECT (optional)
+
+- Name: `AZURE_DEVOPS_DEFAULT_PROJECT`
+- Value: Your project name
+
+## Personal Access Token (PAT) Requirements
+
+The PAT used for integration tests should have the following permissions:
+
+- **Code**: Read & Write
+- **Work Items**: Read & Write
+- **Build**: Read & Execute
+- **Project and Team**: Read
+- **Graph**: Read
+- **Release**: Read & Execute
+
+## Security Considerations
+
+- Use a dedicated Azure DevOps organization or project for testing
+- Create a PAT with the minimum required permissions
+- Consider setting an expiration date for the PAT
+- Regularly rotate the PAT used in GitHub Secrets
+
+## Troubleshooting
+
+If integration tests fail in CI:
+
+1. Check the GitHub Actions logs for detailed error messages
+2. Verify that the PAT has not expired
+3. Ensure the PAT has the required permissions
+4. Confirm that the organization URL is correct
+5. Check if the default project exists and is accessible with the provided PAT

package/docs/examples/README.md

@@ -0,0 +1,33 @@
+# Authentication Examples
+
+This directory contains example `.env` files for different authentication methods supported by the Azure DevOps MCP Server.
+
+## Available Examples
+
+1. **[pat-authentication.env](./pat-authentication.env)** - Example configuration for Personal Access Token (PAT) authentication
+2. **[azure-identity-authentication.env](./azure-identity-authentication.env)** - Example configuration for Azure Identity (DefaultAzureCredential) authentication
+3. **[azure-cli-authentication.env](./azure-cli-authentication.env)** - Example configuration for Azure CLI authentication
+
+## How to Use These Examples
+
+1. Choose the authentication method that best suits your needs
+2. Copy the corresponding example file to the root of your project as `.env`
+3. Replace the placeholder values with your actual values
+4. Start the Azure DevOps MCP Server
+
+For example:
+
+```bash
+# Copy the PAT authentication example
+cp docs/examples/pat-authentication.env .env
+
+# Edit the .env file with your values
+nano .env
+
+# Start the server
+npm start
+```
+
+## Additional Resources
+
+For more detailed information about authentication methods, setup instructions, and troubleshooting, refer to the [Authentication Guide](../authentication.md).

package/docs/examples/azure-cli-authentication.env

@@ -0,0 +1,25 @@
+# Example .env file for Azure CLI authentication
+# Replace the values with your own
+
+# Authentication method (required)
+AZURE_DEVOPS_AUTH_METHOD=azure-cli
+
+# Azure DevOps organization URL (required)
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+
+# Default project to use when not specified (optional)
+AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+
+# API Version to use (optional, defaults to latest)
+# AZURE_DEVOPS_API_VERSION=6.0
+
+# Logging Level (optional)
+LOG_LEVEL=info
+
+# Note: This server uses stdio for communication with the MCP client,
+# not HTTP. It does not listen on a network port.
+
+# Note: Before using Azure CLI authentication, make sure you have:
+# 1. Installed the Azure CLI (https://docs.microsoft.com/cli/azure/install-azure-cli)
+# 2. Logged in with 'az login'
+# 3. Verified your account has access to the Azure DevOps organization 

package/docs/examples/azure-identity-authentication.env

@@ -0,0 +1,33 @@
+# Example .env file for Azure Identity (DefaultAzureCredential) authentication
+# Replace the values with your own
+
+# Authentication method (required)
+AZURE_DEVOPS_AUTH_METHOD=azure-identity
+
+# Azure DevOps organization URL (required)
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+
+# Default project to use when not specified (optional)
+AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+
+# API Version to use (optional, defaults to latest)
+# AZURE_DEVOPS_API_VERSION=6.0
+
+# Azure AD tenant ID (required for service principal authentication)
+# AZURE_TENANT_ID=your-tenant-id
+
+# Azure AD client ID (required for service principal authentication)
+# AZURE_CLIENT_ID=your-client-id
+
+# Azure AD client secret (required for service principal authentication)
+# AZURE_CLIENT_SECRET=your-client-secret
+
+# Logging Level (optional)
+LOG_LEVEL=info
+
+# Note: This server uses stdio for communication with the MCP client,
+# not HTTP. It does not listen on a network port.
+
+# Note: When using DefaultAzureCredential, you don't need to set AZURE_TENANT_ID, 
+# AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET if you're using other credential types
+# like Managed Identity or Azure CLI. 

package/docs/examples/pat-authentication.env

@@ -0,0 +1,24 @@
+# Example .env file for Personal Access Token (PAT) authentication
+# Replace the values with your own
+
+# Authentication method (required)
+AZURE_DEVOPS_AUTH_METHOD=pat
+
+# Azure DevOps organization URL (required)
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+
+# Personal Access Token (required for PAT authentication)
+# Create one at: https://dev.azure.com/your-organization/_usersSettings/tokens
+AZURE_DEVOPS_PAT=your-personal-access-token
+
+# Default project to use when not specified (optional)
+AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+
+# API Version to use (optional, defaults to latest)
+# AZURE_DEVOPS_API_VERSION=6.0
+
+# Logging Level (optional)
+LOG_LEVEL=info
+
+# Note: This server uses stdio for communication with the MCP client,
+# not HTTP. It does not listen on a network port.