DollhouseMCP 是一个全面的模型上下文协议(MCP)服务器,它借助集成的 GitHub 集合,实现了动态 AI 角色管理。该项目允许 Claude 等兼容的 AI 助手激活不同的行为角色,同时支持社区共享和货币化。
npm install -g @mickdarling/dollhousemcp
安装完成后,将 DollhouseMCP 添加到你的 Claude Desktop 配置中:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json配置内容如下:
{
"mcpServers": {
"dollhousemcp": {
"command": "npx",
"args": ["@mickdarling/dollhousemcp"]
}
}
}
[!WARNING] 仅适用于 Claude Desktop:自动化设置脚本专门为 Claude Desktop 集成设计。如果你使用的是 Claude Code、其他 AI 平台(如 ChatGPT、BoltAI、Gemini 等)或自定义 MCP 实现,请使用下面的手动安装流程。
# 克隆仓库
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
# 运行自动化设置脚本(仅适用于 Claude Desktop)
./setup.sh
设置脚本将完成以下操作:
注意:手动安装适用于所有与 MCP 兼容的平台,包括 Claude Desktop、Claude Code、ChatGPT、BoltAI、Gemini 和自定义实现。
# 克隆仓库
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
# 安装依赖项并构建
npm install
npm run build
# 可选:设置用户身份以进行角色归因
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"
将 DollhouseMCP 添加到你的 Claude Desktop 配置中:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS){
"mcpServers": {
"dollhousemcp": {
"command": "npx",
"args": ["@mickdarling/dollhousemcp"]
}
}
}
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
}
}
}
🔄 配置完成后:
| 特性 | 描述 |
|---|---|
| 🎭 23 个 MCP 工具 | 通过聊天界面实现完整的角色生命周期管理 |
| 🏪 GitHub 集合 | 浏览、搜索、安装角色并提交到社区集合 |
| 👤 用户身份系统 | 基于环境的角色创建者归因 |
| 🆔 唯一 ID 系统 | 高级 ID 生成:what-it-is_YYYYMMDD-HHMMSS_who-made-it |
| 💬 基于聊天的管理 | 通过对话界面创建、编辑和验证角色 |
| 🔄 实时操作 | 实时编辑,自动增加版本号并进行验证 |
| 🚀 自动更新系统 | 企业级自动更新,支持备份/回滚和依赖验证 |
| 🛡️ 数据保护 | 默认角色的写时复制,全面的备份系统 |
| 🏠 本地优先架构 | 无需依赖云即可实现完整功能 |
DollhouseMCP 实施了全面的安全措施,以保护你的角色和系统:
注意:DollhouseMCP 在 Node.js 24 上开发,但支持 Node.js 20+ 以实现广泛的兼容性。
browse_collection # 查看所有类别
browse_collection "creative" # 浏览创意角色
search_collection "writing" # 搜索写作角色
install_persona "creative/storyteller.md" # 从集合中安装
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" # 检查质量和格式
submit_persona "Study Buddy" # 与社区共享
set_user_identity "your-username" # 设置角色归因的用户名
get_user_identity # 查看当前身份状态
clear_user_identity # 返回匿名模式
自动更新系统提供企业级更新管理,具备安全功能:
check_for_updates # 检查 GitHub 版本以获取可用的 DollhouseMCP 更新
update_server true # 自动执行 git pull + npm install + 构建,并创建备份
rollback_update true # 根据需要恢复到上一个版本
get_server_status # 获取全面的服务器状态,包括版本、git 信息和系统详细信息
自动更新的工作原理:
git pull 以获取最新代码npm install 以更新依赖项npm run build 重新构建 TypeScript安全特性:
当角色激活时,DollhouseMCP 会在 AI 响应中添加视觉指示器:
[🎭 Creative Writer v2.1 by @mickdarling] Your creative response here...
配置指示器:
get_indicator_config # 查看当前设置
configure_indicator enabled:false # 禁用指示器
configure_indicator style:"minimal" # 使用简约格式:🎭 Creative Writer
configure_indicator style:"compact" # 使用紧凑格式:[Creative Writer v2.1]
configure_indicator style:"full" # 使用完整格式(默认)
configure_indicator emoji:"🤖" # 更改表情符号
configure_indicator showAuthor:false # 隐藏作者归因
configure_indicator bracketStyle:"round" # 使用括号 () 代替方括号 []
使用环境变量进行持久配置:
export DOLLHOUSE_INDICATOR_ENABLED=true
export DOLLHOUSE_INDICATOR_STYLE=minimal
export DOLLHOUSE_INDICATOR_EMOJI=🎨
# Ubuntu/Debian
sudo apt update
sudo apt install -y nodejs npm git
# 验证 Node.js 版本
node --version # 应为 v20.0.0 或更高版本
# CentOS/RHEL/Fedora
sudo dnf install -y nodejs npm git
# 验证 Node.js 版本
node --version # 应为 v20.0.0 或更高版本
# Arch Linux
sudo pacman -S nodejs npm git
# 验证 Node.js 版本
node --version # 应为 v20.0.0 或更高版本
注意:如果你的系统中的 Node.js 版本低于 v20,请从 NodeSource 安装或使用 nvm。
# 克隆并构建
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
# 可选:设置用户身份
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"
# 配置位置
~/.config/Claude/claude_desktop_config.json
# 或者,如果设置了 XDG_CONFIG_HOME
$XDG_CONFIG_HOME/Claude/claude_desktop_config.json
配置内容:
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
}
}
}
# 从 https://nodejs.org/ 安装 Node.js(下载 LTS 版本)
# 或者使用 Chocolatey
choco install nodejs --version=20.18.0
choco install git
# 或者使用 winget
winget install OpenJS.NodeJS Git.Git
# 验证 Node.js 版本
node --version # 应为 v20.0.0 或更高版本
# 克隆并构建
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
# 可选:设置用户身份
$env:DOLLHOUSE_USER = "your-username"
$env:DOLLHOUSE_EMAIL = "your-email@example.com"
# 配置位置
$env:APPDATA\Claude\claude_desktop_config.json
配置内容(使用正斜杠或双反斜杠):
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["C:/path/to/DollhouseMCP/dist/index.js"]
}
}
}
# 使用 Homebrew(推荐)
brew install node git
# 或者从 https://nodejs.org/ 下载(LTS 版本)
# 验证 Node.js 版本
node --version # 应为 v20.0.0 或更高版本
# 克隆并构建
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
# 可选:设置用户身份
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"
# 配置位置
~/Library/Application Support/Claude/claude_desktop_config.json
配置内容:
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
}
}
}
# 克隆仓库
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
# 使用 Docker Compose 构建并运行
docker-compose up -d
# 或者手动构建
docker build -t dollhousemcp .
docker run -d --name dollhousemcp dollhousemcp
docker-compose up -d
docker-compose --profile dev up dollhousemcp-dev
# 挂载自定义角色目录
docker run -d \
--name dollhousemcp \
-v /path/to/your/personas:/app/personas \
-e DOLLHOUSE_USER="your-username" \
dollhousemcp
# 设置用户身份
DOLLHOUSE_USER=your-username
DOLLHOUSE_EMAIL=your-email@example.com
# 自定义角色目录(容器内)
PERSONAS_DIR=/app/personas
# Node.js 环境
NODE_ENV=production
该项目包含全面的测试,以确保跨平台兼容性:
# 运行所有测试
npm test
# 运行测试并生成覆盖率报告
npm run test:coverage
# 在开发模式下以监视模式运行测试
npm run test:watch
# 运行特定的测试套件
npm run test:auto-update
npm run test:personas
npm run test:collection
当前的测试覆盖率包括:
验证你的设置是否正常工作:
# 构建项目
npm run build
# 测试服务器(应输出服务器信息)
node dist/index.js --help 2>/dev/null || echo "Server compiled successfully"
# 验证角色目录
ls -la personas/
# 测试自动更新系统
check_for_updates # 在 Claude Desktop 中使用
get_server_status # 检查当前系统状态
该项目支持部署到以下容器注册表:
{
"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"}
]
}]
}
gcloud run deploy dollhousemcp \
--image ghcr.io/mickdarling/dollhousemcp:latest \
--platform managed \
--region us-central1 \
--set-env-vars NODE_ENV=production,DOLLHOUSE_USER=production
az container create \
--name dollhousemcp \
--resource-group myResourceGroup \
--image ghcr.io/mickdarling/dollhousemcp:latest \
--environment-variables NODE_ENV=production DOLLHOUSE_USER=production
DollhouseMCP/
├── .github/
│ ├── actions/
│ │ └── validate-yaml/ # 可重用的 YAML 验证操作
│ ├── workflows/ # CI/CD 工作流
│ └── ISSUE_TEMPLATE/ # 用于 bug/功能/任务的问题模板
├── __tests__/
│ ├── unit/ # 组件的单元测试
│ ├── integration/ # 集成测试
│ └── *.test.ts # 测试文件(共 372 个测试)
├── src/
│ ├── index.ts # 主 MCP 服务器(DollhouseMCPServer)
│ ├── cache/ # API 缓存层
│ ├── config/ # 配置管理
│ ├── marketplace/ # GitHub 集合集成
│ ├── persona/ # 角色管理核心
│ ├── security/ # 输入验证和安全
│ ├── server/ # MCP 服务器设置和工具
│ ├── types/ # TypeScript 类型定义
│ ├── update/ # 自动更新系统组件
│ └── utils/ # 实用函数
├── dist/ # 编译后的 JavaScript(自动生成)
├── personas/ # 默认角色集合
│ ├── creative-writer.md
│ ├── technical-analyst.md
│ ├── eli5-explainer.md
│ ├── business-consultant.md
│ └── debug-detective.md
├── custom-personas/ # 用户创建的角色(git 忽略)
├── docs/ # 文档
│ ├── auto-update/ # 自动更新系统文档
│ └── development/ # 开发笔记和指南
├── scripts/ # 管理和实用脚本
├── Dockerfile # 多阶段 Docker 构建
├── docker-compose.yml # 生产和开发配置
├── package.json # 项目配置(dollhousemcp v1.2.1)
├── tsconfig.json # TypeScript 配置
├── jest.config.cjs # Jest 测试配置
├── setup.sh # 自动化安装脚本
├── LICENSE # AGPL-3.0 许可证
├── CHANGELOG.md # 版本历史
├── claude.md # 项目背景信息
└── README.md # 本文件
在 personas/ 目录中创建 .md 文件,结构如下:
---
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
| 字段 | 描述 |
|---|---|
name |
角色的显示名称 |
description |
角色用途和功能的简要描述 |
| 字段 | 描述 |
|---|---|
unique_id |
自动生成的格式:what-it-is_YYYYMMDD-HHMMSS_who-made-it |
author |
创建者的用户名(使用 DOLLHOUSE_USER 环境变量或生成匿名 ID) |
category |
类别之一:creative、professional、educational、gaming、personal |
triggers |
建议使用此角色的关键字数组 |
version |
语义化版本号(编辑时自动递增) |
age_rating |
内容评级:all、13+ 或 18+ |
ai_generated |
布尔标志,指示内容是否由 AI 创建 |
price |
货币化字段 - 待办事项:未来版本(将支持 "free" 或定价层级) |
| 角色 | 用途 | 适用场景 |
|---|---|---|
| 创意作家 | 富有想象力的故事讲述和创意内容创作 | 头脑风暴、创意写作、引人入胜的叙事 |
| 技术分析师 | 深入的技术分析和系统问题解决 | 架构决策、调试、技术文档编写 |
| ELI5 解释者 | 为初学者简化复杂主题 | 教学、入门、概念解释 |
| 商业顾问 | 战略商业分析和建议 | 战略规划、商业决策、市场分析 |
| 调试侦探 | 系统调试和故障排除 | 查找 bug、系统故障排除、根本原因分析 |
🧪 测试版功能:基于 GitHub 的集合目前处于测试阶段。功能可能会根据社区反馈进行更改。
DollhouseMCP 包含一个实验性的基于 GitHub 的集合:
submit_persona 工具提交你的角色注意:集合功能需要互联网连接和 GitHub API 访问权限。可能会应用速率限制。
重要:最近版本中工具名称发生了更改:
browse_marketplace → browse_collectionsearch_marketplace → search_collectionget_marketplace_persona → get_collection_persona如果你有使用旧工具名称的脚本或工作流,请更新它们以使用新名称。
| 脚本 | 描述 |
|---|---|
npm run build |
将 TypeScript 编译为 JavaScript |
npm run start |
运行编译后的服务器 |
npm run dev |
在开发模式下运行,支持自动重新加载 |
npm run clean |
删除编译后的文件 |
npm run rebuild |
清理并重新构建项目 |
npm run setup |
安装依赖项并构建 |
npm test |
运行全面的测试套件 |
npm run test:coverage |
运行测试并生成覆盖率报告 |
使用以下环境变量自定义服务器行为:
# 用户归因
export DOLLHOUSE_USER="your-username" # 用户归因,用于角色创建
export DOLLHOUSE_EMAIL="your-email" # 联系电子邮件(可选)
# 目录配置
export PERSONAS_DIR="/custom/path/to/personas" # 自定义角色目录
# 自动更新配置
export GITHUB_TOKEN="your-token" # 用于访问私有仓库(可选)
# 开发配置
export NODE_ENV="development" # 开发模式
export DEBUG="dollhousemcp:*" # 调试日志记录(可选)
每个工具都遵循 MCP 规范:
interface DollhouseTool {
name: string;
description: string;
inputSchema: {
type: "object";
properties: Record<string, any>;
required?: string[];
};
}
// list_personas - 无参数
// activate_persona - { persona: string }
// get_active_persona - 无参数
// deactivate_persona - 无参数
// get_persona_details - { persona: string }
// reload_personas - 无参数
// browse_collection - { category?: string }
// search_collection - { query: string }
// get_collection_persona - { path: string }
// install_persona - { path: string }
// submit_persona - { persona: string }
// set_user_identity - { username: string }
// get_user_identity - 无参数
// clear_user_identity - 无参数
// create_persona - { name: string, description: string, category?: string, instructions: string }
// edit_persona - { persona: string, field: string, value: string }
// validate_persona - { persona: string }
// check_for_updates - 无参数
// update_server - { confirm: boolean }
// rollback_update - { confirm: boolean }
// get_server_status - 无参数
服务器为以下情况提供详细的错误消息:
所有响应遵循一致的模式:
本项目采用 AGPL-3.0 许可证,并对平台稳定性做出承诺 - 详情请参阅 LICENSE 文件。
平台稳定性保证:
集合重命名与重大更改:
browse_marketplace → browse_collectionsearch_marketplace → search_collectionget_marketplace_persona → get_collection_personainstall_persona → install_persona(未更改)submit_persona → submit_persona(未更改)/personas 到 /collection关键修复:
错误修复:
🎭 借助角色的力量改变你的 AI 交互体验