DollhouseMCP

# Portfolio Sync Fix Summary ## Date: August 26, 2025 ## PR: #764 - Fix GitHub portfolio sync error reporting ## Issues Addressed ### 1. GitHub API Response Parsing Error **Problem**: The sync_portfolio function failed with "Cannot read properties of null (reading 'commit')" for all elements. **Root Cause**: The code at `PortfolioRepoManager.ts:304` assumed GitHub's API would always return `result.commit.html_url`, but the API response structure varies. **Fix**: Added multiple fallback paths to extract URLs: ```typescript // Try multiple paths in order of preference: 1. result.commit?.html_url // Standard response 2. result.content?.html_url // Alternative structure 3. Generated URL from path // Build URL from known data 4. Fallback to repository tree // Worst case, link to folder ``` ### 2. Poor Error Reporting **Problem**: Users received cryptic error messages with no actionable guidance. **Fix**: Added specific error codes: - `PORTFOLIO_SYNC_001`: Authentication failure - `PORTFOLIO_SYNC_002`: Repository not found - `PORTFOLIO_SYNC_003`: File creation failed - `PORTFOLIO_SYNC_004`: API response parsing error - `PORTFOLIO_SYNC_005`: Network error - `PORTFOLIO_SYNC_006`: Rate limit exceeded ### 3. Tool Selection Confusion **Problem**: When users asked to upload a single element to their portfolio, the AI assistant used `sync_portfolio` (which uploads EVERYTHING) instead of `submit_content`. **Root Cause**: Misleading tool descriptions: - `submit_content` said "Submit to collection for community review" (didn't mention personal portfolio) - `sync_portfolio` didn't warn it uploads ALL elements **Fix**: Updated tool descriptions: - `submit_content`: Now clearly states it uploads a single element to personal GitHub portfolio first, then optionally to community - `sync_portfolio`: Added WARNING that it uploads ALL elements and may include private content ## Code Changes ### src/portfolio/PortfolioRepoManager.ts - Lines 304-348: Fixed commit URL extraction with fallbacks - Lines 349-386: Added enhanced error reporting with specific codes ### src/index.ts - Lines 4676-4702: Extract and display error codes in sync output - Lines 4756-4796: Provide targeted troubleshooting based on error codes ### src/server/tools/CollectionTools.ts - Line 133: Updated submit_content description to clarify single element upload ### src/server/tools/PortfolioTools.ts - Line 138: Added WARNING to sync_portfolio about bulk upload ## Testing Recommendations ### Manual Testing with Real GitHub Token 1. Create a test persona locally 2. Use `submit_content` to upload ONLY that persona 3. Verify only one element is uploaded (not everything) 4. Test with various GitHub API response formats ### Verify Error Codes 1. Test with expired token (should get PORTFOLIO_SYNC_001) 2. Test with non-existent repo (should get PORTFOLIO_SYNC_002) 3. Test during rate limit (should get PORTFOLIO_SYNC_006) ## User Impact ### Before Fix - All portfolio syncs failed with cryptic error - No guidance on how to resolve issues - Wrong tool selected for single uploads - Risk of uploading private content unintentionally ### After Fix - Robust handling of GitHub API responses - Clear error codes with actionable fixes - Proper tool selection for single vs bulk uploads - Clear warnings about privacy implications ## Next Steps 1. Test with actual GitHub portfolio operations 2. Monitor for any new GitHub API response formats 3. Consider adding a dedicated `upload_single_element` tool for even clearer UX 4. Add telemetry to track which error codes users encounter most ## Related Documentation - QA Report: `/docs/QA/QA-version-1-6-5-save-to-github-portfolio-failure.md` - Session Notes: `/docs/development/SESSION_NOTES_2025_08_26_RELEASE_FOLLOWUP.md` - PR: https://github.com/DollhouseMCP/mcp-server/pull/764