Microsoft Style Guide Server

A professional Model Context Protocol (MCP) server implementation for analyzing content against the official Microsoft Writing Style Guide. This tool provides seamless integration with VS Code, GitHub Copilot Chat, and other MCP-compatible AI tools to help content creators ensure their writing follows Microsoft's style principles: warm and relaxed, crisp and clear, and ready to help.

🚀 Two Server Versions

🌐 Web-Enabled Version (mcp_server_web.py) - Recommended

• Fetches live guidance from the official Microsoft Style Guide website
• Always up-to-date with the latest style guide changes
• Provides real official content and examples from Microsoft Learn
• Requires internet connection for comprehensive analysis

📚 Offline Version (mcp_server.py)

• Built-in style guide rules and patterns
• Fast local analysis without internet dependency
• Perfect for secure environments or offline work
• Provides links to official documentation for detailed guidance

✨ Key Features

• 🔍 Official Style Guide Integration: Fetches current guidance from Microsoft Learn
• 🛠️ VS Code Integration: Seamless MCP protocol integration with automated setup
• 💬 AI Chat Compatible: Works with GitHub Copilot, Claude, and other MCP-enabled AI tools
• 📊 Comprehensive Analysis: Voice/tone, grammar, terminology, and accessibility checking
• ⚡ One-Command Setup: Fully automated installation and configuration
• 🌐 Always Current: Web version stays synchronized with official style guide updates

🚀 Quick Installation

Prerequisites

• Python 3.8+
• VS Code (for IDE integration)
• Internet connection (for web-enabled version)

One-Command Setup

# Clone or download this repository
git clone https://github.com/your-username/mslearn-authoring-mcp-server.git
cd mslearn-authoring-mcp-server

# Run automated setup (chooses web version by default)
python setup_script.py

That's it! The setup script will:

• ✅ Install Python dependencies
• ✅ Configure VS Code MCP integration
• ✅ Set up AI chat tool compatibility
• ✅ Test server functionality
• ✅ Create all necessary configuration files

Advanced Setup Options

# Auto-select web version (default)
python setup_script.py --auto

# Force offline version
python setup_script.py --offline

# Skip all prompts with environment variable
set AUTOMATED_SETUP=true & python setup_script.py

📁 Project Structure

mslearn-authoring-mcp-server/
├── mcp_server.py              # Offline MCP server implementation
├── mcp_server_web.py          # Web-enabled MCP server (recommended)
├── mcp_client.py              # Client for testing and interaction
├── mcp_manifest.json          # MCP server manifest for VS Code
├── setup_script.py            # Automated installation script
├── requirements.txt           # Python dependencies
└── README.md                  # This documentation

📖 Usage

Command Line Interface

Quick Test

# Test with simple text (web version)
python mcp_client.py --mode text --text "Your content here"

# Interactive mode
python mcp_client.py --mode interactive

# Analyze a specific file
python mcp_client.py --mode file --file document.md

Available Analysis Types

• comprehensive - Complete style analysis (default)
• voice_tone - Voice and tone compliance
• grammar - Grammar and style patterns
• terminology - Terminology consistency
• accessibility - Inclusive language checking

VS Code Integration

After running the setup script, the MCP server is automatically configured in VS Code:

1. Automatic Configuration: Setup script creates all necessary VS Code settings
2. MCP Server Detection: Server appears in MCP-compatible extensions
3. AI Chat Integration: Works with GitHub Copilot Chat and other AI tools
4. Real-time Analysis: Content analysis through MCP protocol

Using with GitHub Copilot Chat

In VS Code, use Copilot Chat with commands like:

@workspace analyze this document for Microsoft Style Guide compliance
@workspace check the voice and tone of this content
@workspace suggest style improvements for this text

Direct MCP Integration

For developers integrating with other MCP clients:

# Server connection parameters
{
  "command": "python",
  "args": ["path/to/mcp_server_web.py"],
  "env": {
    "PYTHONPATH": "path/to/project"
  }
}

🎯 Microsoft Style Guide Principles

This tool analyzes content based on Microsoft's core principles:

Voice and Tone

