Add MCP server

Author: timothywarner

src/README.md

@@ -0,0 +1,193 @@
+# Copilot Tips MCP Server
+
+A FastMCP server providing GitHub Copilot tips and tricks via the Model Context Protocol. Built for O'Reilly teaching demonstrations.
+
+## Features
+
+- 📚 **46 curated tips** across 6 categories (Prompting, Shortcuts, Code Gen, Chat, Context, Security)
+- 🔍 **Resources** — List categories and stats
+- 🛠️ **Tools** — Search, filter, random tips, delete/reset
+- 💬 **Prompts** — Task suggestions, category exploration, learning paths
+- 🎯 **Elicitations** — Interactive guided discovery with real MCP elicitations
+- 🧪 **26 unit tests** with pytest
+
+## Quick Start
+
+### 1. Setup Environment
+
+```powershell
+# Windows (PowerShell 7+)
+cd src
+pwsh .\setup.ps1
+```
+
+```bash
+# macOS/Linux
+cd src
+chmod +x setup.sh
+./setup.sh
+```
+
+This creates a `.venv` virtual environment and installs dependencies.
+
+### 2. Run the Server
+
+```bash
+python copilot_tips_server.py
+```
+
+The server runs via stdio transport (standard MCP protocol).
+
+### 3. Test with MCP Inspector
+
+The MCP Inspector provides a web UI for testing your server interactively:
+
+```bash
+python start_inspector.py
+```
+
+This will:
+- ✅ Check for Node.js 18+ (shows version)
+- ✅ Verify the port is actually available before using it
+- ✅ Validate server script and Python executable exist
+- 🚀 Launch the inspector web UI
+- 🔗 Connect to your MCP server automatically
+
+Open the URL shown in the terminal (e.g., `http://localhost:52341`).
+
+### 4. Run Tests
+
+```bash
+pytest test_copilot_tips_server.py -v
+```
+
+All 26 tests should pass.
+
+## Using the Inspector
+
+### Testing Resources
+
+1. Click **Resources** tab
+2. Click `tips://categories` to see all tip categories
+3. Click `tips://stats` to see tip counts by category and difficulty
+
+### Testing Tools
+
+1. Click **Tools** tab
+2. Select a tool and fill in parameters:
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `get_tip_by_id` | `tip_id`: e.g., `prompt-001` | Get specific tip |
+| `get_tip_by_topic` | `search_term`: e.g., `chat` | Search tips |
+| `get_random_tip` | `category`, `difficulty` (optional) | Random tip |
+| `delete_tip` | `tip_id` | Delete tip (in-memory) |
+| `reset_tips` | (none) | Restore deleted tips |
+| `interactive_tip_finder` | (uses elicitation) | Guided tip discovery |
+| `guided_random_tip` | (uses elicitation) | Random tip with prompts |
+
+3. Click **Run** to execute
+
+**Note**: The `interactive_tip_finder` and `guided_random_tip` tools use MCP elicitations to prompt you for input. These require client support for elicitations.
+
+### Testing Prompts
+
+1. Click **Prompts** tab
+2. Select a prompt template:
+   - `tip_suggestion` — Get tips for a specific task
+   - `category_explorer` — Deep dive into a category
+   - `learning_path` — Personalized learning plan
+
+## VS Code Integration
+
+The server is pre-configured for VS Code:
+
+- **Debug**: Press `F5` and select "🚀 Run MCP Server"
+- **Tasks**: `Ctrl+Shift+P` → "Tasks: Run Task" → choose setup/run tasks
+- **MCP Client**: The `.vscode/mcp.json` configures the server for Copilot Chat
+
+### Auto-Activate Virtual Environment
+
+VS Code automatically activates the venv in new terminals. If not working:
+1. `Ctrl+Shift+P` → "Python: Select Interpreter"
+2. Choose `src/.venv/Scripts/python.exe`
+3. Reload window
+
+## Project Structure
+
+```
+src/
+├── copilot_tips_server.py      # Main FastMCP server (resources, tools, prompts)
+├── test_copilot_tips_server.py # Pytest test suite (26 tests)
+├── start_inspector.py          # Robust inspector launcher
+├── setup.ps1                   # Windows setup script (pwsh)
+├── setup.sh                    # Unix setup script
+├── pyproject.toml              # Python project config
+├── README.md                   # This file
+└── data/
+    └── copilot_tips.json       # Tips database (46 tips, 6 categories)
+```
+
+## Data Format
+
+Tips are stored in `data/copilot_tips.json`:
+
+```json
+{
+  "tips": [
+    {
+      "id": "prompt-001",
+      "title": "Provide Top-Level Comments",
+      "description": "Add a high-level comment...",
+      "category": "Prompting Techniques",
+      "difficulty": "beginner"
+    }
+  ]
+}
+```
+
+**Categories**: Prompting Techniques, IDE Shortcuts, Code Generation, Chat Features, Workspace Context, Security & Privacy
+
+**Difficulty levels**: beginner, intermediate, advanced
+
+## Troubleshooting
+
+### "Node.js/npx not found"
+Install Node.js 18+ from https://nodejs.org/ and restart your terminal. The inspector shows detailed error messages if npx isn't working.
+
+### Import errors in VS Code
+The Python extension may not detect the venv. Select the interpreter manually or reload the window.
+
+### "Port already in use"
+The inspector now verifies port availability before use. If issues persist, close other inspector instances or processes using ports in the 49152-65535 range.
+
+### Inspector exits immediately
+Check the terminal output for error details. Common issues:
+- Server script not found (verify `copilot_tips_server.py` exists)
+- Python venv not created (run `setup.ps1` or `setup.sh`)
+- Node.js version too old (need 18+)
+
+## Requirements
+
+- Python 3.10+
+- Node.js 18+ (for MCP Inspector)
+- PowerShell 7+ (Windows) or Bash (Unix)
+
+## Architecture
+
+```
+┌─────────────────┐     stdio      ┌──────────────────────┐
+│  MCP Inspector  │◄──────────────►│  copilot_tips_server │
+│  (Web UI)       │                │  (FastMCP/Python)    │
+└─────────────────┘                └──────────┬───────────┘
+                                              │
+                                              ▼
+                                   ┌──────────────────────┐
+                                   │  data/copilot_tips   │
+                                   │  .json (46 tips)     │
+                                   └──────────────────────┘
+```
+
+## License
+
+MIT

