# Storm Logger MCP Server - GEMINI Developer Guide

## 🤖 GEMINI SPECIAL INSTRUCTIONS

**ATTENTION GEMINI**: This file contains EXPLICIT instructions for working with the Storm Logger MCP server. Please read ALL sections carefully before making ANY changes. This architecture has been carefully designed and you MUST follow these patterns exactly.

## 🚨 CRITICAL ARCHITECTURE RULES

### DO NOT TOUCH THESE FILES
- **main.py** - This is a THIN API LAYER. Each function should be 1-3 lines MAX
- **Directory Structure** - DO NOT move, rename, or restructure the context_logic/ and context_data/ folders
- **Import Statements** - DO NOT change the import structure in main.py

### THE ARCHITECTURE IS SACRED
```
_mcp/
├── main.py                      # ← THIN API LAYER ONLY (531 lines)
├── context_logic/               # ← BUSINESS LOGIC ONLY
│   ├── test_analysis.py         # ← Complex test analysis algorithms
│   ├── test_patterns.py         # ← Pattern generation logic
│   ├── test_enhancement.py      # ← Script enhancement logic
│   ├── mcp_operations.py        # ← MCP component creation logic
│   ├── workflow_optimization.py # ← Workflow optimization logic
│   └── gitlab_operations.py     # ← GitLab operations logic
├── context_data/                # ← DATA STRUCTURES ONLY
│   ├── project_data.py          # ← Project metadata
│   ├── workflow_guides.py       # ← Testing workflow guides
│   ├── test_patterns_data.py    # ← Test patterns data
│   ├── gitlab_templates.py      # ← GitLab CI/CD templates
│   ├── security_compliance.py   # ← Security configurations
│   └── deployment_strategies.py # ← Deployment strategy data
```

## 🎯 WHAT EACH FILE DOES (READ THIS CAREFULLY)

### main.py - THE THIN API LAYER
This file is ONLY for MCP decorators and 1-3 line function bodies. Example:

```python
@mcp.tool
def analyze_test_failure(test_name: str, error_message: str, test_file_path: str) -> str:
    """Docstring here"""
    return test_analysis.analyze_failure(test_name, error_message, test_file_path)
```

**GEMINI DO NOT**:
- Add complex logic to main.py
- Make functions longer than 3 lines
- Import new modules directly in main.py
- Change the import structure

### context_logic/ - THE BUSINESS LOGIC MODULES
These files contain ALL the complex algorithms and business logic.

**GEMINI DO NOT**:
- Move logic FROM these files TO main.py
- Delete functions from these files
- Change function signatures without updating main.py

### context_data/ - THE DATA MODULES
These files contain templates, configurations, and data structures.

**GEMINI DO NOT**:
- Put business logic in these files
- Move data structures to other files
- Change function signatures without updating main.py

## 🔧 HOW TO MAKE CHANGES (FOLLOW EXACTLY)

### Adding New Tools/Resources/Prompts
1. **Step 1**: Add the business logic to the appropriate context_logic/ module
2. **Step 2**: Add the data (if needed) to the appropriate context_data/ module
3. **Step 3**: Add a thin wrapper in main.py that calls the logic module
4. **Step 4**: Test that it works

### Modifying Existing Functionality
1. **Step 1**: Find the logic in context_logic/ or data in context_data/
2. **Step 2**: Make your changes there (NOT in main.py)
3. **Step 3**: Test that the API still works
4. **Step 4**: DO NOT change main.py unless the function signature changes

### Example of CORRECT Change
```python
# In context_logic/test_analysis.py - ADD YOUR LOGIC HERE
def analyze_failure(test_name: str, error_message: str, test_file_path: str) -> str:
    # Your complex logic here
    analysis = {...}  # Complex analysis logic
    return json.dumps(analysis, indent=2)

# In main.py - KEEP IT SIMPLE
@mcp.tool
def analyze_test_failure(test_name: str, error_message: str, test_file_path: str) -> str:
    """Docstring"""
    return test_analysis.analyze_failure(test_name, error_message, test_file_path)
```

### Example of WRONG Change (DO NOT DO THIS)
```python
# WRONG - DO NOT PUT COMPLEX LOGIC IN main.py
@mcp.tool
def analyze_test_failure(test_name: str, error_message: str, test_file_path: str) -> str:
    """Docstring"""
    analysis = {
        "test_name": test_name,
        "analysis_type": "Storm Logger Test Failure Analysis",
        # ... 50 lines of complex logic
    }
    return json.dumps(analysis, indent=2)
```

