DollhouseMCP

Platform Support

A comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management with an integrated GitHub-powered marketplace. DollhouseMCP allows Claude and other compatible AI assistants to activate different behavioral personas while supporting community sharing and monetization.

🌐 Repository: https://github.com/DollhouseMCP/mcp-server
🏪 Marketplace: https://github.com/DollhouseMCP/personas
📦 NPM Package: https://www.npmjs.com/package/@mickdarling/dollhousemcp
🌍 Website: https://dollhousemcp.com (planned)
📦 Version: v1.2.4 - MCP Protocol Compatibility Fix

🚀 Quick Start

# Install globally
npm install -g @mickdarling/dollhousemcp

# Add to Claude Desktop config (see path below for your OS)
# 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": "npx",
      "args": ["@mickdarling/dollhousemcp"]
    }
  }
}

Restart Claude Desktop and you're ready to use DollhouseMCP! Try list_personas to get started.

✨ Key Features

Feature	Description
🎭 23 MCP Tools	Complete persona lifecycle management through chat interface
🏪 GitHub Marketplace	Browse, search, install, and submit personas to community marketplace
👤 User Identity System	Environment-based attribution for persona creators
🆔 Unique ID System	Advanced ID generation: `what-it-is_YYYYMMDD-HHMMSS_who-made-it`
💬 Chat-Based Management	Create, edit, and validate personas through conversational interface
🔄 Real-time Operations	Live editing with automatic version bumping and validation
🚀 Auto-Update System	Enterprise-grade auto-update with backup/rollback and dependency validation
🛡️ Data Protection	Copy-on-write for default personas, comprehensive backup system
🏠 Local-First Architecture	Full functionality without cloud dependency

🔒 Enterprise-Grade Security (v1.2.4)

DollhouseMCP implements comprehensive security measures to protect your personas and system:

Security Features

🛡️ Content Sanitization: DOMPurify integration prevents XSS attacks in persona content
📝 YAML Injection Prevention: Secure parsing with schema validation and size limits
🔐 Token Security: GitHub tokens are validated, encrypted at rest, with rotation support
🐳 Container Hardening: Non-root execution, read-only filesystem, resource limits
🚦 Rate Limiting: Token bucket algorithm prevents API abuse (10 checks/hour default)
✅ Signature Verification: GPG verification ensures release authenticity
🔍 Input Validation: Comprehensive validation for all user inputs
📊 Security Monitoring: Audit logging for security-relevant operations

Security Testing

487 comprehensive tests including security-specific test suites
Continuous security scanning with GitHub Advanced Security
Vulnerability-free: All security alerts resolved (0 active)

📋 Prerequisites

Node.js: v20.0.0 or higher (LTS recommended)
npm: v10.0.0 or higher
git: For cloning the repository
Operating System: Windows, macOS, or Linux

Note: DollhouseMCP is developed on Node.js 24 but supports Node.js 20+ for broad compatibility.

🚀 Quick Start

Installation

NPM Installation (NEW! - Recommended)

npm install -g @mickdarling/dollhousemcp

After installation, add DollhouseMCP to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "npx",
      "args": ["@mickdarling/dollhousemcp"]
    }
  }
}

Note: If you have other MCP servers configured, add dollhousemcp to your existing mcpServers object.

Automated Setup (Alternative) - Claude Desktop Only

Warning

Claude Desktop Only: The automated setup script is specifically designed for Claude Desktop integration. If you're using Claude Code, other AI platforms (ChatGPT, BoltAI, Gemini, etc.), or custom MCP implementations, please use the Manual Installation process below.

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

# Run automated setup script (Claude Desktop only)
./setup.sh

The setup script will:

📦 Install all dependencies
🔨 Build the TypeScript code
📍 Detect your installation path
🔧 Generate the exact Claude Desktop configuration
📋 Provide step-by-step setup instructions

Manual Installation

Note: Manual installation works with all MCP-compatible platforms including Claude Desktop, Claude Code, ChatGPT, BoltAI, Gemini, and custom implementations.

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

# Install dependencies and build
npm install
npm run build

