DollhouseMCP

DollhouseMCP

---

工作原理

 CREATE or EDIT                    PORTFOLIO                   ACTIVATE → USE
 ─────────────────────────────────────────────────────────────────────────────

 "Create a skill for            📁 ~/.dollhouse/portfolio/    "Activate the Dollhouse
  writing blog posts"                                              Expert ensemble"
                                 37 starter elements:
 "Edit the code review      ──▶  personas · skills ·       ──▶  Your AI now has
  persona to add security"       templates · agents ·           new behavior,
                                 memories · ensembles           capabilities, and
  persona · skill · template                                    permission policies
  agent · memory · ensemble      + everything you create
                                 + community installs

选择任意方式开始：

• 从你的作品集启用一个入门元素——你的 AI 会立即发生变化
• 用通俗易懂的语言描述你的需求，即可创建任何类型的元素（角色、技能、模板、Agent、记忆、组合）
• 编辑任何现有元素并对其进行完善
• 浏览社区内容集，安装其他用户制作的元素

你的作品集（macOS/Linux 上的 ~/.dollhouse/portfolio/，Windows 上的 %USERPROFILE%\.dollhouse\portfolio\）是一个本地文件夹，用于存放所有 Dollhouse 元素。它预装了 37 个入门元素，其中包括可启用以获取引导式帮助的 dollhouse-expert-suite 组合（角色 + 知识库）。你创建或安装的所有内容都会保存在这里。准备就绪后，可以与社区分享，或同步到 GitHub。

---

快速开始

v2.0.0 现已推出。 DollhouseMCP v2 是默认版本。发行说明 | 迁移指南 | 报告问题

DollhouseMCP 可安装在任何兼容 MCP 的 AI 客户端上，包括 Claude Code、Claude Desktop、Cursor、Gemini、Codex 和本地大模型。核心元素管理功能（创建、激活、搜索、浏览）适用于所有平台。高级功能（Gatekeeper 确认流程、Agentic 循环执行）已在 Claude Code 上经过广泛测试，并且应该适用于支持标准 MCP 工具调用/响应模式的任何客户端。

交互式设置（适用于任何平台）：

npx @dollhousemcp/mcp-server@latest --web

此功能会打开基于浏览器的设置向导，可一键安装到 Claude Desktop、Claude Code、Cursor、VS Code、Codex、Gemini CLI、Windsurf、Cline 和 LM Studio。它会检测现有安装，并支持自动更新和固定版本。

设置向导中的权限钩子支持目前如下：

平台	设置状态	权限钩子状态
Claude Code	一键安装	完整原生支持
Cursor	一键安装	部分原生支持
VS Code	一键安装	部分原生支持
Codex	一键安装	部分原生支持，仅支持 Bash
Gemini CLI	一键安装	部分原生支持
Windsurf	一键安装	部分原生支持
Cline	一键安装	此版本仅支持 MCP 设置
LM Studio	一键安装	此版本仅支持 MCP 设置
Claude Desktop	一键安装	此版本不提供原生权限钩子方式

Claude Code（一条命令）：

claude mcp add -s user dollhousemcp -- npx -y @dollhousemcp/mcp-server

Claude Desktop（一键安装）：

下载 DollhouseMCP Desktop Extension（.mcpb 文件）并双击。其余操作由 Claude Desktop 处理——无需使用终端。

其他平台——请参阅快速开始指南，或运行上面的交互式设置。

然后开始对话：

"What DollhouseMCP tools do you have available?"
"List all available Dollhouse personas"
"Activate the Dollhouse debug detective persona"

DollhouseMCP 随附 6 种类型共 38 个 Dollhouse 元素。只需用自然语言描述你的需求即可。

第一次使用？ 公开测试版入门指南将带你从安装开始，在不到 10 分钟内激活你的第一个 Dollhouse persona。

---

Dollhouse 元素：行为、能力与权限

Dollhouse 元素是用于定制 AI 的模块化构件。激活 Dollhouse 元素时，你改变的不只是提示词，还会改变 AI 可访问的工具、可运行的命令，以及需要你批准的操作。