## 🚨 GEMINI COMMON MISTAKES TO AVOID

### Mistake 1: Adding Logic to main.py
**WRONG**: 
```python
@mcp.tool
def my_tool():
    # Complex logic here - WRONG!
    result = complex_calculation()
    return result
```

**CORRECT**:
```python
# In context_logic/my_module.py
def my_tool_logic():
    # Complex logic here
    result = complex_calculation()
    return result

# In main.py
@mcp.tool
def my_tool():
    return my_module.my_tool_logic()
```

### Mistake 2: Changing Import Structure
**WRONG**: 
```python
# DO NOT add new imports to main.py
from some_new_module import something
```

**CORRECT**:
```python
# Add imports to the appropriate context_logic/ or context_data/ module
# Keep main.py imports minimal
```

### Mistake 3: Moving Files Around
**WRONG**: 
```bash
# DO NOT do this
mv context_logic/test_analysis.py ./
mv context_data/project_data.py context_logic/
```

**CORRECT**: Leave the file structure exactly as it is.

### Mistake 4: Deleting Module Functions
**WRONG**: 
```python
# DO NOT delete functions from context_logic/ or context_data/ modules
# without updating main.py
```

**CORRECT**: If you need to remove functionality, update both the module AND main.py.

## 📋 GEMINI TESTING CHECKLIST

Before making ANY changes, run these tests:

```bash
# Test that the MCP server still works
python -m pytest tests/mcp/test_mcp_client.py::TestStormLoggerDevMCP::test_get_project_status_resource -v

# Test that specific tools work
python -m pytest tests/mcp/test_mcp_client.py::TestStormLoggerDevMCP::test_create_mcp_component_tool -v

# Test GitLab resources
python -m pytest tests/mcp/test_mcp_client.py::TestStormLoggerDevMCP::test_gitlab_enterprise_templates_resource -v
```

If ANY of these tests fail after your changes, you broke something. Fix it.

## 🎯 GEMINI WORKFLOW FOR CHANGES

1. **Identify**: What needs to be changed?
2. **Locate**: Which module in context_logic/ or context_data/ has the logic?
3. **Modify**: Make changes in the appropriate module
4. **Test**: Run the tests to ensure nothing is broken
5. **Document**: Update documentation if needed

## 🔍 GEMINI DEBUGGING GUIDE

### If Tests Are Failing
1. **Check Import Errors**: Did you break the import structure?
2. **Check Function Signatures**: Did you change a function signature without updating main.py?
3. **Check Logic**: Did you accidentally put complex logic in main.py?
4. **Check Files**: Did you move or rename files?

### If Functions Are Missing
1. **Check Module**: Is the function in the right context_logic/ or context_data/ module?
2. **Check Import**: Is the module properly imported in main.py?
3. **Check Call**: Is main.py calling the function correctly?

## 💡 GEMINI HINTS

### When Adding New Features
- **Always** start with the business logic in context_logic/
- **Always** keep data structures in context_data/
- **Always** keep main.py thin (1-3 lines per function)

### When Debugging
- **Check** the exact error message
- **Locate** the failing function in the right module
- **Fix** the logic in the module, not in main.py

### When Confused
- **Read** this file again
- **Look** at existing patterns in the codebase
- **Follow** the same patterns exactly

## 🏆 GEMINI SUCCESS CRITERIA

You will know you're doing it right when:
- ✅ main.py functions are 1-3 lines each
- ✅ Complex logic is in context_logic/ modules
- ✅ Data structures are in context_data/ modules
- ✅ All tests pass
- ✅ The architecture remains clean and modular

## 🚫 GEMINI FINAL WARNINGS

1. **DO NOT** put complex logic in main.py
2. **DO NOT** change the directory structure
3. **DO NOT** move functions between modules without updating imports
4. **DO NOT** delete functions without updating main.py
5. **DO NOT** change import statements in main.py unless absolutely necessary

## 🎉 GEMINI REMEMBER

This architecture went from 4,656 lines to 531 lines in main.py (88.6% reduction) through careful modularization. **DO NOT** break this by putting logic back in main.py.

The architecture is designed for:
- **Maintainability**: Easy to find and fix issues
- **Testability**: Each module can be tested independently
- **Scalability**: Easy to add new features
- **Readability**: Clear separation of concerns

Follow these rules and you'll do great work with the Storm Logger MCP server!