Reorganize file structure and tests to reduce context issues for AI (#20)

* Update configuration files and enhance documentation

- Added missing newlines at the end of several configuration files (.eslintrc.json, .prettierrc, tsconfig.json, jest.config.js, jest.integration.config.js).
- Updated README.md to include additional environment variable setup instructions for Azure DevOps.
- Improved documentation across various files, ensuring clarity and completeness, particularly in authentication and project setup sections.
- Removed deprecated files and tests to streamline the codebase and improve maintainability.

* Refactor test structure and enhance error handling

- Updated test files to follow colocation patterns, improving organization and maintainability.
- Added tasks to fix specific test files by co-locating or moving individual tests to appropriate files.
- Enhanced error handling in authentication tests to provide clearer error messages for token acquisition failures.
- Updated mock implementations in tests to ensure accurate behavior and error handling for Azure DevOps API interactions.

* Enhance error handling in authentication and repository listing tests

- Added tests to handle non-Error objects in catch blocks for both listRepositories and listWorkItems functions, ensuring proper error messages are thrown.
- Updated existing tests to convert generic error messages into specific Azure DevOps error types, improving clarity and robustness in error handling.
- Refactored mock implementations in authentication tests to simulate various error scenarios, enhancing test coverage and reliability.

* Remove obsolete test files and refactor existing tests for improved organization

- Deleted outdated test files including server-coverage.test.ts, server-client.test.ts, auth.test.ts, and server-auth.test.ts to streamline the codebase.
- Refactored existing tests to enhance clarity and maintainability, ensuring they follow updated patterns and practices.
- Improved error handling in authentication tests, ensuring comprehensive coverage for various authentication scenarios.
- Updated mock implementations to accurately simulate Azure DevOps API interactions, enhancing test reliability.

* Reorganize test structure to follow co-location pattern

This PR completes the test reorganization task by moving tests to follow the co-location pattern, ensuring proper organization and maintainability of the codebase.

* Complete task to reorganize repository structure around "Screaming Architecture" and "Vertical Slices"

This commit finalizes the restructuring of the codebase to emphasize business domains over technical layers, implementing a feature-based module organization. All tasks related to the refactor have been completed, including the migration of tests to co-locate with their respective implementations, enhancing clarity and maintainability. The old layer-based directories have been removed, and the new structure has been validated with passing tests across all features.

* Refactor setup_env.sh to remove PAT creation logic and update authentication method

This commit simplifies the setup_env.sh script by removing the Personal Access Token (PAT) creation process, which included both automated and manual methods. The script now defaults to using Azure Identity for authentication, streamlining the setup process. Additionally, the .env file has been updated to reflect the new authentication method, enhancing clarity and maintainability.

---------

Co-authored-by: Micah Rairdon <[email protected]>

Author: Tiberriver256

.eslintrc.json

@@ -15,10 +15,13 @@
     "prettier/prettier": "error",
     "@typescript-eslint/explicit-function-return-type": "off",
     "@typescript-eslint/no-explicit-any": "warn",
-    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "^_" }
+    ]
   },
   "parserOptions": {
     "ecmaVersion": 2020,
     "sourceType": "module"
   }
-} 
+}

.github/workflows/main.yml

@@ -2,9 +2,9 @@ name: CI/CD
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   build:
@@ -28,4 +28,4 @@ jobs:
           CI: 'true'
           AZURE_DEVOPS_ORG_URL: ${{ secrets.AZURE_DEVOPS_ORG_URL }}
           AZURE_DEVOPS_PAT: ${{ secrets.AZURE_DEVOPS_PAT }}
-          AZURE_DEVOPS_DEFAULT_PROJECT: ${{ secrets.AZURE_DEVOPS_DEFAULT_PROJECT }}
+          AZURE_DEVOPS_DEFAULT_PROJECT: ${{ secrets.AZURE_DEVOPS_DEFAULT_PROJECT }}

.prettierrc

@@ -6,4 +6,4 @@
   "tabWidth": 2,
   "useTabs": false,
   "endOfLine": "lf"
-} 
+}

README.md

@@ -43,49 +43,59 @@ The server is structured around the Model Context Protocol (MCP) for communicati
 ### Installation
 
 1. Clone the repository:
+
    ```
    git clone https://github.com/your-username/azure-devops-mcp.git
    cd azure-devops-mcp
    ```
 
 2. Install dependencies:
+
    ```
    npm install
    ```
 
 3. Set up your environment:
 
    Option A: Using the automated setup script (recommended):
+
    ```
    chmod +x setup_env.sh
    ./setup_env.sh
    ```
+
    This script will:
+
    - Check for and install the Azure CLI DevOps extension if needed
    - Let you select from your available Azure DevOps organizations
    - Optionally set a default project
    - Create a Personal Access Token with the required permissions
    - Generate your `.env` file with the correct settings
 
    Option B: Manual setup:
+
    ```
    cp .env.example .env
    ```
+
    Then edit the `.env` file with your Azure DevOps credentials (see Authentication section below).
 
 ### Running the Server
 
 Build the TypeScript files:
+
 ```
 npm run build
 ```
 
 Start the server:
+
 ```
 npm start
 ```
 
 For development with hot reloading:
+
 ```
 npm run dev
 ```