Dollhouse 元素	功能
Dollhouse Personas	塑造行为、语气、专业知识和优先级。 作为安全主体，通过权限策略控制 AI 可以执行的操作。
Dollhouse Skills*	添加 AI 可按需启用的独立能力。 代码审查、数据分析、渗透测试、翻译等。
Dollhouse Templates	通过变量替换规范输出。 报告、电子邮件、简报、文档——每次都保持一致的结构。变量会根据内容中的 {{placeholder}} 标记自动推导，无需手动定义架构。
Dollhouse Agents	自主执行多步骤目标。 状态跟踪、韧性策略、自主性评估和执行生命周期。
Dollhouse Memories	在不同会话间持久保存结构化上下文。 事实、偏好、项目状态。可在启动时自动加载。
Dollhouse Ensembles	将多个元素打包成一个可激活单元。 激活策略、冲突解决和协调一致的权限策略。

*Skills 兼容性

Dollhouse Skills（于 2025 年 7 月推出）早于 Claude/Anthropic 后来采用的 Agent Skills 格式。DollhouseMCP 内置了无损双向转换器，可在两种格式之间转换。

• 导入：通过 convert_skill_format 将 Agent Skills 转换为 Dollhouse Skills。转换后，它们就是一等 Dollhouse 元素，可与 Ensembles 中的 Personas、Templates 和其他 Skills 组合使用，由 Dollhouse Agents 管理，并受 Gatekeeper 策略保护。
• 导出：将 Dollhouse Skills 转换为 Agent Skills，供未安装 DollhouseMCP 的平台使用。
• 往返转换：转换器支持无损模式，可在两个方向上保留所有内容。另有安全模式，可在转换过程中清理可能存在风险的模式。

Skills 转换器完整文档

所有 Dollhouse 元素都是可读的 Markdown 或 YAML 文件，存储在你的本地作品集内。你拥有它们，也由你掌控。与 AI 交互时，请使用“Dollhouse”以明确所指——例如说“激活 Dollhouse 代码审查 persona”或“运行 Dollhouse 研究 agent”，确保 AI 使用 DollhouseMCP 元素，而非平台原生功能。

---

MCP-AQL：AI 如何与 DollhouseMCP 通信

大多数 MCP 服务会公开数十个独立工具，每个工具都会占用上下文令牌，并迫使大模型从一份未分类的列表中挑选合适的工具。DollhouseMCP 采用了不同的方法。

MCP-AQL（Model Context Protocol – Advanced Agent API Adapter Query Language）将所有操作组织到 5 个语义端点中——CRUDE：Create（创建）、Read（读取）、Update（更新）、Delete（删除）、Execute（执行）。其中的 A 身兼四职：Advanced query（高级查询）能力、以 Agent 为先的设计、API 整合，以及用于连接其他 MCP 服务和 API、使其可直接与大模型协同工作的 Adapter（适配器）层。每个端点都按其对状态的操作类型对操作进行分组，让大模型清楚了解每个操作的后果：

端点	用途	权限级别
Create	添加新元素、从集合安装、添加记忆条目	每个会话确认一次
Read	列出、搜索、获取详情、激活、内省	自动批准（安全、无副作用）
Update	编辑现有元素	每次都需确认
Delete	移除元素、清除条目	每次都需确认
Execute	运行 Agent、管理执行生命周期、确认操作	每次都需确认

这为何重要

• 语义清晰 — 大模型知道，调用 mcp_aql_read 始终安全，而调用 mcp_aql_delete 始终具有破坏性。无需猜测。

• 主机级权限控制 — Claude Code 等 MCP 客户端可以为每个端点设置不同的审批策略（读取自动批准，删除需要确认）。