src/copilot_tips_server.py

@@ -23,15 +23,16 @@
 import json
 import random
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Literal
 from collections import Counter
+from dataclasses import dataclass
 
-from fastmcp import FastMCP
+from fastmcp import FastMCP, Context
 
 # Initialize FastMCP server
 mcp = FastMCP(
-    "Copilot Tips Server",
-    description="MCP server for GitHub Copilot tips and tricks - O'Reilly teaching example"
+    name="Copilot Tips Server",
+    instructions="MCP server for GitHub Copilot tips and tricks. Use tools to search, retrieve, and manage tips. Use resources to get categories and statistics."
 )
 
 # Load tips data
@@ -391,67 +392,143 @@ def learning_path(current_skill_level: str) -> str:
 
 
 # =============================================================================
-# ELICITATIONS (Basic examples - client support varies)
+# ELICITATIONS - Interactive tools that prompt users for input
 # =============================================================================
 
-# Note: Elicitations are a newer MCP feature with limited client support.
-# These are included as teaching examples but may fall back to prompts.
+# Dataclass for structured tip finder input
+@dataclass
+class TipFinderPreferences:
+    """User preferences for finding tips."""
+    difficulty: str
+    category: str
 
-@mcp.prompt()
-def interactive_tip_finder() -> str:
+
+@mcp.tool
+async def interactive_tip_finder(ctx: Context) -> dict:
     """
-    Interactive prompt that guides users through finding the right tip.
+    Interactively gather user preferences and find matching tips.
 
-    This serves as a fallback for elicitations where client support is limited.
+    Uses MCP elicitation to prompt the user for their experience level
+    and area of interest, then returns relevant tips.
+
+    Note: Requires client support for elicitations.
     """
