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
đ 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
Open Source, Community-Powered AI Customization
Create, Edit, and Share Customization Elements for Your AI Platforms
Elements That Customize Your AI's Capabilities and Actions
DollhouseMCP is open source, community-powered AI customization. Create your own customization elementsâpersonas that shape behavior, skills that add capabilities, templates for consistent outputs, agents for automation, and memories for persistent contextâor use and modify an ever-growing number of customization elements from the community. Every element you create can be saved to your portfolio and used again or shared back to the DollhouseMCP Collection to help others.
What Are Customization Elements?
Personas â Shape how your AI acts and responds in specific domains
Skills â Add specialized capabilities your AI can use
Templates â Ensure consistent, high-quality outputs
Agents â Enable autonomous task completion with smart decision-making
Memory â Persistent context storage across sessions
Core Capabilities
đ Community Element Library â A growing number of tested personas, skills, templates, agents, and memories
âš Create Custom Elements â Create personas, skills, templates, agents, and memories from scratch using natural language
đ€ Open Source â AGPL-3.0 licensed, ensuring community contributions stay free
đ The DollhouseMCP Collection â Install any community element with one command
đ ïž 41 Professional Tools â Complete toolkit for element creation and management
đĄïž Security-First Validation â All elements validated against hundreds of attack vectors
⥠Hot-Swap Elements â Change personas, skills, and templates without restarting as needed
đŠ Personal Portfolio â Your library of custom AI configurations on your local computer or personal GitHub repo
Claude Skills Compatibility
100% lossless round-trip conversion between DollhouseMCP Skills and Claude Skillsâall metadata, validation, and structure preserved without loss in either direction.
Import Claude Skills into the DollhouseMCP ecosystem for enhanced version control, deployment across hundreds of AI platforms that support MCP servers, security validation against hundreds of attack vectors, and integration with personas, templates, agents, and memories. Convert DollhouseMCP Skills to Claude Skills when you need compatibility with Claude-specific environments that cannot run DollhouseMCP.
â Complete Skills Converter Guide â Lossless round-trip translation in both directions with CLI reference and examples
â Use the DollhouseMCP skill-converter skill to convert directly from chat on LLMs with command-line access like Claude Code, Cursor, Gemini Code Assist, etc.
Use Cases
Get Started
See Quick Start for complete setup instructions.
đŻ Element Types
â Available Now
đ Personas
Shape how your AI behaves and responds
Creative Writer - Imaginative storyteller for engaging narratives
Business Consultant - Strategic advisor for business decisions
Debug Detective - Systematic problem-solver for code issues
Security Analyst - Vulnerability assessment and threat analysis
Technical Analyst - Deep dive technical documentation
Use:
"Activate the creative writer persona"
đĄ Skills
Add specialized capabilities your AI can use
Code Review - Analyze code quality and suggest improvements
Data Analysis - Statistical analysis and visualization
Language Translation - Multi-language communication
API Integration - Connect and interact with external services
Testing Automation - Generate and run test suites
Use:
"Enable the code review skill"
đ Templates
Ensure consistent, high-quality outputs
Project Proposal - Structured business proposals
Penetration Test Report - Security assessment documentation
Meeting Notes - Organized meeting summaries
Code Review - Systematic code evaluation format
Documentation - Technical documentation structure
Use:
"Use the project proposal template"
đ€ Agents
Enable autonomous task completion
Code Reviewer - Automated code quality assessment
Task Manager - Project organization and tracking
Research Assistant - Information gathering and synthesis
Academic Researcher - Scholarly research and citations
Security Fix Specialist - Vulnerability remediation
Use:
"Run the code reviewer agent"
đ§ Memory NEW in v1.9.0
Persistent context across sessions with intelligent organization
Text-based storage - Currently supports text content (PDFs, images, and other media types coming soon)
Date-based folders - Automatic YYYY-MM-DD organization prevents flat directory issues
YAML format - Human-readable structured data (vs Markdown for other elements)
Smart deduplication - SHA-256 hashing prevents duplicate storage
Search indexing - Fast queries across thousands of entries
Use:
"Create a memory for this project"or"Remember this conversation"
Typical file sizes: Single memories up to ~100KB, folder structure enables unlimited collections
đ Coming Soon
đŻ Ensembles
Combine multiple elements as one unified entity
Full-Stack Developer - Frontend + Backend + DevOps skills
Writing Suite - Creative + Technical + Editorial capabilities
Security Team - Analyst + Auditor + Remediation skills
Data Science Platform - Analysis + Visualization + ML skills
Status: In development
đ Prompts
Reusable instruction sets
Code Review Checklist - Systematic review steps
Security Audit Guide - Vulnerability assessment process
Writing Guidelines - Style and tone instructions
Debug Workflow - Problem-solving methodology
Status: Planned
đ§ Tools
External function calls and commands
Git Operations - Version control management
Database Queries - Direct database interaction
API Calls - External service integration
File Operations - Advanced file manipulation
Status: Under consideration
đ Memory Enhancements
Expanding memory capabilities
PDF Support - Text extraction from PDF documents
Image Analysis - Visual content understanding
Audio Transcription - Voice and sound processing
Video Understanding - Motion and scene analysis
Status: Roadmap planned
đŹ Natural Language Usage Examples
DollhouseMCP is designed for natural language interaction. Just describe what you want in plain English - you don't need to be overly specific, the system will figure it out.
Importing from the Community Collection
Natural Language Examples:
"Show me all the personas in the Dollhouse Collection""What creative writing personas are available?""Install the storyteller persona from the collection""Search for Python development skills""Find templates for technical documentation"
Direct Commands (if you prefer):
Managing Your Portfolio
Natural Language Examples:
"What's in my portfolio?""Show me all my custom personas""Sync my portfolio with GitHub""Create a backup of my elements""Search my portfolio for marketing templates"
Direct Commands (if you prefer):
Working with Elements
Natural Language Examples:
"Activate the code reviewer persona""What's currently active?""Switch to creative writing mode""Deactivate all elements""Show me details about the data analyst skill""Create a new persona for customer support""Edit the email template to be more formal"
Direct Commands (if you prefer):
Complete Workflow Example
Here's how a typical session might look:
Pro Tips
Be conversational:
"Help me write better code"works as well as specific commandsStack elements:
"Activate both the code reviewer and the Python expert"Save your favorites:
"Save this configuration as my default setup"Share with others:
"Submit my custom persona to the community collection"
đŠ Installation
Choose Your Installation Method
Method 1: Local Installation (Recommended)
Create a dedicated folder for your MCP servers and install there:
Configure Claude Desktop:
Add to your config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
đĄ Pro tip: Replace /Users/YOUR_USERNAME with your actual home directory path.
Method 2: Always Latest with npx
No installation needed! Configure Claude Desktop to always use the latest version:
đ Note: The @latest tag ensures you always get the newest version. Remove it to use npm's cached version.
Method 3: Global Installation
Configure Claude Desktop:
â ïž Warning: Only one version system-wide. Consider local installation for more flexibility.
đŻ Advanced: Multiple Configurations
Want separate portfolios for different contexts? Create multiple local installations:
Configure each with its own portfolio:
Now you can enable/disable different configurations in Claude Desktop as needed!
â Verify Installation
After configuring and restarting Claude Desktop, test with:
You should see your available personas. If not, check the Troubleshooting section.
đ Default Portfolio Location
By default, your elements are stored in:
macOS/Linux:
~/.dollhouse/portfolio/Windows:
%USERPROFILE%\.dollhouse\portfolio\
Use the DOLLHOUSE_PORTFOLIO_DIR environment variable to customize this location.
đ Quick Start
Once installed, try these commands in Claude:
đ 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 |
đ 41 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:
|
đŹ 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 System
The DollhouseMCP Portfolio system provides a comprehensive framework for managing AI elements locally and in the cloud.
Portfolio Structure
Your portfolio is organized by element type:
Note on File Types:
Markdown (.md): Used for personas, skills, templates, agents, and ensembles - human-readable with YAML frontmatter
YAML (.yaml): Used exclusively for memories - structured data optimized for context storage
Memory Organization:
Memories use automatic YYYY-MM-DD folder structure to prevent flat directory performance issues
Each memory file can grow up to ~100KB before creating a new file
Folder structure enables unlimited memory collections without degradation
Key Features
Local-First Architecture: All elements stored locally with optional cloud sync
GitHub Integration: Sync your portfolio with GitHub for backup and sharing
Version Control: Full git integration for tracking changes
Smart Detection: Automatically identifies element types from content
Flexible Naming: Use any naming convention you prefer
Portfolio Management Tools
Use the comprehensive set of MCP tools to manage your portfolio:
list_portfolio_elements- View all elements across typessync_portfolio- Synchronize with GitHubupload_to_portfolio- Share elements with the communitydownload_from_portfolio- Get elements from GitHub
For detailed portfolio documentation, see the Portfolio Guide.
đ Security
DollhouseMCP implements enterprise-grade security measures to protect your data and ensure safe operation.
Security Features
Input Sanitization: All user inputs validated and sanitized
Path Traversal Prevention: Filesystem access strictly controlled
YAML Injection Protection: Safe parsing with validation
Command Injection Prevention: No direct shell command execution
Token Encryption: OAuth tokens encrypted at rest
Rate Limiting: API calls throttled to prevent abuse
Audit Logging: Security events tracked for analysis
Security Testing
Automated Security Scanning: GitHub Advanced Security enabled
Dependency Scanning: Automated vulnerability detection
Code Analysis: Static analysis with CodeQL
Secret Scanning: Prevents credential leaks
Reporting Security Issues
If you discover a security vulnerability, please:
DO NOT create a public GitHub issue
Open a private security advisory on GitHub
Include steps to reproduce if possible
Allow up to 48 hours for initial response
For more details, see our Security Policy.
đ ïž Development
Getting Started
Development Workflow
Create Feature Branch:
git checkout -b feature/your-featureMake Changes: Implement your feature or fix
Run Tests:
npm testBuild:
npm run buildSubmit PR: Create pull request to develop branch
Available Scripts
npm run build- Compile TypeScriptnpm run dev- Development mode with watchnpm test- Run test suitenpm run lint- Check code stylenpm run typecheck- TypeScript type checking
Project Structure
For detailed development guides, see Development Documentation.
đ Architecture
System Overview
DollhouseMCP follows a modular, extensible architecture built on the Model Context Protocol (MCP) standard.
Core Components
MCP Server
Transport: StdioServerTransport for Claude Desktop integration
Protocol: JSON-RPC 2.0 communication
Tools: 41 MCP tools for comprehensive functionality
Element System
BaseElement: Abstract base class for all elements
IElement Interface: Common contract for elements
Element Types: Personas, Skills, Templates, Agents, Memories, Ensembles
Portfolio Manager
Local Storage: File-based element storage
GitHub Sync: Git-based synchronization
Version Control: Full git integration
Security Layer
Input Validation: All inputs sanitized
Path Security: Traversal prevention
Token Management: Encrypted storage
Data Flow
Client Request â MCP Server
Tool Routing â Appropriate handler
Element Processing â Element system
Storage â Portfolio manager
Response â Client
For detailed architecture documentation, see Architecture Guide.
đŻ Troubleshooting
Common Issues
MCP Server Not Connecting
Symptoms: Claude Desktop doesn't show DollhouseMCP in available servers
Solutions:
Verify configuration file location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Check JSON syntax is valid
Restart Claude Desktop after configuration changes
OAuth Authentication Fails
Symptoms: Cannot authenticate with GitHub
Solutions:
Check internet connection
Verify GitHub account has proper permissions
Try using Personal Access Token instead:
export GITHUB_TOKEN=your_pat_tokenClear cached credentials and retry
Elements Not Loading
Symptoms: Portfolio appears empty
Solutions:
Check portfolio directory exists:
~/.dollhouse/portfolio/Verify file permissions
Run
list_portfolio_elementstool to diagnoseCheck element file format (YAML frontmatter required)
Performance Issues
Symptoms: Slow response times
Solutions:
Check portfolio size (large portfolios may be slow)
Verify adequate system resources
Consider using pagination for large lists
Check network latency for GitHub operations
Getting Help
Documentation: Full docs
Issues: GitHub Issues
Discussions: GitHub Discussions
For detailed troubleshooting, see Troubleshooting Guide.
đ€ Contributing
We welcome contributions to DollhouseMCP! Here's how you can help:
Ways to Contribute
đ Report Bugs: Open an issue with reproduction steps
âš Request Features: Suggest new functionality
đ Improve Documentation: Fix typos, add examples
đ» Submit Code: Fix bugs or implement features
đš Share Elements: Contribute personas, skills, templates
Development Process
Fork the Repository
gh repo fork DollhouseMCP/mcp-serverCreate Feature Branch
git checkout -b feature/your-featureMake Changes
Follow existing code style
Add tests for new functionality
Update documentation
Test Thoroughly
npm test npm run lint npm run typecheckSubmit Pull Request
Target the
developbranchProvide clear description
Reference any related issues
Code Style
TypeScript with strict mode
ESLint configuration provided
Prettier for formatting
Comprehensive JSDoc comments
Commit Messages
Follow conventional commits:
feat:New featurefix:Bug fixdocs:Documentationtest:Testingchore:Maintenance
Review Process
Automated CI checks must pass
Code review by maintainers
Address feedback
Merge when approved
For detailed guidelines, see CONTRIBUTING.md.
đ Resources
Documentation
Quick Start Guide - Get up and running quickly
Portfolio Setup - Configure your portfolio
Element Development - Create custom elements
API Reference - Complete tool documentation
Architecture Guide - System design details
Security Documentation - Security measures and best practices
Repositories
Main Repository - Core MCP server
Collection - Community elements
Developer Kit - Development tools
Community
GitHub Discussions - Q&A and ideas
GitHub Issues - Bug reports and features
Discord Server - Real-time chat (coming soon)
External Resources
Model Context Protocol - MCP specification
Claude Desktop - AI assistant with MCP support
Anthropic Documentation - Claude documentation
Learning Materials
Tutorials (coming soon)
Building Your First Persona
Creating Custom Skills
Portfolio Management Best Practices
GitHub Integration Setup
Videos (coming soon)
Installation Walkthrough
Feature Demonstrations
Developer Tutorials
Support
GitHub Issues: Report issues or request features
Security Issues: Private security advisories
Discussions: Community Q&A
đ·ïž Version History
v1.9.24 - 2025-10-27
Documentation Release: Claude Skills Compatibility & Dependency Updates
đ Documentation
Claude Skills Compatibility Section (#1413)
Added prominent README section highlighting 100% lossless round-trip conversion
Documents bidirectional conversion between DollhouseMCP Skills and Claude Skills
Includes skill-converter usage for CLI-enabled LLMs (Claude Code, Cursor, Gemini Code Assist)
Complete metadata, validation, and structure preservation in both directions
Merge Strategy Documentation
Documented squash vs. regular merge strategy in
docs/development/PR_BEST_PRACTICES.mdFeature â develop: SQUASH merge (clean history)
Develop â main: REGULAR merge (preserves commits)
đ Dependency Updates
@modelcontextprotocol/sdk1.20.1 â 1.20.2posthog-node5.10.0 â 5.10.3jsdom27.0.0 â 27.0.1 (dev)@types/node24.8.1 â 24.9.1 (dev)@modelcontextprotocol/inspector0.17.1 â 0.17.2 (dev)
v1.9.23 - 2025-10-26
Feature Release: Bidirectional Skills Converter
âš Features
Bidirectional Skills Converter (#1400, #1401)
Lossless conversion between DollhouseMCP Skills and Claude Skills
CLI:
dollhouse convert from-anthropic/to-anthropicAutomatic format detection and metadata enrichment
100% fidelity roundtrip conversion
Comprehensive documentation in
docs/guides/SKILLS_CONVERTER.md
DollhouseMCP Primacy Messaging
README section establishing timeline (July 2025 vs October 2025)
Positions DollhouseMCP as superset with 6 element types
Professional framing for legal review
Technical Details
13 converter tests passing
Security: ZIP size limits, bomb detection, Unicode normalization
Components: SchemaMapper, ContentExtractor, bidirectional converters
Performance: Sub-second for small skills, scales to large multi-MB skills
v1.9.21 - 2025-10-23
Patch Release: Memory validation system activation and element formatting
âš Features
Element file formatter script (#1388, fixes #1387)
New
scripts/fix-element-formatting.tsto reformat blob content elementsFixes element files stored as single-line blobs (unreadable in editors)
Intelligently adds newlines before/after markdown headers
Formats code blocks and YAML structures properly
Dry-run mode for safe testing
Average line length detection (>200 chars triggers formatting)
đ§ Fixed
Background memory validation startup (#1389)
BackgroundValidator service now starts automatically on server initialization
Memory entries with UNTRUSTED status will be automatically validated every 5 minutes
Trust levels are now properly updated (VALIDATED, FLAGGED, QUARANTINED)
Validation runs server-side with zero token cost
đ Changed
README version history optimization
Limited version history in README to 1.9.x releases only (21 versions instead of 35)
Reduced README size from ~75KB to ~61KB for better readability
Complete history remains in CHANGELOG.md (source of truth)
Updated
generate-version-history.jsminVersion from 1.6.0 to 1.9.0
Added missing v1.9.20 changelog entry to README
Previous README was missing the v1.9.20 MCP Registry Publishing Fix
Context
The BackgroundValidator service was fully implemented in Issue #1314 (Phase 1: Background validation for memory security) but was never activated. The backgroundValidator.start() method was missing from server initialization, causing all memories to remain UNTRUSTED indefinitely.
This patch release adds proper lifecycle management:
Import backgroundValidator singleton in server initialization
Start validation service after resource handlers are set up
Stop service during server cleanup
Impact
Memory security architecture is now fully operational
UNTRUSTED memories will be automatically validated
Trust level updates work correctly
No performance impact (runs in background outside LLM context)
v1.9.20 - 2025-10-17
Fix Release: MCP Registry Publishing Compatibility
đ§ Fixed
MCP Registry publishing case sensitivity issue (#XXXX)
Corrected
mcpNamefield in package.json to match GitHub organization capitalizationChanged from
io.github.dollhousemcp/mcp-servertoio.github.DollhouseMCP/mcp-serverResolves NPM package validation errors when publishing to MCP Registry
Ensures proper namespace permission matching
Context
The MCP Registry performs two case-sensitive validations:
Permission check against GitHub org name (
io.github.DollhouseMCP/*)NPM package validation against
mcpNamefield in package.json The initial implementation incorrectly used lowercase formcpName, causing a validation mismatch. This patch release corrects the capitalization to match our GitHub organization name.
v1.9.19 - 2025-10-17
Comprehensive Release: 90 commits including security fixes, PostHog telemetry, MCP registry support, and major cleanup
âš Features
MCP registry publishing workflow with OIDC authentication (#1367)
Automated publishing to registry.modelcontextprotocol.io
GitHub Actions workflow with manual dry-run mode
Comprehensive test suite for workflow validation (50+ tests)
Pinned mcp-publisher CLI to v1.3.3 for reproducibility
PostHog remote telemetry integration (#1357, #1361)
Opt-in remote analytics with DOLLHOUSE_TELEMETRY_OPTIN=true
Usage patterns and error tracking
Privacy-focused with explicit consent
MCP Resources support for capability index (#1360)
Future-proof architecture (disabled by default)
Ready for MCP protocol evolution
Dual licensing model with commercial option (#1350)
AGPL-3.0 with platform stability commitments
Commercial licensing pathway
Minimal installation telemetry (#1359)
Operational metrics for v1.9.19
Installation success tracking
Security telemetry tracking for blocked attacks (#1313)
Automated release issue verification system (#1249)
Orphaned issues checker for systematic cleanup (#1251)
Personal development notes directory (#1275)
đ Security
Phase 1: Background validation for memory security (#1316, #1320, #1322)
Phase 2: AES-256-GCM pattern encryption (#1323)
Fixed symlink path traversal vulnerability (#1290, #1306)
Resolve symlinks before validation
Enhanced audit logging
Comprehensive path sanitization
Fixed command injection in verify-release-issues.js (#1249)
DMCP-SEC-001: Critical vulnerability patched
PATH injection protection with absolute paths
Tightened YAML bomb detection threshold from 10:1 to 5:1 (#1305)
Fixed multiple security audit issues (3 MEDIUM/LOW severity)
đ§ Fixed
Missing shell: bash declarations in MCP registry workflow
OAuth device flow zero-scopes bug (using OIDC instead)
Test isolation to prevent resource contention (#1288)
GitHub rate limiter test failures (#1285)
Recognition of MERGED state in release verification (#1250)
Resolved 26+ SonarCloud code quality issues across multiple files
Import/export ordering issues
Cognitive complexity reductions
Security hotspot resolutions
Cross-platform workflow compatibility improvements
Namespace casing for MCP registry (DollhouseMCP)
đ Changed
Improved whitespace detection performance
Enhanced path traversal protection mechanisms
Skip Claude Code Review for Dependabot PRs (#1241)
Refactored CLAUDE.md into modular documentation (#1270)
Renamed docs/archive/ to docs/session-history/ (#1277)
Added node: prefix for built-in module imports
Reduced cognitive complexity in multiple modules
Dependencies
Updated @modelcontextprotocol/sdk from 1.18.0 to 1.20.0
Updated jest from 30.0.5 to 30.2.0
Updated @types/node from 24.4.0 to 24.7.0
Updated typescript from 5.9.2 to 5.9.3
Updated multiple dev dependencies
Added PostHog SDK for telemetry
Technical
OIDC permissions: id-token:write, contents:read
server.json included in NPM package
Docker build optimizations and multi-platform support
Auto-sync README files on develop push
Enhanced test coverage and reliability
Improved CI/CD pipeline stability
v1.9.18 - 2025-10-17
Feature Release: PostHog remote telemetry (opt-in), MCP Resources support, and operational telemetry foundation
âš Features
PostHog Remote Telemetry Integration (#1357, #1361) - Opt-in remote analytics
Simple opt-in: Set
DOLLHOUSE_TELEMETRY_OPTIN=trueto enable remote telemetryUses shared PostHog project for community-wide insights
Default PostHog project key embedded (safe to expose - write-only)
Backward compatible with custom
POSTHOG_API_KEYfor enterprise deploymentsMultiple control levels:
DOLLHOUSE_TELEMETRY_OPTIN=true- Enable remote telemetryDOLLHOUSE_TELEMETRY_NO_REMOTE=true- Local only, no PostHogDOLLHOUSE_TELEMETRY=false- Disable all telemetry
GDPR compliant - fully opt-in by design
See docs/privacy/OPERATIONAL_TELEMETRY.md for complete privacy policy
Future incentive program planned for community contributors
MCP Resources Support (#1360) - Future-proof implementation of MCP Resources protocol
Three resource variants exposed: summary (~3K tokens), full (~40K tokens), and stats (JSON)
Capability index exposed as MCP resources for intelligent element discovery
Status: Non-functional in Claude Code (Oct 2025) - discovery only, not read
Default: Disabled for safety - zero overhead when not enabled
Manual attachment works in Claude Desktop and VS Code
Comprehensive user documentation at
docs/configuration/MCP_RESOURCES.mdResearch document at
docs/development/MCP_RESOURCES_SUPPORT_RESEARCH_2025-10-16.mdConfiguration options:
resources.enabled,resources.expose[],resources.cache_ttlEarly adopter advantage - ready when MCP clients implement full resource reading
Operational Telemetry Foundation (#1358, #1359) - Minimal installation tracking
Tracks single installation event on first run (version, OS, Node version, MCP client)
Local-only logging to
~/.dollhouse/telemetry.logby defaultSimple opt-out via
DOLLHOUSE_TELEMETRY=falseenvironment variablePrivacy-first design: no PII, no behavioral data, no user content
Anonymous UUID generated locally for installation identification
Graceful error handling (never crashes if files can't be written)
Zero performance impact when opted out
Documentation
Added comprehensive telemetry incentive strategy guide
Updated privacy policy with PostHog opt-in details
Added session notes for telemetry implementation
Enhanced README with telemetry opt-in section
Test Results
2546 tests passing
Test coverage: >96% maintained
All CI checks passing across all platforms
v1.9.17 - 2025-10-08
Test isolation and repository cleanup patch
đ§ Fixed
Performance Test Isolation (#1288): Fixed flaky IndexOptimization test by isolating performance tests
Created dedicated
jest.performance.config.cjswith 4 parallel workersMain test suite no longer runs performance tests concurrently (prevents resource contention)
IndexOptimization test now consistently passes at 60-70ms (was failing at 926ms due to interference)
Added
test:performanceandtest:allnpm scriptsCI workflows updated with dedicated performance test step
Execution time: 18.7s with 4 workers vs 10+ minutes serial
Reduced code duplication by using filter to inherit base config patterns
Repository Cleanup (#1287): Removed ignored files from Git tracking
Removed
.obsidian/directory (4 files) andtest-results/(3 files) from version controlFiles remain available locally but no longer tracked in repository
Follows gitignore additions from PR #1276
Flaky Test Management (#1286): Skip flaky GitHubRateLimiter tests
Marked intermittent GitHub API rate limiter tests as skipped
Prevents CI failures from external API dependencies
Tests can be run manually when needed
Chores
Repository Organization (#1276): Added
.obsidian/andtest-results/to .gitignoreDocumentation Structure (#1277): Renamed docs/archive/ to docs/session-history/
Docker Best Practices (#1273): Enhanced Docker environment file documentation
Data Directory Documentation (#1274): Added README to data/ directory
Documentation Refactor (#1270): Improved CLAUDE.md organization and clarity
âš Features
Issue Management (#1251): Added orphaned issues checker for repository maintenance
Developer Experience (#1275): Added dev-notes/ directory for personal documentation
CI Improvements: Added automated release issue verification (#1241)
Dependabot Integration (#1241): Skip Claude Code Review for Dependabot PRs
Test Results
Main suite: 2269 tests passing (performance tests excluded)
Performance suite: 62 tests passing (isolated execution)
Total: 2331 tests passing
No flaky tests remaining
CI/CD: All workflows passing across all platforms
v1.9.15 - 2025-10-01
Security patch: Zero-width Unicode bypass vulnerability + SonarCloud cleanup SECURITY FIX [HIGH]:
Block zero-width Unicode characters in metadata validation (#1228, #1229)
Prevents steganography and homograph attacks
CODE QUALITY:
228+ SonarCloud issues resolved (#1220-1224)
199 security hotspots evaluated (all safe)
Number.parseInt modernization, String.replaceAll updates
All production security concerns resolved.
v1.9.14 - 2025-09-30
đ§ Fixed
ElementFormatter Security Scanner False Positives (Issue #1211, PR #1212)
Fixed SecureYamlParser ignoring
validateContent: falseoptionPre-parse security validation now properly respects validation flag
ElementFormatter now uses
validateContent: falsefor all YAML parsing (5 locations)Allows local trusted files to bypass content scanning while maintaining security for untrusted sources
Improved memory name generation: derives names from filenames instead of auto-generated IDs
Example:
sonarcloud-rules-referenceinstead ofmem_1759077319164_w9m9fk56y
Portfolio Search File Extension Display (Issue #1213, PR #1215)
Portfolio search now displays correct file extensions based on element type
Memories show
.yamlextension, other elements show.mdextensionAdded
getFileExtension()public method to PortfolioManagerFixed hardcoded
.mdextension in search result formattingNo breaking changes, display-only fix
Code Quality
Fixed SonarCloud issues in Docker test files:
S7018: Sorted apt packages alphabetically in Dockerfile.test-enhanced
S7031: Merged consecutive RUN instructions in Dockerfile.test-enhanced
S7772: Added
node:prefix for built-in module imports (4 occurrences)S2486: Added proper error logging for JSON parse exceptions
S7780: Used String.raw for grep regex patterns (2 occurrences)
Added comprehensive test coverage for portfolio search file extensions
2,277 tests passing with >96% coverage
Documentation
Added SESSION_NOTES_2025-09-30-AFTERNOON-PR1215-SONARCLOUD-PROCEDURE.md
Added SONARCLOUD_QUERY_PROCEDURE.md - Critical guide for querying SonarCloud correctly
Updated CLAUDE.md with naming conventions and style guide for session notes and memories
v1.9.13 - 2025-09-29
đ§ Fixed
Memory System Critical Fixes (Issue #1206, PR #1207)
Fixed security scanner false positives preventing legitimate security documentation from loading
Memory files with security terms (vulnerability, exploit, attack) now load correctly
Local memory files are now pre-trusted (validateContent: false)
Added visible error reporting for failed memory loads
Users now see "Failed to load X memories" with detailed error messages
New getLoadStatus() diagnostic method for troubleshooting
New legacy memory migration tool (migrate-legacy-memories.ts)
Migrates old .md files to .yaml format in date-organized folders
Safe archiving of original files, dry-run mode by default
âš Features
CLI Utility: migrate-legacy-memories.ts for legacy file migration
Diagnostic Method: getLoadStatus() for memory loading diagnostics
Error Tracking: failedLoads tracking in MemoryManager
Code Quality
Fixed SonarCloud S3776: Reduced cognitive complexity in getLoadStatus()
Fixed SonarCloud S3358: Replaced nested ternary with if-else chain
Fixed SonarCloud S7785: Use top-level await instead of promise chain
Extracted handleLoadFailure() to eliminate code duplication
Use os.homedir() for cross-platform reliability
đ Security
Fixed DMCP-SEC-004: Added Unicode normalization to CLI input validation
v1.9.12 - 2025-09-29
đ§ Fixed
Memory System Critical Fixes
Fixed PortfolioIndexManager overwriting memory metadata during indexing (Issue #1196, PR #1197)
Memory descriptions now properly preserved instead of being replaced with "Memory element"
Fixed memory portfolio index test isolation (Issue #1194, PR #1195)
Tests now use temporary directories instead of contaminating real user portfolio
Added security validation for memory YAML parsing (size limits, type checking)
Code Quality
Fixed SonarCloud S7781: Use String#replaceAll() for modern string replacement (PR #1195)
Fixed SonarCloud S1135: Removed TODO comments, documented test isolation patterns (PR #1195)
Added ElementFormatter tool for cleaning malformed elements (Issue #1190, PR #1193)
đ Security
Added content size validation (1MB limit) for memory YAML parsing
Added type safety validation for parsed memory content
Documented security trade-offs with audit suppressions
Test Coverage
Memory portfolio index tests: 8/8 passing (was 3/8)
All tests properly isolated from user portfolio state
No regressions introduced (2260+ tests passing)
Closed Issues
#1196 - Memory metadata preservation
#1194 - Test isolation
#1190 - ElementFormatter tool
#659 - Tool execution timeout (verified fixed in earlier release)
#404 - Element system MCP exposure (verified fixed in earlier release)
#919 - Duplicate tool names (verified fixed in earlier release)
v1.9.11 - 2025-09-28
đ§ Fixed
SonarCloud Quality Improvements
Resolved S1143 violation: unsafe throw in finally block (PR #1162)
Fixed async constructor pattern in GitHubRateLimiter (PR #1161)
Addressed remaining test file reliability issues (PR #1158)
Removed SonarCloud analysis artifacts from tracking (PR #1157)
Fixed remaining source file bugs (PR #1156)
Resolved regex precedence and ReDoS vulnerabilities (PR #1155)
Fixed control character literal usage (PR #1154)
Fixed unsafe throw in finally blocks (PR #1153)
Removed hardcoded token from validation script (PR #1152)
đ Security
Fixed command injection vulnerabilities in GitHub Actions workflows (Issue #1149)
Resolved ReDoS vulnerabilities in RelationshipManager by replacing regex with string methods (Issue #1144)
đ Changed
Test Utilities: Extracted reusable permission test helpers for cross-platform compatibility
Code Quality: Achieved 82% reduction in SonarCloud reliability bugs (from 55 to 10)
Security Posture: All critical and high severity security issues resolved
v1.9.10 - 2025-09-27
âš Features
Enhanced Capability Index - Major new feature for intelligent element discovery
NLP Scoring System (PR #1091)
Jaccard similarity and Shannon entropy scoring
Advanced sampling algorithm for performance
Extensible Enhanced Index Manager architecture
Verb-based action triggers for natural language queries
Cross-Element Relationships (PR #1093)
GraphRAG-style relationship mapping between elements
Automatic discovery of element dependencies and connections
Comprehensive Trigger Extraction - Extended to all element types
Memory elements trigger extraction (PR #1133, Issue #1124)
Skills elements trigger extraction (PR #1136, Issue #1121)
Template elements trigger extraction (PR #1137, Issue #1122)
Agent elements trigger extraction (PR #1138, Issue #1123)
Comprehensive trigger extraction documentation (PR #1135)
đ§ Fixed
Enhanced Index Stability
Fixed verb extraction with comprehensive configuration support (PR #1125)
Fixed undefined metadata handling in EnhancedIndexManager (PR #1110)
Fixed loadIndex error and Docker Hub rate limits (PR #1107)
Improved type safety in relationship parsing (PR #1106, Issue #1103)
Fixed caching issues and added error boundaries (PR #1098)
Enhanced trigger validation for Skills and Memories (PR #1140, Issue #1139)
Test Infrastructure
Fixed Extended Node compatibility test failures (PR #1141, Issue #1142)
Fixed CI test failures in IndexConfig and EnhancedIndexManager (PR #1115)
Fixed CI environment tests for GitHub Actions (PR #1114)
Fixed Extended Node test failures with Node 22+ (PR #1111)
Removed dangerous restore-keys from cache configuration (PR #1109)
Added test isolation to prevent file system pollution (PR #1094, #1095)
Added memory trigger tests to ESM ignore list (PR #1134)
Skip ESM-incompatible tests in CI (PR #1130)
Code Quality
Standardized element ID parsing logic (PR #1104, Issue #1099)
Moved magic numbers to configuration (PR #1105, Issue #1100)
Fixed broken README badge links (PR #1079)
đ Changed
Performance: Enhanced Index now includes batching, caching, and memory cleanup mechanisms
Security: Added validation for configuration changes with audit logging
Documentation: Added CHANGELOG_PROCESS.md and restored lost session documentation (PR #1082, #1077)
Technical Details
The Enhanced Capability Index provides intelligent element discovery using NLP techniques
All element types now support trigger extraction for improved searchability
Comprehensive test coverage improvements and CI reliability fixes
Node 22+ compatibility fully verified and tested
v1.9.9 - 2025-09-22
âš Features
Security Utilities Module (PR #1072)
New
src/utils/securityUtils.tswith reusable security patternsPrototype pollution protection functions
Safe object creation with Object.create(null)
Secure property setting with Object.defineProperty()
Memory Auto-Repair (PR #1070)
Automatic repair of corrupted memory timestamps during read operations
No migration needed - repairs happen transparently
Enhanced sorting operations with defensive timestamp conversions
đ§ Fixed
Memory Timestamp Crashes (PR #1070)
Fixed toISOString() errors when memory entries have string timestamps (#1069)
Added comprehensive timestamp validation with detailed error reporting
Security Badge Link (PR #1071, #1075)
Fixed broken security badge link in README pointing to docs/SECURITY.md
Badge now correctly points to SECURITY.md at repository root
Prototype Pollution False Positives (PR #1072)
Added CodeQL suppressions for false positive alerts (#202-#205)
Implemented belt-and-suspenders protection to satisfy code scanners
đ Security
Added comprehensive prototype pollution protection across ConfigManager
Proper CodeQL suppressions for validated false positives
Enhanced input validation and sanitization
v1.9.8 - 2025-09-20
âš Features
Memory Deletion Support (PR #1043)
Full deletion functionality for memory elements
Handles date-based folder structure (YYYY-MM-DD)
Cleans up both YAML and optional .storage files
Deactivates memories before deletion
Fixes issue #1040
Memory Editing Support (PR #1044)
Complete edit functionality for memory elements
Fixed file extension handling (.yaml for memories, .md for others)
Supports field updates including nested properties
Version auto-increment on edits
Fixes issue #1041
Memory Validation Support (PR #1046)
Full validation functionality for memory elements
Validates metadata, retention settings, entry structure
Supports strict mode for additional quality checks
Returns detailed validation reports with errors/warnings
Fixes issue #1042
đ Changed
Code Organization: Test files moved from root directory to proper test subdirectories (PR #1047)
Manual test files now in
test/manual/Security audit reports in
.security-audit/Cleaner root directory structure
Technical Details
Memory elements now have complete CRUD + validation operations matching other element types
All memory operations properly handle the date-based folder structure
Comprehensive test coverage for all new memory operations
v1.9.7 - 2025-09-20
đ§ Fixed
NPM Package Build: Corrected v1.9.6 NPM package which was built from wrong commit
The v1.9.6 tag was created before the memory display fixes were merged
This resulted in the NPM package missing the critical memory content display fix
v1.9.7 includes all fixes that were intended for v1.9.6
Memory elements now correctly display their content instead of "No content stored"
Note
This release republishes v1.9.6 with the correct code. The memory display fix (PR #1036) and other improvements were merged to main before the v1.9.6 release but the NPM package was accidentally built from an earlier commit.
v1.9.6 - 2025-09-20
đ First External Contribution
Community Milestone: This release includes improvements from our first external contributor! Special thanks to Jeet Singh (@jeetsingh008) for identifying performance and security improvements in PR #1035.
đ§ Fixed
Memory Display Bug: Added content getter to Memory class (PR #1036)
Fixed "No content stored" issue when displaying memory elements
Memory files were being loaded but content wasn't accessible
Added proper getter method to retrieve content from entries
Resolves issue where memories appeared empty despite having content
Flaky macOS Tests: Fixed ToolCache test failures on macOS with Node 22+ (PR #1038)
Addressed race condition in directory cleanup
Added retry logic for ENOTEMPTY errors during rmdir operations
Tests now consistently pass on all platforms and Node versions
Particularly affects macOS runners with Node 22.x
Enhanced
Performance Optimization: Improved whitespace detection in memory file parsing (PR #1037)
Replaced regex-based whitespace detection with character code checks
Eliminates repeated regex evaluations during format detection
More efficient for large memory files
Improvement identified by @jeetsingh008
đ Security
Path Validation: Strengthened path traversal protection (PR #1037)
Enhanced validation checks both original and normalized paths
Adds validation before path normalization
Comprehensive protection against directory traversal attacks
Security enhancement identified by @jeetsingh008
Attribution
The performance and security improvements in this release were originally identified and proposed by Jeet Singh (@jeetsingh008) in PR #1035. While we implemented these changes internally for security review purposes, full credit goes to Jeet for these valuable contributions. Thank you for helping make DollhouseMCP better! đ
v1.9.5 - 2025-09-19
đ§ Fixed
Memory YAML Parsing: Fixed memory files not displaying correct names for pure YAML format
Memory files saved by v1.9.3+ are pure YAML without frontmatter markers
MemoryManager.load() now detects pure YAML and wraps it for SecureYamlParser compatibility
Added proper handling for nested metadata structure (data.metadata || data)
Fixed entries loading to look in correct location (parsed.data.entries)
Added edge case handling for empty memory files
Fixes issue where v1.9.3/v1.9.4 memory files showed as "Unnamed Memory"
Enhanced
Test Coverage: Added comprehensive tests for memory file format handling
Test for pure YAML files without frontmatter markers
Test for files with frontmatter (backward compatibility)
Test for empty file handling
Test for mixed formats in same directory
All 40 MemoryManager tests now passing
Technical Details
SecureYamlParser is designed for markdown files with YAML frontmatter
Memory files are pure YAML, requiring format detection and wrapping
Solution maintains backward compatibility while fixing the core issue
v1.9.4 - 2025-09-19
đ§ Fixed
Memory Name Display: Fixed memory elements showing as "Unnamed Memory" in list output
Corrected metadata parsing to use
parsed.datainstead ofparsed.metadataSecureYamlParser returns YAML frontmatter in the
dataproperty for markdown filesAdded
parseRetentionDays()helper to handle various retention formats (permanent, perpetual, "30 days")Memory files are correctly identified as .yaml format only (removed incorrect .md support)
Ensures
validateAndResolvePath()only accepts .yaml and .yml extensions for consistencyFixes PR #1030: All memory names now display correctly instead of showing "Unnamed Memory"
Technical Details
The bug was caused by incorrect property path when parsing YAML frontmatter from SecureYamlParser
Legacy .md files in memories directory are templates/schemas, not actual memory files
All real memory files are stored as .yaml in date-based folders as designed
v1.9.3 - 2025-09-19
đ§ Fixed
Memory Element MCP Support: Added complete Memory element support to all MCP tool handlers
Fixed "Unknown element type 'memories'" errors in DollhouseMCP client
Added Memory case handling to 8 critical methods in src/index.ts:
listElements: Lists available memories with retention policy and tagsactivateElement: Activates memory and shows statusgetActiveElements: Shows active memories with their tagsdeactivateElement: Deactivates memory elementsgetElementDetails: Shows comprehensive memory detailsreloadElements: Reloads memories from portfoliocreateElement: Creates new memory instances with contenteditElement: Supports editing memory properties
Memory infrastructure was already implemented but MCP tool handlers were missing the switch cases
Fixes user-reported issue with memories not working in v1.9.2
đ§ Fixed
Test Compatibility: Updated GenericElementTools test to use ensembles instead of memories
Test was expecting memories to be unsupported but they are now fully functional
Changed test to use ensembles which remain unsupported for creation/editing/validation
v1.9.2 - 2025-09-19
đ§ Fixed
Branch Synchronization: Resolved divergence between main and develop branches
Synchronized documentation updates that were only in develop
Fixed security audit suppressions path to use proper location
Ensured all v1.9.0 and v1.9.1 features are properly documented
Enhanced
Documentation: Updated README and CHANGELOG to accurately reflect all implemented features
Security Audit: Corrected suppressions file path from root to proper config location
Technical Details
Merged 58 commits from develop that were missing from main
No actual code changes to Memory element (already fully implemented in main)
Primary changes are documentation and configuration fixes
v1.9.1 - 2025-09-19
đ§ Fixed
Memory Element Support: Fixed validation and tool descriptions for memory elements
Added 'memories' to all validation arrays in index.ts
Updated browse_collection, get_collection_content, and install_collection_content tool descriptions
Fixed switch statements to handle memory element type properly
Resolves Issue #1019 where browse_collection returned "Invalid type 'memories'" error
Memory elements can now be browsed, installed, and managed through all MCP tools
Technical Details
Modified validation arrays at lines 2034, 5322, and 5394 in src/index.ts
Added memory case to element type switch statements
Updated all collection tool descriptions to include memory elements
Clean hotfix approach with cherry-picked commit from develop branch
v1.9.0 - 2025-09-17
âš Features
Memory Element Implementation: Complete memory element support with advanced features
Persistent context storage across sessions
Date-based folder organization for scalability
Search indexing with content-based retrieval
Retention policies and privacy levels
Performance optimizations for large memory sets
Enhanced
Collection Support: Full memory element support in collection browsing and installation
Portfolio System: Memory elements fully integrated with portfolio management
For complete release history prior to v1.9.0, see the GitHub Releases page.
đ License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) with Platform Stability Commitments.
What This Means
â You CAN:
Use the software for personal projects
Use the software for commercial projects
Modify the source code
Distribute the software
Use personas and elements you create
â ïž You MUST:
Include the license and copyright notice
State changes made to the code
Disclose your source code when distributing
Use the same AGPL-3.0 license for derivatives
Make network use source available (AGPL requirement)
â You CANNOT:
Hold us liable for damages
Use our trademarks without permission
Claim warranty or guarantee of fitness
Resell commercially
Platform Stability Commitments
We provide additional guarantees beyond the AGPL-3.0:
90-day advance notice for monetization policy changes
12-month revenue sharing locks for content creators
Full data portability - export all your content anytime
180-day transition period for platform ownership changes
Community advisory input on major policy decisions
Contributor License Agreement
By contributing to DollhouseMCP, you agree that:
You have the right to grant us license to your contribution
Your contribution is licensed under AGPL-3.0
You grant us additional rights to use your contribution in our commercial offerings
You retain copyright to your contribution
For the complete license text, see LICENSE.
Questions?
If you have questions about the license or what you can do with DollhouseMCP:
Documentation: License FAQ
GitHub Issue: Open an issue with the
licenselabelDiscussions: Ask in GitHub Discussions
Copyright © 2025 DollhouseMCP. All rights reserved.
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
- Open Source, Community-Powered AI Customization
- Create, Edit, and Share Customization Elements for Your AI Platforms
- Elements That Customize Your AI's Capabilities and Actions
- đŻ Element Types
- đŹ Natural Language Usage Examples
- đŠ Installation
- đ Quick Start
- âš Key Features
- đš Portfolio System
- đ Security
- đ ïž Development
- đ Architecture
- đŻ Troubleshooting
- đ€ Contributing
- đ Resources
- đ·ïž Version History
- đ License
Related MCP Servers
- -security-license-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
- Asecurity-licenseAqualityA 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 -9232168MIT License
- -security-license-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
- Asecurity-licenseAqualityA 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 -12197MIT License