# Optional: Set user identity for persona attribution
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"

Claude Desktop Configuration

Add DollhouseMCP to your Claude Desktop configuration:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

For NPM Installation:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "npx",
      "args": ["@mickdarling/dollhousemcp"]
    }
  }
}

For Source Installation:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
    }
  }
}

🔄 After configuration:

Save the file
Restart Claude Desktop completely
All 23 DollhouseMCP tools will be available

🛠️ Available Tools (23 Total)

Core Persona Management

list_personas - Display all local personas with enhanced metadata
activate_persona - Activate by name, filename, or unique ID
get_active_persona - Get current persona information
deactivate_persona - Return to default mode
get_persona_details - View complete persona details
reload_personas - Refresh from filesystem

GitHub Marketplace Integration

browse_marketplace - Browse personas by category
search_marketplace - Search across all marketplace personas
get_marketplace_persona - View detailed marketplace persona info
install_persona - One-click download and installation
submit_persona - Submit to marketplace via GitHub issue

User Identity Management

set_user_identity - Set username for persona attribution
get_user_identity - View current identity status
clear_user_identity - Return to anonymous mode

Chat-Based Persona Management

create_persona - Guided persona creation through chat
edit_persona - Modify existing persona fields
validate_persona - Comprehensive quality validation

Auto-Update System

check_for_updates - Check GitHub releases for available DollhouseMCP updates
update_server - Automated git pull + npm install + build with backup creation
rollback_update - Restore previous version from automatic backups
get_server_status - Comprehensive server status with version, git info, and system details

Persona Indicators

configure_indicator - Configure how persona indicators appear in AI responses
get_indicator_config - View current indicator configuration settings

📖 Usage Examples

Marketplace Operations

browse_marketplace                          # See all categories
browse_marketplace "creative"               # Browse creative personas
search_marketplace "writing"                # Search for writing personas
install_persona "creative/storyteller.md"  # Install from marketplace

Persona Creation & Management

create_persona "Study Buddy" "A helpful tutor" "educational" "You are a patient tutor..."
edit_persona "Study Buddy" "description" "An encouraging academic mentor"
validate_persona "Study Buddy"             # Check quality and format
submit_persona "Study Buddy"               # Share with community

User Identity

set_user_identity "your-username"          # Set attribution
get_user_identity                          # Check current status
clear_user_identity                        # Return to anonymous

Auto-Update Operations

The auto-update system provides enterprise-grade update management with safety features:

check_for_updates                          # Check for new DollhouseMCP versions
get_server_status                          # View current version and system info
update_server true                         # Perform automated update with backup
rollback_update true                       # Revert to previous version if needed

How Auto-Update Works:

Version Check: Queries GitHub releases API for latest version
Backup Creation: Automatically backs up current installation (including user personas)
Update Process:
- Performs git pull to fetch latest code
- Runs npm install for dependency updates
- Rebuilds TypeScript with npm run build
Verification: Validates the update succeeded
Rollback Option: Keep last 5 backups for easy recovery

Safety Features:

Rate limiting prevents API abuse
GPG signature verification (when available)
Dependency version validation
Automatic backup retention (5 most recent)
User personas preserved during updates

Persona Indicators

DollhouseMCP adds visual indicators to AI responses when a persona is active:

[🎭 Creative Writer v2.1 by @mickdarling] Your creative response here...

Configure indicators:

get_indicator_config                       # View current settings
configure_indicator enabled:false          # Disable indicators
configure_indicator style:"minimal"        # Use minimal format: 🎭 Creative Writer
configure_indicator style:"compact"        # Use compact: [Creative Writer v2.1]
configure_indicator style:"full"           # Full format (default)
configure_indicator emoji:"🤖"             # Change emoji
configure_indicator showAuthor:false       # Hide author attribution
configure_indicator bracketStyle:"round"   # Use (parentheses) instead of [brackets]

Environment variables for persistent configuration:

export DOLLHOUSE_INDICATOR_ENABLED=true
export DOLLHOUSE_INDICATOR_STYLE=minimal
export DOLLHOUSE_INDICATOR_EMOJI=🎨

