@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
1,308 lines (999 loc) • 74.2 kB
Markdown
# DollhouseMCP
## Project Status
[](https://modelcontextprotocol.io)
[](https://www.npmjs.com/package/@dollhousemcp/mcp-server)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://github.com/DollhouseMCP/mcp-server/graphs/traffic)
## Build & Quality
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml)
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/build-artifacts.yml)
[](https://github.com/DollhouseMCP/mcp-server/tree/develop/test/__tests__)
[](https://github.com/DollhouseMCP/mcp-server/blob/develop/../docs/security/documentation-guide.md)
[](https://sonarcloud.io/summary/new_code?id=DollhouseMCP_mcp-server)
[](https://sonarcloud.io/summary/new_code?id=DollhouseMCP_mcp-server)
[](https://sonarcloud.io/summary/new_code?id=DollhouseMCP_mcp-server)
[](https://sonarcloud.io/summary/new_code?id=DollhouseMCP_mcp-server)
[](https://sonarcloud.io/summary/new_code?id=DollhouseMCP_mcp-server)
[](https://sonarcloud.io/summary/new_code?id=DollhouseMCP_mcp-server)
## Platform Support
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml?query=branch:main "Windows CI Build Status")
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml?query=branch:main "macOS CI Build Status")
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/core-build-test.yml?query=branch:main "Linux CI Build Status")
[](https://github.com/DollhouseMCP/mcp-server/blob/main/Dockerfile)
## Technology
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/extended-node-compatibility.yml)
[](https://github.com/DollhouseMCP/mcp-server/actions/workflows/docker-testing.yml)
---
**🌐 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
---
<div align="center">
<img src="docs/assets/dollhouse-logo.png" alt="DollhouseMCP" width="200" />
# Open Source, Community-Powered AI Customization
### Create, Edit, and Share Customization Elements for Your AI Platforms
[](https://www.npmjs.com/package/@dollhousemcp/mcp-server)
[](https://github.com/DollhouseMCP/collection)
[](https://github.com/DollhouseMCP/mcp-server#contributing)
</div>
---
## 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](docs/guides/SKILLS_CONVERTER.md)** – 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
<table>
<tr>
<td width="25%" align="center">
<h4>👨💻 For Developers</h4>
<p>Use community-powered code review personas and debugging skills. Share your language-specific optimizations.</p>
</td>
<td width="25%" align="center">
<h4>✍️ For Writers</h4>
<p>Access community-crafted writing styles and templates. Contribute your genre expertise.</p>
</td>
<td width="25%" align="center">
<h4>🎯 For Professionals</h4>
<p>Leverage community-built industry elements. Share your domain knowledge.</p>
</td>
<td width="25%" align="center">
<h4>🌟 For Everyone</h4>
<p>Give your AI any personality you want. Describe it, modify it, save it to your portfolio, share it with the world.</p>
</td>
</tr>
</table>
### Get Started
```bash
npm install @dollhousemcp/mcp-server
```
See [Quick Start](#-quick-start) for complete setup instructions.
---
## 🎯 Element Types
### ✅ Available Now
<table>
<tr>
<td width="50%">
#### 🎭 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"`
</td>
<td width="50%">
#### 💡 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"`
</td>
</tr>
<tr>
<td width="50%">
#### 📝 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"`
</td>
<td width="50%">
#### 🤖 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"`
</td>
</tr>
<tr>
<td colspan="2">
#### 🧠 Memory <span style="background-color: #4CAF50; color: white; padding: 2px 6px; border-radius: 3px; font-size: 0.8em;">NEW in v1.9.0</span>
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
</td>
</tr>
</table>
### 🚀 Coming Soon
<table>
<tr>
<td width="50%">
#### 🎯 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
</td>
<td width="50%">
#### 📋 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
</td>
</tr>
<tr>
<td width="50%">
#### 🔧 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
</td>
<td width="50%">
#### 📚 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
</td>
</tr>
</table>
## 💬 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):**
```bash
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):**
```bash
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):**
```bash
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
### Interactive Setup (Recommended)
One command opens a browser-based setup wizard with one-click install for 9 MCP clients:
```bash
npx @dollhousemcp/mcp-server@latest --web
```
Supports Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Cline, and LM Studio. Detects existing installations, auto-updating and pinned version options.
---
### Claude Code
```bash
claude mcp add -s user dollhousemcp -- npx -y @dollhousemcp/mcp-server
```
---
### Method 1: Local Installation (Recommended)
Create a dedicated folder for your MCP servers and install there:
```bash
# 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`
```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:
```json
{
"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
```bash
# Install globally (may require sudo/admin)
npm install -g @dollhousemcp/mcp-server
```
**Configure Claude Desktop:**
```json
{
"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:
```bash
# 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:**
```json
{
"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](#-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:
```bash
# 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](docs/guides/roundtrip-workflow-user-guide.md) 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](docs/guides/portfolio-setup-guide.md).
## 🔒 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:
1. **DO NOT** create a public GitHub issue
2. Open a private security advisory on GitHub
3. Include steps to reproduce if possible
4. Allow up to 48 hours for initial response
For more details, see our [Security Policy](docs/security/documentation-guide.md).
## 🛠️ Development
### Getting Started
```bash
# 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
1. **Create Feature Branch**: `git checkout -b feature/your-feature`
2. **Make Changes**: Implement your feature or fix
3. **Run Tests**: `npm test`
4. **Build**: `npm run build`
5. **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](docs/developer-guide/).
## 🏭 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
1. **Client Request** → MCP Server
2. **Tool Routing** → Appropriate handler
3. **Element Processing** → Element system
4. **Storage** → Portfolio manager
5. **Response** → Client
For detailed architecture documentation, see [Architecture Guide](docs/architecture/overview.md).
## 🔌 MCP-AQL Interface
DollhouseMCP uses **MCP-AQL** (Model Context Protocol - Agent Query Language) to expose its tools efficiently. Instead of 42 individual tools consuming ~29,600 tokens, MCP-AQL consolidates operations into semantic endpoints.
### Endpoint Modes
| Mode | Endpoints | Tokens | Reduction |
|------|-----------|--------|-----------|
| **CRUDE** (Recommended) | 5 | ~4,314 | 85% fewer tokens |
| **Single** | 1 | ~1,100 | 96% fewer tokens |
**We recommend CRUDE mode** for most deployments. The five semantic endpoints (Create, Read, Update, Delete, Execute) provide:
- **Host-level permission control** — MCP hosts like Claude Code can set different approval policies per endpoint (e.g., auto-approve `mcp_aql_read`, require confirmation for `mcp_aql_delete`). This lets you grant LLMs appropriate access levels based on operation risk.
- **Clear operation categorization** — Operations are grouped by their side effects (read-only, additive, destructive)
- **Better error messages** — Semantic endpoint mismatches provide actionable guidance
- **85% token reduction** — Only ~4,300 tokens vs ~29,600 for discrete tools
Use Single mode only when working with severely constrained context windows where every token matters.
### Configuration
DollhouseMCP uses two environment variables to control the interface:
#### Level 1: Interface Mode (`MCP_INTERFACE_MODE`)
Chooses which tool interface style to expose:
| Value | Description | Token Cost |
|-------|-------------|------------|
| `mcpaql` | MCP-AQL consolidated interface (default) | See Level 2 |
| `discrete` | ~40 individual tools (legacy) | ~29,600 tokens |
#### Level 2: Endpoint Mode (`MCP_AQL_ENDPOINT_MODE`)
**Only applies when `MCP_INTERFACE_MODE=mcpaql` (the default)**
| Value | Description | Token Cost |
|-------|-------------|------------|
| `crude` | 5 CRUDE endpoints (default, recommended) | ~4,300 tokens |
| `single` | 1 unified endpoint | ~1,100 tokens |
#### Examples
```bash
# Default: MCP-AQL with CRUDE endpoints (recommended)
# No environment variables needed - this is the default
# Minimal tokens: MCP-AQL with single endpoint
MCP_AQL_ENDPOINT_MODE=single
# Legacy: Discrete individual tools
MCP_INTERFACE_MODE=discrete
```
#### Claude Desktop Configuration
```json
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/path/to/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
"env": {
"MCP_AQL_ENDPOINT_MODE": "crude"
}
}
}
}
```
> **⚠️ Migration Note:** Earlier documentation incorrectly showed `MCP_INTERFACE_MODE=crude`. If you have this in your config, change it to `MCP_AQL_ENDPOINT_MODE=crude`. The `MCP_INTERFACE_MODE` variable only accepts `mcpaql` or `discrete`.
### CRUDE Endpoints
| Endpoint | Purpose | Example Operations |
|----------|---------|-------------------|
| `mcp_aql_create` | Add new data | `create_element`, `activate_element`, `import_element` |
| `mcp_aql_read` | Query data | `list_elements`, `get_element`, `search`, `introspect` |
| `mcp_aql_update` | Modify data | `edit_element` |
| `mcp_aql_delete` | Remove data | `delete_element`, `clear` |
| `mcp_aql_execute` | Runtime operations | `execute_agent`, `complete_execution` |
### Usage Example
```javascript
// List all personas
{ operation: "list_elements", element_type: "persona" }
// Create a new skill
{
operation: "create_element",
element_type: "skill",
params: {
element_name: "CodeReviewer",
description: "Reviews code for quality"
}
}
// Discover available operations
{ operation: "introspect", params: { query: "operations" } }
```
### Documentation
For complete MCP-AQL documentation including all operations, introspection, and debugging:
→ **[MCP-AQL Architecture Documentation](docs/architecture/mcp-aql/README.md)**
## 🎯 Troubleshooting
### Common Issues
#### MCP Server Not Connecting
**Symptoms**: Claude Desktop doesn't show DollhouseMCP in available servers
**Solutions**:
1. Verify configuration file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Check JSON syntax is valid
3. Restart Claude Desktop after configuration changes
#### OAuth Authentication Fails
**Symptoms**: Cannot authenticate with GitHub
**Solutions**:
1. Check internet connection
2. Verify GitHub account has proper permissions
3. Try using Personal Access Token instead:
```bash
export GITHUB_TOKEN=your_pat_token
```
4. Clear cached credentials and retry
#### Elements Not Loading
**Symptoms**: Portfolio appears empty
**Solutions**:
1. Check portfolio directory exists: `~/.dollhouse/portfolio/`
2. Verify file permissions
3. Run `list_portfolio_elements` tool to diagnose
4. Check element file format (YAML frontmatter required)
#### Performance Issues
**Symptoms**: Slow response times
**Solutions**:
1. Check portfolio size (large portfolios may be slow)
2. Verify adequate system resources
3. Consider using pagination for large lists
4. Check network latency for GitHub operations
### Getting Help
- **Documentation**: [Full docs](https://github.com/DollhouseMCP/mcp-server/tree/main/docs)
- **Issues**: [GitHub Issues](https://github.com/DollhouseMCP/mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/DollhouseMCP/mcp-server/discussions)
For detailed troubleshooting, see [Troubleshooting Guide](docs/troubleshooting/).
## 🤝 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
1. **Fork the Repository**
```bash
gh repo fork DollhouseMCP/mcp-server
```
2. **Create Feature Branch**
```bash
git checkout -b feature/your-feature
```
3. **Make Changes**
- Follow existing code style
- Add tests for new functionality
- Update documentation
4. **Test Thoroughly**
```bash
npm test
npm run lint
npm run typecheck
```
5. **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
1. Automated CI checks must pass
2. Code review by maintainers
3. Address feedback
4. Merge when approved
For detailed guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
## 📚 Resources
### Documentation
- **[Quick Start Guide](docs/guides/getting-started.md)** - Get up and running quickly
- **[Portfolio Setup](docs/guides/portfolio-setup-guide.md)** - Configure your portfolio
- **[Element Development](docs/developer-guide/element-development.md)** - Create custom elements
- **[API Reference](docs/reference/api-reference.md)** - Complete tool documentation
- **[Architecture Guide](docs/architecture/overview.md)** - System design details
- **[Security Documentation](docs/security/documentation-guide.md)** - Security measures and best practices
### Repositories
- **[Main Repository](https://github.com/DollhouseMCP/mcp-server)** - Core MCP server
- **[Collection](https://github.com/DollhouseMCP/collection)** - Community elements
- **[Developer Kit](https://github.com/DollhouseMCP/developer-kit)** - Development tools
### Community
- **[GitHub Discussions](https://github.com/DollhouseMCP/mcp-server/discussions)** - Q&A and ideas
- **[GitHub Issues](https://github.com/DollhouseMCP/mcp-server/issues)** - Bug reports and features
- **[Discord Server](#)** - Real-time chat (coming soon)
### External Resources
- **[Model Context Protocol](https://modelcontextprotocol.io)** - MCP specification
- **[Claude Desktop](https://claude.ai/download)** - AI assistant with MCP support
- **[Anthropic Documentation](https://docs.anthropic.com)** - 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](https://github.com/DollhouseMCP/mcp-server/issues)
- **Security Issues**: [Private security advisories](https://github.com/DollhouseMCP/mcp-server/security/advisories)
- **Discussions**: [Community Q&A](https://github.com/DollhouseMCP/mcp-server/discussions)
## 🏷️ Version History
### 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.21.0
- 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:
1. Permission check against GitHub org name (`io.github.DollhouseMCP/*`)
2. 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
- Remote telemetry piggybacks on the new opt‑in controls (details in the next bullet):
- First enable local telemetry with `DOLLHOUSE_TELEMETRY=true`
- Then opt into remote analytics with `DOLLHOUSE_TELEMETRY_OPTIN=true`
- Use `DOLLHOUSE_TELEMETRY_NO_REMOTE=true` to force local-only even when telemetry is enabled
- Set `DOLLHOUSE_TELEMETRY=false` (or leave it unset) to disable everything
- GDPR compliant - fully opt-in by design
- See [docs/privacy/OPERATIONAL_TELEMETRY.md](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) **after you opt in**
- Local-only logging to `~/.dollhouse/telemetry.log` when `DOLLHOUSE_TELEMETRY=true`
- Simple opt-in/out via `DOLLHOUSE_TELEMETRY=true|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 duplicati