Create comprehensive .github/copilot-instructions.md with validated setup and troubleshooting guide

.github/copilot-instructions.md

@@ -0,0 +1,211 @@
+# GitHub Copilot Masterclass Repository
+
+Always reference these instructions first before searching or running bash commands. Only fallback to additional exploration when the information here is incomplete or conflicts with what you observe.
+
+## Working Effectively
+
+**CRITICAL**: Always follow these exact setup steps in order. All commands and timings have been validated.
+
+### Python Environment Setup
+- Use Python 3.12+ (available in environment)
+- Use pip3 for package management
+- All installations use user directory (--user flag automatic due to permissions)
+
+### Bootstrap the Flask Chat Application
+```bash
+cd /path/to/repo/chat-sample
+pip3 install -r requirements.txt
+```
+**TIMING**: Installation takes ~10 seconds. NEVER CANCEL - set timeout to 30+ seconds.
+
+### Bootstrap the MCP Server
+```bash
+cd /path/to/repo/chat-sample/steve-mcp
+pip3 install -e .
+```
+**TIMING**: Installation takes ~8 seconds. NEVER CANCEL - set timeout to 30+ seconds.
+
+### Environment Configuration
+**CRITICAL**: Both applications require Azure OpenAI credentials to function fully.
+
+#### Flask App Environment Setup:
+```bash
+cd /path/to/repo/chat-sample
+cp .env.sample .env
+# Edit .env with these EXACT variable names:
+AZURE_OPENAI_API_KEY="your-api-key"
+AZURE_OPENAI_ENDPOINT="https://your-resource-name.openai.azure.com"
+AZURE_OPENAI_DEPLOYMENT="gpt-4o"
+```
+
+#### MCP Server Environment Setup:
+```bash
+cd /path/to/repo/chat-sample/steve-mcp
+# Create .env file with these EXACT variable names:
+AZURE_OPENAI_API_KEY="your-api-key"
+AZURE_OPENAI_ENDPOINT="https://your-resource-name.openai.azure.com"
+AZURE_OPENAI_API_VERSION="2024-04-01-preview"
+AZURE_OPENAI_DEPLOYMENT="gpt-4o"
+```
+
+**WARNING**: The `.env.sample` file uses incorrect variable names (`AZURE_OPENAI_GPT4O_*`). Always use the exact names shown above.
+
+### Run the Applications
+
+#### Start Flask Chat Application:
+```bash
+cd /path/to/repo/chat-sample
+python3 app.py
+```
+- **TIMING**: Starts in ~2 seconds. NEVER CANCEL.
+- **Access**: Application runs on http://127.0.0.1:5001
+- **Behavior**: Serves homepage even without valid credentials
+- **Error Handling**: Returns graceful error message for chat without credentials
+
+#### Start MCP Server:
+```bash
+cd /path/to/repo/chat-sample/steve-mcp
+python3 steve-mcp.py
+```
+- **TIMING**: Starts in ~1 second. NEVER CANCEL.
+- **Transport**: Uses stdio (Standard Input/Output)
+- **Behavior**: Starts without errors even without valid credentials
+
+**CRITICAL**: DO NOT use `python3 main.py` for MCP server - it has import errors. Always use `python3 steve-mcp.py`.
+
+## Validation and Testing
+
+### Manual Validation Steps
+Always run these validation steps after making changes:
+
+1. **Test Flask App Startup and Homepage**:
+   ```bash
+   # In background or separate terminal
+   cd /path/to/repo/chat-sample && python3 app.py &
+   # Test homepage loads
+   curl -s http://127.0.0.1:5001/ | head -5
+   # Test chat endpoint (expect graceful error without credentials)
+   curl -X POST http://127.0.0.1:5001/chat -H "Content-Type: application/json" -d '{"message": "test", "stream": false}'
+   ```
+
+2. **Test MCP Server Startup**:
+   ```bash
+   cd /path/to/repo/chat-sample/steve-mcp
+   timeout 5s python3 steve-mcp.py
+   # Should start without errors and exit after timeout
+   ```
+
+3. **Test Dependencies Installation**:
+   ```bash
+   # Test Flask dependencies
+   cd /path/to/repo/chat-sample && pip3 install -r requirements.txt
+   # Test MCP dependencies  
+   cd /path/to/repo/chat-sample/steve-mcp && pip3 install -e .
+   ```
+
+### Linting and Code Quality
+```bash
+# Install flake8 if not available
+pip3 install flake8
+
+# Lint Flask application
+cd /path/to/repo/chat-sample
+~/.local/bin/flake8 app.py --max-line-length=120
+
+# Lint MCP server
+cd /path/to/repo/chat-sample/steve-mcp
+~/.local/bin/flake8 steve-mcp.py --max-line-length=120
+```
+**TIMING**: Linting takes ~1-2 seconds per file. NEVER CANCEL.
+
+## Repository Structure and Key Files
+
+### Root Directory
+```
+/repo-root/
+├── .gitignore
+├── README.md              # Workshop overview and setup
+├── chat.png              # Reference image for UI
+├── chat-sample/          # Main Flask application
+├── docs/                 # Workshop documentation
+└── media/                # Images and assets
+```
+
+### Flask Application (`/chat-sample/`)
+```
+/chat-sample/
+├── app.py                # Main Flask application (port 5001)
+├── requirements.txt      # Flask dependencies
+├── .env.sample          # Environment variable template (WRONG NAMES)
+├── templates/
+│   └── index.html       # Chat interface with themes and reactions
+├── static/
+│   ├── steve.png        # Steve Jobs avatar
+│   └── user.png         # User avatar
+└── steve-mcp/          # MCP server subdirectory
+```
+
+### MCP Server (`/chat-sample/steve-mcp/`)
+```
+/steve-mcp/
+├── steve-mcp.py         # Main MCP server (USE THIS)
+├── main.py             # Broken entry point (DO NOT USE)
+├── pyproject.toml      # Dependencies and project config
+├── README.md           # MCP server documentation
+└── uv.lock            # UV package manager lock file
+```
+
+## Common Tasks and Troubleshooting
+
+### Environment Variable Issues
+- **Problem**: Chat returns "trouble connecting" error
+- **Solution**: Verify `.env` file exists with correct variable names (not GPT4O variants)
+- **Validation**: Check `os.getenv()` calls in app.py and steve-mcp.py match your .env
+
+### Port Conflicts
+- **Problem**: "Address already in use" on port 5001
+- **Solution**: `pkill -f "python3 app.py"` then restart
+- **Prevention**: Always stop previous Flask instances before starting new ones
+
+### MCP Server Won't Start
+- **Problem**: AttributeError about missing 'main' function
+- **Solution**: Use `python3 steve-mcp.py` NOT `python3 main.py`
+- **Explanation**: main.py has import issues, steve-mcp.py is the correct entry point
+
+### Dependency Installation Fails
+- **Problem**: Permission errors during pip install
+- **Solution**: Commands automatically use --user flag due to environment setup
+- **Validation**: Check packages install to ~/.local/lib/python3.12/site-packages
+
+## Workshop Components
+
+### Documentation Files
+- `docs/01-explore-github-copilot.md`: Copilot features and setup
+- `docs/02-application-setup.md`: Flask app building guide
+- `docs/03-creating-mcp-server.md`: MCP server creation guide
+- `docs/copilot-instructions.md`: Existing project-specific guidance
+
+### Key Features
+- **Flask App**: Chat interface with Steve Jobs AI, multiple themes, reaction system
+- **MCP Server**: Product management tools in Steve Jobs style for GitHub Copilot
+- **Azure OpenAI Integration**: GPT-4o model with streaming support
+- **FastMCP Framework**: Modern MCP server implementation
+
+## Development Workflow
+
+1. **Always run bootstrap steps first** (dependencies installation)
+2. **Always create proper .env files** with correct variable names
+3. **Always validate applications start correctly** after changes
+4. **Always run linting** before committing changes
+5. **Always test both Flask app and MCP server** after modifications
+6. **NEVER use main.py for MCP server** - it's broken
+
+## Performance Expectations
+
+- **Total setup time**: Under 20 seconds for both applications
+- **Flask app ready**: ~2 seconds after `python3 app.py`
+- **MCP server ready**: ~1 second after `python3 steve-mcp.py`
+- **No long builds or complex compilation required**
+- **All operations complete quickly** - extended timeouts not needed except for safety
+
+This repository is designed for rapid development and teaching GitHub Copilot concepts. The setup is intentionally simple and fast.