🖥️ Cross-Platform Installation

🐧 Linux Installation

Prerequisites

Node.js: v20.0.0 or higher
npm: v10.0.0 or higher
git: For version control

# Ubuntu/Debian
sudo apt update
sudo apt install -y nodejs npm git
# Verify Node.js version
node --version  # Should be v20.0.0 or higher

# CentOS/RHEL/Fedora  
sudo dnf install -y nodejs npm git
# Verify Node.js version
node --version  # Should be v20.0.0 or higher

# Arch Linux
sudo pacman -S nodejs npm git
# Verify Node.js version
node --version  # Should be v20.0.0 or higher

Note: If your system's Node.js is older than v20, install from NodeSource or use nvm.

Installation Steps

# Clone and build
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build

# Optional: Set user identity
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"

Claude Desktop Configuration (Linux)

# Configuration location
~/.config/Claude/claude_desktop_config.json

# Or use XDG_CONFIG_HOME if set
$XDG_CONFIG_HOME/Claude/claude_desktop_config.json

Configuration content:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
    }
  }
}

🪟 Windows Installation

Prerequisites

Node.js: v20.0.0 or higher
npm: v10.0.0 or higher (included with Node.js)
git: For version control

# Install Node.js from https://nodejs.org/ (download LTS version)
# Or using Chocolatey
choco install nodejs --version=20.18.0
choco install git

# Or using winget
winget install OpenJS.NodeJS Git.Git

# Verify Node.js version
node --version  # Should be v20.0.0 or higher

Installation Steps (PowerShell)

# Clone and build
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build

# Optional: Set user identity
$env:DOLLHOUSE_USER = "your-username"
$env:DOLLHOUSE_EMAIL = "your-email@example.com"

Claude Desktop Configuration (Windows)

# Configuration location
$env:APPDATA\Claude\claude_desktop_config.json

Configuration content (use forward slashes or double backslashes):

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["C:/path/to/DollhouseMCP/dist/index.js"]
    }
  }
}

🍎 macOS Installation

Prerequisites

Node.js: v20.0.0 or higher
npm: v10.0.0 or higher (included with Node.js)
git: For version control

# Using Homebrew (recommended)
brew install node git

# Or download from https://nodejs.org/ (LTS version)

# Verify Node.js version
node --version  # Should be v20.0.0 or higher

Installation Steps

# Clone and build
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build

# Optional: Set user identity
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"

Claude Desktop Configuration (macOS)

# Configuration location
~/Library/Application Support/Claude/claude_desktop_config.json

Configuration content:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
    }
  }
}

🐳 Docker Installation

Quick Start with Docker

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

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t dollhousemcp .
docker run -d --name dollhousemcp dollhousemcp

Docker Compose (Recommended)

Production deployment:

docker-compose up -d

Development with hot reload:

docker-compose --profile dev up dollhousemcp-dev

Custom Personas with Docker

# Mount your custom personas directory
docker run -d \
  --name dollhousemcp \
  -v /path/to/your/personas:/app/personas \
  -e DOLLHOUSE_USER="your-username" \
  dollhousemcp

Docker Environment Variables

# Set user identity
DOLLHOUSE_USER=your-username
DOLLHOUSE_EMAIL=your-email@example.com

# Custom personas directory (inside container)
PERSONAS_DIR=/app/personas

# Node.js environment
NODE_ENV=production

🧪 Testing

Running Tests

The project includes comprehensive tests for cross-platform compatibility:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

# Run specific test suites
npm run test:auto-update
npm run test:personas
npm run test:marketplace

Test Coverage

Current test coverage includes:

✅ 102 comprehensive tests covering all functionality
✅ Auto-update system - GitHub API, backup/rollback, dependency validation
✅ Security testing - Command injection prevention, input validation
✅ Cross-platform compatibility - Windows, macOS, Linux path handling
✅ Version validation - Parsing tests for git/npm output formats
✅ Edge case coverage - Network failures, missing dependencies, malformed input

Manual Verification

Verify your setup works correctly:

# Build the project
npm run build