@@ -108,26 +118,27 @@ For a complete list of environment variables and their descriptions, see the [Au
 
 Key environment variables include:
 
-| Variable | Description | Required | Default |
-|----------|-------------|----------|---------|
-| `AZURE_DEVOPS_AUTH_METHOD` | Authentication method (`pat`, `azure-identity`, or `azure-cli`) | No | `azure-identity` |
-| `AZURE_DEVOPS_ORG` | Azure DevOps organization name | No | Extracted from URL |
-| `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_AD_TENANT_ID` | Azure AD tenant ID (for AAD auth) | Only with AAD auth | - |
-| `AZURE_AD_CLIENT_ID` | Azure AD application ID (for AAD auth) | Only with AAD auth | - |
-| `AZURE_AD_CLIENT_SECRET` | Azure AD client secret (for AAD auth) | Only with AAD auth | - |
-| `PORT` | Server port | No | 3000 |
-| `HOST` | Server host | No | localhost |
-| `LOG_LEVEL` | Logging level (debug, info, warn, error) | No | info |
+| Variable                       | Description                                                     | Required           | Default            |
+| ------------------------------ | --------------------------------------------------------------- | ------------------ | ------------------ |
+| `AZURE_DEVOPS_AUTH_METHOD`     | Authentication method (`pat`, `azure-identity`, or `azure-cli`) | No                 | `azure-identity`   |
+| `AZURE_DEVOPS_ORG`             | Azure DevOps organization name                                  | No                 | Extracted from URL |
+| `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_AD_TENANT_ID`           | Azure AD tenant ID (for AAD auth)                               | Only with AAD auth | -                  |
+| `AZURE_AD_CLIENT_ID`           | Azure AD application ID (for AAD auth)                          | Only with AAD auth | -                  |
+| `AZURE_AD_CLIENT_SECRET`       | Azure AD client secret (for AAD auth)                           | Only with AAD auth | -                  |
+| `PORT`                         | Server port                                                     | No                 | 3000               |
+| `HOST`                         | Server host                                                     | No                 | localhost          |
+| `LOG_LEVEL`                    | Logging level (debug, info, warn, error)                        | No                 | info               |
 
 ## Troubleshooting Authentication
 
 For detailed troubleshooting information for each authentication method, see the [Authentication Guide](docs/authentication.md#troubleshooting-authentication-issues).
 
 Common issues include:
+
 - Invalid or expired credentials
 - Insufficient permissions
 - Network connectivity problems
@@ -142,23 +153,27 @@ For technical details about how authentication is implemented in the Azure DevOp
 The Azure DevOps MCP server provides a variety of tools for interacting with Azure DevOps resources. For detailed documentation on each tool, please refer to the corresponding documentation.
 
 ### Core Navigation Tools
+
 - `list_organizations`: List all accessible organizations
 - `list_projects`: List all accessible projects
 - `list_repositories`: List all repositories in a project
 
 For comprehensive documentation on all core navigation tools, see the [Core Navigation Tools Guide](docs/tools/core-navigation.md).
 
 ### Project Tools
+
 - `get_project`: Get details of a specific project
 
 For project-specific tool documentation, see the [Projects Tools Guide](docs/tools/projects.md).
 
 ### Repository Tools
+
 - `get_repository`: Get repository details
 
 For repository-specific tool documentation, see the [Repositories Tools Guide](docs/tools/repositories.md).
 
 ### Work Item Tools
+
 - `get_work_item`: Retrieve a work item by ID
 - `create_work_item`: Create a new work item
 
@@ -177,6 +192,7 @@ npm run test:unit
 Integration tests require a connection to a real Azure DevOps instance. To run them:
 
 1. Ensure your `.env` file is configured with valid Azure DevOps credentials:
+
    ```
    AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
    AZURE_DEVOPS_PAT=your-personal-access-token

docs/authentication.md

@@ -17,6 +17,7 @@ PAT authentication is the simplest method and works well for personal use or tes
 ### 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"
@@ -69,6 +70,7 @@ This makes it ideal for applications that need to work in different environments
    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
@@ -78,18 +80,20 @@ This makes it ideal for applications that need to work in different environments
 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
-      ```
+
+   ```
+   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.
+   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
+
+   - Log in with Azure CLI: `az login`
+   - Or use Visual Studio Code Azure Account extension
 
 ### Security Considerations
 
@@ -105,9 +109,11 @@ Azure CLI authentication uses the `AzureCliCredential` class from the `@azure/id
 ### 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
    ```
@@ -127,26 +133,28 @@ Azure CLI authentication uses the `AzureCliCredential` class from the `@azure/id
 
 ## Configuration Reference
 
-| Environment Variable | Description | Required | Default |
-|----------|-------------|----------|---------|
-| `AZURE_DEVOPS_AUTH_METHOD` | Authentication method (`pat`, `azure-identity`, or `azure-cli`) | 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 | - |
+| Environment Variable           | Description                                                     | Required                     | Default          |
+| ------------------------------ | --------------------------------------------------------------- | ---------------------------- | ---------------- |
+| `AZURE_DEVOPS_AUTH_METHOD`     | Authentication method (`pat`, `azure-identity`, or `azure-cli`) | 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 | -                |
 
 ## 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
 
@@ -157,10 +165,12 @@ Azure CLI authentication uses the `AzureCliCredential` class from the `@azure/id
 ### 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
 
@@ -171,10 +181,12 @@ Azure CLI authentication uses the `AzureCliCredential` class from the `@azure/id
 ### 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`
 
@@ -185,15 +197,18 @@ Azure CLI authentication uses the `AzureCliCredential` class from the `@azure/id
 ## 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
@@ -242,4 +257,4 @@ AZURE_CLIENT_SECRET=your-client-secret
 AZURE_DEVOPS_AUTH_METHOD=azure-cli
 AZURE_DEVOPS_ORG_URL=https://dev.azure.com/mycompany
 AZURE_DEVOPS_DEFAULT_PROJECT=MyProject
-``` 
+```