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

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

👨‍💻 For Developers

Use community-powered code review personas and debugging skills. Share your language-specific optimizations.

✍️ For Writers

Access community-crafted writing styles and templates. Contribute your genre expertise.

🎯 For Professionals

Leverage community-built industry elements. Share your domain knowledge.

🌟 For Everyone

Give your AI any personality you want. Describe it, modify it, save it to your portfolio, share it with the world.

Get Started

npm install @dollhousemcp/mcp-server

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):

browse_collection type="personas"
search_collection "creative writing"
install_content "personas/storyteller.md"

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):

portfolio_status
list_elements type="personas"
sync_portfolio
search_portfolio "marketing"

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):

activate_element "code-reviewer" type="personas"
get_active_elements
deactivate_element type="personas"
get_element_details "data-analyst" type="skills"
create_element type="personas" name="customer-support"

Complete Workflow Example

Here's how a typical session might look:

You: "I need help with creative writing"
Assistant: "I'll help you with creative writing. Let me check what personas are available..."

You: "Show me creative writing personas in the collection"
Assistant: [Shows list of available creative writing personas]

You: "Install and activate the storyteller persona"
Assistant: "I've installed and activated the Storyteller persona. I'm now ready to help craft engaging narratives..."

You: "Actually, let me create my own persona for science fiction writing"
Assistant: "I'll help you create a custom science fiction writing persona. What characteristics would you like?"

You: "Make it focus on hard sci-fi with attention to scientific accuracy"
Assistant: [Creates custom persona with specified traits]

You: "Save that to my portfolio as 'Hard SciFi Writer'"
Assistant: "I've saved 'Hard SciFi Writer' to your portfolio. You can activate it anytime."

Pro Tips

Be conversational: "Help me write better code" works as well as specific commands
Stack 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	Best For	Pros	Cons
Local Install (Recommended)	Most users, multiple configs, customization	✅ Multiple setups ✅ Easy backup ✅ No permissions	❌ Longer path in config
npx	Quick testing, always latest	✅ No install ✅ Always updated	❌ Slower startup ❌ Needs internet
Global Install	Single shared instance	✅ Short command	❌ Only one version ❌ Needs sudo/admin

Method 1: Local Installation (Recommended)

Create a dedicated folder for your MCP servers and install there:

# Create MCP servers directory
mkdir ~/mcp-servers
cd ~/mcp-servers

# Install DollhouseMCP
npm install @dollhousemcp/mcp-server

Configure Claude Desktop:

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/mcp-servers/node_modules/@dollhousemcp/mcp-server/dist/index.js"]
    }
  }
}

💡 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:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "npx",
      "args": ["@dollhousemcp/mcp-server@latest"]
    }
  }
}

📝 Note: The @latest tag ensures you always get the newest version. Remove it to use npm's cached version.

Method 3: Global Installation

# Install globally (may require sudo/admin)
npm install -g @dollhousemcp/mcp-server

Configure Claude Desktop:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "dollhousemcp"
    }
  }
}

⚠️ 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:

# Personal assistant
mkdir ~/mcp-servers/personal
cd ~/mcp-servers/personal
npm install @dollhousemcp/mcp-server

# Work assistant
mkdir ~/mcp-servers/work
cd ~/mcp-servers/work
npm install @dollhousemcp/mcp-server

# Creative writing
mkdir ~/mcp-servers/creative
cd ~/mcp-servers/creative
npm install @dollhousemcp/mcp-server

Configure each with its own portfolio:

