Copilot Studio Agent Direct Line MCP Server

# Setup and Deployment Guide Complete guide for setting up the Copilot Studio Agent Direct Line MCP Server locally and deploying to production. ## Table of Contents - [Prerequisites](#prerequisites) - [Local Development Setup](#local-development-setup) - [Configuration](#configuration) - [Running Locally](#running-locally) - [Testing](#testing) - [Building for Production](#building-for-production) - [Deployment Options](#deployment-options) - [Monitoring and Maintenance](#monitoring-and-maintenance) - [Troubleshooting](#troubleshooting) ## Prerequisites ### Required Software - **Node.js**: v18.0.0 or higher - **npm**: v8.0.0 or higher - **Git**: Latest version Verify installations: ```bash node --version # Should be >= v18.0.0 npm --version # Should be >= v8.0.0 git --version ``` ### Required Azure Resources 1. **Azure Bot Service** with Direct Line channel configured 2. **Direct Line Secret** (obtain from Azure Portal) 3. (Optional) **Azure Entra ID App Registration** for OAuth authentication ## Local Development Setup ### 1. Clone the Repository ```bash git clone https://github.com/bradcstevens/copilot-studio-agent-direct-line-mcp.git cd copilot-studio-agent-direct-line-mcp ``` ### 2. Install Dependencies ```bash npm install ``` This installs all required dependencies including: - `@modelcontextprotocol/sdk` - MCP server framework - `@azure/msal-node` - Azure authentication - `axios` - HTTP client - `express` - HTTP server (for HTTP mode) - Development tools (TypeScript, Jest, ESLint, Prettier) ### 3. Environment Configuration Create a `.env` file in the project root: ```bash cp .env.example .env ``` Edit `.env` with your configuration: ```bash # Required - Direct Line API Secret DIRECT_LINE_SECRET=your-direct-line-secret-here # Optional - Logging LOG_LEVEL=debug # debug | info | warn | error NODE_ENV=development # Optional - Token refresh interval (milliseconds) TOKEN_REFRESH_INTERVAL=1800000 # 30 minutes # Optional - Transport mode MCP_TRANSPORT_MODE=stdio # stdio | http ``` **Get your Direct Line Secret:** 1. Go to [Azure Portal](https://portal.azure.com) 2. Navigate to your Bot Service 3. Go to **Channels** > **Direct Line** 4. Click **Show** next to the secret key 5. Copy the secret to your `.env` file ### 4. Verify Setup Build the project to ensure everything is configured correctly: ```bash npm run build ``` You should see TypeScript compilation complete successfully with no errors. ### 5. VS Code Development Setup For VS Code-specific development workflows including debugging, hot reload, and testing, see the comprehensive [VS Code Development Guide](./VSCODE_DEVELOPMENT.md). Quick setup: 1. Build the project: `npm run build` 2. Configure `.vscode/mcp.json` (see [VS Code Development Guide](./VSCODE_DEVELOPMENT.md)) 3. Start the server in VS Code's MCP panel ## Configuration For detailed configuration options including environment variables, transport modes, and deployment settings, see the [Configuration Guide](./CONFIGURATION.md). Quick reference for essential variables: - **DIRECT_LINE_SECRET** (required): Your Direct Line secret from Copilot Studio - **MCP_TRANSPORT_MODE**: `stdio` (local) or `http` (production) - **LOG_LEVEL**: `debug`, `info`, `warn`, or `error` For HTTP mode configuration including OAuth setup, see: - [Configuration Guide](./CONFIGURATION.md) - All environment variables - [Authentication Guide](./AUTHENTICATION.md) - OAuth and Azure Entra ID setup ## Running Locally ### Development Mode (with hot reload) ```bash npm run dev ``` This starts the server with automatic reloading when files change. Output: ``` Starting Copilot Studio Agent Direct Line MCP Server... [Config] Environment loaded successfully [Config] Log level: debug [Config] Transport mode: stdio [DirectLine] Client initialized [TokenManager] Token manager initialized ✅ Server ready and listening for MCP requests ``` ### Production Build and Run ```bash # Build npm run build # Start npm start ``` ### Verify Server is Running **For stdio mode:** The server will listen on stdin/stdout. You can test it with an MCP client. **For HTTP mode:** ```bash curl http://localhost:3000/health # Expected response: { "status": "healthy", "timestamp": "2025-01-07T12:00:00.000Z", "uptime": 1234567, "version": "1.0.5" } ``` ## Testing ### Run All Tests ```bash npm test ``` ### Watch Mode (during development) ```bash npm run test:watch ``` ### Coverage Report ```bash npm run test:coverage ``` View coverage report at `coverage/lcov-report/index.html` ### Test MCP Integration ```bash # Build first npm run build # Run MCP test client npx ts-node tests/test-mcp-client.ts ``` This tests: - ✅ MCP server connection - ✅ Tool listing - ✅ Conversation creation - ✅ Message sending - ✅ History retrieval - ✅ Error handling ## Building for Production ### 1. Production Build ```bash npm run build ``` This: - Compiles TypeScript to JavaScript - Generates source maps - Creates type declarations - Outputs to `dist/` directory ### 2. Verify Build ```bash node dist/index.js ``` ### 3. Build Optimization The production build is optimized for: - **Tree shaking** - Removes unused code - **Type checking** - Validates all types - **ES modules** - Modern JavaScript output - **Source maps** - Debugging support ### Build Output ``` dist/ ├── index.js # Main entry point ├── index.d.ts # Type declarations ├── config/ # Configuration modules ├── services/ # Service implementations ├── utils/ # Utility functions └── types/ # Type definitions ``` ## Deployment Options ### Option 1: Azure Container Apps (Recommended) Azure Container Apps provides serverless container hosting with auto-scaling. #### Prerequisites - Azure CLI installed - Docker installed - Azure Container Registry (ACR) #### Step 1: Build Docker Image ```bash # Build docker build -t copilot-mcp:latest . # Test locally docker run -p 3000:3000 \ -e DIRECT_LINE_SECRET=your-secret \ -e MCP_TRANSPORT_MODE=http \ copilot-mcp:latest ``` #### Step 2: Push to Azure Container Registry ```bash # Login to ACR az acr login --name yourregistry # Tag image docker tag copilot-mcp:latest yourregistry.azurecr.io/copilot-mcp:latest # Push docker push yourregistry.azurecr.io/copilot-mcp:latest ``` #### Step 3: Deploy to Container Apps ```bash # Create resource group az group create --name copilot-mcp-rg --location eastus # Deploy using Bicep template az deployment group create \ --resource-group copilot-mcp-rg \ --template-file azure/container-apps/main-simple.bicep \ --parameters \ containerAppName=copilot-mcp \ containerRegistryName=yourregistry \ directLineSecret=your-direct-line-secret \ sessionSecret=your-session-secret \ azureClientId=your-client-id \ azureClientSecret=your-client-secret \ azureTenantId=your-tenant-id ``` #### Step 4: Verify Deployment ```bash # Get app URL az containerapp show \ --name copilot-mcp \ --resource-group copilot-mcp-rg \ --query properties.configuration.ingress.fqdn # Test health endpoint curl https://your-app.azurecontainerapps.io/health ``` **Detailed guide:** See `azure/container-apps/README.md` ### Option 2: Docker Compose (Local/Development) Perfect for local multi-container setups. ```bash # Start all services docker-compose up -d # View logs docker-compose logs -f # Stop services docker-compose down ``` **Configuration:** Edit `docker-compose.yml` ### Option 3: Azure App Service Traditional PaaS deployment option. ```bash # Create App Service plan az appservice plan create \ --name copilot-mcp-plan \ --resource-group copilot-mcp-rg \ --sku B1 --is-linux # Create web app az webapp create \ --resource-group copilot-mcp-rg \ --plan copilot-mcp-plan \ --name copilot-mcp-app \ --deployment-container-image-name yourregistry.azurecr.io/copilot-mcp:latest # Configure app settings az webapp config appsettings set \ --name copilot-mcp-app \ --resource-group copilot-mcp-rg \ --settings \ DIRECT_LINE_SECRET=your-secret \ MCP_TRANSPORT_MODE=http ``` ### Option 4: Kubernetes For enterprise-scale deployments. ```bash # Apply Kubernetes manifests kubectl apply -f k8s/ # Check deployment kubectl get pods -n copilot-mcp kubectl get svc -n copilot-mcp # View logs kubectl logs -f deployment/copilot-mcp -n copilot-mcp ``` **Note:** Kubernetes manifests are available but Container Apps is recommended for simplicity. ## Monitoring and Maintenance ### Health Checks The server provides a `/health` endpoint (HTTP mode): ```bash curl http://your-server/health ``` Response: ```json { "status": "healthy", "timestamp": "2025-01-07T12:00:00.000Z", "uptime": 3600000, "version": "1.0.5", "dependencies": [], "circuitBreakers": { "oauth": { "state": "CLOSED", "metrics": { "failures": 0, "successes": 42 } } } } ``` ### Logging Configure logging level via `LOG_LEVEL`: ```bash LOG_LEVEL=debug # Detailed logs LOG_LEVEL=info # Standard logs (default) LOG_LEVEL=warn # Warnings only LOG_LEVEL=error # Errors only ``` Logs include: - Server startup and shutdown - Configuration loading - Token refresh events - Circuit breaker state changes - Error details with stack traces ### Application Insights (Azure) For production monitoring: ```bash # Add Application Insights npm install applicationinsights # Configure in code export APPLICATIONINSIGHTS_CONNECTION_STRING=your-connection-string ``` ### Metrics to Monitor 1. **Health Status** - `/health` endpoint 2. **Response Times** - API latency 3. **Error Rates** - Failed requests 4. **Token Refresh** - OAuth token renewals 5. **Circuit Breaker** - Service degradation 6. **Memory Usage** - Container memory 7. **CPU Usage** - Container CPU ### Log Aggregation **Azure Container Apps:** ```bash # View logs az containerapp logs show \ --name copilot-mcp \ --resource-group copilot-mcp-rg \ --follow ``` **Docker:** ```bash docker logs -f copilot-mcp ``` ### Alerts Configure alerts for: - Health check failures - High error rates (>5%) - Circuit breaker open state - Token refresh failures - High memory usage (>80%) ## Troubleshooting ### Common Issues #### 1. Server won't start **Error:** `MODULE_NOT_FOUND` **Solution:** ```bash # Reinstall dependencies rm -rf node_modules package-lock.json npm install # Rebuild npm run build ``` #### 2. Direct Line authentication fails **Error:** `401 Unauthorized` from Direct Line API **Solution:** - Verify `DIRECT_LINE_SECRET` is correct - Check secret hasn't expired in Azure Portal - Ensure Direct Line channel is enabled ```bash # Test secret curl -H "Authorization: Bearer YOUR_SECRET" \ https://directline.botframework.com/v3/directline/tokens/generate ``` #### 3. OAuth authentication fails **Error:** `invalid_grant` or `AADSTS` errors **Solution:** - Verify Entra ID app registration - Check redirect URI matches exactly - Ensure client secret hasn't expired - Grant admin consent if required See: [Authentication Guide](./AUTHENTICATION.md) #### 4. TypeScript compilation errors **Error:** Type errors during build **Solution:** ```bash # Check TypeScript version npx tsc --version # Should be >= 5.0 # Clean build rm -rf dist/ npm run build # Check for type issues npm run lint ``` #### 5. Port already in use **Error:** `EADDRINUSE` when starting HTTP mode **Solution:** ```bash # Find process using port lsof -i :3000 # Kill process or change port HTTP_PORT=3001 npm run dev ``` #### 6. Circuit breaker open **Error:** `Circuit breaker is OPEN - failing fast` **Solution:** - Check external service availability - Review error logs for root cause - Wait for recovery timeout (60 seconds default) - Or manually reset: ```bash # Restart server to reset circuit breakers docker restart copilot-mcp # or kubectl rollout restart deployment/copilot-mcp ``` ### Debug Mode Enable detailed debugging: ```bash # Set debug log level LOG_LEVEL=debug npm run dev # Enable Node.js debugging NODE_OPTIONS='--inspect' npm run dev ``` Connect debugger: - Chrome DevTools: `chrome://inspect` - VS Code: Use launch configuration ### Getting Help 1. **Documentation** - `README.md` - Project overview - `docs/ERROR_HANDLING.md` - Error handling guide - `docs/AUTHENTICATION.md` - Authentication and OAuth setup 2. **Logs** - Check application logs for errors - Review Azure diagnostics - Enable debug logging 3. **Support** - GitHub Issues: [Report a bug](https://github.com/bradcstevens/copilot-studio-agent-direct-line-mcp/issues) - Azure Support: For Azure-specific issues ### Useful Commands ```bash # Check server status curl http://localhost:3000/health # View real-time logs npm run dev 2>&1 | grep -i error # Test build npm run build && npm start # Run specific test npm test -- src/utils/__tests__/circuit-breaker.test.ts # Format code npm run format # Lint code npm run lint # Clean install rm -rf node_modules dist && npm install && npm run build ``` ## Security Best Practices ### Development - ✅ Never commit `.env` file - ✅ Use strong secrets (min 32 characters) - ✅ Rotate secrets regularly - ✅ Enable OAuth in production - ✅ Use HTTPS in production ### Production - ✅ Store secrets in Azure Key Vault - ✅ Enable Azure Managed Identity - ✅ Configure CORS properly - ✅ Enable rate limiting - ✅ Use Azure Private Link (if needed) - ✅ Enable Azure DDoS Protection - ✅ Configure Web Application Firewall ### Checklist Before deploying to production: - [ ] All secrets in Key Vault - [ ] OAuth configured and tested - [ ] HTTPS enabled - [ ] Health checks configured - [ ] Monitoring enabled - [ ] Alerts configured - [ ] Backup strategy defined - [ ] Incident response plan ready - [ ] Tests passing (`npm test`) - [ ] No linting errors (`npm run lint`) - [ ] Documentation updated ## Next Steps 1. **Complete Setup** - Configure OAuth (see [Authentication Guide](./AUTHENTICATION.md)) - Set up monitoring - Configure alerts 2. **Deploy to Production** - Choose deployment option - Deploy using provided templates - Verify deployment 3. **Integrate with Applications** - Connect MCP clients - Configure authentication - Test end-to-end 4. **Maintain** - Monitor health metrics - Review logs regularly - Update dependencies - Rotate secrets ## Additional Resources - [MCP Protocol Specification](https://modelcontextprotocol.io) - [Azure Container Apps Documentation](https://learn.microsoft.com/en-us/azure/container-apps/) - [Direct Line API Reference](https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-concepts) - [Azure Entra ID Documentation](https://learn.microsoft.com/en-us/entra/identity/) --- **Questions?** Open an issue on [GitHub](https://github.com/bradcstevens/copilot-studio-agent-direct-line-mcp/issues)