# Test the server (should output server info)
node dist/index.js --help 2>/dev/null || echo "Server compiled successfully"

# Verify personas directory
ls -la personas/

# Test auto-update system
check_for_updates    # Use in Claude Desktop
get_server_status    # Check current system status

☁️ Cloud Deployment

Container Registries

The project supports deployment to:

GitHub Container Registry (ghcr.io)
Docker Hub
AWS ECR
Google Container Registry

Example Cloud Deployments

AWS ECS

{
  "family": "dollhousemcp",
  "containerDefinitions": [{
    "name": "dollhousemcp",
    "image": "ghcr.io/mickdarling/dollhousemcp:latest",
    "memory": 512,
    "cpu": 256,
    "environment": [
      {"name": "NODE_ENV", "value": "production"},
      {"name": "PERSONAS_DIR", "value": "/app/personas"},
      {"name": "DOLLHOUSE_USER", "value": "production"}
    ]
  }]
}

Google Cloud Run

gcloud run deploy dollhousemcp \
  --image ghcr.io/mickdarling/dollhousemcp:latest \
  --platform managed \
  --region us-central1 \
  --set-env-vars NODE_ENV=production,DOLLHOUSE_USER=production

Azure Container Instances

az container create \
  --name dollhousemcp \
  --resource-group myResourceGroup \
  --image ghcr.io/mickdarling/dollhousemcp:latest \
  --environment-variables NODE_ENV=production DOLLHOUSE_USER=production

🏗️ Project Structure

DollhouseMCP/
├── .github/
│   ├── actions/
│   │   └── validate-yaml/         # Reusable YAML validation action
│   ├── workflows/                 # CI/CD workflows
│   └── ISSUE_TEMPLATE/           # Issue templates for bug/feature/task
├── __tests__/
│   ├── unit/                     # Unit tests for components
│   ├── integration/              # Integration tests
│   └── *.test.ts                 # Test files (372 tests total)
├── src/
│   ├── index.ts                  # Main MCP server (DollhouseMCPServer)
│   ├── cache/                    # API caching layer
│   ├── config/                   # Configuration management
│   ├── marketplace/              # GitHub marketplace integration
│   ├── persona/                  # Persona management core
│   ├── security/                 # Input validation and security
│   ├── server/                   # MCP server setup and tools
│   ├── types/                    # TypeScript type definitions
│   ├── update/                   # Auto-update system components
│   └── utils/                    # Utility functions
├── dist/                         # Compiled JavaScript (auto-generated)
├── personas/                     # Default persona collection
│   ├── creative-writer.md
│   ├── technical-analyst.md
│   ├── eli5-explainer.md
│   ├── business-consultant.md
│   └── debug-detective.md
├── custom-personas/              # User-created personas (git-ignored)
├── docs/                         # Documentation
│   ├── auto-update/             # Auto-update system docs
│   └── development/             # Development notes and guides
├── scripts/                      # Management and utility scripts
├── Dockerfile                    # Multi-stage Docker build
├── docker-compose.yml           # Production and development configs
├── package.json                 # Project config (dollhousemcp v1.2.1)
├── tsconfig.json                # TypeScript configuration
├── jest.config.cjs              # Jest test configuration
├── setup.sh                     # Automated installation script
├── LICENSE                      # AGPL-3.0 with platform stability
├── CHANGELOG.md                 # Version history
├── claude.md                    # Project context for Claude
└── README.md                    # This file

📝 Creating Custom Personas

Enhanced Persona Format

Create .md files in the personas/ directory with this structure:

---
name: "Your Persona Name"
description: "Brief description of what this persona does"
unique_id: "auto-generated-if-missing"
author: "your-username"
triggers: ["keyword1", "keyword2"]
version: "1.0"
category: "creative"
age_rating: "all"
ai_generated: false
generation_method: "human"
price: "free"
license: "CC-BY-SA-4.0"
---

# Your Persona Name

Your persona instructions go here. This content defines how the AI should behave when this persona is activated.

## Response Style
- Communication guidelines
- Tone and approach
- Specific behaviors

## Key Techniques
- Problem-solving methods
- Interaction patterns

