MCP & Copilot Studio Learning Project

# 🚀 MCP & Copilot Studio Learning Project **Learn Model Context Protocol (MCP) development from absolute zero to production!** Welcome to your comprehensive learning journey with **Model Context Protocol (MCP)** and **Copilot Studio**! This project assumes you're starting completely from scratch - no prior knowledge, no tools installed. We'll get you up and running in under 30 minutes! 🎯 ## 📋 Prerequisites (Install Everything from Scratch) ### 1. Install Visual Studio Code **Everyone starts here - even if you have another editor!** 1. **Download VS Code**: Go to [https://code.visualstudio.com/](https://code.visualstudio.com/) 2. **Install**: Run the installer with default settings 3. **Verify**: Open VS Code and you should see the welcome screen ### 2. Install Node.js (Required for MCP Development) **MCP servers run on Node.js - this is essential!** 1. **Download Node.js**: Go to [https://nodejs.org/](https://nodejs.org/) 2. **Choose LTS Version**: Download the "LTS" (Long Term Support) version 3. **Install**: Run installer with default settings 4. **Verify Installation**: - Open Command Prompt (Windows) or Terminal (Mac/Linux) - Type: `node --version` (should show v16.0.0 or higher) - Type: `npm --version` (should show 8.0.0 or higher) ### 3. Install Git (For Project Management) **You'll need this to clone projects and manage code** 1. **Download Git**: Go to [https://git-scm.com/downloads](https://git-scm.com/downloads) 2. **Install**: Use default settings during installation 3. **Verify**: Type `git --version` in your terminal ### 4. Install Claude Desktop (For Testing Your MCP Server) **This is where you'll test your MCP tools!** 1. **Download Claude Desktop**: Go to [https://claude.ai/download](https://claude.ai/download) 2. **Install**: Follow platform-specific instructions 3. **Create Account**: Sign up for Claude if you don't have an account 4. **Verify**: Open Claude Desktop and ensure it launches ### 5. Install PowerShell 7+ (Windows Users) **Modern PowerShell for better development experience** 1. **Download**: Go to [https://github.com/PowerShell/PowerShell/releases](https://github.com/PowerShell/PowerShell/releases) 2. **Install**: Choose the .msi installer for Windows 3. **Verify**: Type `pwsh --version` in Command Prompt ## 🏗️ Project Structure (What You're About to Build) ``` 📁 MCP Learning Project ├── 📖 README.md ← You are here! Main project guide ├── 📁 src/ │ └── 📄 index.ts ← Your working file (copy day files here) ├── 📁 days/ ← Day-by-day learning files │ ├── 📁 day-1/ ← Greeting tool (basics) │ │ ├── 📄 index-starter.ts ← Starting template │ │ ├── 📄 index-complete.ts ← Finished example │ │ └── 📖 README.md ← Day overview │ ├── 📁 day-2/ ← Multi-tool development │ │ ├── 📄 index-starter.ts ← Advanced template │ │ ├── 📄 index-complete.ts ← Finished example │ │ └── 📖 README.md ← Day overview │ ├── 📁 day-3/ ← Resources and data management │ │ ├── 📄 index-starter.ts ← Resources template │ │ ├── 📄 index-complete.ts ← Full implementation │ │ └── 📖 README.md ← Day overview │ └── 📁 day-4/ ← Smart prompts and templates │ ├── 📄 index-starter.ts ← Prompts template │ ├── 📄 index-complete.ts ← Full implementation │ └── 📖 README.md ← Day overview ├── 📁 exercises/ ← Step-by-step instructions │ ├── 📖 day-1-basics.md ← Complete Day 1 guide │ ├── 📖 day-2-advanced-tools.md ← Complete Day 2 guide │ ├── 📖 day-3-resources.md ← Complete Day 3 guide │ └── 📖 day-4-prompts.md ← Complete Day 4 guide ├── 📁 docs/ ← Additional learning resources ├── 📁 examples/ ← Code examples and templates ├── 📄 package.json ← Project configuration └── 📄 tsconfig.json ← TypeScript settings ``` ## ⚡ Complete Setup Process (Start Here!) ### Step 1: Get This Project ```powershell # 1. Open VS Code # 2. Open Terminal in VS Code (Terminal > New Terminal) # 3. Navigate to where you want this project cd "C:\Users\YourName\Documents" # 4. Clone or download this project # (If you downloaded a ZIP, extract it and open the folder in VS Code) ``` ### Step 2: Install Project Dependencies ```powershell # 1. Open this project folder in VS Code # 2. Open Terminal in VS Code # 3. Install required packages npm install # This installs: # - @modelcontextprotocol/sdk (MCP development framework) # - zod (input validation) # - typescript (TypeScript compiler) ``` ### Step 3: Verify Everything Works ```powershell # 1. Build the project npm run build # 2. Test the basic server npm start # You should see: "MCP Server running on stdio" # Press Ctrl+C to stop ``` ## 🎯 Your First 30 Minutes (Complete Beginner Path) ### Minutes 0-10: Understanding the Structure 1. **Open the project** in VS Code (File > Open Folder) 2. **Explore the folders** using the VS Code sidebar: - Look at `days/day-1/` - this is your Day 1 lesson - Look at `exercises/day-1-basics.md` - this is your step-by-step guide - Notice `src/` is empty - you'll copy files here to work on them - See `days/day-2/`, `days/day-3/`, and `days/day-4/` for upcoming lessons ### Minutes 10-20: Your First MCP Tool 1. **Copy the starter file**: ```powershell Copy-Item days/day-1/index-starter.ts src/index.ts ``` 2. **Open** `exercises/day-1-basics.md` and follow Step 2B 3. **Build and test**: ```powershell npm run build npm start ``` ### Minutes 20-30: Connect to Claude Desktop 1. **Configure Claude Desktop** following Step 3 in `exercises/day-1-basics.md` 2. **Test your greeting tool** in Claude Desktop 3. **See the magic happen** - you just built your first MCP tool! 🎉 ## 🔧 Connect to Claude Desktop (Essential Step) ### Windows Configuration 1. **Find the config file**: `%APPDATA%\Claude\claude_desktop_config.json` - If the file doesn't exist, create it - If the folder doesn't exist, run Claude Desktop once first 2. **Add your server configuration**: ```json { "mcpServers": { "mcp-learning-server": { "command": "node", "args": ["D:\\OneDrive\\OneDrive - Microsoft\\Documents\\Learning Projects\\MCP\\build\\index.js"] } } } ``` **Important**: Change the path to match where YOU put this project! 3. **Restart Claude Desktop completely** 4. **Look for the tools icon** 🔧 in Claude Desktop ### Mac Configuration 1. **Find the config file**: `~/Library/Application Support/Claude/claude_desktop_config.json` 2. **Follow the same JSON structure** but with Mac paths 3. **Use forward slashes** in paths: `/Users/YourName/Projects/MCP/build/index.js` ### Test Prompts for Claude Desktop Once connected, try these: - "Use the greeting tool to greet me formally as John" - "Use the calculator tool to multiply 15 by 8" - "Generate 3 random passwords with length 12" - "What resources are available?" - "Read the project information resource" - "Use the code-review prompt for TypeScript code focusing on performance" - "Generate a writing-helper prompt for professional email to executives" ## 🎓 Learning Path (Your 7-Day Journey) > 💡 **Pro Tip**: Each day builds on the previous day. Don't skip ahead! ### Day 1: Basics (Start Here!) ⭐ - [ ] **Follow** `exercises/day-1-basics.md` step-by-step - [ ] **Build your first greeting tool** - Simple but functional - [ ] **Connect to Claude Desktop** - See your tool in action - [ ] **Try bonus challenges** - Time-based greetings, multi-language support **What You'll Learn**: MCP server structure, basic tool creation, Claude Desktop integration ### Day 2: Advanced Tools - [ ] **Follow** `exercises/day-2-advanced-tools.md` for complete guide - [ ] **Create 3 custom tools** - Calculator, text analyzer, random generator - [ ] **Master input validation** - Learn advanced Zod patterns - [ ] **Implement error handling** - Graceful failures and user feedback **What You'll Learn**: Complex tools, input validation, professional error handling ### Day 3: Resources ⭐ - [ ] **Follow** `exercises/day-3-resources.md` for complete guide - [ ] **Create dynamic resources** - File-like data for Claude - [ ] **Add static documentation** - Help content and guides - [ ] **Test resource access** - Interactive resource testing **What You'll Learn**: Resource architecture, URI schemes, content types, Claude integration ### Day 4: Prompts ⭐ - [ ] **Follow** `exercises/day-4-prompts.md` for complete guide - [ ] **Create 5 smart prompt templates** - Code review, writing helper, meeting summary, learning tutor, project planner - [ ] **Master dynamic content generation** - Context-aware prompt customization - [ ] **Implement management tools** - Prompt organization and preview systems **What You'll Learn**: Prompt architecture, template design, context-aware assistance, structured AI frameworks ### Day 5: Integration (Coming Soon) - [ ] **Connect to external APIs** - Real-world data integration - [ ] **Add environment configuration** - Secure API key management - [ ] **Implement caching** - Performance optimization ### Day 6: Best Practices (Coming Soon) - [ ] **Add comprehensive logging** - Production-ready logging - [ ] **Implement rate limiting** - Prevent abuse - [ ] **Write unit tests** - Quality assurance ### Day 7: Advanced Features (Coming Soon) - [ ] **Create complex workflows** - Multi-step tool interactions - [ ] **Add performance monitoring** - Health checks and metrics - [ ] **Deploy and test** - Production deployment ## 🚀 Daily Quick Start Routine **Each morning, run these commands:** ```powershell # 1. Open the day's exercise file code exercises/day-X-[topic].md # 2. Copy the day's starter file (replace X with day number) Copy-Item days/day-X/index-starter.ts src/index.ts # 3. Build and test npm run build && npm start # 4. Follow the step-by-step instructions! ``` ## 📚 Key Files to Know (Your Learning Roadmap) > 🎯 **New to MCP?** Read `docs/learning-journey-guide.md` first to understand how all these files work together! | File/Folder | Purpose | When to Use | |-------------|---------|-------------| | `days/day-X/` | **Day-by-day lesson files** | Copy starter files, reference complete solutions | | `src/index.ts` | **Your working file** | Edit this TypeScript file daily | | `build/index.js` | **Compiled output** | Generated automatically, Node.js runs this | | `exercises/day-X-[topic].md` | **Step-by-step learning** | Daily hands-on practice guides | | `docs/best-practices.md` | **Professional reference** | Understanding WHY & production patterns | | `docs/typescript-javascript-guide.md` | **TypeScript vs JavaScript** | Understanding the build process | | `docs/learning-journey-guide.md` | **How everything fits together** | When confused about what to use when | | `package.json` | **Project configuration** | Adding dependencies, scripts | ## 🛠️ What You'll Build (Your MCP Tools Portfolio) ### Day 1: Greeting Tool ⭐ **Your first MCP tool - simple but powerful!** - Personalized greetings with different styles (formal, casual, enthusiastic) - Input validation for names and greeting types - **Bonus**: Time-aware greetings, multi-language support, mood detection ### Day 2: Professional Tool Suite 💼 **Three production-ready tools working together!** - **Calculator Tool**: All arithmetic operations with advanced math functions - **Text Analyzer Tool**: Word count, sentiment analysis, text transformations - **Random Generator Tool**: Passwords, UUIDs, numbers with custom ranges - **Bonus**: Tool chaining, batch operations, export capabilities ### Day 3: Dynamic Resources 📁 **File-like data that Claude can read and process** - Project documentation that updates automatically - Configuration files that tools can reference - Dynamic content generation based on user preferences - User progress tracking and analytics - **Bonus**: Resource analytics, configuration management, code examples library ### Day 4: Smart Prompts 🧠 **Pre-written templates that make Claude more effective** - Code review frameworks with language-specific analysis - Context-aware writing assistance for different audiences - Meeting summary templates for various meeting types - Adaptive learning prompts based on skill level and style - Project planning frameworks for different contexts - **Bonus**: Template systems, prompt history, smart suggestions ### Day 5: API Integration 🌐 **Connect to real-world data sources** - Weather information tools - News and content aggregation - Database connections and queries ## 📋 Troubleshooting (When Things Go Wrong) ### ❌ "Node is not recognized as a command" **Problem**: Node.js isn't installed or not in PATH **Solution**: 1. Download Node.js from [nodejs.org](https://nodejs.org/) 2. Install with default settings 3. Restart your terminal/VS Code 4. Test with `node --version` ### ❌ "Cannot find module 'build/index.js'" **Problem**: Project hasn't been built yet **Solution**: ```powershell npm run build ``` ### ❌ Claude Desktop doesn't show tools **Problem**: Configuration file issues **Solution**: 1. Check the file path in `claude_desktop_config.json` is correct 2. Ensure the path uses YOUR actual project location 3. Restart Claude Desktop completely 4. Verify no JSON syntax errors (use a JSON validator) ### ❌ TypeScript errors in VS Code **Problem**: TypeScript configuration or dependencies **Solution**: ```powershell # Reinstall dependencies npm install # Check TypeScript compilation npm run build # Verify tsconfig.json exists and is valid ``` ### ❌ Permission denied errors **Problem**: File permissions on Windows/Mac **Solution**: - Run VS Code as administrator (Windows) - Use `sudo` for install commands (Mac/Linux) - Check folder permissions ## � Essential Resources & Documentation ### Official MCP Documentation - [MCP Specification](https://modelcontextprotocol.io/) - The official protocol docs - [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Code examples and API - [Python SDK](https://github.com/modelcontextprotocol/python-sdk) - If you prefer Python ### This Project's Learning Materials - `docs/best-practices.md` - Production guidelines and patterns - `docs/typescript-javascript-guide.md` - Understanding the build process - `docs/learning-journey-guide.md` - How all the files work together - `examples/weather-server.md` - Real API integration example ### VS Code Extensions (Recommended) Install these for better development experience: - **TypeScript and JavaScript Language Features** (built-in) - **MCP Tools** (if available in marketplace) - **Error Lens** - Shows errors inline - **Prettier** - Code formatting - **GitLens** - Git integration ## � What's Next After This Project? ### Immediate Next Steps 1. **Build something for your workflow** - Create tools you'll actually use 2. **Explore Copilot Studio integration** - Check `docs/copilot-studio-integration.md` 3. **Join the MCP community** - Share your tools and learn from others ### Advanced Learning Paths - **Production Deployment**: Learn to deploy MCP servers to cloud platforms - **Advanced Integrations**: Connect to databases, APIs, and enterprise systems - **Custom Protocols**: Extend MCP for specialized use cases - **Performance Optimization**: Scale your MCP servers for high-volume usage ### Real-World Applications - **Development Tools**: Code analysis, testing automation, deployment helpers - **Business Automation**: Report generation, data analysis, workflow optimization - **Content Creation**: Writing assistance, research tools, content management - **Personal Productivity**: Task management, note organization, learning aids ## 💡 Learning Tips for Success ### Before You Start Each Day - ✅ Read the day's README file first (`days/day-X/README.md`) - ✅ Have the step-by-step guide open (`exercises/day-X-[topic].md`) - ✅ Start with a fresh coffee ☕ (optional but recommended!) ### During Development - 🔄 **Build often**: Run `npm run build` after each change - 🧪 **Test immediately**: Use `npm start` to verify your server works - 📝 **Read error messages**: They usually tell you exactly what's wrong - 🤔 **Experiment freely**: Copy code, modify it, see what happens ### When Stuck - 📖 Check the complete example file (`days/day-X/index-complete.ts`) - 🔍 Read the troubleshooting section above - 🎯 Start with the simplest version, then add complexity - 💬 Ask questions in MCP community forums ### Building Good Habits - 📁 **Organize your code**: Use clear variable names and comments - ⚡ **Version control**: Commit your work frequently with Git - 📚 **Document as you go**: Write notes about what you learn - 🔄 **Review and refactor**: Make your code better over time ## 🎉 Welcome to MCP Development! You're about to embark on an exciting journey into the world of Model Context Protocol development. This isn't just about learning a new technology - you're gaining skills that will help you build AI-powered tools that can transform how you and others work. ### What Makes This Special - **Hands-on Learning**: You'll build real tools, not just read about them - **Progressive Complexity**: Each day builds naturally on the previous day - **Practical Focus**: Everything you build has real-world applications - **Community Driven**: Join a growing ecosystem of MCP developers ### Your Success Metrics By the end of this project, you'll be able to: - ✅ Build MCP servers from scratch - ✅ Create tools that Claude Desktop can use - ✅ Handle complex input validation and error scenarios - ✅ Integrate with external APIs and data sources - ✅ Deploy and maintain production MCP servers - ✅ Understand when and why to use different MCP patterns **Ready to begin?** Open `exercises/day-1-basics.md` and start your Day 1 journey! 🚀 --- *Happy learning! The future of AI-assisted development starts with understanding how to build the bridges between humans, AI, and the tools we use every day.*