• 通过自省实现渐进式披露 — 大模型最初只会看到 5 个工具端点。它会在运行时向服务查询，发现操作、参数、元素格式和使用示例：

  { "operation": "introspect", "params": { "query": "operations" } }
  { "operation": "introspect", "params": { "query": "format", "name": "persona" } }
  

  这是内置于协议中的渐进式披露——大模型只在需要时加载所需内容。与需要特殊工具链支持的客户端解决方案（例如 Claude Code 的延迟工具加载）不同，MCP-AQL 的自省适用于任何 MCP 客户端，因为它只是一个返回结构化数据的标准工具调用。无需客户端具备特殊功能。服务会描述自身。

  元素也采用相同的原则：YAML 前置元数据可供快速浏览，完整的 Markdown 内容则仅在激活后加载。大模型可以一目了然地列出 200 个元素，并深入查看所需元素。

• Token 效率 — 5 个端点约占 4,300 个 Token，而约 40 个独立工具约占 29,600 个 Token（减少 85%）。单一模式可进一步降至约 350 个 Token。

MCP-AQL 完整文档 — 协议设计、CRUDE 模式的设计依据、自省系统、端点模式和调试。

---

守门人：元素控制权限

每个 MCP-AQL 操作都会经过守门人——这是一个由 Dollhouse 元素直接控制的服务端权限系统。激活 Dollhouse Persona、Skill 或 Ensemble 后，其权限策略会立即生效。

 Example: Activate a "read-only analyst" persona

 ┌─────────────────────────────────────────────────────────────────┐
 │  Persona: read-only-analyst                                     │
 │                                                                 │
 │  gatekeeper:                                                    │
 │    allow:  [list_elements, search, get_element, introspect]     │
 │    deny:   [create_element, edit_element, delete_element,       │
 │             execute_agent, confirm_operation]                    │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  What the LLM CAN do:           What the LLM CANNOT do:        │
 │                                                                 │
 │  ✓ List and search elements     ✗ Create new elements           │
 │  ✓ Read element details         ✗ Edit existing elements        │
 │  ✓ Introspect operations        ✗ Delete anything               │
 │  ✓ Activate/deactivate          ✗ Run agents                    │
 │                                 ✗ Confirm any gated operation   │
 └─────────────────────────────────────────────────────────────────┘

即使 MCP 客户端启用了“始终允许”，此机制仍然有效。 守门人在服务端运行——客户端批准工具调用后，守门人仍会执行当前激活元素的策略。任何当前激活元素的拒绝策略都不能被大模型或客户端覆盖。

请根据用途使用守门人的两个界面：

• allow / confirm / deny 用于 MCP-AQL 操作模式，例如 read_*、edit_*、delete_element 和 execute_agent
• externalRestrictions 用于外部工具和钩子模式，例如 Read:*、Edit:*、Bash:git status* 和 Bash:rm *

策略解析方式

 deny  >  confirm  >  allow  >  route default
 (highest priority)              (lowest priority)

1. 元素拒绝 — 硬性阻止，无法确认或绕过
2. 元素确认 — 即使路由默认设置为自动批准，也需要用户确认
3. 元素允许 — 自动批准通常需要确认的操作
4. 路由默认设置 — 端点内置的权限级别（读取自动批准，删除需要确认）

所有当前激活元素的策略会叠加生效。如果一个 Persona 允许某项操作，而另一个拒绝该操作，则拒绝优先。这样你就能放心组合元素——以安全为重点的 Persona 可以限制操作，而 Skill 则可以添加功能。

实际使用效果

• 启用只读 Persona → 大模型只能浏览和搜索，即使你已向 MCP 客户端授予完全访问权限
• 启用安全分析师组合 → delete_element 和 rm -rf * 会被拒绝，但代码审查工具仍可正常工作
• 停用限制性元素 → 立即恢复完全访问权限
• 核弹级沙箱 → deny: ['confirm_operation'] 会阻止所有确认操作，使会话完全只读，直到停用该元素

平台兼容性：Gatekeeper 在服务端执行策略——拒绝和允许决策适用于任何 MCP 客户端。确认流程（大模型在遇到拦截时调用 confirm_operation）已在 Claude Code 和 DollhouseMCP Bridge 上经过广泛测试。只要大模型能够解析结构化工具响应并发起后续工具调用，该流程应该适用于任何 MCP 客户端，但尚未在所有平台上经过严格验证。

Gatekeeper 文档 — 确认流程、元素策略语法、沙箱模型、外部工具限制，以及会话允许问题。

