diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..68bd87f --- /dev/null +++ b/.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. \ No newline at end of file diff --git a/.gitignore b/.gitignore index e9b4cac..c549c97 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file +.DS_S*.egg-info/ diff --git a/chat-sample/steve-mcp/__pycache__/steve-mcp.cpython-312.pyc b/chat-sample/steve-mcp/__pycache__/steve-mcp.cpython-312.pyc index 3f5b388..4513d93 100644 Binary files a/chat-sample/steve-mcp/__pycache__/steve-mcp.cpython-312.pyc and b/chat-sample/steve-mcp/__pycache__/steve-mcp.cpython-312.pyc differ diff --git a/chat-sample/steve-mcp/steve_mcp.egg-info/PKG-INFO b/chat-sample/steve-mcp/steve_mcp.egg-info/PKG-INFO new file mode 100644 index 0000000..36f4f3a --- /dev/null +++ b/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 diff --git a/chat-sample/steve-mcp/steve_mcp.egg-info/SOURCES.txt b/chat-sample/steve-mcp/steve_mcp.egg-info/SOURCES.txt new file mode 100644 index 0000000..116b5d9 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/chat-sample/steve-mcp/steve_mcp.egg-info/dependency_links.txt b/chat-sample/steve-mcp/steve_mcp.egg-info/dependency_links.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/chat-sample/steve-mcp/steve_mcp.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/chat-sample/steve-mcp/steve_mcp.egg-info/requires.txt b/chat-sample/steve-mcp/steve_mcp.egg-info/requires.txt new file mode 100644 index 0000000..e19877b --- /dev/null +++ b/chat-sample/steve-mcp/steve_mcp.egg-info/requires.txt @@ -0,0 +1,3 @@ +httpx>=0.28.1 +mcp[cli]>=1.6.0 +openai>=1.75.0 diff --git a/chat-sample/steve-mcp/steve_mcp.egg-info/top_level.txt b/chat-sample/steve-mcp/steve_mcp.egg-info/top_level.txt new file mode 100644 index 0000000..ba2906d --- /dev/null +++ b/chat-sample/steve-mcp/steve_mcp.egg-info/top_level.txt @@ -0,0 +1 @@ +main