📝 README Improvements: Enhanced UX, Navigation, and Tools Documentation Link by spboyer · Pull Request #732 · Azure/azure-mcp

spboyer · 2025-07-25T14:17:58Z

README Improvements: Enhanced User Experience and Documentation

This PR implements immediate improvements to the README.md to enhance user experience, navigation, and documentation discoverability. These changes address several points from issue #724 using existing content and structure.

🔄 Changes Overview

✨ Structural Improvements

✅ Added comprehensive Table of Contents with proper navigation
✅ Enhanced header section with version badges and project status
✅ Added Quick Start section with streamlined 5-step setup process
✅ Reorganized "What can you do" section into logical categories

📖 Content Enhancements

✅ Added prominent link to tools.md with clear description of 130+ tools coverage
✅ Improved Getting Started section with validation steps and troubleshooting hints
✅ Added comprehensive FAQ section addressing common user questions
✅ Enhanced visual hierarchy with better organization and badges

🚀 User Experience Improvements

✅ Made installation more prominent in Quick Start section
✅ Added "Pro Tip" showing how to chain operations
✅ Included version information and what's new in v0.5.0
✅ Strategic placement of comprehensive tools documentation link

🔧 Developer Experience Improvements

✅ Updated PR template to include explicit tools.md reference in checklist
✅ Enhanced documentation workflow to ensure tools.md stays current

📋 Specific Changes

1. Header Enhancements

# 🌟 Azure MCP Server

