microsoft
diff --git a/‎README.md
Lines changed: 18 additions & 141 deletions b/‎README.md
Lines changed: 18 additions & 141 deletions
diff --git a/‎docs/EXAMPLES.md
Lines changed: 134 additions & 0 deletions b/‎docs/EXAMPLES.md
Lines changed: 134 additions & 0 deletions
@@ -15,11 +15,10 @@ This TypeScript project provides a **local** MCP server for Azure DevOps, enabli
 2. [🏆 Expectations](#-expectations)
 3. [⚙️ Supported Tools](#️-supported-tools)
 4. [🔌 Installation & Getting Started](#-installation--getting-started)
-5. [🔦 Usage](#-usage)
-6. [📝 Troubleshooting](#-troubleshooting)
-7. [🎩 Samples & Best Practices](#-samples--best-practices)
-8. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
-9. [📌 Contributing](#-contributing)
+5. [📝 Troubleshooting](#-troubleshooting)
+6. [🎩 Examples & Best Practices](#-samples--best-practices)
+7. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
+8. [📌 Contributing](#-contributing)
 
 ## 📺 Overview
 
@@ -135,14 +134,7 @@ Interact with these Azure DevOps services:
 
 ## 🔌 Installation & Getting Started
 
-Clone the repository, install dependencies, and add it to your MCP client configuration.
-
-[VS Code and GitHub Copilot](#%EF%B8%8F-visual-studio-code--github-copilot)<br/>
-[Visual Studio 2022 and GitHub Copilot](#%EF%B8%8F-visual-studio-2022--github-copilot)
-
-### ➡️ Visual Studio Code & GitHub Copilot
-
-For the best experience, use Visual Studio Code and GitHub Copilot.
+For the best experience, use Visual Studio Code and GitHub Copilot. See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.
 
 ### Prerequisites
 
@@ -176,108 +168,7 @@ This installation method is the easiest for all users of Visual Studio Code.
 
 ##### Steps
 
-1. In your project, add a `.vscode\mcp.json` file with the following content:
-
-```json
-{
-  "inputs": [
-    {
-      "id": "ado_org",
-      "type": "promptString",
-      "description": "Azure DevOps organization name  (e.g. 'contoso')"
-    }
-  ],
-  "servers": {
-    "ado": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}"]
-    }
-  }
-}
-```
-
-2. Save the file, then click 'Start'.
-
-  <img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
-
-3. In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
-4. Click "Select Tools" and choose the available tools.
-5. We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
-
-#### 🛠️ Install from Source (Dev Mode)
-
-This installation method is recommended for advanced users and contributors who want immediate access to the latest updates from the main branch. It is ideal if you are developing new tools, enhancing existing features, or maintaining a custom fork.
-
-> **Note:** For most users, installing from the public feed is simpler and preferred. Use the source installation only if you need the latest changes or are actively contributing to the project.
-
-##### Steps
-
-1. Clone the repository.
-2. Install dependencies:
-
-```sh
-npm install
-```
-
-3. Edit or add `.vscode/mcp.json`:
-
-```json
-{
-  "inputs": [
-    {
-      "id": "ado_org",
-      "type": "promptString",
-      "description": "Azure DevOps organization's name  (e.g. 'contoso')"
-    }
-  ],
-  "servers": {
-    "ado": {
-      "type": "stdio",
-      "command": "mcp-server-azuredevops",
-      "args": ["${input:ado_org}"]
-    }
-  }
-}
-```
-
-4. Start the Azure DevOps MCP Server.
-
-  <img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
-
-5. In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
-6. Click "Select Tools" and choose the available tools.
-7. We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will help you get the best experience using the Azure DevOps MCP Server in GitHub Copilot Chat.
-
-See the [How To](./docs/HOWTO.md) section for details.
-
-### ➡️ Visual Studio 2022 & GitHub Copilot
-
-For the best experience, use Visual Studio Code and GitHub Copilot 👆.
-
-### Prerequisites
-
-1. Install [VS Studio 2022 version 17.14](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-history) or later
-2. Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
-3. Open a project in Visual Studio.
-
-### Azure Login
-
-Ensure you are logged in to Azure DevOps via the Azure CLI:
-
-```sh
-az login
-```
-
-#### 🧨 Install from Public Feed (Recommended)
-
-This installation method is the easiest for all users of Visual Studio 2022.
-
-🎥 [Watch this quick start video to get up and running in under two minutes!](https://youtu.be/nz_Gn-WL7j0)
-
-##### Steps
-
-1. Add a `.mcp.json` file to the solution folder with the following content:
+In your project, add a `.vscode\mcp.json` file with the following content:
 
 ```json
 {
@@ -298,45 +189,31 @@ This installation method is the easiest for all users of Visual Studio 2022.
 }
 ```
 
-2. Save the file.
-3. Add your organization name by clicking on the `input` option.
+Save the file, then click 'Start'.
 
-   <img src="./docs/media/start-mcp-server-from-vs.png" alt="start mcp server from visual studio 2022" width="250"/>
+<img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
 
-4. Open Copilot chat and switch to [Agent Mode](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-agent-mode?view=vs-2022).
-5. Click the "Tools" icon and choose the available tools.
+In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
 
-   <img src="./docs/media/set-tools-from-vs.png" alt="set tools to use in visual studio 2022" width="250"/>
+Click "Select Tools" and choose the available tools.
 
-6. We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
+<img src="./docs/media/configure-mcp-server-tools.gif" alt="configure mcp server tools" width="300"/>
 
-## 🔦 Usage
+Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
 
-### Visual Studio Code + GitHub Copilot
+> 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
 
-1. Open GitHub Copilot in VS Code and switch to Agent mode.
-2. Start the Azure DevOps MCP Server.
-3. The server appears in the tools list.
-4. Try prompts like "List ADO projects".
-
-### Visual Studio + GitHub Copilot
-
-> _Prerequisites:_ Visual Studio 2022 v17.14+, Agent mode enabled in Tools > Options > GitHub > Copilot > Copilot Chat.
-
-1. Switch to Agent mode in the Copilot Chat window.
-2. Enter your Azure DevOps organization name.
-3. Select desired `ado` tools.
-4. Try prompts like "List ADO projects".
-
-For more details, see [Visual Studio MCP Servers documentation](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022) and the [Getting Started Video](https://www.youtube.com/watch?v=oPFecZHBCkg).
+See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.
 
 ## 📝 Troubleshooting
 
 See the [Troubleshooting guide](./docs/TROUBLESHOOTING.md) for help with common issues and logging.
 
-## 🎩 Samples & Best Practices
+## 🎩 Examples & Best Practices
+
+Explore example prompts in our [Examples documentation](./docs/EXAMPLES.md).
 
-Find sample prompts and best practices in our [How-to Guide](./docs/HOWTO.md).
+For best practices and tips to enhance your experience with the MCP Server, refer to the [How-To guide](./docs/HOWTO.md).
 
 ## 🙋‍♀️ Frequently Asked Questions
 
 
@@ -0,0 +1,134 @@
+This guide offers step-by-step examples for using the Azure DevOps MCP Server to interact with your Azure DevOps organization. For additional tips and best practices, see the [How To guide](./HOWTO.md).
+
+> 📝 These examples have been tested and validated only in English. If you encounter issues when using a different language, please open an issue in the repository so we can investigate.
+
+[Get List of Projects](#get-list-of-projects)<br/>
+[Get List of Teams](#get-list-of-teams)<br/>
+[Get My Work Items](#get-my-work-items)<br/>
+[Get Work Items in a Backlog](#get-all-work-items-in-a-backlog)<br/>
+[Retrieve and Edit Work Items](#retrieve-and-edit-work-items)<br/>
+[Create and Link Test Cases](#create-and-link-test-cases)<br/>
+[Triage Work](#triage-work)<br/>
+[Using Markdown Format](#adding-and-updating-work-items-using-the-format-paramater)<br/>
+
+## 🙋‍♂️ Projects and Teams
+
+### Get List of Projects
+
+Most work item tools require project context. You can retrieve the list of projects and specify the desired project:
+
+```plaintext
+get list of ado projects
+```
+
+### Get List of Teams
+
+This command returns all Azure DevOps projects for the organization defined in the `mcp.json` file. Similarly, you can retrieve the team context:
+
+```plaintext
+get list of teams for project contoso
+```
+
+📽️ [Azure DevOps MCP Server: Get list of projects and teams](https://youtu.be/x579E4_jNtY)
+
+## 📅 Work Items
+
+### Get My Work Items
+
+Retrieve a list of work items assigned to you. This tool requires project context:
+
+```plaintext
+get my work items for project contoso
+```
+
+The model should automatically use the `wit_get_work_items_batch_by_ids` tool to fetch work item details.
+
+📽️ [Azure DevOps MCP Server: Get my work items](https://youtu.be/y_ri8n7mBlg)
+
+### Get All Work Items in a Backlog
+
+You need project, team and backlog (Epics, Stories, Features) context in order to get a list of all the work items in a backlog.
+
+```plaintext
+get backlogs for Contoso project and Fabrikam team
+```
+
+Once you have the backlog levels, you can then get work items for that backlog.
+
+```plaintext
+get list of work items for Features backlog
+```
+
+The model should automatically use the `wit_get_work_items_batch_by_ids` tool to fetch work item details.
+
+📽️ [Azure DevOps MCP Server: Get backlog](https://youtu.be/LouuyoscNrI)
+
+### Retrieve and Edit Work Items
+
+Get a work item, get the work item comments, update the work item fields, and add a new comment.
+
+```plaintext
+Get work item 12345 and show me fields ID, Type, State, Repro Steps, Story Points, and Priority. Get all comments for the work item and summarize them for me.
+```
+
+The model now has context of the work item. You can then update specific fields. In this case, we want the LLM to generate a better set of Repro Steps and then update the work item with those new steps. Along with updating the Story Points and State fields.
+
+```plaintext
+Polish the Repro Steps with more information and details. Then take that value and update the work item. Also update StoryPoints = 5 and State = Active.
+```
+
+Assign the work item to me and add a new comment.
+
+```plaintext
+Assign this work item to [email protected] and add a comment "I will own this Bug and get it fixed"
+```
+
+📽️ [Azure DevOps MCP Server: Work with Work Items](https://youtu.be/tT7wqSIPKdA)
+
+### Create and Link Test Cases
+
+Open a user story and automatically generate test cases with detailed steps based on the story's description. Link the generated test cases back to the original user story.
+
+```plaintext
+Open work item 1234 in 'Contoso' project. Then look at the description and create 1-3 Test Cases with test steps. But show me a preview first before creating the Test Case in Azure DevOps. Be sure to link the new Test Case to the User Story 1234 when you do.
+```
+
+📽️ [Azure DevOps MCP Server: Creating Test Cases from Work Item](https://youtu.be/G7fnYjlSh_w)
+
+### Triage Work
+
+Retrieve all work items in a backlog and triage them according to your own criteria. For example, you can fetch all bugs and user stories, identify security-related bugs, and assign them to the current team iteration. Similarly, you can select a few high-priority user stories and assign them to the most recent iteration.
+
+Retrieve the team's iterations and backlog levels to provide the LLM with the necessary context for accurate work item management.
+
+```plaintext
+list iterations for Contoso team
+```
+
+```plaintext
+list backlog levels for Contoso team
+```
+
+Retrieve the work items and their details, then instruct the LLM to identify security-related bugs and high-priority user stories. Assign the identified items to the current iteration and, if needed, to the next iteration.
+
+```plaintext
+List of work items for Stories backlog. But then go thru and find all the security related bugs. Assign the first 4 to the current iteration. If there are more than four, assign the rest to the next iteration. Then find 2-3 high priority user stories and assign them to the current iteration. Do it!
+```
+
+📽️ [Azure DevOps MCP Server: Triage Work](https://youtu.be/gCI_pPS76C8)
+
+### Adding and Updating Work Items Using the `format` Paramater
+
+You can use the `format` paramater to indicate markdown formatting for large text fields. It is now available on the following tools:
+
+- **wit_update_work_items_batch**
+- **wit_add_child_work_items**
+- **wit_create_work_item**
+
+> 🚩 HTML is the default unless `Markdown` is explicity set.
+
+```plaintext
+Update work item 12345 with a new description and use Markdown text. Use Markdown format param. Use bulk update.
+```
+
+📽️ [Azure DevOps MCP Server: Using Markdown format for create and update work items](https://youtu.be/OD4c2m7Fj9U)