-    return """Let me help you find the perfect GitHub Copilot tip!
+    # Step 1: Get difficulty preference
+    difficulty_result = await ctx.elicit(
+        message="What's your experience level with GitHub Copilot?",
+        response_type=Literal["beginner", "intermediate", "advanced"]
+    )
+
+    if difficulty_result.action != "accept":
+        return {
+            "success": False,
+            "message": "Tip finder cancelled - no difficulty selected"
+        }
 
-Please answer these questions:
+    difficulty = difficulty_result.data
+
+    # Step 2: Get category preference
+    category_result = await ctx.elicit(
+        message="Which area would you like tips for?",
+        response_type=Literal[
+            "Prompting Techniques",
+            "IDE Shortcuts",
+            "Code Generation",
+            "Chat Features",
+            "Workspace Context",
+            "Security & Privacy"
+        ]
+    )
+
+    if category_result.action != "accept":
+        return {
+            "success": False,
+            "message": "Tip finder cancelled - no category selected"
+        }
 
-1. **What's your experience level?**
-   - Beginner (just getting started)
-   - Intermediate (comfortable with basics)
-   - Advanced (looking for power-user tips)
+    category = category_result.data
 
-2. **What area are you interested in?**
-   - Prompting Techniques (writing better prompts)
-   - IDE Shortcuts (keyboard efficiency)
-   - Code Generation (getting better code output)
-   - Chat Features (using Copilot Chat effectively)
-   - Workspace Context (leveraging project context)
-   - Security & Privacy (safe Copilot usage)
+    # Step 3: Find matching tips
+    tips = get_tips_store()
+    matching = [
+        t for t in tips
+        if t["difficulty"] == difficulty and t["category"] == category
+    ]
 
-3. **What's your specific goal right now?**
-   (Describe what you're trying to accomplish)
+    if not matching:
+        # Fall back to just category match
+        matching = [t for t in tips if t["category"] == category]
 
-Once you answer, I'll search for the most relevant tips and provide personalized recommendations!"""
+    return {
+        "success": True,
+        "preferences": {
+            "difficulty": difficulty,
+            "category": category
+        },
+        "tips": matching[:5],
+        "total_matches": len(matching)
+    }
 
 
-@mcp.prompt()
-def quiz_me(category: Optional[str] = None) -> str:
+@mcp.tool
+async def guided_random_tip(ctx: Context) -> dict:
     """
-    Generate a quiz prompt to test knowledge of Copilot tips.
+    Get a random tip with optional guided filtering via elicitation.
 
-    Args:
-        category: Optional category to focus the quiz on
+    Prompts the user to optionally filter by category before
+    returning a random tip.
 
-    Returns:
-        A formatted quiz prompt.
+    Note: Requires client support for elicitations.
     """
-    category_text = f' in the "{category}" category' if category else ""
+    # Ask if user wants to filter
+    filter_result = await ctx.elicit(
+        message="Would you like to filter tips by category, or get a completely random tip?",
+        response_type=Literal["filter by category", "completely random"]
+    )
 
-    return f"""Let's test your GitHub Copilot knowledge{category_text}!
+    if filter_result.action != "accept":
+        return {
+            "success": False,
+            "message": "Cancelled"
+        }
 
-I'll ask you questions about best practices and tips. For each question:
-1. I'll describe a scenario
-2. You tell me which tip or technique would be most helpful
-3. I'll provide feedback and explain the best approach
+    tips = get_tips_store()
 
-Ready? Let's start with an easy one!
+    if filter_result.data == "filter by category":
+        # Get category preference
+        category_result = await ctx.elicit(
+            message="Select a category:",
+            response_type=Literal[
+                "Prompting Techniques",
+                "IDE Shortcuts",
+                "Code Generation",
+                "Chat Features",
+                "Workspace Context",
+                "Security & Privacy"
+            ]
+        )
+
+        if category_result.action != "accept":
+            return {
+                "success": False,
+                "message": "Category selection cancelled"
+            }
 
-**Question 1:** You're writing a new function but Copilot's suggestions don't match what you need. What's the FIRST thing you should try?
+        tips = [t for t in tips if t["category"] == category_result.data]
 
-(Answer, and I'll give you feedback and move to the next question!)"""
+        if not tips:
+            return {
+                "success": False,
+                "error": f"No tips in category '{category_result.data}'"
+            }
+
+    selected = random.choice(tips)
+
+    return {
+        "success": True,
+        "tip": selected,
+        "pool_size": len(tips)
+    }
 
 
 # =============================================================================