msteams-mcp-server/MIGRATION.md

Microsoft Teams MCP Server - Complete Teams integration for Claude Desktop and MCP clients with secure OAuth2 authentication and comprehensive team management

# Migration Guide: OAuth Redirect Only

This document helps users migrate from the previous device code authentication to the new OAuth redirect-only authentication.

## 🚀 What Changed

**Version 1.0.16** removed device code authentication and now uses **OAuth redirect flow only**. This provides a simpler, more user-friendly authentication experience.

### Before (Device Code Flow)
```bash
# Old device code flow
npx msteams-mcp-server --login
# Would show: "Enter this code: ABC123 at https://microsoft.com/devicelogin"
# Required manual code entry and completion checking
```

### After (OAuth Redirect Flow)
```bash
# New OAuth redirect flow
npx msteams-mcp-server --login
# Shows: "Visit: https://login.microsoftonline.com/oauth2/v2.0/authorize?..."
# Direct clickable link, automatic completion detection
```

## 📋 Migration Steps

### 1. Clear Existing Authentication (Recommended)
```bash
# Clear any existing authentication tokens
npx msteams-mcp-server --reset-auth
```

### 2. Re-authenticate with OAuth Redirect
```bash
# Start new OAuth redirect authentication
npx msteams-mcp-server --login
```

### 3. Follow the OAuth URL
- Click the provided OAuth URL
- Sign in with your Microsoft account
- Complete the authorization process
- The system automatically detects completion

### 4. Verify Authentication
```bash
# Check authentication status
npx msteams-mcp-server --verify-login
```

## 🔧 Configuration Changes

### Removed Options
The following CLI options have been removed:
- `--auth-type` (OAuth redirect is now the only option)

### Environment Variables
- `TEAMS_AUTH_TYPE` is no longer needed (OAuth redirect is default)
- All other environment variables remain the same

### Claude/SIYA Desktop Configuration
No changes needed to your Claude Desktop or SIYA Desktop configuration files.

## 🎯 Benefits of OAuth Redirect

1. **Simpler User Experience**: Direct clickable links instead of manual code entry
2. **Automatic Completion**: No need to manually check authentication completion
3. **Better Security**: Standard OAuth 2.0 redirect flow with PKCE
4. **Faster Authentication**: One-click authentication process
5. **Reduced Complexity**: Fewer moving parts, fewer potential issues

## 🛠️ Tool Changes

### Authentication Tool
The `authenticate` tool now only supports these actions:
- `login` - Start OAuth redirect flow
- `logout` - Clear stored tokens
- `status` - Check authentication status

**Removed**: `check_completion` action (no longer needed)

### Error Handling
Authentication errors now provide direct OAuth URLs instead of device codes:

```json
{
  "error": "OAuth authentication required: https://login.microsoftonline.com/..."
}
```

## 🔍 Troubleshooting

### Common Issues

**Problem**: "Invalid client" error
- **Solution**: Ensure your Azure app is configured for OAuth redirect flow
- **Check**: Redirect URI should be `http://localhost:44005/oauth2callback`

**Problem**: Authentication doesn't complete
- **Solution**: Make sure you complete the OAuth flow in your browser
- **Check**: Look for any popup blockers or security restrictions

**Problem**: Port conflicts
- **Solution**: Ensure port 44005 is available, or configure a different redirect URI

### Getting Help

1. **Check Authentication Status**:
   ```bash
   npx msteams-mcp-server --verify-login
   ```

2. **Reset and Retry**:
   ```bash
   npx msteams-mcp-server --reset-auth
   npx msteams-mcp-server --login
   ```

3. **Enable Debug Mode**:
   ```bash
   npx msteams-mcp-server --debug --login
   ```

## 📖 Documentation

- [README.md](./README.md) - Complete documentation
- [GitHub Issues](https://github.com/siya-ai/msteams-mcp-server/issues) - Report problems

## 🎉 Conclusion

The OAuth redirect flow provides a much smoother authentication experience. Most users will find the new system easier to use and more reliable than the previous device code flow.

If you encounter any issues during migration, please refer to the troubleshooting section above or create an issue on GitHub.