DollhouseMCP

# Anonymous Persona Submission Guide ## Overview The DollhouseMCP persona collection supports both authenticated (GitHub account required) and anonymous submission workflows. Anonymous submissions provide an accessible way for users without GitHub accounts to contribute personas to the community collection. ## How Anonymous Submissions Work ### 1. Submission Detection The `PersonaSubmitter` class automatically detects whether a user is authenticated: - **Authenticated users**: Have valid GitHub credentials/tokens - **Anonymous users**: No GitHub authentication present ### 2. Response Formatting Different response formats are provided based on authentication status: #### Authenticated Users - Direct GitHub issue creation workflow - Standard submission process with immediate issue creation capability - Pull request submission option available #### Anonymous Users - Guided anonymous submission process - Multiple submission pathways provided - GitHub account required for all submissions ## Anonymous Submission Process ### Step 1: Persona Preparation The system generates a GitHub issue URL with pre-filled persona content, regardless of authentication status. ### Step 2: Submission Pathways #### Option A: GitHub Account Available If the user has or creates a GitHub account: 1. Click the generated GitHub issue URL 2. Review the pre-filled content 3. Submit the issue directly #### Option B: No GitHub Account If the user doesn't have a GitHub account: 1. Click the generated GitHub issue URL (read-only access) 2. Copy the pre-filled content from the form 3. Create a free GitHub account to submit (required for security) ### Step 3: Community Review - All submissions (authenticated and anonymous) receive equal consideration - Community maintainers review submissions within 2-3 business days - Anonymous submissions are attributed to "Community Contributor" if accepted ## Technical Implementation ### Configuration ```typescript // All submissions require GitHub authentication // This ensures security and prevents spam // GitHub URL limits const GITHUB_URL_LIMIT = 8192; // ~8KB GitHub URL limit ``` ### URL Length Management The system automatically handles large persona content: - **Normal content**: Full persona details included in GitHub URL - **Large content**: Content is truncated with "[Content truncated due to length]" marker - **Essential information**: Always preserved (name, author, description, metadata) ### Security Considerations - All user input is properly URL-encoded - Special characters and HTML/script tags are safely handled - Content is placed within markdown code blocks for safety - Unicode characters are properly supported ## Response Templates ### Anonymous Submission Response ```markdown 📤 **Anonymous Submission Path Available** 🎭 **[Persona Name]** can be submitted without GitHub authentication! **Anonymous Submission Process:** 1. Click this link to create a GitHub issue (no account needed for viewing): [GitHub Issue URL] 2. **If you have a GitHub account:** • Click "Submit new issue" to submit directly 3. **If you don't have a GitHub account:** • Copy the pre-filled content from the form • Create a free GitHub account at: https://github.com/signup • Then submit the issue with your new account **What happens next:** • Community maintainers review all submissions • Anonymous submissions get the same consideration as authenticated ones • If accepted, your persona joins the collection with attribution to "Community Contributor" • The review typically takes 2-3 business days 💡 **Pro tip:** Creating a free GitHub account unlocks additional features, but it's completely optional for submissions! ``` ### Standard Submission Response ```markdown 📤 **Persona Submission Prepared** 🎭 **[Persona Name]** is ready for collection submission! **Next Steps:** 1. Click this link to create a GitHub issue: [GitHub Issue URL] 2. Review the pre-filled content 3. Click "Submit new issue" 4. The maintainers will review your submission ⭐ **Tip:** You can also submit via pull request if you're familiar with Git! ``` ## Usage Examples ### Basic Usage ```typescript import { PersonaSubmitter } from './collection/PersonaSubmitter.js'; const submitter = new PersonaSubmitter(); const persona = { metadata: { name: 'Test Persona', description: 'A test persona' }, content: 'Persona content...', filename: 'test.md', unique_id: 'test_123' }; // Generate submission data const submission = submitter.generateSubmissionIssue(persona); // Format response based on authentication status const isAuthenticated = false; // Detected from GitHub token/credentials const response = isAuthenticated ? submitter.formatSubmissionResponse(persona, submission.githubIssueUrl) : submitter.formatAnonymousSubmissionResponse(persona, submission.githubIssueUrl); ``` ### With Persona Indicator ```typescript // Include persona indicator in response const personaIndicator = '🎭 '; const response = submitter.formatAnonymousSubmissionResponse( persona, submission.githubIssueUrl, personaIndicator ); ``` ## Environment Variables ### GITHUB_REPO All submissions go through the GitHub repository: ```bash # The official collection repository https://github.com/DollhouseMCP/collection ``` Submissions are created as GitHub issues for review. ## Metrics and Analytics The system supports tracking submission patterns: - **Authenticated vs Anonymous**: Track submission method preferences - **Success rates**: Monitor completion rates for each pathway - **User experience**: Identify pain points in anonymous workflow ## Testing Comprehensive test coverage includes: - Anonymous user submission flow - Authenticated user submission flow - Large persona content handling - Special character encoding - URL length validation - GitHub authentication verification - Security validation (XSS prevention) ## Troubleshooting ### Common Issues #### URL Too Long Error - **Cause**: Persona content exceeds GitHub's ~8KB URL limit - **Solution**: Content is automatically truncated while preserving essential information #### Special Characters Not Displaying - **Cause**: Improper URL encoding - **Solution**: All content is properly URL-encoded using `encodeURIComponent()` #### GitHub Submissions Not Working - **Cause**: Network issues or GitHub API limitations - **Solution**: Check network connectivity and GitHub status page ### Debugging Enable detailed logging to troubleshoot submission issues: ```typescript // Log submission data for debugging console.log('Submission URL length:', submission.githubIssueUrl.length); console.log('Is authenticated:', isAuthenticated); console.log('Submission repo:', 'https://github.com/DollhouseMCP/collection'); ``` ## Future Enhancements ### Planned Features - **Submission tracking**: Unique IDs for tracking anonymous submissions - **GitHub automation**: Automated processing of GitHub issues - **Submission templates**: Pre-formatted issue templates for easier submission - **Status notifications**: GitHub issue status updates for submissions ### Community Feedback Integration - User experience surveys for anonymous submitters - Success rate analysis and workflow optimization - Enhanced guidance based on common user questions --- ## Related Documentation - [API Reference](API_REFERENCE.md) - Complete API documentation - [Quick Start Guide](QUICK_START.md) - Getting started with DollhouseMCP - [Security Guide](SECURITY.md) - Security best practices and considerations