README.md•7.13 kB
# Azure DevOps MCP Server
A **Model Context Protocol (MCP)** server that integrates Azure DevOps with GitHub Copilot Chat, allowing you to query work items naturally through conversation
## 🚀 What is MCP?
**Model Context Protocol (MCP)** is an open standard that connects AI assistants like GitHub Copilot to external data sources. This tool implements an MCP server that:
- 🔌 **Connects GitHub Copilot** to your Azure DevOps project
- 💬 **Enables natural language queries** - just ask Copilot about your tickets
- ⚡ **Provides instant responses** from cached data
- 🔒 **Keeps your data local** - no third-party services involved
Instead of switching between VS Code and Azure DevOps web portal, you can ask Copilot directly:
- "Show my sprint tickets"
- "Summarize ticket 13080"
- "What tickets are in ACC?"
## 🎯 What This Does
This tool helps you:
- **Instantly view** all User Stories where you have verification tasks assigned
- **Query cached data** without API rate limits or permission prompts
- **Summarize tickets** with full details including comments and descriptions
- **Track your sprint work** efficiently
- **Stay in your IDE** - no context switching needed
## ✨ Key Features
- 🔌 **MCP Protocol Implementation** - Native integration with GitHub Copilot via Model Context Protocol
- 🚀 **Cache-based queries** - Instant responses from local cache
- 🔍 **Smart filtering** - Automatically finds User Stories with your query
- 💬 **Full ticket details** - Descriptions, comments, state, assignees, tags
- 📊 **Sprint tracking** - Focused on current sprint items only
- 🤖 **Natural language interface** - Ask Copilot in plain English, no special syntax needed
## 🛠️ Setup
### 1. Prerequisites
- Node.js installed
- Azure DevOps personal access token
### 2. Configuration
Create a `.env` file with your credentials:
```env
AZURE_DEVOPS_ORG_URL=https://your-org.visualstudio.com
AZURE_DEVOPS_TOKEN=your-personal-access-token
AZURE_DEVOPS_PROJECT=your-project-name
AZURE_DEVOPS_USER_EMAIL=your.email@company.com
```
### 3. Install Dependencies
```bash
npm install
npm run build
```
## 📖 How to Use
### Step 1: Refresh Cache (Once per day or when needed)
```bash
npm run refresh
```
This fetches all User Stories from the current sprint where you have a "Verify" task assigned. Takes ~10-30 seconds depending on the number of stories.
**Output example:**
```
Found 12 user stories with your verify tasks
✓ Cache updated successfully!
Work items: 12
Last updated: 2025-11-17T07:33:36.435Z
```
### Step 2: Query Your Tickets (Instant, no prompts!)
After caching, you can query instantly using GitHub Copilot Chat in VS Code:
**In Copilot Chat, ask:**
- `show all my sprint user stories`
- `summarize ticket 13080`
- `show all tickets in status "In ACC"`
- `show tickets with tag "HIGHPRIO"`
**Or use the CLI:**
```bash
# List all your verify stories
node cli.js my-verify
# Get details of a specific ticket
node cli.js item 13080
# Query cached data
npm run query
```
### Query Cache Commands
```bash
npm run query
```
Available commands:
- `list` - List all cached user stories
- `item <id>` - Show details for a specific ticket
- `by-state <state>` - Filter by state (Active, "In ACC", New, etc.)
- `info` - Show cache information
## 🎨 MCP Server Integration with GitHub Copilot
### What Makes This Special?
This tool implements the **Model Context Protocol (MCP)**, which means:
1. **🔌 Direct Integration** - Copilot can access your Azure DevOps data as if it's a native feature
2. **💬 Natural Conversation** - No special commands or syntax needed
3. **⚡ Real-time Context** - Copilot knows about your tickets while you code
4. **🔒 Secure & Local** - Your data stays on your machine, accessed via your personal token
### How It Works
```
┌─────────────────┐
│ GitHub Copilot │ "Show my sprint tickets"
│ in VS Code │
└────────┬────────┘
│ MCP Protocol
▼
┌─────────────────┐
│ MCP Server │ Queries local cache
│ (This Tool) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Cached Data │ Your sprint tickets
│ work-items.json│ (refreshed from Azure DevOps)
└─────────────────┘
```
```
### MCP Configuration
The MCP server is configured in `.vscode/settings.json`:
```json
{
"github.copilot.chat.codeGeneration.instructions": [
{
"file": "azure-devops-mcp-server"
}
],
"mcp.servers": {
"azure-devops": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "${workspaceFolder}/azure-devops-mcp-server"
}
}
}
```
This tells VS Code to run the MCP server when Copilot needs Azure DevOps data.
## 📁 Project Structure
```
azure-devops-mcp-server/
├── src/
│ ├── azure-devops-client.ts # Azure DevOps API client
│ └── index.ts # MCP server implementation
├── cache/
│ └── work-items.json # Cached sprint data
├── cli.js # Command-line interface
├── refresh-cache.js # Cache refresh script
├── query-cache.js # Cache query script
├── .env # Your credentials (gitignored)
└── package.json # Project configuration
```
## 🔄 Typical Workflow
1. **Morning:** Run `npm run refresh` to get today's sprint data
2. **During work:** Ask Copilot about tickets - instant responses from cache
3. **Need updates?** Run `npm run refresh` again
## 🎯 Why This Matters
**Before this tool:**
- Every query required clicking "Allow" button
- Interrupts your flow
- Slow responses
**With this tool:**
- Cache once, query unlimited times
- No permission prompts
- Instant responses in Copilot Chat
## 🚀 Quick Start for Team Members
1. **Clone/copy this folder** to your machine
2. **Create `.env` file** with your Azure DevOps credentials
3. **Install dependencies:** `npm install && npm run build`
4. **Refresh cache:** `npm run refresh`
5. **Configure VS Code** to enable MCP server (see MCP Configuration above)
6. **Start chatting with Copilot** about your tickets!
> 💡 **Pro Tip:** Once the MCP server is running, Copilot becomes your Azure DevOps assistant. Just ask questions naturally!
## 💡 Tips
- Refresh cache at the start of your workday
- Cache includes all comments and descriptions
- Works offline once cached
- Cache file is human-readable JSON (check `cache/work-items.json`)
## 🔧 Troubleshooting
**"Error: azureClient.getUserStoriesWithMyVerifyTasks is not a function"**
- Run `npm run build` to recompile TypeScript
**"Found 0 user stories"**
- Check your email in `.env` matches Azure DevOps
- Verify you have "Verify" tasks assigned in current sprint
**Cache is outdated**
- Run `npm run refresh` to update
## 📝 License
ISC