---

作品集

你的 Dollhouse 元素存储在本地作品集 ~/.dollhouse/portfolio/（macOS/Linux）或 %USERPROFILE%\.dollhouse\portfolio\（Windows）中。让 AI “打开作品集浏览器”（或通过 MCP-AQL 调用 open_portfolio_browser），即可直观浏览其中的内容。通过大模型激活元素——让它“激活 Dollhouse 代码审查 Persona”，剩下的交给它处理。

• 本地优先 — 所有功能均可离线使用。无需账户。
• 捆绑 37 个元素 — 服务附带 7 个 Persona、7 个技能、8 个模板、7 个 Agent、3 个记忆和 5 个组合，作为入门内容。其中包括用于引导式帮助的 dollhouse-expert-suite 组合（Persona + 知识库记忆），以及能让大模型与服务端状态变化保持同步的 Session Monitor Agent。
• GitHub 同步 — 可选择将作品集备份到 GitHub 仓库，并与他人分享元素。
• 社区合集 — 浏览合集查看可用内容，然后直接通过 AI 安装元素。或者提交你自己的元素。

GitHub 作品集同步指南 — 备份到 GitHub、在多台设备间同步，以及向社区提交内容。

---

Dollhouse Agent 执行

Dollhouse Agent 不只是运行——每个步骤都会经过 MCP 服务、返回大模型，再经过 Gatekeeper。大模型负责语义决策；服务负责程序化强制执行。双方缺一不可。

 ┌───────────────┐
 │   HUMAN       │
 │  (optional)   │◄──── LLM asks for guidance
 │               │      when autonomy evaluator
 │ Approve, deny,│      says "pause"
 │ or guide      │
 └───────┬───────┘
         │ responds to LLM
         ▼
 ┌─────────────┐     ┌─────────────────────────────┐     ┌─────────────┐
 │             │     │  DollhouseMCP MCP Server     │     │             │
 │    LLM      │────▶│                              │────▶│    LLM      │
 │             │     │  1. Gatekeeper checks policy  │     │             │
 │  Decides    │     │  2. Autonomy Evaluator scores │     │  Records    │
 │  next       │     │  3. Danger Zone enforcement   │     │  step and   │
 │  action     │     │  4. Execute or block          │     │  continues  │
 │             │     │  5. Return result + autonomy  │     │  or pauses  │
 │             │◀────│     guidance to LLM           │◀────│             │
 └─────────────┘     └─────────────────────────────┘     └─────────────┘
        │                                                       │
        └──────────────── repeats every step ───────────────────┘

循环中的每个步骤：

• Gatekeeper 会根据当前生效的元素策略检查每项操作——拒绝、确认或允许
• Autonomy Evaluator 会评估 Agent 是否应继续自主运行，或暂停以等待人工输入
• Danger Zone 会对高风险操作（删除文件、调用外部 API、执行系统命令）实施硬性拦截
• 步骤记录 会为每项决策和结果创建审计跟踪
• 大模型会在每次响应中收到自主性指导——继续、暂停或升级处理——确保 Agent 始终受到监控

这意味着 Dollhouse Agent 无法在不被察觉的情况下提升权限。每个操作都清晰可见，每个步骤都会经过评估，生效的元素策略会在整个执行过程中得到强制执行。

平台说明：Agent 式循环依赖大模型按顺序调用 MCP 工具并解读结构化响应——这是标准的 MCP 行为。该功能已在 Claude Code 和 DollhouseMCP Bridge 上经过充分测试。服务端强制执行机制（Gatekeeper、Danger Zone、步骤记录）与平台无关。大模型遵循自主性指导（继续／暂停／升级处理）的能力取决于其解读结构化工具响应的能力，不同平台之间可能有所差异。

完整的 Agent 执行文档——涵盖 Agent 式循环、安全强制执行、人机协同控制、Agent 组合、弹性策略和执行生命周期操作。

---

更多功能

