Tiberriver256 · Tiberriver256 · Feb 28, 2025 · Feb 28, 2025 · Feb 28, 2025 · Feb 28, 2025
diff --git a/.env.example b/.env.example
@@ -5,21 +5,27 @@
 # Example: mycompany
 AZURE_DEVOPS_ORG=your-organization-name
 
-# Azure DevOps Personal Access Token (PAT)
-# Create a PAT with the following scopes:
-# - Code (Read & Write)
-# - Work Items (Read & Write)
-# - Build (Read & Execute)
-# - Project and Team (Read)
-# - Graph (Read)
-# - Release (Read & Execute)
+# Azure DevOps Organization URL (required)
+# e.g., https://dev.azure.com/your-organization
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+
+# Azure DevOps Personal Access Token (required)
+# Create one at: https://dev.azure.com/your-organization/_usersSettings/tokens
+# Required scopes: Code (Read & Write), Work Items (Read & Write), Build (Read & Execute),
+# Project and Team (Read), Graph (Read), Release (Read & Execute)
 AZURE_DEVOPS_PAT=your-personal-access-token
 
 # Azure DevOps Project Name (Optional)
 # If specified, this project will be used as the default for operations
 # Example: MyProject
 AZURE_DEVOPS_PROJECT=your-project-name
 
+# 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
+
 # Server Configuration
 PORT=3000
 HOST=localhost

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -21,4 +21,4 @@ jobs:
       - name: Build
         run: npm run build
       - name: Test
-        run: npm run test
+        run: npm run test:unit
diff --git a/README.md b/README.md
@@ -1,127 +1,125 @@
 # Azure DevOps MCP Server
 
-A reference server implementation for the Model Context Protocol (MCP) that integrates with Azure DevOps. This server enables AI-driven workflows from user story creation to pull request management.
-
-## Features
-
-- Core Azure DevOps navigation (organizations, projects, repositories)
-- Work item management (create/update user stories, tasks, bugs)
-- Repository operations (file creation/updates, pushing changes)
-- Branch and pull request management
-- Pipeline interactions
-- Search capabilities across Azure DevOps entities
-
-## Prerequisites
-
-- Node.js (v18 or higher)
-- TypeScript
-- Azure DevOps account with appropriate permissions
-- Personal Access Token (PAT) or Azure Active Directory (AAD) credentials
-
-## Installation
-
-```bash
-# Clone the repository
-git clone [repository-url]
-cd azure-devops-mcp
-
-# Install dependencies
-npm install
+A Model Context Protocol (MCP) server implementation for Azure DevOps, allowing AI assistants to interact with Azure DevOps APIs through a standardized protocol.
+
+## Server Structure
+
+The server is structured around the Model Context Protocol (MCP) for communicating with AI assistants. It provides tools for interacting with Azure DevOps resources including:
+
+- Projects
+- Work Items
+- Repositories
+- Pull Requests
+- Branches
+- Pipelines
+
+### Core Components
+
+- **AzureDevOpsServer**: Main server class that initializes the MCP server and registers tools
+- **Tool Handlers**: Modular functions for each Azure DevOps operation
+- **Configuration**: Environment-based configuration for organization URL, PAT, etc.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (v16+)
+- npm or yarn
+- Azure DevOps account with a Personal Access Token
+
+### 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:
+   ```
+   AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+   AZURE_DEVOPS_PAT=your-personal-access-token
+   AZURE_DEVOPS_DEFAULT_PROJECT=your-default-project
+   ```
+
+### Running the Server
+
+Build the TypeScript files:
 ```