Metadata Fields

Required Fields

Field	Description
`name`	Display name for the persona
`description`	Brief description of purpose and capabilities

Optional Fields

Field	Description
`unique_id`	Auto-generated in format: `what-it-is_YYYYMMDD-HHMMSS_who-made-it`
`author`	Creator username (uses DOLLHOUSE_USER environment variable or generates anonymous ID)
`category`	One of: creative, professional, educational, gaming, personal
`triggers`	Array of keywords that suggest when to use this persona
`version`	Semantic version number (auto-incremented on edits)
`age_rating`	Content rating: all, 13+, or 18+
`ai_generated`	Boolean flag indicating if content was AI-created
`price`	Monetization field - TODO: Future Release (will support "free" or pricing tiers)

📚 Built-in Personas

Persona	Purpose	Best For
Creative Writer	Imaginative storytelling and creative content	Brainstorming, creative writing, engaging narratives
Technical Analyst	Deep technical analysis and systematic problem-solving	Architecture decisions, debugging, technical docs
ELI5 Explainer	Simplifying complex topics for beginners	Teaching, onboarding, concept explanation
Business Consultant	Strategic business analysis and recommendations	Strategy planning, business decisions, market analysis
Debug Detective	Systematic debugging and troubleshooting	Bug hunting, system troubleshooting, root cause analysis

🏪 Marketplace Integration (Beta)

🧪 Beta Feature: The GitHub-powered marketplace is currently in beta. Features may change based on community feedback.

DollhouseMCP includes an experimental GitHub-powered marketplace:

Browse by Category: creative, professional, educational, gaming, personal
Search Content: Find personas by keywords and descriptions
One-Click Install: Download and integrate marketplace personas
Community Submissions: Submit your personas via submit_persona tool
Version Control: Full Git history for all marketplace content

Note: Marketplace features require internet connection and GitHub API access. Rate limits may apply.

💼 Business Model & Legal

Licensing

Core Server: AGPL-3.0 (prevents proprietary competing platforms)
Persona Content: CC-BY-SA-4.0 for free personas, custom licenses for premium
Platform Terms: Creator-friendly 80/20 revenue split (applies only to paid personas when monetization is implemented)

Platform Stability Commitments

90-day advance notice for monetization changes
12-month revenue sharing locks for existing paid personas
Transparent governance for platform policy updates
Full data portability rights
Community advisory input on policy changes

🛠️ Development

Available Scripts

Script	Description
`npm run build`	Compile TypeScript to JavaScript
`npm run start`	Run the compiled server
`npm run dev`	Run in development mode with auto-reload
`npm run clean`	Remove compiled files
`npm run rebuild`	Clean and rebuild the project
`npm run setup`	Install dependencies and build
`npm test`	Run the comprehensive test suite
`npm run test:coverage`	Run tests with coverage reporting

Environment Variables

Customize server behavior with these environment variables:

# User Attribution
export DOLLHOUSE_USER="your-username"          # User attribution for persona creation
export DOLLHOUSE_EMAIL="your-email"            # Contact email (optional)

# Directory Configuration
export PERSONAS_DIR="/custom/path/to/personas"  # Custom personas directory

# Auto-Update Configuration
export GITHUB_TOKEN="your-token"               # For private repository access (optional)

# Development Configuration
export NODE_ENV="development"                  # Development mode
export DEBUG="dollhousemcp:*"                  # Debug logging (optional)

🔧 Troubleshooting

Common Issues

Issue	Solution
Personas not loading	Check `personas/` directory exists and has read permissions
Server won't start	Run `npm run rebuild` to clean and rebuild
Marketplace not working	Check internet connection and GitHub API access
User identity not saving	Set `DOLLHOUSE_USER` environment variable before starting Claude
"Cannot find module" errors	Ensure `npm install` completed successfully
TypeScript compilation errors	Verify Node.js version is 20+ with `node --version`
Tools not appearing in Claude	Restart Claude Desktop completely after config changes
Default personas modified	v1.2.1+ uses copy-on-write; git restore if needed
Update/rollback issues	Check write permissions; disable with `DOLLHOUSE_DISABLE_UPDATES=true`
Rate limit errors	Wait 60 seconds; GitHub API has hourly limits