{
  "mcpServers": {
    "dollhouse-personal": {
      "command": "node",
      "args": ["/Users/YOU/mcp-servers/personal/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
      "env": {
        "DOLLHOUSE_PORTFOLIO_DIR": "/Users/YOU/portfolios/personal"
      }
    },
    "dollhouse-work": {
      "command": "node",
      "args": ["/Users/YOU/mcp-servers/work/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
      "env": {
        "DOLLHOUSE_PORTFOLIO_DIR": "/Users/YOU/portfolios/work"
      }
    }
  }
}

Now you can enable/disable different configurations in Claude Desktop as needed!

✅ Verify Installation

After configuring and restarting Claude Desktop, test with:

list_elements type="personas"

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:

# Browse available personas
list_elements type="personas"

# Activate a persona
activate_element name="creative-writer" type="personas"

# Browse the community collection
browse_collection type="personas"

# Search for specific content
search_collection query="python" type="skills"

📘 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: `{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 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:

~/.dollhouse/portfolio/
├── personas/       # Behavioral profiles (Markdown files)
├── skills/         # Discrete capabilities (Markdown files)
├── templates/      # Reusable content structures (Markdown files)
├── agents/         # Goal-oriented actors (Markdown files)
├── memories/       # Persistent context (YAML files with date folders)
│   ├── 2025-09-18/
│   │   └── project-context.yaml
│   └── 2025-09-19/
│       ├── meeting-notes.yaml
│       └── code-review.yaml
└── ensembles/      # Element combinations (Markdown files)

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 types
sync_portfolio - Synchronize with GitHub
upload_to_portfolio - Share elements with the community
download_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

# Clone the repository
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Development Workflow

Create Feature Branch: git checkout -b feature/your-feature
Make Changes: Implement your feature or fix
Run Tests: npm test
Build: npm run build
Submit PR: Create pull request to develop branch

Available Scripts

npm run build - Compile TypeScript
npm run dev - Development mode with watch
npm test - Run test suite
npm run lint - Check code style
npm run typecheck - TypeScript type checking

Project Structure

src/
├── index.ts           # Main server entry
├── tools/            # MCP tool implementations
├── utils/            # Utility functions
├── types/            # TypeScript definitions
└── elements/         # Element system

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.json
- Windows: %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_token
```
Clear cached credentials and retry

Elements Not Loading

Symptoms: Portfolio appears empty

Solutions:

Check portfolio directory exists: ~/.dollhouse/portfolio/
Verify file permissions
Run list_portfolio_elements tool to diagnose
Check 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-server
```
Create Feature Branch
```
git checkout -b feature/your-feature
```
Make Changes
- Follow existing code style
- Add tests for new functionality
- Update documentation

Test Thoroughly

npm test
npm run lint
npm run typecheck

Submit Pull Request
- Target the develop branch
- Provide 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 feature
fix: Bug fix
docs: Documentation
test: Testing
chore: 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.27 - 2025-12-05

Patch Release: Dependency Updates & Bug Fixes

📦 Dependencies

express 5.1.0 → 5.2.1
posthog-node 5.11.0 → 5.14.1
tsx 4.20.6 → 4.21.0
zod 4.1.12 → 4.1.13
jsdom 27.0.0 → 27.2.0
@types/node 24.10.0 → 24.10.1

🐛 Bug Fixes

Jest ESM compatibility for jsdom nested modules (#1515, #1516)

🔒 Security

MCP SDK already updated to 1.24.0 in v1.9.26-hotfix (CVE-2025-66414)

v1.9.26 - 2025-11-07

Major Feature Release: Element Source Priority System & Critical Bug Fixes

✨ Features

Element Source Priority System (#1451-#1456) 🌟
- Intelligent element selection based on configurable source priority
- Priority levels: local (highest) → github → collection (lowest)
- User-facing API for configuration via dollhouse_config tool
- Automatic conflict resolution for duplicate elements
- Search and installation integration
- Configuration persistence to ~/.dollhouse/config.yaml

🐛 Bug Fixes

Memory Content Preservation (#1442) - Fixed data loss during YAML parsing
VerbTriggerManager Critical Bugs (#1443) - Fixed verb trigger extraction reliability
OAuth Terminal Error Propagation (#1444) - RFC 6749/8628 compliance for device flow
GitHubAuthManager Test Mocks (#1459) - Fixed 8 test failures from incomplete mocks

🔧 Technical

jsdom rollback to 27.0.0 for stability (#1458)
SonarCloud badges restored to README chunk file

📦 Dependencies

@modelcontextprotocol/sdk 1.20.2 → 1.24.0 (security update for CVE-2025-66414)
posthog-node 5.10.3 → 5.11.0
@types/archiver 6.0.4 → 7.0.0
@types/node 24.9.1 → 24.10.0

v1.9.25 - 2025-10-30

Major Feature Release: Auto-Load Baseline Memories & Production Stability

✨ Features

Auto-Load Baseline Memories (#1430, #1431) 🌟
- Self-aware DollhouseMCP: Server loads baseline knowledge automatically on startup
- Eliminates 20-40k token searches - now instant with zero search
- Users can mark ANY memory for auto-load via autoLoad: true metadata flag
- Priority-based loading system with configurable token budget
- Includes seed memory: dollhousemcp-baseline-knowledge.yaml (~2500 tokens)
- Configuration via ~/.dollhouse/config.yaml
- Token estimate caching (~50% performance improvement)
- 3 new seed memory guides for custom auto-load memories

🐛 Bug Fixes (CRITICAL)

Extended Node Compatibility CI Failures (#1432-#1434)
- Fixed ALL 6 platforms (Ubuntu/macOS/Windows × Node 20.x/22.x)
- Root cause: JSDOM/parse5 ESM race condition during Jest teardown
- 19 test files broken - now ALL passing ✅
- Platform-specific memory thresholds for Windows Node 22.x
README Badge Issues (#1432, #1435)
- Restored 6 SonarCloud quality metrics badges
- Fixed Extended Node Compatibility and Docker Testing badge URLs
- All badges now point to develop branch

🔧 Technical

LICENSE synchronization with main (763-line monolithic structure)
Jest configuration optimization with maxConcurrency: 1
Comprehensive documentation updates

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.md
- Feature → develop: SQUASH merge (clean history)
- Develop → main: REGULAR merge (preserves commits)

🔄 Dependency Updates

@modelcontextprotocol/sdk 1.20.1 → 1.20.2
posthog-node 5.10.0 → 5.10.3
jsdom 27.0.0 → 27.0.1 (dev)
@types/node 24.8.1 → 24.9.1 (dev)
@modelcontextprotocol/inspector 0.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-anthropic
- Automatic 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.ts to reformat blob content elements
- Fixes 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.js minVersion 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 mcpName field in package.json to match GitHub organization capitalization
- Changed from io.github.dollhousemcp/mcp-server to io.github.DollhouseMCP/mcp-server
- Resolves 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 mcpName field in package.json The initial implementation incorrectly used lowercase for mcpName, 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=true to enable remote telemetry
- Uses shared PostHog project for community-wide insights
- Default PostHog project key embedded (safe to expose - write-only)
- Backward compatible with custom POSTHOG_API_KEY for enterprise deployments
- Multiple control levels:
  - DOLLHOUSE_TELEMETRY_OPTIN=true - Enable remote telemetry
  - DOLLHOUSE_TELEMETRY_NO_REMOTE=true - Local only, no PostHog
  - DOLLHOUSE_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.md
- Research document at docs/development/MCP_RESOURCES_SUPPORT_RESEARCH_2025-10-16.md
- Configuration options: resources.enabled, resources.expose[], resources.cache_ttl
- Early 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.log by default
- Simple opt-out via DOLLHOUSE_TELEMETRY=false environment variable
- Privacy-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.cjs with 4 parallel workers
- Main 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:performance and test:all npm scripts
- CI 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) and test-results/ (3 files) from version control
- Files 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/ and test-results/ to .gitignore
Documentation 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: false option
- Pre-parse security validation now properly respects validation flag
- ElementFormatter now uses validateContent: false for 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-reference instead of mem_1759077319164_w9m9fk56y
Portfolio Search File Extension Display (Issue #1213, PR #1215)
- Portfolio search now displays correct file extensions based on element type
- Memories show .yaml extension, other elements show .md extension
- Added getFileExtension() public method to PortfolioManager
- Fixed hardcoded .md extension in search result formatting
- No 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.ts with reusable security patterns
- Prototype 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.data instead of parsed.metadata
- SecureYamlParser returns YAML frontmatter in the data property for markdown files
- Added 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 consistency
- Fixes 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 tags
  - activateElement: Activates memory and shows status
  - getActiveElements: Shows active memories with their tags
  - deactivateElement: Deactivates memory elements
  - getElementDetails: Shows comprehensive memory details
  - reloadElements: Reloads memories from portfolio
  - createElement: Creates new memory instances with content
  - editElement: 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 license label
Discussions: Ask in GitHub Discussions

DollhouseMCP

Project Status

Build & Quality

Platform Support

Technology

Open Source, Community-Powered AI Customization

Elements That Customize Your AI's Capabilities and Actions

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.

→ 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

👨‍💻 For Developers

Use community-powered code review personas and debugging skills. Share your language-specific optimizations.

✍️ For Writers

Access community-crafted writing styles and templates. Contribute your genre expertise.

🎯 For Professionals

Leverage community-built industry elements. Share your domain knowledge.

🌟 For Everyone

Give your AI any personality you want. Describe it, modify it, save it to your portfolio, share it with the world.

Get Started

npm install @dollhousemcp/mcp-server

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):

browse_collection type="personas"
search_collection "creative writing"
install_content "personas/storyteller.md"

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):

portfolio_status
list_elements type="personas"
sync_portfolio
search_portfolio "marketing"

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):

activate_element "code-reviewer" type="personas"
get_active_elements
deactivate_element type="personas"
get_element_details "data-analyst" type="skills"
create_element type="personas" name="customer-support"

Complete Workflow Example

Here's how a typical session might look:

You: "I need help with creative writing"
Assistant: "I'll help you with creative writing. Let me check what personas are available..."

You: "Show me creative writing personas in the collection"
Assistant: [Shows list of available creative writing personas]

You: "Install and activate the storyteller persona"
Assistant: "I've installed and activated the Storyteller persona. I'm now ready to help craft engaging narratives..."

You: "Actually, let me create my own persona for science fiction writing"
Assistant: "I'll help you create a custom science fiction writing persona. What characteristics would you like?"

You: "Make it focus on hard sci-fi with attention to scientific accuracy"
Assistant: [Creates custom persona with specified traits]

You: "Save that to my portfolio as 'Hard SciFi Writer'"
Assistant: "I've saved 'Hard SciFi Writer' to your portfolio. You can activate it anytime."

Pro Tips

Be conversational: "Help me write better code" works as well as specific commands
Stack 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	Best For	Pros	Cons
Local Install (Recommended)	Most users, multiple configs, customization	✅ Multiple setups ✅ Easy backup ✅ No permissions	❌ Longer path in config
npx	Quick testing, always latest	✅ No install ✅ Always updated	❌ Slower startup ❌ Needs internet
Global Install	Single shared instance	✅ Short command	❌ Only one version ❌ Needs sudo/admin

Method 1: Local Installation (Recommended)

Create a dedicated folder for your MCP servers and install there:

# Create MCP servers directory
mkdir ~/mcp-servers
cd ~/mcp-servers

# Install DollhouseMCP
npm install @dollhousemcp/mcp-server

Configure Claude Desktop:

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/mcp-servers/node_modules/@dollhousemcp/mcp-server/dist/index.js"]
    }
  }
}

💡 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:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "npx",
      "args": ["@dollhousemcp/mcp-server@latest"]
    }
  }
}

📝 Note: The @latest tag ensures you always get the newest version. Remove it to use npm's cached version.

Method 3: Global Installation

# Install globally (may require sudo/admin)
npm install -g @dollhousemcp/mcp-server

Configure Claude Desktop:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "dollhousemcp"
    }
  }
}

⚠️ 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:

# Personal assistant
mkdir ~/mcp-servers/personal
cd ~/mcp-servers/personal
npm install @dollhousemcp/mcp-server

# Work assistant
mkdir ~/mcp-servers/work
cd ~/mcp-servers/work
npm install @dollhousemcp/mcp-server

# Creative writing
mkdir ~/mcp-servers/creative
cd ~/mcp-servers/creative
npm install @dollhousemcp/mcp-server

Configure each with its own portfolio:

{
  "mcpServers": {
    "dollhouse-personal": {
      "command": "node",
      "args": ["/Users/YOU/mcp-servers/personal/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
      "env": {
        "DOLLHOUSE_PORTFOLIO_DIR": "/Users/YOU/portfolios/personal"
      }
    },
    "dollhouse-work": {
      "command": "node",
      "args": ["/Users/YOU/mcp-servers/work/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
      "env": {
        "DOLLHOUSE_PORTFOLIO_DIR": "/Users/YOU/portfolios/work"
      }
    }
  }
}

Now you can enable/disable different configurations in Claude Desktop as needed!

✅ Verify Installation

After configuring and restarting Claude Desktop, test with:

list_elements type="personas"

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:

# Browse available personas
list_elements type="personas"

# Activate a persona
activate_element name="creative-writer" type="personas"

# Browse the community collection
browse_collection type="personas"

# Search for specific content
search_collection query="python" type="skills"

📘 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: `{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 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:

~/.dollhouse/portfolio/
├── personas/       # Behavioral profiles (Markdown files)
├── skills/         # Discrete capabilities (Markdown files)
├── templates/      # Reusable content structures (Markdown files)
├── agents/         # Goal-oriented actors (Markdown files)
├── memories/       # Persistent context (YAML files with date folders)
│   ├── 2025-09-18/
│   │   └── project-context.yaml
│   └── 2025-09-19/
│       ├── meeting-notes.yaml
│       └── code-review.yaml
└── ensembles/      # Element combinations (Markdown files)

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 types
sync_portfolio - Synchronize with GitHub
upload_to_portfolio - Share elements with the community
download_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

# Clone the repository
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Development Workflow

Create Feature Branch: git checkout -b feature/your-feature
Make Changes: Implement your feature or fix
Run Tests: npm test
Build: npm run build
Submit PR: Create pull request to develop branch

Available Scripts

npm run build - Compile TypeScript
npm run dev - Development mode with watch
npm test - Run test suite
npm run lint - Check code style
npm run typecheck - TypeScript type checking

Project Structure

src/
├── index.ts           # Main server entry
├── tools/            # MCP tool implementations
├── utils/            # Utility functions
├── types/            # TypeScript definitions
└── elements/         # Element system

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.json
- Windows: %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_token
```
Clear cached credentials and retry

Elements Not Loading

Symptoms: Portfolio appears empty

Solutions:

Check portfolio directory exists: ~/.dollhouse/portfolio/
Verify file permissions
Run list_portfolio_elements tool to diagnose
Check 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-server
```
Create Feature Branch
```
git checkout -b feature/your-feature
```
Make Changes
- Follow existing code style
- Add tests for new functionality
- Update documentation

Test Thoroughly

npm test
npm run lint
npm run typecheck

Submit Pull Request
- Target the develop branch
- Provide 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 feature
fix: Bug fix
docs: Documentation
test: Testing
chore: 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.27 - 2025-12-05

Patch Release: Dependency Updates & Bug Fixes

📦 Dependencies

express 5.1.0 → 5.2.1
posthog-node 5.11.0 → 5.14.1
tsx 4.20.6 → 4.21.0
zod 4.1.12 → 4.1.13
jsdom 27.0.0 → 27.2.0
@types/node 24.10.0 → 24.10.1

🐛 Bug Fixes

Jest ESM compatibility for jsdom nested modules (#1515, #1516)

🔒 Security

MCP SDK already updated to 1.24.0 in v1.9.26-hotfix (CVE-2025-66414)

v1.9.26 - 2025-11-07

Major Feature Release: Element Source Priority System & Critical Bug Fixes

✨ Features

Element Source Priority System (#1451-#1456) 🌟
- Intelligent element selection based on configurable source priority
- Priority levels: local (highest) → github → collection (lowest)
- User-facing API for configuration via dollhouse_config tool
- Automatic conflict resolution for duplicate elements
- Search and installation integration
- Configuration persistence to ~/.dollhouse/config.yaml

🐛 Bug Fixes

Memory Content Preservation (#1442) - Fixed data loss during YAML parsing
VerbTriggerManager Critical Bugs (#1443) - Fixed verb trigger extraction reliability
OAuth Terminal Error Propagation (#1444) - RFC 6749/8628 compliance for device flow
GitHubAuthManager Test Mocks (#1459) - Fixed 8 test failures from incomplete mocks

🔧 Technical

jsdom rollback to 27.0.0 for stability (#1458)
SonarCloud badges restored to README chunk file

📦 Dependencies

@modelcontextprotocol/sdk 1.20.2 → 1.24.0 (security update for CVE-2025-66414)
posthog-node 5.10.3 → 5.11.0
@types/archiver 6.0.4 → 7.0.0
@types/node 24.9.1 → 24.10.0

v1.9.25 - 2025-10-30

Major Feature Release: Auto-Load Baseline Memories & Production Stability

✨ Features

Auto-Load Baseline Memories (#1430, #1431) 🌟
- Self-aware DollhouseMCP: Server loads baseline knowledge automatically on startup
- Eliminates 20-40k token searches - now instant with zero search
- Users can mark ANY memory for auto-load via autoLoad: true metadata flag
- Priority-based loading system with configurable token budget
- Includes seed memory: dollhousemcp-baseline-knowledge.yaml (~2500 tokens)
- Configuration via ~/.dollhouse/config.yaml
- Token estimate caching (~50% performance improvement)
- 3 new seed memory guides for custom auto-load memories

🐛 Bug Fixes (CRITICAL)

Extended Node Compatibility CI Failures (#1432-#1434)
- Fixed ALL 6 platforms (Ubuntu/macOS/Windows × Node 20.x/22.x)
- Root cause: JSDOM/parse5 ESM race condition during Jest teardown
- 19 test files broken - now ALL passing ✅
- Platform-specific memory thresholds for Windows Node 22.x
README Badge Issues (#1432, #1435)
- Restored 6 SonarCloud quality metrics badges
- Fixed Extended Node Compatibility and Docker Testing badge URLs
- All badges now point to develop branch

🔧 Technical

LICENSE synchronization with main (763-line monolithic structure)
Jest configuration optimization with maxConcurrency: 1
Comprehensive documentation updates

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.md
- Feature → develop: SQUASH merge (clean history)
- Develop → main: REGULAR merge (preserves commits)

🔄 Dependency Updates

@modelcontextprotocol/sdk 1.20.1 → 1.20.2
posthog-node 5.10.0 → 5.10.3
jsdom 27.0.0 → 27.0.1 (dev)
@types/node 24.8.1 → 24.9.1 (dev)
@modelcontextprotocol/inspector 0.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-anthropic
- Automatic 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.ts to reformat blob content elements
- Fixes 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.js minVersion 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

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 mcpName field in package.json to match GitHub organization capitalization
- Changed from io.github.dollhousemcp/mcp-server to io.github.DollhouseMCP/mcp-server
- Resolves 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 mcpName field in package.json The initial implementation incorrectly used lowercase for mcpName, 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=true to enable remote telemetry
- Uses shared PostHog project for community-wide insights
- Default PostHog project key embedded (safe to expose - write-only)
- Backward compatible with custom POSTHOG_API_KEY for enterprise deployments
- Multiple control levels:
  - DOLLHOUSE_TELEMETRY_OPTIN=true - Enable remote telemetry
  - DOLLHOUSE_TELEMETRY_NO_REMOTE=true - Local only, no PostHog
  - DOLLHOUSE_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.md
- Research document at docs/development/MCP_RESOURCES_SUPPORT_RESEARCH_2025-10-16.md
- Configuration options: resources.enabled, resources.expose[], resources.cache_ttl
- Early 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.log by default
- Simple opt-out via DOLLHOUSE_TELEMETRY=false environment variable
- Privacy-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.cjs with 4 parallel workers
- Main 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:performance and test:all npm scripts
- CI 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) and test-results/ (3 files) from version control
- Files 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/ and test-results/ to .gitignore
Documentation 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: false option
- Pre-parse security validation now properly respects validation flag
- ElementFormatter now uses validateContent: false for 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-reference instead of mem_1759077319164_w9m9fk56y
Portfolio Search File Extension Display (Issue #1213, PR #1215)
- Portfolio search now displays correct file extensions based on element type
- Memories show .yaml extension, other elements show .md extension
- Added getFileExtension() public method to PortfolioManager
- Fixed hardcoded .md extension in search result formatting
- No 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.ts with reusable security patterns
- Prototype 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

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

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.data instead of parsed.metadata
- SecureYamlParser returns YAML frontmatter in the data property for markdown files
- Added 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 consistency
- Fixes 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 tags
  - activateElement: Activates memory and shows status
  - getActiveElements: Shows active memories with their tags
  - deactivateElement: Deactivates memory elements
  - getElementDetails: Shows comprehensive memory details
  - reloadElements: Reloads memories from portfolio
  - createElement: Creates new memory instances with content
  - editElement: 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 license label
Discussions: Ask in GitHub Discussions

DollhouseMCP

DollhouseMCP

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

What Are Customization Elements?

Core Capabilities

Claude Skills Compatibility

Use Cases

👨‍💻 For Developers

✍️ For Writers

🎯 For Professionals

🌟 For Everyone

Get Started

🎯 Element Types

✅ Available Now

🎭 Personas

💡 Skills

📝 Templates

🤖 Agents

🧠 Memory NEW in v1.9.0

🚀 Coming Soon

🎯 Ensembles

📋 Prompts

🔧 Tools

📚 Memory Enhancements

💬 Natural Language Usage Examples

Importing from the Community Collection

Managing Your Portfolio

Working with Elements

Complete Workflow Example

Pro Tips

📦 Installation

Choose Your Installation Method

Method 1: Local Installation (Recommended)

Method 2: Always Latest with npx

Method 3: Global Installation

🎯 Advanced: Multiple Configurations

✅ Verify Installation

📁 Default Portfolio Location

🚀 Quick Start

✨ Key Features

🎨 Portfolio System

Portfolio Structure

Key Features

Portfolio Management Tools

🔒 Security

Security Features

Security Testing

Reporting Security Issues

🛠️ Development

Getting Started

Development Workflow

Available Scripts

Project Structure

🏭 Architecture

System Overview

Core Components

MCP Server

Element System

Portfolio Manager

Security Layer

Data Flow

🎯 Troubleshooting

Common Issues

MCP Server Not Connecting

OAuth Authentication Fails

Elements Not Loading

Performance Issues

Getting Help

🤝 Contributing

Ways to Contribute

Development Process

Code Style

Commit Messages

Review Process