Absolutely! Below is a complete, detailed README.md you can drop at the root of your project. It includes:
- 📘 Project overview & goals
- 🗂️ File/folder structure
- 🛠️ Tools implemented
- ⚙️ Setup instructions for Copilot Agent Mode
- ✅ Usage examples
- 📚 References
# 🚀 Azure DevOps MCP Server
> A modular [MCP (Model Context Protocol)](https://modelcontextprotocol.org/) Server built with Node.js that connects GitHub Copilot’s Agent Mode to your Azure DevOps projects (boards, pipelines, pull requests, and more) using natural language.
---
## 🎯 What Are We Trying to Achieve?
GitHub Copilot in **Agent Mode** can understand natural language and use external tools to help developers automate tasks.
This project builds an **MCP server** that integrates with Azure DevOps APIs to allow Copilot to:
- 🧠 Understand prompts like: “Get work item 1234” or “List my open pull requests”
- 🔄 Automatically fetch, create, update, delete, or comment on:
- Work Items
- Pipelines/Builds
- Pull Requests
- Boards & Sprints
- ⚡ Improve developer productivity without needing to leave VS Code
Copilot translates human language into tool calls — this server implements those tools.
---
## 🗂️ Project Structure
azure-devops-mcp-server/ ├── index.js # Entry point for your MCP server ├── package.json # Node.js project config ├── setup-env.sh # Helper script to export environment variables ├── mcp.json # VS Code MCP config for tool discovery ├── README.md # This documentation file └── src/ ├── tools/ # All MCP tool implementations │ ├── getWorkItem.js │ ├── createWorkItem.js │ ├── updateWorkItem.js │ ├── deleteWorkItem.js │ ├── listWorkItems.js │ ├── getWorkItemHistory.js │ ├── addWorkItemComment.js │ ├── getBuildDefinitions.js │ ├── queueBuild.js │ ├── getRecentBuilds.js │ ├── getBoards.js │ ├── listPullRequests.js │ ├── getPullRequestDetails.js │ ├── createPullRequest.js │ ├── approvePullRequest.js │ ├── completePullRequest.js │ └── commentOnPullRequest.js └── utils/ └── azureConnection.js # Shared logic to authenticate to Azure DevOps
---
## ⚙️ Setup Instructions
### 1. ✅ Install dependencies
npm install
### 2. ✅ Configure environment variables
Create or update a `.env` file or export these in your shell:
export AZURE_DEVOPS_ORG_URL="https://dev.azure.com/yourorg" export AZURE_DEVOPS_PAT="your-personal-access-token" export AZURE_DEVOPS_PROJECT="your-project-name" export AZURE_DEVOPS_TEAM="your-team-name" # (required only for Boards)
TIP: You can use `setup-env.sh` and run:
source setup-env.sh
### 3. ✅ Configure Copilot Agent Mode (VS Code)
Create a `.vscode/mcp.json` like this:
{ "mcpServers": { "azure-devops": { "command": "node", "args": ["./index.js"], "env": { "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/yourorg", "AZURE_DEVOPS_PAT": "your-pat", "AZURE_DEVOPS_PROJECT": "your-project" } } } }
### 4. ✅ Run the MCP server
node index.js
Copilot Agent Mode will now auto-discover all tools from this server when opened.
---
## 📚 Tools Available
| Tool Name | Description |
|----------------------------|------------------------------------------------------|
| `get_work_item` | Get details for a work item by ID |
| `create_work_item` | Create a new work item (bug, task, etc.) |
| `update_work_item` | Update fields of a work item |
| `delete_work_item` | Permanently delete a work item |
| `list_work_items` | Query work items by state or assigned user |
| `add_work_item_comment` | Add a comment to a work item |
| `get_work_item_history` | View update history of a work item |
| `get_build_definitions` | List build/pipeline definitions |
| `queue_build` | Start a new build |
| `get_recent_builds` | Show recent builds |
| `get_boards` | List available boards for the project/team |
| `list_pull_requests` | Get open/closed PRs in a repo |
| `get_pull_request_details` | Get PR status, reviewers, and metadata |
| `create_pull_request` | Open a new pull request |
| `approve_pull_request` | Approve a pull request |
| `complete_pull_request` | Complete/merge a PR |
| `comment_on_pull_request` | Add a comment to a PR |
---
## 💬 Example Prompts for Copilot
Prompt these into GitHub Copilot Chat in Agent Mode:
Get details of work item 12345 List active bugs assigned to me Create a task called “Setup CI workflow” Mark task 12345 as Done Delete work item 12345 Comment “Reviewed with QA” on work item 12345 List all build pipelines Trigger pipeline ID 8 Get last 5 builds for the project List open pull requests in my repo Approve PR #72 Merge PR #72 into main
---
## 🧠 NLP & Copilot Agent Mode
> Did we write our own NLP engine?
**No.** NLP is provided by GitHub Copilot’s LLM:
- You write prompts in natural language
- Copilot understands the intent
- It selects the tool from your MCP server
- It provides the structured inputs from your prompt
Your job: expose reliable tools with clear inputs and descriptions.
---
## ✅ Test Your Server
Run manually to confirm it registers tools without error:
node index.js
You should see logs (optional) confirming tool setup. Then try using it directly inside VS Code with Agent Mode.
---
## 📦 Requirements
- Node.js v18+
- VS Code with Copilot Chat (Agent Mode)
- An Azure DevOps Personal Access Token (PAT) with:
- Work Items: **Read & Write**
- Build: **Read & Execute**
- Git Repositories: **Read & Write**
- Project & Teams: **Read**
- Pull Requests: **Read & Contribute** (for PR lifecycle tools)
---
## 📚 References
- [GitHub Copilot Agent Mode](https://docs.github.com/en/copilot/how-tos/context/model-context-protocol)
- [Azure DevOps Node API](https://www.npmjs.com/package/azure-devops-node-api)
- [Azure DevOps REST Docs](https://learn.microsoft.com/en-us/rest/api/azure/devops/)
- [Model Context Protocol](https://modelcontextprotocol.org/)
---
## 📝 License
MIT — free to use, extend, and integrate into your own DevOps agent ✨
---
## 🙌 Credits
Built using:
- Model Context Protocol SDK
- Azure DevOps Node API
- GitHub Copilot Agent Mode