MCP & Copilot Studio Learning Project

# 🔄 TypeScript vs JavaScript: Complete Guide Understanding the relationship between `.ts` and `.js` files is crucial for your MCP learning journey. ## 📚 **The Simple Explanation** ### **TypeScript (.ts)** = What You Write ✍️ - **Human-friendly** code with type safety - **Modern syntax** with helpful features - **Cannot run directly** in Node.js ### **JavaScript (.js)** = What Node.js Runs 🏃‍♂️ - **Machine-readable** code - **Generated automatically** from TypeScript - **What actually executes** your server ## 🔄 **The Build Process** ``` ┌─────────────────┐ npm run build ┌─────────────────┐ │ src/index.ts │ ──────────────────> │ build/index.js │ │ │ │ │ │ Your TypeScript │ │ Node.js runs │ │ (edit this!) │ │ (don't edit!) │ └─────────────────┘ └─────────────────┘ ``` ## 📁 **File Structure in Your Project** ``` MCP/ ├── src/ ← You work here │ └── index.ts ← Edit this file ├── build/ ← Generated automatically │ └── index.js ← Node.js runs this ├── days/ │ └── day-1/ │ ├── index-starter.ts ← Copy to src/index.ts │ └── index-complete.ts ← Reference when stuck └── package.json ← Scripts and dependencies ``` ## 🎯 **Your Daily Workflow** ### **Step 1: Write TypeScript** ```bash # Edit your TypeScript source code src/index.ts ``` ### **Step 2: Build to JavaScript** ```bash # Convert TypeScript → JavaScript npm run build ``` ### **Step 3: Run JavaScript** ```bash # Node.js runs the compiled JavaScript npm start # OR node build/index.js ``` ## 💡 **Key Differences You'll See** ### **TypeScript (What You Write)** ```typescript // Type safety and modern syntax server.tool( "greeting", "Create personalized greetings", { name: z.string().describe("Name of the person to greet"), style: z.enum(["formal", "casual"]).optional(), }, async ({ name, style = "casual" }) => { // TypeScript understands types here return { content: [{ type: "text", text: `Hello ${name}!` }] }; } ); ``` ### **JavaScript (What Gets Generated)** ```javascript // Compiled, machine-readable version import { z } from "zod"; server.tool("greeting", "Create personalized greetings", { name: z.string().describe("Name of the person to greet"), style: z.enum(["formal", "casual"]).optional(), }, async ({ name, style = "casual" }) => { return { content: [{ type: "text", text: `Hello ${name}!` }] }; }); ``` ## 🛠️ **What `npm run build` Does** 1. **Reads** your TypeScript files (`src/*.ts`) 2. **Checks** for type errors 3. **Compiles** to JavaScript 4. **Outputs** to `build/` folder 5. **Creates** source maps for debugging ## ⚠️ **Important Rules** ### **✅ DO** - Edit files in `src/` folder (`.ts` files) - Run `npm run build` after making changes - Check `build/` folder exists before running server ### **❌ DON'T** - Edit files in `build/` folder (they get overwritten!) - Run `.ts` files directly with Node.js - Commit `build/` folder to git (it's generated) ## 🔧 **Troubleshooting Common Issues** ### **Error: "Cannot find module 'build/index.js'"** **Solution**: Run `npm run build` first ```bash npm run build npm start ``` ### **Error: "SyntaxError: Cannot use import statement"** **Solution**: You're trying to run TypeScript directly ```bash # Wrong: node src/index.ts # Right: npm run build node build/index.js # OR just: npm start ``` ### **Changes not taking effect** **Solution**: You forgot to build after editing ```bash # After editing src/index.ts: npm run build npm start ``` ## 🎯 **Day-by-Day File Management** ### **Day 1: Starting Fresh** ```bash # Copy clean starter cp days/day-1/index-starter.ts src/index.ts # Work on it code src/index.ts # Build and test npm run build npm start ``` ### **Day 1: Check Your Progress** ```bash # Compare with solution code days/day-1/index-complete.ts code src/index.ts ``` ### **Day 2: Building on Day 1** ```bash # Start with Day 1 complete cp days/day-1/index-complete.ts src/index.ts # Follow Day 2 exercises code exercises/day-2-tools.md ``` ## 📋 **Quick Reference Commands** | Action | Command | When to Use | |--------|---------|-------------| | **Start fresh** | `cp days/day-X/index-starter.ts src/index.ts` | Beginning a new day | | **Build** | `npm run build` | After editing TypeScript | | **Run server** | `npm start` | Testing your server | | **Compare solution** | `code days/day-X/index-complete.ts` | When stuck | | **Clean build** | `rm -rf build && npm run build` | If build seems broken | ## 🎉 **Now You Understand!** - **TypeScript** = Your coding experience (types, modern features) - **JavaScript** = What actually runs (compiled output) - **Build step** = The bridge between them - **Day folders** = Your progressive learning checkpoints Ready to start Day 1 with confidence? 🚀