[![npm version](https://img.shields.io/npm/v/@azure/mcp.svg)](https://www.npmjs.com/package/@azure/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub issues](https://img.shields.io/github/issues/Azure/azure-mcp.svg)](https://github.com/Azure/azure-mcp/issues)

> 🚀 New in v0.5.0: Namespace mode (default), improved tool organization, and Azure Workbooks support  
> 📢 Public Preview: This project is in Public Preview

2. Quick Start Section

Added a streamlined "🚀 Quick Start" section that gets users running in under 60 seconds with clear step-by-step instructions and validation.

3. Table of Contents

Comprehensive navigation with links to all major sections including the new FAQ section.

4. Enhanced Examples Organization

Reorganized the "What can you do" section into logical categories:

🔍 Data & Analytics (AI Search, Cosmos DB, Data Explorer, Monitor)
🏗️ Infrastructure & Resources (Resource Management, AKS, Storage)
🗄️ Databases (SQL Database)
⚙️ Configuration & Management (App Configuration)

5. Tools Documentation Link

Strategic placement after the "Currently Supported Tools" section:

## 📖 Complete Tools Documentation

For comprehensive documentation of all 130+ available tools across 29+ Azure service namespaces, 
including detailed parameters, examples, and usage patterns, see our 
**[Complete Tools Documentation](./docs/tools.md)**.

6. FAQ Section

Added comprehensive FAQ addressing:

Differences between "All Tools" vs individual service installs
Azure CLI requirements
Authentication methods
Production readiness considerations
Troubleshooting guidance

7. PR Template Enhancement

Updated .github/PULL_REQUEST_TEMPLATE.md to include explicit tools.md checklist item:

Added requirement to update tools.md when adding/modifying MCP tools
Ensures documentation stays current with new tool additions
Improves developer workflow for maintaining comprehensive documentation

🎯 Impact on User Experience

These changes directly address several improvement areas from issue #724:

✅ Better navigation and structure → Table of Contents + reorganized sections
✅ Clearer onboarding process → Quick Start + improved Getting Started
✅ More organized examples → Categorized use cases with logical grouping
✅ FAQ for common questions → Comprehensive FAQ section
✅ Prominent tools documentation link → Strategic placement with clear value prop
✅ Better visual hierarchy → Badges, better formatting, logical flow
✅ Enhanced developer workflow → PR template ensures docs stay current

🔗 Related Issues

Addresses multiple points from 📝 README Improvements: Enhanced User Experience and Documentation #724 "README Improvements: Enhanced User Experience and Documentation"
Provides foundation for future improvements outlined in the issue roadmap

🧪 Testing

✅ Build passes successfully (dotnet build)
✅ All existing functionality preserved
✅ Links verified and functional
✅ Markdown structure validated

📝 Notes

All changes use existing content and structure - no breaking changes
Maintains backward compatibility with all existing links and references
Sets foundation for future enhancements outlined in issue 📝 README Improvements: Enhanced User Experience and Documentation #724
Ready for immediate deployment to improve user experience
PR template improvements will help maintain documentation quality going forward

Closes: Part of #724
Type: Documentation Enhancement
Impact: User Experience & Developer Workflow Improvement

… and FAQs for Azure MCP Server

- Add explicit checklist item for updating docs/tools.md when adding/modifying MCP tools - Improve clarity of documentation requirements for MCP tool changes - Ensure tools.md stays up-to-date with new tool additions

🎯 All reviewer feedback addressed: ✅ Rebase on latest main + remove video + change to VSIX: - 🎬 Removed video element that was deleted from main branch - 📦 Updated Quick Start to use VS Code Marketplace VSIX instead of NPX - ⚙️ Simplified VS Code Install Steps (removed Node.js requirement) ✅ Add VS Code Marketplace badge: - 🏷️ Added badge linking to GitHub Copilot for Azure extension ✅ Remove Available MCP Servers section: - 📋 Removed large table since it's 'a tiny server again' in 0.5.0 - 🧭 Updated Table of Contents accordingly 🔄 Key improvements: - Simplified installation process focuses on VSIX - Cleaner UX aligned with 0.5.0 architecture changes - Streamlined user onboarding experience - Build verified successful ✅ Co-authored-by: Josh Free <joshfree@microsoft.com>

… numbering

Copilot

Pull Request Overview

This PR enhances the Azure MCP Server's documentation by creating a comprehensive tools reference guide and improving the main README structure. The changes focus on improving user experience through better organization, clearer onboarding, and enhanced discoverability of the extensive Azure tools catalog.

Key changes include:

Creation of a comprehensive tools documentation file with 130+ Azure tools across 29+ service namespaces
Enhanced README with improved structure, Quick Start section, and better navigation
Updated PR template to ensure tools documentation stays current

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
`docs/tools.md`	New comprehensive reference documenting all 130+ Azure MCP tools with detailed parameters, examples, and categorization
`README.md`	Enhanced structure with badges, Quick Start section, improved navigation, FAQ section, and strategic link to tools documentation
`.github/PULL_REQUEST_TEMPLATE.md`	Updated to include requirement for maintaining tools.md when adding/modifying MCP tools

Comments suppressed due to low confidence (1)

docs/tools.md:65

The emoji character appears to be corrupted or not displaying properly. It should be a clear, recognizable emoji like 🔍 or 📊.

- [Azure Terraform Best Practices](#azure-terraform-best-practices)

joshfree · 2025-08-05T21:25:27Z

    - [ ] Updated `CHANGELOG.md` for product changes (`features, bug fixes, UI/UX, updated dependencies`)
    - [ ] Spelling check passes: `.\eng\common\spelling\Invoke-Cspell.ps1`
- [ ] For MCP tool changes, updated:
+- [ ] If adding an MCP tool, updated the docstring and/or documentation


these should be indented 4 spaces under the ` - [ ] For MCP tool changes, updated:"

KarishmaGhiya · 2025-08-05T21:59:09Z

What are the differences between azmcp-commands.md and tools.md? Do these need to be consolidated? I feel there is some overlapping information between these two documents. I like that tools.md has an index structure at the start.

spboyer · 2025-08-06T23:11:47Z

What are the differences between azmcp-commands.md and tools.md? Do these need to be consolidated? I feel there is some overlapping information between these two documents. I like that tools.md has an index structure at the start.

azmcp-commands appears to be more cli based documentation

charris-msft

Looks like a nice improvement in streamlining the getting started.
I've got a couple suggestions.

charris-msft · 2025-08-06T22:59:49Z

+[![GitHub issues](https://img.shields.io/github/issues/Azure/azure-mcp.svg)](https://github.com/Azure/azure-mcp/issues)

-### ✅ VS Code Install Guide (Recommended)
+The Azure MCP Server implements the [MCP specification](https://modelcontextprotocol.io) to create a seamless connection between AI agents and Azure services. Azure MCP Server can be used alone or with the [GitHub Copilot for Azure extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot) in VS Code.


This text is a bit stodgy.

How about something like:

From prompt to provision—fast.
Azure MCP Server connects your agents to real Azure services with zero boilerplate. Run it solo or inside VS Code with GitHub Copilot for Azure.

charris-msft · 2025-08-06T23:02:34Z

-### ✅ VS Code Install Guide (Recommended)
+The Azure MCP Server implements the [MCP specification](https://modelcontextprotocol.io) to create a seamless connection between AI agents and Azure services. Azure MCP Server can be used alone or with the [GitHub Copilot for Azure extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot) in VS Code.
+
+> **🚀 New in v0.5.0:** Namespace mode (default), improved tool organization, and Azure Workbooks support


Need to update for v0.5.3

charris-msft · 2025-08-06T23:05:42Z

-    - 👉 [Open an issue in the public repository](https://github.com/Azure/azure-mcp/issues/new/choose)
+1. Install the [Azure MCP Server](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-mcp-server) extension

+1. Install the [GitHub Copilot for Azure](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot) extension from the VS Code Marketplace


We need the button for installing to Insiders here too.

charris-msft · 2025-08-06T23:06:22Z

-1. Check out the [documentation](https://learn.microsoft.com/azure/developer/azure-mcp-server/) and review the [troubleshooting guide](https://github.com/Azure/azure-mcp/blob/main/TROUBLESHOOTING.md) for commonly asked questions
-1. We're building this in the open. Your feedback is much appreciated, and will help us shape the future of the Azure MCP server
-    - 👉 [Open an issue in the public repository](https://github.com/Azure/azure-mcp/issues/new/choose)
+1. Install the [Azure MCP Server](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-mcp-server) extension


We don't need this if they install GHCP4A

charris-msft · 2025-08-06T23:16:57Z

+
+**Get started in under 60 seconds:**
+
+1. **Install the GitHub Copilot for Azure extension**: [![Install from VS Code Marketplace](https://img.shields.io/badge/VS_Code-Install_GitHub_Copilot_for_Azure-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot)


We need the button for installing to Insiders here too.

charris-msft

More feedback on tools.md

charris-msft · 2025-08-06T23:37:47Z

+- **Single Tool Mode**: Single "azure" tool that routes to all operations
+- **Namespace Filtering**: Expose only specific namespaces using `--namespace` flags
+
+## Tool Categories


Since we're currently adding Namespaces instead of tools, it seems we should group the tools by namespace here in the docs so a user can figure out which tools are in each namespace.

charris-msft · 2025-08-06T23:39:16Z

+
+Tools for managing Azure subscriptions and tenant access.
+
+| Tool | Description | Read-Only | Parameters |


How about adding "Namespace" to the table so a user can lookup a tool and figure out which namespace it's in?

jongio · 2025-08-21T15:40:17Z

Let's close and reopen against new repo next week.

Copilot AI review requested due to automatic review settings July 25, 2025 14:17

spboyer requested a review from a team as a code owner July 25, 2025 14:17

spboyer requested review from KarishmaGhiya, g2vinay, hallipr, jongio and joshfree July 25, 2025 14:17

github-project-automation Bot added this to Azure MCP Server (OLD) Jul 25, 2025

spboyer requested review from conniey and sandeep-sen July 25, 2025 14:18

github-project-automation Bot moved this to Untriaged in Azure MCP Server (OLD) Jul 25, 2025

This comment was marked as outdated.

Sign in to view

spboyer mentioned this pull request Jul 25, 2025

📝 README Improvements: Enhanced User Experience and Documentation #724

Closed

12 tasks

spboyer requested a review from a team as a code owner July 28, 2025 18:51

joshfree reviewed Jul 28, 2025

View reviewed changes

Comment thread README.md Outdated

Comment thread README.md

Comment thread README.md Outdated

spboyer requested review from Copilot and joshfree August 4, 2025 20:19

This comment was marked as outdated.

Sign in to view

joshfree reviewed Aug 4, 2025

View reviewed changes

Comment thread README.md

Comment thread README.md

spboyer and others added 6 commits August 4, 2025 19:17

Add comprehensive documentation for Azure MCP tools and operations

886f193

Enhance README.md with installation instructions, tool documentation,…

cec3eab

… and FAQs for Azure MCP Server

docs: Update PR template to include tools.md reference

c58110c

- Add explicit checklist item for updating docs/tools.md when adding/modifying MCP tools - Improve clarity of documentation requirements for MCP tool changes - Ensure tools.md stays up-to-date with new tool additions

fix: Remove trailing spaces in README.md for improved formatting

ad3a2a1

docs: Update Quick Start instructions in README.md for clarity

cfb0440

spboyer force-pushed the docs branch from b649520 to cfb0440 Compare August 4, 2025 23:19

docs: Update Quick Start section in README.md for clarity and correct…

d7a2f54

… numbering

spboyer requested review from Copilot and joshfree August 4, 2025 23:26

Copilot AI reviewed Aug 4, 2025

View reviewed changes

joshfree reviewed Aug 5, 2025

View reviewed changes

charris-msft suggested changes Aug 6, 2025

View reviewed changes

github-project-automation Bot moved this from Untriaged to In Progress in Azure MCP Server (OLD) Aug 6, 2025

charris-msft suggested changes Aug 6, 2025

View reviewed changes

jongio closed this Aug 21, 2025

github-project-automation Bot moved this from In Progress to Done in Azure MCP Server (OLD) Aug 21, 2025


		Get started in under 60 seconds:

		1. Install the GitHub Copilot for Azure extension: [![Install from VS Code Marketplace](https://img.shields.io/badge/VS_Code-Install_GitHub_Copilot_for_Azure-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot)


		Tools for managing Azure subscriptions and tenant access.

		\| Tool \| Description \| Read-Only \| Parameters \|

Uh oh!

Conversation

spboyer commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

README Improvements: Enhanced User Experience and Documentation

🔄 Changes Overview

✨ Structural Improvements

📖 Content Enhancements

🚀 User Experience Improvements

🔧 Developer Experience Improvements

📋 Specific Changes

1. Header Enhancements

2. Quick Start Section

3. Table of Contents

4. Enhanced Examples Organization

5. Tools Documentation Link

6. FAQ Section

7. PR Template Enhancement

🎯 Impact on User Experience

🔗 Related Issues

🧪 Testing

📝 Notes

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KarishmaGhiya commented Aug 5, 2025

Uh oh!

spboyer commented Aug 6, 2025

Uh oh!

charris-msft left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

charris-msft left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jongio commented Aug 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

spboyer commented Jul 25, 2025 •

edited

Loading