mcp-mac

# MCP-MAC LESSONS LEARNED - ACTIVE **Created**: September 10, 2025 **Last Updated**: September 20, 2025 (16:53) **Purpose**: Current/active lessons for ongoing development --- ## **APPLESCRIPT INTEGRATION LESSONS** ### **🔴 CRITICAL: AppleScript vs UI Verification Required** - **Issue**: AppleScript object models don't match UI terminology/scope, raw output includes system artifacts - **Examples**: Contacts "people" (100) vs "cards" (99), Finder ".localized" suffixes, directory path formatting - **Impact**: Tools return data users can't verify in application UI - **Prevention Checklist**: - [ ] Set known application states before testing - [ ] Compare tool output against manual UI verification - [ ] Process output to remove system artifacts (.localized suffixes) - [ ] Test with both files and directories for path processing - **When to Apply**: Every new tool implementation, all AppleScript queries ### **🟡 Application Integration Complexity Spectrum** - **Pattern**: Applications have varying levels of AppleScript integration quality - **Clean Integration**: Mail (real-time, no caching, matches UI perfectly) - **Complex Integration**: Contacts/Finder (terminology mismatches, system artifacts) - **Lesson**: Adjust development approach based on application complexity - **Prevention Checklist**: - [ ] Test integration quality early in development - [ ] Adapt strategy based on application complexity - [ ] Use simple parsing for clean integrations (Mail) - [ ] Implement complex processing for problematic apps (Contacts/Finder) - **Related**: AppleScript vs UI Verification Required ### **🟡 Path Processing Complexity** - **Issue**: AppleScript alias format differs for files vs directories - **Technical Details**: Directories end with colon creating empty array element, files don't - **Solution**: Conditional logic based on trailing colon detection - **Prevention Checklist**: - [ ] Always test path processing with both files and directories - [ ] Implement conditional logic for trailing colon detection - [ ] Verify path output matches expected format - **Related**: AppleScript vs UI Verification Required ### **🟡 Buffer Overflow Prevention** - **Issue**: "Get all properties" commands exceed Node.js stdout maxBuffer limits - **Scope**: All applications - Contacts, Mail, Notes, Safari content retrieval - **Prevention Checklist**: - [ ] Use selective property retrieval (max 5-10 properties per query) - [ ] Implement multi-line AppleScript with variable assignment for complex queries - [ ] Test with largest expected data during implementation - [ ] Avoid "get all properties" commands - **Update**: Basic contact fields don't cause overflow - strategy was overly conservative ### **🟡 Standards Verification Required** - **Issue**: Cannot assume Apple implementations follow RFC standards without verification - **Specific Example**: vCard RFC 6350 properties ≠ Apple Contacts actual properties - **Prevention Checklist**: - [ ] Test actual AppleScript properties before designing tools - [ ] Don't assume RFC compliance without verification - [ ] Use evidence-based tool design, not standards-based assumptions - [ ] Document actual vs expected property differences ### 🔴 CRITICAL: macOS Version Upgrade Impact - **Issue**: AppleScript/Apple Events APIs may change between major macOS versions - **Evidence**: Major OS upgrades often introduce naming or API changes requiring full compatibility testing - **Prevention**: Full compatibility testing after OS upgrades - **When to Apply**: After any macOS major version upgrade --- ## **TESTING & VERIFICATION LESSONS** ### **🔴 CRITICAL: Comprehensive Testing Protocol** - **Structured Sequence**: Single item → Multiple items → Fix bugs → Edge cases - **Key Rule**: Stop testing and fix immediately when raw AppleScript output doesn't match tool output - **State Management**: Confirm selection state before each test, one test per selection state - **File-Based Verification**: Use structured metadata in output files for platform-independent verification - **Prevention Checklist**: - [ ] Document expected results before running test - [ ] Compare raw AppleScript output vs tool output immediately - [ ] Use file-based verification instead of AI response interpretation - [ ] Test across different AI platforms (Q CLI vs Gemini behavior differs) ### **🟢 Tool Response Metadata for Testing Efficiency** - **Problem**: Testing required multiple platforms and manual verification (~15 minutes) - **Solution**: Append structured metadata to tool output files (STATUS/METHOD/APP/TOOL_VERSION) - **Benefit**: Immediate verification without AI dependency (~2 minutes) - **Implementation Checklist**: - [ ] Add separator line + metadata to all discovery files - [ ] Include STATUS/METHOD/APP/TOOL_VERSION in output - [ ] Use structured format for consistent parsing - **Related**: AI Platform Response Behavior Differences ### **🟡 Raw Output Development Strategy** - **Pattern**: Save raw AppleScript output to files before implementing MCP tools - **Benefits**: Protects against phantom functionality, enables safe buffer overflow testing - **Implementation Checklist**: - [ ] Use `/tmp/` files for raw data, develop parsing separately - [ ] Test with largest expected data sets first - [ ] Validate parsing logic against raw output - **When to Apply**: Any tools accessing large data sets (Photos, Mail, full contact properties) - **Related**: Buffer Overflow Prevention --- ## **MCP SERVER & SESSION LESSONS** ### **🔴 CRITICAL: MCP Server Session Caching** - **Issue**: MCP servers cached by Node.js module system, persist until Q CLI restart - **Impact**: Code changes don't take effect until fresh Q CLI session, even after rebuilding - **Evidence**: Enhanced functionality persisted despite not existing in source code - **Session Isolation**: Tools implemented in one session may not be immediately available - **Solution Checklist**: - [ ] Restart Q CLI sessions when testing MCP server changes - [ ] Use fresh sessions for validating actual vs expected behavior - [ ] Verify npm run build completes before testing - [ ] Check tool count matches expected implementation ### **🟡 AI Platform Response Behavior Differences** - **Issue**: Different AI platforms handle MCP tool responses differently - **Evidence**: Q CLI AI interprets/reformats responses vs Gemini shows raw responses - **Impact**: Testing verification depends on platform behavior, not just tool functionality - **Solution**: Use file-based verification instead of relying on AI response presentation --- ## **DEVELOPMENT PROCESS LESSONS** ### **🔴 CRITICAL: String Escaping in AppleScript Contexts** - **Failed Approach**: JSON.stringify() for AppleScript string preparation - **Root Cause**: JSON.stringify() adds outer quotes that break AppleScript syntax - **Correct Approach**: Internal character escaping without external quote wrapping - **Working Pattern**: Direct string embedding (contacts_get_person_info style) - **When to Apply**: All AppleScript string parameter handling - **Related**: Evidence-Based Development Violations ### **🔴 CRITICAL: Evidence-Based Development Violations** - **Pattern**: Making "should work perfectly" statements without evidence - **Governance Violation**: Contradicted "evidence-based development" requirements - **Prevention Checklist**: - [ ] No assumptions about implementation success until tested - [ ] Stop after 2 failed attempts, don't try 3+ variations - [ ] Always provide evidence for claims - [ ] Test before claiming functionality works - **Related**: String Escaping in AppleScript Contexts, Governance Violation Despite Strong Documentation ### **🟡 Creation Tool Implementation Patterns** - **Working Pattern**: Direct string embedding (contacts tools) - **Failed Pattern**: JSON.stringify() approach (mail creation) - **Date Handling**: AppleScript requires specific date construction, not string parsing - **Validation**: Core functionality can work even with parameter parsing issues - **Related**: String Escaping in AppleScript Contexts --- ## **GOVERNANCE & DOCUMENTATION LESSONS** ### **🔴 CRITICAL: Governance Violation Despite Strong Documentation** - **Pattern**: Added functionality (timestamp) without explicit permission despite clear governance - **Root Cause**: Failure to follow existing rules, not missing governance - **Evidence**: Existing governance already prohibited this behavior - **Lesson**: Strong governance documents don't prevent violations - adherence discipline required - **Prevention**: Always check governance before adding ANY functionality ### **🔴 CRITICAL: Documentation Accuracy Crisis Pattern** - **Issue**: SESSION-CONTEXT.md severely outdated despite recent updates - **Reality**: Project 17+ tools ahead of documented status, 3 versions behind - **Root Cause**: Documentation not updated during chat disruptions - **Prevention Checklist**: - [ ] Always verify source code vs documented claims - [ ] Check package versions independently - [ ] Update documentation during disruptions - [ ] Never trust session context without verification --- ## **HISTORICAL FAILURE PATTERNS** ### **Foundation Lessons (Pre-Iteration)** #### **Test Framework Catastrophic Failure** - **Pattern**: Creating test infrastructure that tests wrong things (console output vs actual functionality) - **Prevention**: Verify test framework tests actual functionality, not console output #### **Systematic Fix Misapplication** - **Pattern**: Applying "systematic fixes" to already working code - **Prevention**: Test individual components before and after changes #### **Validator Redundancy** - **Pattern**: Creating duplicate functionality without realizing it exists - **Prevention**: Check existing code before implementing new functionality #### **Terminology Inconsistency** - **Pattern**: Incomplete find/replace operations leaving mixed terminology - **Prevention**: Comprehensive search for all references before claiming completion #### **Coverage Claim Discrepancies** - **Pattern**: Multiple conflicting numbers for same metric - **Prevention**: Single source of truth for all metrics --- ## **SEVERITY LEGEND** - **🔴 CRITICAL**: Prevents project-stopping failures, must follow always - **🟡 IMPORTANT**: Significant impact on development efficiency - **🟢 HELPFUL**: Process improvements and optimizations *Lessons organized by category with cross-references and actionable checklists for AI implementation.*