DollhouseMCP is a comprehensive Model Context Protocol (MCP) server for managing, sharing, and customizing AI behaviors through dynamic personas and other AI customization elements. Key capabilities include:
AI Customization Management: Create, edit, validate, activate/deactivate, and manage personas, skills, templates, agents, memory, and ensembles through a portfolio system
Element-Specific Operations: Render content using templates with variables and execute autonomous agents for specific goals
GitHub Collection Integration: Browse, search, install, and submit AI customization elements to/from a community-driven GitHub collection with secure OAuth authentication
Import/Export & Sharing: Import personas from files/URLs, export to JSON format, and generate time-limited shareable URLs
User Identity Management: Set, retrieve, and clear user identity for content attribution
Server Management: Check status, perform automated updates with rollback capabilities and built-in safety features
Customization Options: Configure how persona indicators are displayed in AI responses
Offers containerized deployment options with production and development configurations, supporting volume mounts for custom personas and environment variable configuration
Provides a complete GitHub-powered marketplace integration for browsing, searching, installing, and submitting personas, with support for authentication and automated submission workflows
DollhouseMCP
Project Status
Build & Quality
Platform Support
Technology
A comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management with an integrated GitHub-powered collection. DollhouseMCP allows Claude and other compatible AI assistants to activate different behavioral personas while supporting community sharing and monetization.
🌐 Repository: https://github.com/DollhouseMCP/mcp-server
🏪 Collection: https://github.com/DollhouseMCP/collection
📦 NPM Package: https://www.npmjs.com/package/@dollhousemcp/mcp-server
🌍 Website: https://dollhousemcp.com (planned)
📦 Version: v1.6.8
🎉 New in v1.6.8: Fixed version update script to prevent wrong file creation and package-lock.json corruption. The release workflow now works reliably with proper version management.
⚠️ Breaking Change: PersonaTools have been streamlined in v1.6.0. 9 redundant tools were removed in favor of ElementTools. See PersonaTools Migration Guide for migration instructions.
🚀 Quick Start
Restart Claude Desktop and you're ready to use DollhouseMCP! Try list_elements type="personas"
to get started.
🎯 New User? Follow our Roundtrip Workflow Guide for a complete walkthrough of discovering, customizing, and sharing AI elements with the community.
✨ Key Features
Feature | Description |
---|---|
🎭 42 MCP Tools | Complete portfolio element management through chat interface |
🏪 GitHub Collection | Browse, search, install, and submit personas to community collection |
🔄 Roundtrip Workflow | Complete cycle: discover → customize → share → collaborate |
📁 GitHub Portfolio | Personal repository for storing and versioning your AI elements |
👤 User Identity System | Environment-based attribution for persona creators |
🆔 Unique ID System | Advanced ID generation: {type}_{name}_{author}_{YYYYMMDD}-{HHMMSS} |
💬 Chat-Based Management | Create, edit, and validate personas through conversational interface |
🔄 Real-time Operations | Live editing with automatic version bumping and validation |
📦 NPM Installation | Install MCP servers from npm with cross-platform support and atomic operations |
🛡️ Data Protection | Copy-on-write for default personas, comprehensive backup system |
🏠 Local-First Architecture | Full functionality without cloud dependency |
🎨 Portfolio Customization Elements
DollhouseMCP introduces a comprehensive portfolio system for customizing AI behavior through customization element types. Your portfolio is your personal collection of these element types that enhance and tailor your AI experience. Each element type serves a specific purpose in shaping how AI assistants interact with you.
Current Portfolio Element Types
Element | Purpose | Status |
---|---|---|
🎭 Personas | Define AI personality, tone, and behavioral characteristics | ✅ Available |
🛠️ Skills | Add specific capabilities like code review, data analysis, or creative writing | ✅ Available |
📝 Templates | Create reusable response formats for emails, reports, documentation | ✅ Available |
🤖 Agents | Build autonomous assistants that can pursue goals and make decisions | ✅ Available |
Coming Soon
Element | Purpose | Status |
---|---|---|
💬 Prompts | Pre-configured conversation starters and structured interactions | 🔄 Coming Soon |
🧠 Memory | Persistent context storage with retention policies and search capabilities | 🔄 Coming Soon |
🎯 Ensemble | Orchestrate multiple elements together as one unified entity | 🔄 Coming Soon |
📢 Note: Prompt, memory, and ensemble element types are actively being developed and will be available in upcoming releases.
Managing Your Portfolio
Use these new generic tools to manage any element type in your portfolio:
list_elements
- Browse your portfolio elements by typeactivate_element
- Activate elements to customize AI behaviorget_active_elements
- View currently active customizationsdeactivate_element
- Deactivate specific customizationsget_element_details
- Examine element configuration and metadatareload_elements
- Refresh portfolio from filesystem
GitHub Portfolio Integration (NEW!)
Manage your portfolio on GitHub for sharing and collaboration:
portfolio_status
- Check your GitHub portfolio repository statusinit_portfolio
- Create a new GitHub portfolio repositoryportfolio_config
- Configure sync and submission settingssync_portfolio
- Synchronize local and GitHub repositoriessearch_portfolio
- Search your local portfolio with advanced indexingsearch_all
- Unified search across local, GitHub, and collection sourcessubmit_content
- Upload elements to your GitHub portfolio
📘 Getting Started: New to portfolios? Follow our Portfolio Setup Guide for step-by-step instructions.
Smart Element Detection
DollhouseMCP automatically detects element types when submitting content, eliminating the need to manually specify types:
Key Features:
- Automatic Type Detection: Searches all element directories simultaneously
- Fuzzy Matching: Finds content with partial names or different extensions
- Clear Error Messages: Provides actionable guidance when content isn't found
- No More Mistakes: Prevents accidentally submitting content as wrong element type
Example Output:
📖 Learn More: See our Element Detection Guide for detailed usage examples and troubleshooting tips.
Complete Naming Freedom
DollhouseMCP gives you complete freedom to name your elements whatever you want. There are no naming restrictions or forbidden words.
✅ You can create elements named:
- "Test Assistant" - Previously blocked, now fully supported
- "Sample Code Reviewer" - No restrictions
- "テスト" (Japanese for "test") - Unicode supported
- "My Debugging Helper" - Any descriptive name
How it works: DollhouseMCP uses metadata-based test detection instead of filename patterns, so only internal DollhouseMCP test files are filtered (those with _dollhouseMCPTest: true
metadata). Your personal elements are never affected.
📘 Technical Details: See our Test Metadata Convention for information about how DollhouseMCP identifies its own test files without affecting user content.
Specialized Element Tools
Some portfolio elements have specialized operations:
render_template
- Generate content using template elements with variablesexecute_agent
- Deploy agent elements to accomplish specific goals
Portfolio Examples
Portfolio Structure
Your portfolio lives in ~/.dollhouse/portfolio/
with elements organized by type:
Persona Management via ElementTools
Personas are now managed through the generic ElementTools system:
list_elements type="personas"
- Display all local personas with enhanced metadataactivate_element name="name" type="personas"
- Activate by name, filename, or unique IDget_active_elements type="personas"
- Get current active persona informationdeactivate_element type="personas"
- Return to default modeget_element_details name="name" type="personas"
- View complete persona detailsreload_elements type="personas"
- Refresh personas from filesystem
📖 Migration: Legacy PersonaTools were removed in v1.6.0. See PersonaTools Migration Guide for complete migration instructions.
🔒 Enterprise-Grade Security
DollhouseMCP implements comprehensive security measures to protect your personas and system:
Security Features
- 🛡️ Content Sanitization: DOMPurify integration prevents XSS attacks in persona content
- 📝 YAML Injection Prevention: Secure parsing with schema validation and size limits
- 🔐 Token Security: GitHub OAuth device flow authentication with AES-256-GCM encrypted storage
- 🐳 Container Hardening: Non-root execution, read-only filesystem, resource limits
- 🚦 Rate Limiting: Token bucket algorithm prevents API abuse (10 checks/hour default)
- ✅ Signature Verification: GPG verification ensures release authenticity
- 🔍 Input Validation: Comprehensive validation for all user inputs
- 📊 Security Monitoring: Audit logging for security-relevant operations
Security Testing
- 487 comprehensive tests including security-specific test suites
- Continuous security scanning with GitHub Advanced Security
- Vulnerability-free: All security alerts resolved (0 active)
📋 Prerequisites
- Node.js: v20.0.0 or higher (LTS recommended)
- npm: v10.0.0 or higher
- git: For cloning the repository
- Operating System: Windows, macOS, or Linux
Note: DollhouseMCP is developed on Node.js 24 but supports Node.js 20+ for broad compatibility.
🚀 Quick Start
Installation
NPM Installation (NEW! - Recommended)
After installation, add DollhouseMCP to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Note: If you have other MCP servers configured, add dollhousemcp to your existing mcpServers object.
Automated Setup (Alternative) - Claude Desktop Only
Warning
Claude Desktop Only: The automated setup script is specifically designed for Claude Desktop integration. If you're using Claude Code, other AI platforms (ChatGPT, BoltAI, Gemini, etc.), or custom MCP implementations, please use the Manual Installation process below.
The setup script will:
- 📦 Install all dependencies
- 🔨 Build the TypeScript code
- 📍 Detect your installation path
- 🔧 Generate the exact Claude Desktop configuration
- 📋 Provide step-by-step setup instructions
Manual Installation
Note: Manual installation works with all MCP-compatible platforms including Claude Desktop, Claude Code, ChatGPT, BoltAI, Gemini, and custom implementations.
Claude Desktop Configuration
Add DollhouseMCP to your Claude Desktop configuration:
Location: ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS)
For NPM Installation:
For Source Installation:
🔄 After configuration:
- Save the file
- Restart Claude Desktop completely
- All 42 DollhouseMCP tools will be available
🛠️ Available Tools (42 Total)
Portfolio Element Management (NEW!)
list_elements
- List all elements of a specific typeactivate_element
- Activate an element by name and typeget_active_elements
- Get currently active elements of a typedeactivate_element
- Deactivate a specific elementget_element_details
- View detailed information about an elementreload_elements
- Refresh elements from filesystem
Element-Specific Operations (NEW!)
render_template
- Render a template element with provided variablesexecute_agent
- Execute an agent element with a specific goal
Persona Export/Import (Specialized Tools)
export_persona
- Export single persona to JSON formatexport_all_personas
- Export all personas to JSON bundleimport_persona
- Import persona from file path or JSON stringshare_persona
- Generate shareable URL for personaimport_from_url
- Import persona from shared URL
GitHub Collection Integration
browse_collection
- Browse content by section and type (flat structure, no categories)search_collection
- Search across all collection contentsearch_collection_enhanced
- Enhanced search with pagination, filtering, and sortingget_collection_content
- View detailed content infoget_collection_cache_health
- Monitor collection cache status and performanceinstall_element
- One-click download and installation of any element typesubmit_persona
- Submit to collection via GitHub issue
GitHub Portfolio Management (NEW!)
portfolio_status
- Check your GitHub portfolio repository statusinit_portfolio
- Create a new GitHub portfolio repositorysync_portfolio
- Synchronize local and GitHub repositoriessearch_portfolio
- Search your local portfolio with advanced indexingsearch_all
- Unified search across local, GitHub, and collection sourcessubmit_content
- Upload elements to your GitHub portfolio
Collection Configuration (NEW!)
configure_collection_submission
- Configure auto-submit and default settingsget_collection_submission_config
- View current submission configuration
User Identity Management
set_user_identity
- Set username for persona attributionget_user_identity
- View current identity statusclear_user_identity
- Return to anonymous mode
System Tools
get_build_info
- Comprehensive build and runtime information
Persona Indicators
configure_indicator
- Configure how persona indicators appear in AI responsesget_indicator_config
- View current indicator configuration settings
GitHub Authentication (NEW!)
setup_github_auth
- Start GitHub OAuth device flow authenticationcheck_github_auth
- Check current authentication statusclear_github_auth
- Remove stored authentication credentials
📖 Usage Examples
Collection Operations
Portfolio Workflow (NEW!)
Portfolio Element Management
Specialized Element Operations
System Information
Persona Management with ElementTools
User Identity
Persona Indicators
DollhouseMCP adds visual indicators to AI responses when a persona is active:
Configure indicators:
Environment variables for persistent configuration:
🔄 Complete Workflows
Setting Up Portfolio from Scratch
Step 1: Initial Setup
Step 2: Browse and Install Elements
Step 3: Customize and Activate
Step 4: Sync and Share
Searching Across All Sources
Unified Search Example
Advanced Portfolio Search
Content Submission with Auto-Detection
Smart Element Detection
Batch Content Management
Daily Workflow Example
Morning Setup
During Work
End of Day
GitHub Authentication (v1.5.0+)
DollhouseMCP supports GitHub OAuth device flow authentication for enhanced features. FIXED in v1.6.2: Default OAuth client ID now works correctly - no configuration needed!
OAuth Setup (For Self-Hosting)
If you're self-hosting or developing, you need to configure a GitHub OAuth app:
- Create GitHub OAuth App:
- Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
- Application name:
DollhouseMCP Server
- Homepage URL:
https://github.com/DollhouseMCP/mcp-server
- Authorization callback URL:
http://localhost:12345/callback
(required but not used) - Click "Register application"
- Enable Device Flow:
- In your OAuth app settings, check ✅ Enable Device Flow
- Copy your Client ID (format:
Ov23liXXXXXXXXXXXXXX
)
- Configure Environment:
See OAuth Setup Guide for detailed instructions.
Using Authentication
Features:
- 🔐 Secure Token Storage: Tokens encrypted with AES-256-GCM
- 📱 Device Flow: No need to manually create or paste tokens
- 🔄 Automatic Token Management: Secure storage and retrieval
- 🛡️ Rate Limiting: Built-in protection against API abuse
- ✅ Unicode Security: Prevents homograph attacks
How It Works:
- Run
setup_github_auth
to start the OAuth flow - Visit the provided URL and enter the user code
- Authorize DollhouseMCP in your browser
- Authentication completes automatically
- Token is securely stored for future use
Example Usage:
🖥️ Cross-Platform Installation
🐧 Linux Installation
Prerequisites
- Node.js: v20.0.0 or higher
- npm: v10.0.0 or higher
- git: For version control
Note: If your system's Node.js is older than v20, install from NodeSource or use nvm.
Installation Steps
Claude Desktop Configuration (Linux)
Configuration content:
🪟 Windows Installation
Prerequisites
- Node.js: v20.0.0 or higher
- npm: v10.0.0 or higher (included with Node.js)
- git: For version control
Installation Steps (PowerShell)
Claude Desktop Configuration (Windows)
Configuration content (use forward slashes or double backslashes):
🍎 macOS Installation
Prerequisites
- Node.js: v20.0.0 or higher
- npm: v10.0.0 or higher (included with Node.js)
- git: For version control
Installation Steps
Claude Desktop Configuration (macOS)
Configuration content:
🐳 Docker Installation
Quick Start with Docker
Docker Compose (Recommended)
Production deployment:
Development with hot reload:
Custom Personas with Docker
Docker Environment Variables
🧪 Testing
Running Tests
The project includes comprehensive tests for cross-platform compatibility:
Test Coverage
Current test coverage includes:
- ✅ 102 comprehensive tests covering all functionality
- ✅ Auto-update system - GitHub API, backup/rollback, dependency validation
- ✅ Security testing - Command injection prevention, input validation
- ✅ Cross-platform compatibility - Windows, macOS, Linux path handling
- ✅ Version validation - Parsing tests for git/npm output formats
- ✅ Edge case coverage - Network failures, missing dependencies, malformed input
Manual Verification
Verify your setup works correctly:
☁️ Cloud Deployment
Container Registries
The project supports deployment to:
- GitHub Container Registry (ghcr.io)
- Docker Hub
- AWS ECR
- Google Container Registry
Example Cloud Deployments
AWS ECS
Google Cloud Run
Azure Container Instances
🏗️ Project Structure
📝 Creating Custom Personas
Enhanced Persona Format
Create .md
files in the personas/
directory with this structure:
Metadata Fields
Required Fields
Field | Description |
---|---|
name | Display name for the persona |
description | Brief description of purpose and capabilities |
Optional Fields
Field | Description |
---|---|
unique_id | Auto-generated in format: what-it-is_YYYYMMDD-HHMMSS_who-made-it |
author | Creator username (uses DOLLHOUSE_USER environment variable or generates anonymous ID) |
category | One of: creative, professional, educational, gaming, personal |
triggers | Array of keywords that suggest when to use this persona |
version | Semantic version number (auto-incremented on edits) |
age_rating | Content rating: all, 13+, or 18+ |
ai_generated | Boolean flag indicating if content was AI-created |
price | Monetization field - TODO: Future Release (will support "free" or pricing tiers) |
📚 Built-in Personas
Persona | Purpose | Best For |
---|---|---|
Creative Writer | Imaginative storytelling and creative content | Brainstorming, creative writing, engaging narratives |
Technical Analyst | Deep technical analysis and systematic problem-solving | Architecture decisions, debugging, technical docs |
ELI5 Explainer | Simplifying complex topics for beginners | Teaching, onboarding, concept explanation |
Business Consultant | Strategic business analysis and recommendations | Strategy planning, business decisions, market analysis |
Debug Detective | Systematic debugging and troubleshooting | Bug hunting, system troubleshooting, root cause analysis |
🏪 Collection Integration (Beta)
🧪 Beta Feature: The GitHub-powered collection is currently in beta. Features may change based on community feedback.
DollhouseMCP includes an experimental GitHub-powered collection:
- Browse by Category: creative, professional, educational, gaming, personal
- Search Content: Find personas by keywords and descriptions
- One-Click Install: Download and integrate collection personas
- Community Submissions: Submit your personas via
submit_persona
tool - Version Control: Full Git history for all collection content
Note: Collection features require internet connection and GitHub API access. Rate limits may apply.
⚠️ Migration Guide - Breaking Changes
Important: Tool names have changed in recent versions:
browse_marketplace
→browse_collection
search_marketplace
→search_collection
get_marketplace_persona
→get_collection_content
If you have scripts or workflows using the old tool names, please update them to use the new names.
💼 Business Model & Legal
Licensing
- Core Server: AGPL-3.0 (prevents proprietary competing platforms)
- Persona Content: CC-BY-SA-4.0 for free personas, custom licenses for premium
- Platform Terms: Creator-friendly 80/20 revenue split (applies only to paid personas when monetization is implemented)
Platform Stability Commitments
- 90-day advance notice for monetization changes
- 12-month revenue sharing locks for existing paid personas
- Transparent governance for platform policy updates
- Full data portability rights
- Community advisory input on policy changes
🛠️ Development
Available Scripts
Script | Description |
---|---|
npm run build | Compile TypeScript to JavaScript |
npm run start | Run the compiled server |
npm run dev | Run in development mode with auto-reload |
npm run clean | Remove compiled files |
npm run rebuild | Clean and rebuild the project |
npm run setup | Install dependencies and build |
npm test | Run the comprehensive test suite |
npm run test:coverage | Run tests with coverage reporting |
Environment Variables
Customize server behavior with these environment variables:
🔧 Troubleshooting
⚠️ NPM Installation Issues (v1.4.2)
If the MCP server crashes on startup after NPM installation:
- Check your version:
npm list -g @dollhousemcp/mcp-server
- If you have v1.4.2, upgrade immediately:
npm install -g @dollhousemcp/mcp-server@latest
- Clear your portfolio and let it regenerate:
rm -rf ~/.dollhouse/portfolio
Note: v1.4.2 had a critical bug that prevented proper initialization. v1.4.3 attempted to fix this but introduced new crashes. Both issues are fixed in v1.4.4.
Directory Structure (v1.4.3+)
As of v1.4.3, all element directories use plural names:
~/.dollhouse/portfolio/personas/
(waspersona/
in v1.4.2)~/.dollhouse/portfolio/skills/
(wasskill/
in v1.4.2)~/.dollhouse/portfolio/templates/
(wastemplate/
in v1.4.2)~/.dollhouse/portfolio/agents/
(wasagent/
in v1.4.2)~/.dollhouse/portfolio/memories/
(wasmemory/
in v1.4.2)~/.dollhouse/portfolio/ensembles/
(wasensemble/
in v1.4.2)
If you upgraded from v1.4.2, the server will automatically migrate your directories.
Common Issues
Issue | Solution |
---|---|
v1.4.2 or v1.4.3 installation broken | Upgrade to v1.4.4+ immediately |
Personas not loading | Check ~/.dollhouse/portfolio/personas/ directory exists |
Server won't start | Run npm run rebuild to clean and rebuild |
Collection not working | Check internet connection and GitHub API access |
User identity not saving | Set DOLLHOUSE_USER environment variable before starting Claude |
"Cannot find module" errors | Ensure npm install completed successfully |
TypeScript compilation errors | Verify Node.js version is 20+ with node --version |
Tools not appearing in Claude | Restart Claude Desktop completely after config changes |
Default personas modified | v1.2.1+ uses copy-on-write; git restore if needed |
Update/rollback issues | Check write permissions; disable with DOLLHOUSE_DISABLE_UPDATES=true |
Rate limit errors | Wait 60 seconds; GitHub API has hourly limits |
Debug Steps
- Check build status:
- Verify persona files:
- Test server startup:
- Validate configuration:
- Check system status:
- Validate personas:
Use the
reload_personas
tool to check for loading errors
📚 Documentation
User Guides (START HERE!)
- 🎯 Roundtrip Workflow Guide - Complete workflow: discover → customize → share
- 📁 Portfolio Setup Guide - Set up your GitHub portfolio step-by-step
- 🔧 Troubleshooting Guide - Solutions for common workflow issues
Element System Documentation
- Element Architecture - System design and core concepts
- Element Types Reference - Detailed guide for all element types
- Developer Guide - How to create new element types
- API Reference - Complete MCP tool documentation
- Migration Guide - Upgrading from personas-only
Setup & Configuration
- OAuth Setup Guide - GitHub authentication configuration
- Anonymous Submission Guide - Use without GitHub authentication
Additional Resources
- Security Guidelines - Security best practices
- Contributing Guide - How to contribute
🤝 Contributing
We welcome contributions! DollhouseMCP includes integrated tools for submitting personas directly from Claude.
Integrated Contribution Process (Recommended)
- Create or modify a persona using the chat-based tools:
- Validate your persona to ensure quality:
- Submit to the collection directly from Claude:This automatically creates a GitHub issue for community review.
Manual Contribution Process
- Fork the repository
- Create persona files in
personas/
orcustom-personas/
- Follow the metadata format and naming conventions
- Test thoroughly with
validate_persona
tool - Submit a pull request with clear description
Reporting Issues
Please include:
- Node.js version (
node --version
) - Operating system and version
- Complete error messages
- Steps to reproduce the issue
- Relevant persona files (if applicable)
- Claude Desktop configuration (without sensitive paths)
Development Guidelines
- Follow TypeScript best practices
- Maintain existing code style and patterns
- Add comprehensive error handling
- Update documentation for new features
- Test thoroughly across platforms before submitting PRs
- Include tests for new functionality
- Follow semantic versioning for releases
Development Workflow
📄 API Reference
MCP Tool Specifications
Each tool follows the MCP specification:
Tool Categories
Persona Export/Import
Collection Integration
User Identity Management
Error Handling
The server provides detailed error messages for:
- Invalid persona identifiers - Clear suggestions for valid names
- File system issues - Permission and path resolution errors
- Malformed persona files - YAML parsing and validation errors
- Network errors - GitHub API and collection connectivity issues
- Runtime errors - Server startup and operation failures
Response Formats
All responses follow consistent patterns:
- Success responses: Include requested data and operation status
- Error responses: Include error type, message, and suggested resolution
- Progress indicators: Step-by-step feedback for long operations
- Validation results: Detailed reports with recommendations
📄 License
This project is licensed under the AGPL-3.0 License with Platform Stability Commitments - see the LICENSE file for details.
Platform Stability Guarantees:
- 90-day advance notice for policy changes
- 12-month revenue sharing locks
- Full data portability rights
- Community advisory input
🏷️ Version History
v1.6.8 - August 26, 2025 (Current)
Critical Fixes: Fixed OAuth helper NPM packaging and performance testing workflow
🔧 Bug Fixes
- OAuth NPM Packaging: Fixed missing
oauth-helper.mjs
file in NPM distribution- File was present in repository but not included in published package
- OAuth authentication now works correctly for NPM users
- Performance Tests: Fixed CI workflow running all tests instead of performance tests
- Performance monitoring now works correctly in GitHub Actions
v1.6.3 - August 25, 2025
OAuth Authentication Fix: Fixed invalid OAuth client ID and improved error handling
🔧 Bug Fixes
- OAuth Client ID: Updated from incorrect ID to correct
Ov23li9gyNZP6m9aJ2EP
- Error Handling: Added comprehensive error codes throughout OAuth flow
- Debug Logging: Added detailed logging at each authentication step
v1.6.2 - August 25, 2025
Critical Hotfix: Fixed OAuth default client ID not being used in setup_github_auth
tool
🔧 Bug Fixes
- OAuth Authentication: Fixed critical bug where default OAuth client ID wasn't used in
setupGitHubAuth()
method - Configuration Fallback: Now correctly uses
GitHubAuthManager.getClientId()
with proper fallback hierarchy
📚 Technical Details
- Made
GitHubAuthManager.getClientId()
public (was private) - Updated
setupGitHubAuth()
to use proper fallback chain - Restored "just works" authentication experience promised in v1.6.1
v1.6.1 - August 25, 2025
⚠️ Breaking Changes:
- 🔄 Serialization Format Change -
BaseElement.serialize()
now returns markdown with YAML frontmatter instead of JSON- Migration: Use new
serializeToJSON()
method for backward compatibility
- Migration: Use new
- 🏗️ Server Initialization - Portfolio initialization moved from constructor to
run()
method- New
ensureInitialized()
method provides lazy initialization for tests
- New
Major New Features:
- 🔍 Enhanced Portfolio System (6 new tools):
portfolio_status
- Check GitHub portfolio statusinit_portfolio
- Create GitHub portfolio repositorysync_portfolio
- Synchronize local/GitHub repositoriessearch_portfolio
- Search with advanced indexingsearch_all
- Unified search across all sources- Complete GitHub integration with indexing
- 📊 Enhanced Collection Search:
search_collection_enhanced
- Pagination, filtering, sortingget_collection_cache_health
- Cache monitoring- Smart caching with ETags and conditional requests
- 🛠️ System Tools:
get_build_info
- Comprehensive build and runtime information
- ⚙️ Collection Configuration:
configure_collection_submission
- Auto-submit settingsget_collection_submission_config
- Check submission config
Infrastructure Improvements:
- 🚀 High-Performance Caching - Memory-aware LRU cache system
- 🔒 Enhanced Security - YAML bomb protection, content validation
- 📦 Build Information Service - Runtime and build info API
- 🎯 Error Handler - Centralized error management system
- 🔄 Roundtrip Workflow - Complete content submission cycle
Statistics:
- 42 total MCP tools (down from 51 - 9 PersonaTools removed, 5 preserved)
- 89 commits ahead of main
- 257 files changed
- 50,857 lines added
- 76 test files modified/added
v1.5.1 - August 5, 2025
Critical Bug Fixes:
- 🔧 Fixed OAuth Token Retrieval -
setup_github_auth
tokens now properly used for API calls - 🔧 Fixed Collection Browsing - Removed legacy category validation blocking browsing
- 🔧 Persona Creation Simplified - Categories no longer required or validated
- ✅ Element System Alignment - Full consistency with new architecture
v1.5.0 - August 5, 2025
GitHub OAuth Authentication:
- 🔐 OAuth Device Flow - Secure authentication without manual token management
- 🔒 AES-256-GCM Encryption - Tokens encrypted at rest with machine-specific keys
- 🛡️ Rate Limiting - Built-in protection against brute force attacks
- ✅ Natural Language Flow - User-friendly authentication instructions
- 🧪 Comprehensive Tests - 420+ lines of OAuth implementation tests
v1.4.5 - August 5, 2025
Claude Desktop Integration Fix:
- ✅ Fixed "Server disconnected" errors when using
npx
ordollhousemcp
CLI - 🔄 Progressive retry mechanism for better compatibility across different machine speeds
- 🔒 Security improvements - removed detailed error logging to prevent information disclosure
- 🧪 Added comprehensive tests for execution detection logic
v1.4.4 - August 4, 2025
Emergency Hotfix:
- 🚨 Fixed v1.4.3 total failure - initialization crashes fixed
- 🔧 Fixed jsdom crash - heavy dependencies now load lazily
- 🐳 Fixed Docker compatibility - handles read-only environments
v1.4.3 - August 4, 2025
Directory Structure Fix:
- 🚨 Fixed NPM installation failure but introduced new crashes
v1.4.2 - August 4, 2025
Critical NPM Installation Fix:
- 🚨 Fixed NPM installation failure where empty portfolios caused server crashes
- 📦 DefaultElementProvider automatically populates default content on first run
- 🔍 Smart path detection searches multiple NPM/Git installation locations
- 💬 Helpful error messages guide new users when portfolios are empty
- 🔒 Security hardened with audit logging and file integrity verification
v1.4.1 - August 2, 2025
NPM Installation Support:
- 📦 Install MCP servers from npm packages with full cross-platform support
- 🔄 Atomic operations with transaction-based rollback on failure
- 📊 Progress indicators for better user experience during long operations
- 🏗️ Centralized configuration respecting platform conventions (XDG on Linux)
- 🛠️ FileOperations utility for consistent cross-platform behavior
v1.4.0 - August 2, 2025
Complete Element System:
- 🎭 Ensemble elements for orchestrating multiple elements together
- 🧠 Memory elements with retention policies and search capabilities
- 🤖 Agent elements with goal-oriented decision making
- 📝 Template elements with secure variable substitution
- 🛠️ Skill elements with parameter system and proficiency tracking
- 🔒 Comprehensive security throughout all element types
v1.3.3 - August 2, 2025
Portfolio System & Element Types:
- 🎨 Portfolio-based architecture for managing all AI customization elements
- 🛠️ Generic element tools that work with any element type
- 📁 Structured directory layout under
~/.dollhouse/portfolio/
- 🔄 Backward compatibility maintained for existing personas
v1.3.2 - August 1, 2025
GitFlow Implementation:
- 🔀 GitFlow branching model for better release management
- 🏷️ Automated version tagging on releases
- 📦 NPM release automation (pending token configuration)
v1.3.1 - July 31, 2025
Collection System Updates:
- 🏪 Improved collection browsing with better error handling
- 🔍 Enhanced search functionality for finding content
- 📥 Better installation process with validation
v1.3.0 - July 30, 2025
Major Architecture Refactor:
- 🏗️ Element interface system providing foundation for all element types
- 🔐 Security-first implementation with comprehensive protections
- 📊 Improved test coverage reaching 96%+
v1.2.5 - July 2025
Collection Rename & Breaking Changes:
- 🔄 Renamed all "marketplace" tools to "collection":
browse_marketplace
→browse_collection
search_marketplace
→search_collection
get_marketplace_persona
→get_collection_content
install_persona
→install_persona
(unchanged)submit_persona
→submit_persona
(unchanged)
- ✅ Added backward compatibility aliases (deprecated, will be removed in v2.0.0)
- ✅ Updated repository from
/personas
to/collection
- ✅ Created migration guide for users to update their scripts
- ✅ Fixed all date references from January to July 2025
v1.2.4 - July 10, 2025
Critical Fix:
- ✅ Fixed MCP protocol compatibility - console output no longer breaks JSON-RPC communication
- ✅ Added MCP-safe logger utility for proper logging during protocol sessions
- ✅ Resolves connection failures in Claude Desktop
- ✅ Updated Docker tests to work with new logging approach
- ✅ Added comprehensive logger unit tests
v1.2.3 - July 10, 2025
Bug Fix:
- ✅ Fixed personas directory path resolution for production environments
- ✅ Changed from process.cwd() to __dirname-based paths
- ✅ Fixed setup script with correct tool count and repository URLs
v1.2.2 - July 10, 2025
- ✅ Comprehensive security enhancements:
- Content sanitization with DOMPurify (SEC-001)
- YAML injection prevention (SEC-003)
- GitHub token security (SEC-004)
- Docker container hardening (SEC-005)
- ✅ 487 comprehensive tests including extensive security coverage
- ✅ CI timing test fixes for reliable cross-platform testing
- ✅ TypeScript compilation fixes for all test files
- ✅ All security vulnerabilities resolved (0 active alerts)
v1.2.1 - July 8, 2025
- ✅ Critical bug fixes for data protection:
- Copy-on-write for default personas (Issue #145)
- User personas included in backups (Issue #144)
- ✅ Node.js 20+ requirement for npm publishing compatibility
- ✅ 372 comprehensive tests covering all functionality
- ✅ Enhanced security with all vulnerabilities resolved
- ✅ Improved documentation with clear prerequisites
v1.2.0 - July 7, 2025
- ✅ Rate limiting implementation to prevent API abuse
- ✅ GPG signature verification for release authenticity
- ✅ GitHub Advanced Security integration
- ✅ 309 tests with improved CI environment coverage
- ✅ Package optimization at 279.3 kB
v1.1.0 - July 4, 2025
- ✅ Platform-specific badges for Windows, macOS, Linux visibility
- ✅ GitHub Project management with issue templates and milestones
- ✅ ARM64 Docker fix switching from Alpine to Debian base images
- ✅ 100% workflow reliability (except Docker ARM64)
- ✅ First GitHub release with CHANGELOG.md
- ✅ 21 total MCP tools at time of release
Phase 2B+ - July 3, 2025
- ✅ Enterprise-grade auto-update system with 4 new MCP tools
- ✅ 50 comprehensive tests covering all functionality
- ✅ Security hardening - eliminated all command injection vulnerabilities
- ✅ Cross-platform support - Windows, macOS, Linux with CI/CD testing
- ✅ Docker containerization with production and development configurations
- ✅ 21 total MCP tools with backup/rollback and dependency validation
Phase 2B - July 1-2, 2025
- ✅ Complete chat-based persona management
- ✅ GitHub marketplace integration
- ✅ User identity and attribution system
- ✅ Real-time validation and editing
- ✅ Enterprise-grade GitHub Actions security
Phase 1 - July 1, 2025
- ✅ Fresh AGPL-3.0 licensed repository
- ✅ Enhanced unique ID system
- ✅ Anonymous user support
- ✅ Marketplace-ready metadata schema
🎭 Transform your AI interactions with the power of personas
For support, please open an issue or visit our collection.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A comprehensive Model Context Protocol server that enables dynamic AI persona management with GitHub-powered marketplace integration, allowing Claude and other compatible AI assistants to activate different behavioral personas with community sharing capabilities.
- Project Status
- Build & Quality
- Platform Support
- Technology
- 🚀 Quick Start
- ✨ Key Features
- 🎨 Portfolio Customization Elements
- 🔒 Enterprise-Grade Security
- 📋 Prerequisites
- 🚀 Quick Start
- 🛠️ Available Tools (42 Total)
- 📖 Usage Examples
- 🔄 Complete Workflows
- 🖥️ Cross-Platform Installation
- 🐳 Docker Installation
- 🧪 Testing
- ☁️ Cloud Deployment
- 🏗️ Project Structure
- 📝 Creating Custom Personas
- 📚 Built-in Personas
- 🏪 Collection Integration (Beta)
- 💼 Business Model & Legal
- 🛠️ Development
- 🔧 Troubleshooting
- 📚 Documentation
- 🤝 Contributing
- 📄 API Reference
- 📄 License
- 🏷️ Version History
- v1.6.8 - August 26, 2025 (Current)
- v1.6.3 - August 25, 2025
- v1.6.2 - August 25, 2025
- v1.6.1 - August 25, 2025
- v1.5.1 - August 5, 2025
- v1.5.0 - August 5, 2025
- v1.4.5 - August 5, 2025
- v1.4.4 - August 4, 2025
- v1.4.3 - August 4, 2025
- v1.4.2 - August 4, 2025
- v1.4.1 - August 2, 2025
- v1.4.0 - August 2, 2025
- v1.3.3 - August 2, 2025
- v1.3.2 - August 1, 2025
- v1.3.1 - July 31, 2025
- v1.3.0 - July 30, 2025
- v1.2.5 - July 2025
- v1.2.4 - July 10, 2025
- v1.2.3 - July 10, 2025
- v1.2.2 - July 10, 2025
- v1.2.1 - July 8, 2025
- v1.2.0 - July 7, 2025
- v1.1.0 - July 4, 2025
- Phase 2B+ - July 3, 2025
- Phase 2B - July 1-2, 2025
- Phase 1 - July 1, 2025
Related MCP Servers
- -securityFlicense-qualityA comprehensive suite of Model Context Protocol servers designed to extend AI agent Claude's capabilities with integrations for knowledge management, reasoning, advanced search, news access, and workspace tools.Last updated -5
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact with Google Cloud Platform environments through natural language, allowing users to query and manage GCP resources during conversations.Last updated -9175150MIT License
- -securityAlicense-qualityA Model Context Protocol server that connects Claude and other MCP clients to Aider, enabling AI assistants to efficiently edit files, create new files, and interact with git repositories through natural language.Last updated -34The Unlicense
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.Last updated -12161MIT License