# Azure DevOps MCP Server for Cursor 🚀

**Built specifically for Cursor IDE** - Control Azure DevOps with natural language!

## ⚡ What is this?

A tool that lets you talk to Azure DevOps in plain English, right from Cursor's chat. No commands to memorize!

**Examples:**
- *"Show my work items"*
- *"Create a bug for the login issue"*
- *"What PRs need my review?"*
- *"Run the main build"*

---

## 🚨 IMPORTANT: Do Everything in Cursor When Possible! 🚨

This guide assumes you're using **Cursor IDE**. If you don't have it yet, [download Cursor here](https://cursor.sh/).

---

## 📦 Installation Guide (5 minutes)

### 🎯 Step 1: Clone the Project **IN CURSOR**

1. Open **Cursor IDE**
2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
3. Type "Git: Clone" and select it
4. Paste: `https://github.com/EreAlexandru/ADOMCPLocalServer.git`
5. Choose where to save it (remember this location!)
6. Click "Open" when Cursor asks

**You're now in the project folder in Cursor!** ✅

### 🔨 Step 2: Install Dependencies **IN CURSOR**

1. In Cursor, press `` Ctrl+` `` to open the terminal
2. You should see something like `C:\...\ADOMCPLocalServer>`
3. Type these commands:
   ```bash
   npm install
   npm run build
   ```
4. Wait for it to finish (about 30 seconds)

**Alternative for Windows:** You can also double-click `install.bat` in the file explorer

### 🔑 Step 3: Get Your Azure DevOps Token

1. Open your browser and go to:
   ```
   https://dev.azure.com/YOUR-ORG-NAME/_usersSettings/tokens
   ```
   **Replace `YOUR-ORG-NAME` with your organization!**
   
   📍 **How to find your organization name:**
   - Look at your Azure DevOps URL
   - If it's `https://dev.azure.com/contoso/MyProject` → org is `contoso`
   - If it's `https://contoso.visualstudio.com/` → org is `contoso`

2. Click **"+ New Token"**
3. Name it: "Cursor MCP"
4. Expiration: 90 days (recommended)
5. Scopes: Click **"Custom defined"** then check:
   - ✅ Work Items (Read, Write & Manage)
   - ✅ Code (Read)
   - ✅ Build (Read & Execute)
   - ✅ Release (Read, Write & Execute)
   - ✅ Test Management (Read & Write)
   - ✅ Wiki (Read & Write)
6. Click **"Create"**
7. **COPY THE TOKEN NOW!** You won't see it again!

### 🔐 Step 4: Create .env File **IN THE RIGHT PLACE!**

#### ⚠️ CRITICAL: The .env file goes in the ROOT folder, NOT in src/ or dist/! ⚠️

**Option A: Using Cursor (Recommended)** 👈
1. In Cursor, right-click on the **root folder** (ADOMCPLocalServer)
2. Select "New File"
3. Name it exactly: `.env` (yes, starting with a dot!)
4. Paste this (replace with your values):
   ```
   AZURE_DEVOPS_ORG=your-organization-name
   AZURE_DEVOPS_PAT=your-token-from-step-3
   ```
5. Save with `Ctrl+S`

**Option B: Using setup.bat (Windows only)**
1. Double-click `setup.bat` in the root folder
2. Enter your organization name when asked
3. Paste your token when asked
4. It creates the .env file for you!

**Option C: Manual (if above doesn't work)**
1. Open Notepad
2. Paste:
   ```
   AZURE_DEVOPS_ORG=your-organization-name
   AZURE_DEVOPS_PAT=your-token-here
   ```
3. File → Save As
4. Navigate to the ADOMCPLocalServer folder (NOT src or dist!)
5. File name: `.env` (with the dot!)
6. Save as type: **All Files (*.*)**
7. Click Save

#### 📁 Correct File Structure:
```
ADOMCPLocalServer/
├── .env              ← YOUR .ENV FILE GOES HERE!
├── src/              ← NOT HERE!
├── dist/             ← NOT HERE!
├── package.json
├── install.bat
└── README.md
```

### 🔌 Step 5: Connect to Cursor

1. In Cursor, go to **File → Preferences → Cursor Settings**
2. In the left sidebar, find **"Tools & Integration"**
3. Click **"New MCP Server"**
4. **DELETE EVERYTHING** in the box and paste this:

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["C:/PATH/TO/YOUR/ADOMCPLocalServer/dist/index.js"]
    }
  }
}
```

5. **IMPORTANT:** Replace `C:/PATH/TO/YOUR/` with your actual path!
   
   **How to find your path:**
   - In Cursor, look at the top of the window
   - Or right-click on any file → "Copy Path"
   - Use FORWARD SLASHES (/) not backslashes (\)
   
   **Examples:**
   - ✅ Windows: `"C:/Users/John/Projects/ADOMCPLocalServer/dist/index.js"`
   - ✅ Mac: `"/Users/john/Projects/ADOMCPLocalServer/dist/index.js"`
   - ❌ WRONG: `"C:\Users\John\..."` (backslashes don't work!)

6. Click outside the box to save

### 🔄 Step 6: Restart Cursor

**THIS IS REQUIRED!** Close Cursor completely and open it again.

### ✅ Step 7: Verify It Works

1. After restarting, go to **File → Preferences → Cursor Settings → Tools & Integration**
2. Find "azure-devops" in the list
3. **You should see a green dot ✅** = Connected!
4. Click on it to see all 60+ available tools

**No green dot?** See [Troubleshooting](#-troubleshooting)

### 🎉 Step 8: Test It!

1. Open a new chat in Cursor (Ctrl+L)
2. Type: "List my Azure DevOps projects"
3. You should see your projects!

---

## 🆘 Troubleshooting

### 🔍 Quick Diagnostic (Windows)
Double-click `check-env.bat` to automatically check your setup!

### ❌ Common Issues

**"No green dot / Not connected"**
1. Did you restart Cursor after adding the server?
2. Is your path correct in settings? (forward slashes!)
3. Did you run `npm run build`?
4. Is the .env file in the ROOT folder?

**"Authentication failed"**
1. Check your .env file location (must be in root folder!)
2. Is your organization name spelled correctly?
3. Did you copy the ENTIRE token?
4. Has your token expired?

**"Can't find .env file"**
- The .env file should be in the ROOT folder:
  ```
  ADOMCPLocalServer/.env ← HERE!
  NOT in:
  - ADOMCPLocalServer/src/.env ❌
  - ADOMCPLocalServer/dist/.env ❌
  ```

**To verify your .env location:**
1. In Cursor terminal, type: `dir .env` (Windows) or `ls -la .env` (Mac/Linux)
2. You should see the file listed

### 🧪 Test Your Connection
Run this in the Cursor terminal:
```bash
node test-connection.js
```

This will show:
- ✅ If your credentials work
- 📁 What projects you have access to
- ❌ Any connection errors

---

## 💬 What You Can Ask

Just type naturally in Cursor's chat:

**Daily Tasks:**
- "Show my active work items"
- "What did I work on yesterday?"
- "Create a bug for the login issue"

**Code Reviews:**
- "Show PRs waiting for my review"
- "Create a PR from feature/login to main"
- "What PRs are older than 3 days?"

**Builds & Releases:**
- "Run the CI build"
- "Show failed builds from today"
- "Deploy release to staging"

**Sprint Management:**
- "Show sprint 23 progress"
- "What items are blocked?"
- "Calculate team velocity"

---

## 🎪 Advanced: Guided Workflows

Ask for help with complex tasks:

### 👥 **For Development Teams:**
- "Help me prepare for standup"
- "Guide me through sprint planning"
- "Show sprint retrospective data"
- "Analyze build health"

### 🧪 **For QA Manual Testers:**
- "Show test execution status"
- "Analyze failed tests patterns"
- "Generate test coverage report"
- "Check test environment health"

### 🤖 **For QA Automation Engineers:**
- "Find flaky tests in automation"
- "Analyze automation test results"
- "Identify tests needing automation"
- "Show performance test trends"

### 🚀 **For Release Management:**
- "Check release readiness"
- "Analyze defect leakage"
- "Review test data requirements"

**Total: 24 guided workflows** covering development, manual testing, automation, and release management!

The AI will guide you step-by-step through each process!

---

## 🔒 Security

- ✅ Runs 100% locally on YOUR computer
- ✅ Your token never leaves your machine
- ✅ Can only do what YOU have permission for
- ✅ Open source - check the code yourself!

---

## 📝 For Developers

**Made changes?** Rebuild with:
```bash
npm run build
```

Then restart the server in Cursor settings (disable/enable).

---

## 🐛 Still Having Issues?

1. Make sure you're using **Cursor IDE** (not VS Code)
2. Check the .env file is in the **root folder**
3. Use **forward slashes** in the path
4. **Restart Cursor** after any changes

**Need help?** Open an issue: https://github.com/EreAlexandru/ADOMCPLocalServer/issues

---

**License:** MIT - Use it however you want! 🎉