• Warm and Relaxed: Use contractions, natural language
• Crisp and Clear: Direct, scannable content under 25 words per sentence
• Ready to Help: Action-oriented, supportive language

Grammar and Style Standards

• Active Voice: "You can configure settings" vs "Settings can be configured"
• Second Person: Address readers as "you"
• Imperative Mood: Use for instructions (Click, Choose, Select)
• Scannable Format: Use headers, bullets, and short paragraphs

Terminology Consistency

Preferred	Avoid	Context
AI	A.I.	No periods in abbreviation
email	e-mail	One word
sign in (verb)	login, log in	Microsoft standard
website	web site	One word

Accessibility and Inclusion

• Use "everyone" instead of "guys"
• Use "allow list" instead of "whitelist"
• People-first language: "people with disabilities"

📊 Example Analysis Output

Web-Enabled Version

📋 Microsoft Style Guide Analysis

✅ Good - Minor improvements suggested

📊 Text Statistics:
   • Words: 45 | Sentences: 3 | Avg: 15.0 words/sentence

🔍 Issues Found: 2
   • Voice/Tone: Use more contractions for natural tone
   • Accessibility: Consider "everyone" instead of "users"

🌐 Official Microsoft Guidance:
   Voice and tone - Use contractions like "it's" and "you're" 
   to create a friendly, approachable tone...

📎 Reference: https://learn.microsoft.com/en-us/style-guide/voice-tone

Offline Version

📋 Microsoft Style Guide Analysis

⚠️ Minor style issues detected

📊 Text Statistics:
   Words: 45 | Sentences: 3 | Avg: 15.0 words/sentence

🔍 Issues Found: 2
   • Voice/Tone: Consider more conversational language
   • Terminology: Check official Microsoft terms

🌐 For detailed guidance:
   https://learn.microsoft.com/en-us/style-guide

🛠️ Development and Testing

Running Tests

# Test server functionality
python mcp_client.py --mode text --text "Test content"

# Verify web version connectivity
python -c "import mcp_server_web; print('Web server OK')"

# Check offline version
python -c "import mcp_server; print('Offline server OK')"

Server Configuration

Both servers expose these MCP tools:

• analyze_content - Main analysis function
• get_style_guidelines - Retrieve specific guidelines
• suggest_improvements - Get improvement recommendations
• search_style_guide - Search official documentation (web version only)

🐛 Troubleshooting

Common Issues

Setup Script Fails

# Check Python version
python --version  # Should be 3.8+

# Install dependencies manually
pip install -r requirements.txt

VS Code Integration Not Working

• Restart VS Code completely after running setup
• Check that MCP-compatible extensions are installed
• Verify server appears in extension settings

Web Version Connection Issues

• Check internet connectivity
• Verify firewall allows Python to access microsoft.com
• Try offline version as fallback

Debug Mode

# Run with verbose output
python mcp_client.py --mode text --text "test" --verbose

# Check server logs
python mcp_server_web.py  # Should start without errors

🔧 Configuration Options

Environment Variables

# Force specific server version
set MCP_SERVER_VERSION=web
set MCP_SERVER_VERSION=offline

# Enable debug logging
set MCP_DEBUG=true

# Skip VS Code configuration
set SKIP_VSCODE_CONFIG=true

VS Code Settings

The setup script creates comprehensive VS Code configuration:

• MCP server registration
• Multiple extension compatibility
• Automatic server discovery
• Debug configuration

🤝 Contributing

1. Fork this repository
2. Create a feature branch
3. Follow Microsoft Style Guide principles in code and documentation
4. Test with both server versions
5. Submit a pull request

Development Setup

git clone your-fork-url
cd mslearn-authoring-mcp-server
python setup_script.py --auto
# Make changes and test
python mcp_client.py --mode interactive

📚 References

• Microsoft Writing Style Guide
• Model Context Protocol
• VS Code MCP Integration

📄 License

This project is licensed under the MIT License. See LICENSE file for details.

⚠️ Disclaimer

This tool is not officially affiliated with Microsoft. It's an independent implementation based on publicly available Microsoft Style Guide principles and documentation.

---

Built for better technical writing and communication ✨

For questions or issues, please check the troubleshooting section or create an issue in this repository.