-
-## Dependencies
-
-This project relies on the following key dependencies:
-
-- **@modelcontextprotocol/sdk**: The official MCP SDK for TypeScript, providing the core functionality for creating MCP servers with tools, resources, and prompts.
-- **azure-devops-node-api**: The official Node.js client for Azure DevOps REST APIs, simplifying interactions with Azure DevOps services.
-- **zod**: A TypeScript-first schema validation library used for defining tool parameter schemas.
-- **dotenv**: For loading environment variables from a .env file.
-- **@azure/identity**: Facilitates Azure Active Directory (AAD) authentication.
-- **axios**: A promise-based HTTP client for making API requests not covered by the Azure DevOps Node API.
-
-Development dependencies include TypeScript, Jest for testing, ESLint and Prettier for code quality, and other tools to enhance the development experience.
-
-## Configuration
-
-1. Copy the `.env.example` file to `.env` and update with your Azure DevOps credentials:
-```bash
-cp .env.example .env
+npm run build
 ```
 
-2. Edit the `.env` file with your specific values:
-```env
-AZURE_DEVOPS_PAT=your_pat_here
-AZURE_DEVOPS_ORG=your_organization
-AZURE_DEVOPS_PROJECT=your_project
+Start the server:
+```
+npm start
 ```
 
-2. Configure authentication method in your MCP client:
-```json
-{
-  "mcpServers": {
-    "azuredevops": {
-      "command": "npx",
-      "args": ["-y", "@your-org/server-azuredevops"],
-      "env": {
-        "AUTH_METHOD": "PAT",
-        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
-        "AZURE_DEVOPS_ORG": "your-org",
-        "AZURE_DEVOPS_PROJECT": "your-project"
-      }
-    }
-  }
-}
+For development with hot reloading:
+```
+npm run dev
 ```
 
-## Development
+## Available Tools
 
-```bash
-# Build the project
-npm run build
+### Project Tools
+- `list_projects`: List all accessible projects
+- `get_project`: Get details of a specific project
 
-# Run tests
-npm test
+### Work Item Tools
+- `get_work_item`: Retrieve a work item by ID
+- `create_work_item`: Create a new work item
 
-# Run in development mode
-npm run dev
-```
+### Repository Tools
+- `list_repositories`: List all repositories in a project
+- `get_repository`: Get repository details
 
 ## Testing
 
-The project includes:
-- Unit tests for individual tools
-- Integration tests for end-to-end workflows
-- Security tests for authentication and permissions
-
-Run tests with:
-```bash
+Run the unit tests:
+```
 npm test
-npm run test:integration
-npm run test:security
 ```
 
-## Contributing
+Run integration tests (requires valid Azure DevOps credentials):
+```
+npm run test:integration
+```
 
-1. Fork the repository
-2. Create your 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
+## Development
 
-## License
+This project follows Test-Driven Development practices. Each new feature should:
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+1. Begin with a failing test
+2. Implement the minimal code to make the test pass
+3. Refactor while keeping tests green
 
-## Security
+## License
 
-- Use environment variables for sensitive data
-- Scope permissions appropriately in Azure DevOps
-- Follow security best practices when handling credentials
+MIT
 
-## Support
+## Contributing
 
-For support, please:
-1. Check the documentation in the `docs/` directory
-2. Search existing issues
-3. Open a new issue if needed
+Contributions are welcome! Please feel free to submit a Pull Request.
diff --git a/jest.config.js b/jest.config.js
@@ -0,0 +1,15 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+  collectCoverage: true,
+  collectCoverageFrom: ['src/**/*.ts'],
+  coverageDirectory: 'coverage',
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: 'tsconfig.json',
+    }]
+  }
+}; 
diff --git a/jest.integration.config.js b/jest.integration.config.js
@@ -0,0 +1,15 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/integration/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+  collectCoverage: true,
+  collectCoverageFrom: ['src/**/*.ts'],
+  coverageDirectory: 'coverage/integration',
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: 'tsconfig.json',
+    }]
+  }
+}; 
diff --git a/package.json b/package.json
@@ -9,6 +9,7 @@
     "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
     "start": "node dist/index.js",
     "test": "jest",
+    "test:unit": "jest --testPathIgnorePatterns=tests/integration tests/security",
     "test:watch": "jest --watch",
     "test:integration": "jest --config jest.integration.config.js",
     "test:security": "jest --config jest.security.config.js",