.gitignore

@@ -14,10 +14,10 @@ ENV/
 # VSCODE Configuration Files
 .vscode
 
-# Copilot Instructions
-.github/copilot-instructions.md
+# Copilot Instructions - commented out to allow committing our instructions
+# .github/copilot-instructions.md
 
 # Weather MCP Server App
 weather/
 
-.DS_S
+.DS_S*.egg-info/

chat-sample/steve-mcp/steve_mcp.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: steve-mcp
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: openai>=1.75.0
+
+# Steve Jobs MCP Server
+
+A Model Context Protocol (MCP) server that embodies Steve Jobs as a product manager persona to help users brainstorm revolutionary product features and generate clear specifications for GitHub Copilot to implement.
+
+## Features
+
+This MCP server provides:
+
+1. **Tools**:
+   - `generate_feature_idea`: Creates a visionary product feature idea for a specific user persona
+   - `generate_feature_spec`: Generates a detailed specification for a feature, suitable for GitHub Copilot development
+
+2. **Prompts**:
+   - `ask_steve_to_invent`: Simulates Steve Jobs' thinking to invent a feature and create a spec for a specific type of user
+
+## Setup
+
+### Prerequisites
+
+- Python 3.12 or higher
+- An Azure OpenAI API key and endpoint with access to GPT-4o
+
+### Installation
+
+1. Clone this repository
+2. Create a virtual environment (optional but recommended):
+   ```
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+3. Install dependencies:
+   ```
+   pip install -e .
+   ```
+
+### Configuration
+
+1. Copy the `.env.template` file to `.env`
+2. Edit the `.env` file with your Azure OpenAI credentials:
+   ```
+   AZURE_OPENAI_API_KEY=your-api-key
+   AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
+   AZURE_OPENAI_API_VERSION=2024-04-01-preview
+   AZURE_OPENAI_DEPLOYMENT=your-gpt4o-deployment-name
+   ```
+
+## Usage
+
+### Running the Server
+
+Execute the server:
+```
+python main.py
+```
+
+The server uses stdio for communication, making it compatible with MCP clients like Claude Desktop, VS Code GitHub Copilot, and others.
+
+### Connecting from VS Code GitHub Copilot
+
+1. Install the GitHub Copilot extension in VS Code
+2. Add the following configuration to your `.vscode/settings.json`:
+   ```json
+   {
+     "github.copilot.chat.mcp": {
+       "servers": [
+         {
+           "name": "Steve Jobs",
+           "path": "python",
+           "args": ["path/to/steve-mcp.py"]
+         }
+       ]
+     }
+   }
+   ```
+
+### Connecting from Claude Desktop
+
+1. Open Claude Desktop settings
+2. Navigate to the "Tools" section
+3. Add a new tool with the path to the `steve-mcp.py` script
+
+## Example Interactions
+
+### Generate Feature Idea
+
+Ask the MCP server to generate a feature idea for designers:
+
+```
+User: Can you help me brainstorm a feature for designers?
+Steve: Let me generate a feature idea for designers...
+
+# Smart Layout Snap
+
+A revolutionary design tool that intelligently anticipates designer intent, automatically suggesting optimal layout arrangements while preserving creative freedom. This isn't just alignment guides—it's a design partner that learns from your style and helps you achieve pixel-perfect layouts in half the time.
+```
+
+### Generate Feature Specification
+
+Ask the MCP server to create a detailed specification for a feature:
+
+```
+User: Can you create a spec for a "Smart Layout Snap" feature?
+Steve: Here's a specification for Smart Layout Snap...
+
+# Smart Layout Snap - Feature Specification
+
+## Problem
+Designers waste countless hours manually aligning elements and ensuring consistent spacing across their designs, reducing creative time and increasing frustration.
+
+## Solution
+Smart Layout Snap uses machine learning to understand design patterns and intent, automatically suggesting optimal alignment and spacing while adapting to the designer's personal style and project requirements.
+
+## Design Principles
+- Design should feel magical, not mechanical
+- Preserve creative freedom at all costs
+- Learn from user behavior without requiring explicit training
+- Focus on the 80% case to keep the interface simple
+- Performance must be instantaneous
+
+## Implementation Notes for GitHub Copilot
+- Implement a prediction engine using a combination of rule-based heuristics and ML model
+- Store design patterns as vector embeddings for fast similarity matching
+- Use subtle visual cues that appear and disappear smoothly
+- Include an override mechanism with a simple modifier key
+- Create an adaptive learning system that improves with designer usage
+```
+
+### Using the Prompt
+
+Use the `ask_steve_to_invent` prompt to have Steve generate both an idea and spec for a specific user type:
+
+```
+User: /ask_steve_to_invent user_type="mobile developers"
+Steve: [Responds with a complete feature idea and specification targeted at mobile developers]
+```
+
+## Development
+
+### Adding New Tools
+
+To add new tools to the server, add new functions decorated with `@app.register_tool()` in `steve-mcp.py`.
+
+### Modifying Prompts
+
+To modify or add prompts, update the `list_prompts()` and `get_prompt()` functions in `steve-mcp.py`.
+
+## License
+
+MIT

chat-sample/steve-mcp/steve_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+main.py
+pyproject.toml
+steve_mcp.egg-info/PKG-INFO
+steve_mcp.egg-info/SOURCES.txt
+steve_mcp.egg-info/dependency_links.txt
+steve_mcp.egg-info/requires.txt
+steve_mcp.egg-info/top_level.txt

chat-sample/steve-mcp/steve_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+