Debug Steps

Check build status:
npm run build
Verify persona files:
ls -la personas/*.md
Test server startup:
node dist/index.js
Validate configuration:
# Check Claude Desktop config cat ~/Library/Application\ Support/Claude/claude_desktop_config.json # Verify Node.js version (requires 20+) node --version # Check npm version npm --version
Test auto-update system:
# Use within Claude Desktop check_for_updates # Check for available updates get_server_status # View system information
Validate personas: Use the reload_personas tool to check for loading errors

🤝 Contributing

We welcome contributions! DollhouseMCP includes integrated tools for submitting personas directly from Claude.

Integrated Contribution Process (Recommended)

Create or modify a persona using the chat-based tools:
create_persona "My Awesome Persona" "A helpful assistant for..." "professional"
Validate your persona to ensure quality:
validate_persona "My Awesome Persona"
Submit to the marketplace directly from Claude:
submit_persona "My Awesome Persona"
This automatically creates a GitHub issue for community review.

Manual Contribution Process

Fork the repository
Create persona files in personas/ or custom-personas/
Follow the metadata format and naming conventions
Test thoroughly with validate_persona tool
Submit a pull request with clear description

Reporting Issues

Please include:

Node.js version (node --version)
Operating system and version
Complete error messages
Steps to reproduce the issue
Relevant persona files (if applicable)
Claude Desktop configuration (without sensitive paths)

Development Guidelines

Follow TypeScript best practices
Maintain existing code style and patterns
Add comprehensive error handling
Update documentation for new features
Test thoroughly across platforms before submitting PRs
Include tests for new functionality
Follow semantic versioning for releases

Development Workflow

# Fork and clone
git clone https://github.com/your-username/DollhouseMCP.git
cd mcp-server

# Install dependencies
npm install

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and test
npm run build
npm test

# Commit and push
git commit -m "feat: your feature description"
git push origin feature/your-feature-name

# Submit pull request

📄 API Reference

MCP Tool Specifications

Each tool follows the MCP specification:

interface DollhouseTool {
  name: string;
  description: string;
  inputSchema: {
    type: "object";
    properties: Record<string, any>;
    required?: string[];
  };
}

Tool Categories

Core Persona Management

// list_personas - No parameters
// activate_persona - { persona: string }
// get_active_persona - No parameters  
// deactivate_persona - No parameters
// get_persona_details - { persona: string }
// reload_personas - No parameters

Marketplace Integration

// browse_marketplace - { category?: string }
// search_marketplace - { query: string }
// get_marketplace_persona - { path: string }
// install_persona - { path: string }
// submit_persona - { persona: string }

User Identity Management

// set_user_identity - { username: string }
// get_user_identity - No parameters
// clear_user_identity - No parameters

Chat-Based Management

// create_persona - { name: string, description: string, category?: string, instructions: string }
// edit_persona - { persona: string, field: string, value: string }
// validate_persona - { persona: string }

Auto-Update System

// check_for_updates - No parameters
// update_server - { confirm: boolean }
// rollback_update - { confirm: boolean }
// get_server_status - No parameters

Error Handling

The server provides detailed error messages for:

Invalid persona identifiers - Clear suggestions for valid names
File system issues - Permission and path resolution errors
Malformed persona files - YAML parsing and validation errors
Network errors - GitHub API and marketplace connectivity issues
Runtime errors - Server startup and operation failures

Response Formats

All responses follow consistent patterns:

Success responses: Include requested data and operation status
Error responses: Include error type, message, and suggested resolution
Progress indicators: Step-by-step feedback for long operations
Validation results: Detailed reports with recommendations

📄 License

This project is licensed under the AGPL-3.0 License with Platform Stability Commitments - see the LICENSE file for details.

Platform Stability Guarantees:

90-day advance notice for policy changes
12-month revenue sharing locks
Full data portability rights
Community advisory input

🏷️ Version History

v1.2.4 - July 10, 2025 (Current)

Critical Fix:

✅ Fixed MCP protocol compatibility - console output no longer breaks JSON-RPC communication
✅ Added MCP-safe logger utility for proper logging during protocol sessions
✅ Resolves connection failures in Claude Desktop
✅ Updated Docker tests to work with new logging approach
✅ Added comprehensive logger unit tests

v1.2.3 - July 10, 2025

Bug Fix:

✅ Fixed personas directory path resolution for production environments
✅ Changed from process.cwd() to __dirname-based paths
✅ Fixed setup script with correct tool count and repository URLs

v1.2.2 - July 10, 2025

✅ Comprehensive security enhancements:
- Content sanitization with DOMPurify (SEC-001)
- YAML injection prevention (SEC-003)
- GitHub token security (SEC-004)
- Docker container hardening (SEC-005)
✅ 487 comprehensive tests including extensive security coverage
✅ CI timing test fixes for reliable cross-platform testing
✅ TypeScript compilation fixes for all test files
✅ All security vulnerabilities resolved (0 active alerts)

v1.2.1 - January 8, 2025

✅ Critical bug fixes for data protection:
- Copy-on-write for default personas (Issue #145)
- User personas included in backups (Issue #144)
✅ Node.js 20+ requirement for npm publishing compatibility
✅ 372 comprehensive tests covering all functionality
✅ Enhanced security with all vulnerabilities resolved
✅ Improved documentation with clear prerequisites

v1.2.0 - January 7, 2025

✅ Rate limiting implementation to prevent API abuse
✅ GPG signature verification for release authenticity
✅ GitHub Advanced Security integration
✅ 309 tests with improved CI environment coverage
✅ Package optimization at 279.3 kB

v1.1.0 - July 4, 2025

✅ Platform-specific badges for Windows, macOS, Linux visibility
✅ GitHub Project management with issue templates and milestones
✅ ARM64 Docker fix switching from Alpine to Debian base images
✅ 100% workflow reliability (except Docker ARM64)
✅ First GitHub release with CHANGELOG.md
✅ 21 total MCP tools at time of release

Phase 2B+ - July 3, 2025

✅ Enterprise-grade auto-update system with 4 new MCP tools
✅ 50 comprehensive tests covering all functionality
✅ Security hardening - eliminated all command injection vulnerabilities
✅ Cross-platform support - Windows, macOS, Linux with CI/CD testing
✅ Docker containerization with production and development configurations
✅ 21 total MCP tools with backup/rollback and dependency validation

Phase 2B - July 1-2, 2025

✅ Complete chat-based persona management
✅ GitHub marketplace integration
✅ User identity and attribution system
✅ Real-time validation and editing
✅ Enterprise-grade GitHub Actions security

Phase 1 - July 1, 2025

✅ Fresh AGPL-3.0 licensed repository
✅ Enhanced unique ID system
✅ Anonymous user support
✅ Marketplace-ready metadata schema

🎭 Transform your AI interactions with the power of personas

For support, please open an issue or visit our marketplace.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A comprehensive Model Context Protocol server that enables dynamic AI persona management with GitHub-powered marketplace integration, allowing Claude and other compatible AI assistants to activate different behavioral personas with community sharing capabilities.

Related MCP Servers

MTS MCP Server
CalvinMagezi
-
security
F
license
-
quality
A comprehensive suite of Model Context Protocol servers designed to extend AI agent Claude's capabilities with integrations for knowledge management, reasoning, advanced search, news access, and workspace tools.
Last updated -
5
TypeScript
GCP MCP
eniayomi
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants like Claude to interact with Google Cloud Platform environments through natural language, allowing users to query and manage GCP resources during conversations.
Last updated -
9
102
62
TypeScript
MIT License
Aider MCP Server
sengokudaikon
-
security
A
license
-
quality
A Model Context Protocol server that connects Claude and other MCP clients to Aider, enabling AI assistants to efficiently edit files, create new files, and interact with git repositories through natural language.
Last updated -
9
Python
The Unlicense
Hass-MCP
voska
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
Last updated -
126
Python
MIT License

View all related MCP servers