• Web Portfolio 浏览器 — 内置 Web 控制台，可直观浏览和管理你的 Portfolio。让 AI“打开 Portfolio 浏览器”，或单独运行 npm run web。
• 批量操作 — 在单个 MCP-AQL 请求中执行多项操作，提升工作流效率
• 激活状态持久化 — 会话中激活的元素会在服务重启后恢复，无需重新激活。
• 通用备份 — 内置 Portfolio 元素备份服务，并支持恢复
• 缓存内存预算 — 可配置集合和索引缓存的内存预算，以控制资源使用量
• NLP 发现 — 使用 Jaccard 相似度和 Shannon 熵评分，实现智能元素搜索与发现
• 跨元素关联 — 采用 GraphRAG 风格的元素映射，帮助查找相关内容
• 强化安全性 — 输入净化、路径遍历防护、YAML 注入防护、文件锁定、DOMPurify 净化，以及针对数百种攻击向量的内容验证。安全文档
• 跨平台 — 已在 Windows、macOS 和 Linux 上针对 Node.js 20+ 进行测试

---

安装选项

上方的快速入门介绍了最快的安装方式。如需更多控制：

本地安装（推荐用于多个配置）

mkdir -p ~/mcp-servers && cd ~/mcp-servers
npm install @dollhousemcp/mcp-server

然后将 MCP 客户端指向 node <path>/node_modules/@dollhousemcp/mcp-server/dist/index.js。

MCP-AQL 端点模式

模式	端点	Token 数	环境变量	适用场景
CRUDE（默认）	5	~4,300	MCP_AQL_ENDPOINT_MODE=crude	大多数用户。通过主机级权限控制实现语义分组
Single	1	~350	MCP_AQL_ENDPOINT_MODE=single	上下文窗口受限的多服务配置
Discrete	~40	~29,600	MCP_INTERFACE_MODE=discrete	与 v1 工具名称向后兼容

注意：CRUDE 和 Single 由 MCP_AQL_ENDPOINT_MODE 控制。Discrete 模式使用不同的变量：MCP_INTERFACE_MODE=discrete。

常见配置

变量	默认值	描述
MCP_AQL_ENDPOINT_MODE	crude	端点模式：crude、single
MCP_INTERFACE_MODE	mcpaql	接口风格：mcpaql、discrete
DOLLHOUSE_PORTFOLIO_DIR	~/.dollhouse/portfolio/	自定义作品集位置
GITHUB_TOKEN	—	用于 GitHub 操作的个人访问令牌

完整的环境变量参考 · 其他平台的 MCP 客户端设置

---

文档

指南	描述
快速入门指南	Claude Code、Desktop、Cursor、Gemini、Codex、本地大模型的平台专属安装指南
公开测试版入门指南	10 分钟内完成安装并创建第一个人格
大模型快速参考	面向 AI 助手编写的操作速查表
MCP-AQL 架构	CRUDE 协议、内省、端点模式
Gatekeeper 安全模型	权限层、元素策略、沙箱模型
GitHub 作品集同步	备份到 GitHub、在设备间同步、向社区提交内容
记忆系统	持久化上下文的存储与检索
Skills 转换器	双向 Agent 技能转换
Agent 执行	Agent 循环、安全执行、人类参与的闭环、组合
架构概览	系统设计、DI 容器、数据流
安全	威胁模型、测试和漏洞报告
API 参考	完整的 MCP 工具目录和载荷模式
V2 迁移指南	从 v1.x 升级
故障排除	常见问题及解决方案

---

贡献

欢迎提交贡献，包括错误报告、功能请求、文档、代码和社区元素。

git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install && npm run build && npm test

完整的开发工作流、分支策略和代码风格指南，请参阅 CONTRIBUTING.md。

---

社区

• GitHub 讨论区 — 提问、交流想法和展示成果
• GitHub Issues — 错误报告和功能请求
• Discord — 实时聊天
• 浏览作品集 — 浏览并安装社区贡献的 Dollhouse 元素
• 作品集仓库 — 提交内容和贡献的源代码仓库

---

许可证

AGPL-3.0-or-later — 可免费使用、修改和分发。通过网络使用时必须公开源代码。完整条款请参阅 LICENSE。

---

版权所有 2024-2026 Mick Darling / DollhouseMCP