Dollhousemcp

🚀 DollhouseMCP

DollhouseMCP 是一個全面的模型上下文協議（MCP）服務器，它藉助集成的 GitHub 集合實現動態 AI 角色管理。該項目允許 Claude 等兼容的 AI 助手激活不同的行為角色，同時支持社區共享和貨幣化。

項目狀態與支持平臺

平臺支持

項目鏈接

• 🌐 倉庫地址：https://github.com/DollhouseMCP/mcp-server
• 🏪 集合地址：https://github.com/DollhouseMCP/collection
• 📦 NPM 包地址：https://www.npmjs.com/package/@mickdarling/dollhousemcp
• 🌍 網站地址：https://dollhousemcp.com (計劃中)
• 📦 版本信息：v1.2.4 (當前版本) | v1.2.5 (下一版本)

⚠️ 重要提示

工具名稱已從 "marketplace" 更改為 "collection"。舊名稱仍然可用，但已被棄用。詳情請參閱 遷移指南。

🚀 快速開始

安裝

NPM 全局安裝

# 全局安裝
npm install -g @mickdarling/dollhousemcp

# 添加到 Claude Desktop 配置（根據操作系統選擇相應路徑）
# 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"]
    }
  }
}

自動化設置（僅適用於 Claude Desktop）

# 克隆倉庫
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server

# 運行自動化安裝腳本（僅適用於 Claude Desktop）
./setup.sh

手動安裝

# 克隆倉庫
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"

Claude Desktop 配置

NPM 安裝配置

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

源碼安裝配置

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

完成配置後，保存文件並完全重啟 Claude Desktop，即可使用 DollhouseMCP 的 23 個工具。你可以嘗試使用 list_personas 命令開始體驗。

✨ 主要特性

特性	描述
🎭 23 個 MCP 工具	通過聊天界面實現完整的角色生命週期管理
🏪 GitHub 集合	瀏覽、搜索、安裝和提交角色到社區集合
👤 用戶身份系統	基於環境的角色創建者歸屬
🆔 唯一 ID 系統	高級 ID 生成：what-it-is_YYYYMMDD-HHMMSS_who-made-it
💬 基於聊天的管理	通過對話界面創建、編輯和驗證角色
🔄 實時操作	實時編輯，自動增加版本號並進行驗證
🚀 自動更新系統	企業級自動更新，支持備份/回滾和依賴驗證
🛡️ 數據保護	默認角色採用寫時複製，具備全面的備份系統
🏠 本地優先架構	無需依賴雲即可實現完整功能

🔒 企業級安全（v1.2.4）

DollhouseMCP 實施了全面的安全措施，以保護你的角色和系統：

安全特性

• 🛡️ 內容淨化：集成 DOMPurify 防止角色內容中的 XSS 攻擊
• 📝 防止 YAML 注入：通過模式驗證和大小限制進行安全解析
• 🔐 令牌安全：驗證 GitHub 令牌，靜態加密，並支持輪換
• 🐳 容器加固：非根執行、只讀文件系統和資源限制
• 🚦 速率限制：使用令牌桶算法防止 API 濫用（默認每小時 10 次檢查）
• ✅ 簽名驗證：GPG 驗證確保版本的真實性
• 🔍 輸入驗證：對所有用戶輸入進行全面驗證
• 📊 安全監控：對與安全相關的操作進行審計日誌記錄

安全測試

• 487 個全面測試，包括特定於安全的測試套件
• 持續安全掃描，使用 GitHub Advanced Security
• 無漏洞：所有安全警報均已解決（0 個活動警報）

📋 先決條件

• Node.js：v20.0.0 或更高版本（建議使用 LTS 版本）
• npm：v10.0.0 或更高版本
• git：用於克隆倉庫
• 操作系統：Windows、macOS 或 Linux

💡 使用建議

DollhouseMCP 在 Node.js 24 上開發，但支持 Node.js 20 及更高版本以實現廣泛的兼容性。

🛠️ 可用工具（共 23 個）

核心角色管理

• list_personas - 顯示所有本地角色，並帶有增強的元數據
• activate_persona - 通過名稱、文件名或唯一 ID 激活角色
• get_active_persona - 獲取當前角色信息
• deactivate_persona - 返回默認模式
• get_persona_details - 查看完整的角色詳細信息
• reload_personas - 從文件系統刷新角色

GitHub 集合集成

• browse_collection - 按類別瀏覽角色
• search_collection - 在所有集合角色中進行搜索
• get_collection_persona - 查看集合角色的詳細信息
• install_persona - 一鍵下載並安裝
• submit_persona - 通過 GitHub 問題提交到集合

用戶身份管理

• set_user_identity - 設置用於角色歸屬的用戶名
• get_user_identity - 查看當前身份狀態
• clear_user_identity - 返回匿名模式

基於聊天的角色管理

• create_persona - 通過聊天引導創建角色
• edit_persona - 修改現有角色字段
• validate_persona - 進行全面的質量驗證

自動更新系統

• check_for_updates - 檢查 GitHub 版本以獲取可用的 DollhouseMCP 更新
• update_server - 自動執行 git pull + npm install + 構建，並創建備份
• rollback_update - 從自動備份中恢復上一個版本
• get_server_status - 獲取全面的服務器狀態，包括版本、git 信息和系統詳細信息

角色指示器

• configure_indicator - 配置角色指示器在 AI 響應中的顯示方式
• get_indicator_config - 查看當前指示器配置設置

💻 使用示例

集合操作

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                          # 檢查是否有可用的 DollhouseMCP 更新
get_server_status                          # 查看當前版本和系統信息
update_server true                         # 執行自動更新並創建備份
rollback_update true                       # 必要時恢復上一個版本

自動更新系統工作原理：

1. 版本檢查：查詢 GitHub 版本 API 以獲取最新版本
2. 備份創建：自動備份當前安裝（包括用戶角色）
3. 更新過程：執行 git pull 獲取最新代碼，運行 npm install 更新依賴，使用 npm run build 重建 TypeScript
4. 驗證：驗證更新是否成功
5. 回滾選項：保留最後 5 個備份，以便輕鬆恢復

安全特性：

• 速率限制防止 API 濫用
• GPG 簽名驗證（可用時）
• 依賴版本驗證
• 自動備份保留（最近 5 個）
• 更新期間保留用戶角色

角色指示器

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=🎨

🖥️ 跨平臺安裝

🐧 Linux 安裝

先決條件

• Node.js：v20.0.0 或更高版本
• npm：v10.0.0 或更高版本
• git：用於版本控制

# 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 或更高版本

安裝步驟

# 克隆並構建
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"

Claude Desktop 配置（Linux）

# 配置文件位置
~/.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"]
    }
  }
}

🪟 Windows 安裝

先決條件

• Node.js：v20.0.0 或更高版本
• npm：v10.0.0 或更高版本（包含在 Node.js 中）
• git：用於版本控制

# 從 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 或更高版本

安裝步驟（PowerShell）

# 克隆並構建
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"

Claude Desktop 配置（Windows）

# 配置文件位置
$env:APPDATA\Claude\claude_desktop_config.json

配置內容（使用正斜槓或雙反斜槓）：

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

🍎 macOS 安裝

先決條件

• Node.js：v20.0.0 或更高版本
• npm：v10.0.0 或更高版本（包含在 Node.js 中）
• git：用於版本控制

# 使用 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"

Claude Desktop 配置（macOS）

# 配置文件位置
~/Library/Application Support/Claude/claude_desktop_config.json

配置內容：

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

🐳 Docker 安裝

Docker 快速開始

# 克隆倉庫
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（推薦）

生產部署：

docker-compose up -d

開發環境熱重載：

docker-compose --profile dev up dollhousemcp-dev

使用 Docker 自定義角色

# 掛載自定義角色目錄
docker run -d \
  --name dollhousemcp \
  -v /path/to/your/personas:/app/personas \
  -e DOLLHOUSE_USER="your-username" \
  dollhousemcp

Docker 環境變量

# 設置用戶身份
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

測試覆蓋率

當前測試覆蓋率包括：

• ✅ 102 個全面測試，涵蓋所有功能
• ✅ 自動更新系統 - GitHub API、備份/回滾、依賴驗證
• ✅ 安全測試 - 防止命令注入、輸入驗證
• ✅ 跨平臺兼容性 - Windows、macOS、Linux 路徑處理
• ✅ 版本驗證 - 對 git/npm 輸出格式進行解析測試
• ✅ 邊緣情況覆蓋 - 網絡故障、缺少依賴、格式錯誤的輸入

手動驗證

驗證你的設置是否正常工作：

# 構建項目
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    # 檢查當前系統狀態

☁️ 雲部署

容器註冊表

該項目支持部署到以下容器註冊表：

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

雲部署示例

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

🏗️ 項目結構

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                    # 項目上下文（針對 Claude）
└── 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	貨幣化字段 - TODO: 未來版本（將支持 "free" 或定價層級）

📚 內置角色

角色	用途	適用場景
創意作家	富有想象力的故事講述和創意內容創作	頭腦風暴、創意寫作、引人入勝的敘事
技術分析師	深入的技術分析和系統問題解決	架構決策、調試、技術文檔編寫
ELI5 解釋者	為初學者簡化複雜主題	教學、入職培訓、概念解釋
商業顧問	戰略業務分析和建議	戰略規劃、商業決策、市場分析
調試偵探	系統調試和故障排除	查找 bug、系統故障排除、根本原因分析

🏪 集合集成（Beta）

⚠️ 重要提示

基於 GitHub 的集合目前處於 Beta 階段。功能可能會根據社區反饋進行更改。

DollhouseMCP 包含一個實驗性的基於 GitHub 的集合：

• 按類別瀏覽：創意、專業、教育、遊戲、個人
• 內容搜索：通過關鍵字和描述查找角色
• 一鍵安裝：下載並集成集合中的角色
• 社區提交：通過 submit_persona 工具提交你的角色
• 版本控制：所有集合內容都有完整的 Git 歷史記錄

⚠️ 遷移指南 - 重大變更

重要：最近版本中工具名稱已更改：

• browse_marketplace → browse_collection
• search_marketplace → search_collection
• get_marketplace_persona → get_collection_persona

如果你有使用舊工具名稱的腳本或工作流，請更新為使用新名稱。

💼 商業模式與法律

許可協議

• 核心服務器：AGPL-3.0（防止專有競爭平臺）
• 角色內容：免費角色採用 CC-BY-SA-4.0 許可協議，高級角色採用自定義許可協議
• 平臺條款：創作者友好的 80/20 收入分成（僅適用於貨幣化實施後的付費角色）

平臺穩定性承諾

• 提前 90 天通知貨幣化變更
• 現有付費角色的 12 個月收入分成鎖定
• 透明的平臺政策更新治理
• 完整的數據可移植性權利
• 社區對政策變更的諮詢意見

🛠️ 開發

可用腳本

腳本	描述
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:*"                  # 調試日誌記錄（可選）

🔧 故障排除

常見問題

問題	解決方案
角色未加載	檢查 personas/ 目錄是否存在並具有讀取權限
服務器無法啟動	運行 npm run rebuild 清理並重新構建
集合無法工作	檢查網絡連接和 GitHub API 訪問權限
用戶身份未保存	在啟動 Claude 之前設置 DOLLHOUSE_USER 環境變量
"找不到模塊" 錯誤	確保 npm install 成功完成
TypeScript 編譯錯誤	使用 node --version 驗證 Node.js 版本是否為 20+
工具未在 Claude 中顯示	配置更改後完全重啟 Claude Desktop
默認角色被修改	v1.2.1+ 版本使用寫時複製；必要時使用 git restore 恢復
更新/回滾問題	檢查寫入權限；使用 DOLLHOUSE_DISABLE_UPDATES=true 禁用更新
速率限制錯誤	等待 60 秒；GitHub API 有每小時的限制

調試步驟

1. 檢查構建狀態：

   npm run build
   

2. 驗證角色文件：

   ls -la personas/*.md
   

3. 測試服務器啟動：

   node dist/index.js
   

4. 驗證配置：

   # 檢查 Claude Desktop 配置
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # 驗證 Node.js 版本（需要 20+）
   node --version
   
   # 檢查 npm 版本
   npm --version
   

5. 測試自動更新系統：

   # 在 Claude Desktop 中使用
   check_for_updates    # 檢查是否有可用更新
   get_server_status    # 查看系統信息
   

6. 驗證角色： 使用 reload_personas 工具檢查加載錯誤

🤝 貢獻

我們歡迎貢獻！DollhouseMCP 包含集成工具，可直接從 Claude 提交角色。

集成貢獻流程（推薦）

1. 創建或修改角色，使用基於聊天的工具：

   create_persona "My Awesome Persona" "A helpful assistant for..." "professional"
   

2. 驗證你的角色，確保質量：

   validate_persona "My Awesome Persona"
   

3. 直接從 Claude 提交到集合：

   submit_persona "My Awesome Persona"
   

   這將自動創建一個 GitHub 問題供社區審核。

手動貢獻流程

1. 分叉倉庫
2. 在 personas/ 或 custom-personas/ 目錄中創建角色文件
3. 遵循元數據格式和命名約定
4. 使用 validate_persona 工具進行徹底測試
5. 提交帶有清晰描述的拉取請求

報告問題

請提供以下信息：

• Node.js 版本 (node --version)
• 操作系統和版本
• 完整的錯誤消息
• 重現問題的步驟
• 相關的角色文件（如果適用）
• Claude Desktop 配置（不包含敏感路徑）

開發指南

1. 遵循 TypeScript 最佳實踐
2. 保持現有代碼風格和模式
3. 添加全面的錯誤處理
4. 為新功能更新文檔
5. 在提交 PR 之前進行全面的跨平臺測試
6. 為新功能添加測試
7. 遵循語義化版本控制進行發佈

開發工作流

# 分叉並克隆
git clone https://github.com/your-username/DollhouseMCP.git
cd mcp-server

# 安裝依賴
npm install

# 創建功能分支
git checkout -b feature/your-feature-name

# 進行更改並測試
npm run build
npm test

# 提交併推送
git commit -m "feat: your feature description"
git push origin feature/your-feature-name

# 提交拉取請求

📄 API 參考

MCP 工具規範

每個工具遵循 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 - 無參數

錯誤處理

服務器為以下情況提供詳細的錯誤消息：

• 無效的角色標識符 - 提供有效名稱的清晰建議
• 文件系統問題 - 權限和路徑解析錯誤
• 格式錯誤的角色文件 - YAML 解析和驗證錯誤
• 網絡錯誤 - GitHub API 和集合連接問題
• 運行時錯誤 - 服務器啟動和操作失敗

響應格式

所有響應遵循一致的模式：

• 成功響應：包含請求的數據和操作狀態
• 錯誤響應：包含錯誤類型、消息和建議的解決方案
• 進度指示器：為長時間操作提供逐步反饋
• 驗證結果：包含詳細報告和建議

📄 許可證

本項目採用 AGPL-3.0 許可證，並具有平臺穩定性承諾 - 詳情請參閱 LICENSE 文件。

平臺穩定性保證：

• 提前 90 天通知政策變更
• 12 個月的收入分成鎖定
• 完整的數據可移植性權利
• 社區諮詢意見

🏷️ 版本歷史

v1.2.5 - 2025 年 7 月（下一版本）

集合重命名及重大變更：

• 🔄 將所有 "marketplace" 工具重命名為 "collection"：
  • browse_marketplace → browse_collection
  • search_marketplace → search_collection
  • get_marketplace_persona → get_collection_persona
  • install_persona → install_persona（未更改）
  • submit_persona → submit_persona（未更改）
• ✅ 添加向後兼容別名（已棄用，將在 v2.0.0 中移除）
• ✅ 更新倉庫，從 /personas 改為 /collection
• ✅ 創建遷移指南，幫助用戶更新腳本
• ✅ 修復所有日期引用，從 1 月改為 7 月 2025 年

v1.2.4 - 2025 年 7 月 10 日（當前版本）

關鍵修復：

• ✅ 修復 MCP 協議兼容性 - 控制檯輸出不再破壞 JSON-RPC 通信
• ✅ 添加 MCP 安全日誌實用工具，用於在協議會話期間進行正確的日誌記錄
• ✅ 解決 Claude Desktop 中的連接失敗問題
• ✅ 更新 Docker 測試，以適應新的日誌記錄方法
• ✅ 添加全面的日誌單元測試

v1.2.3 - 2025 年 7 月 10 日

錯誤修復：

• ✅ 修復生產環境中角色目錄的路徑解析問題
• ✅ 從 process.cwd() 改為基於 __dirname 的路徑
• ✅ 修復安裝腳本，使用正確的工具數量和倉庫 URL

v1.2.2 - 2025 年 7 月 10 日

• ✅ 全面的安全增強：
  • 使用 DOMPurify 進行內容淨化 (SEC-001)
  • 防止 YAML 注入 (SEC-003)
  • GitHub 令牌安全 (SEC-004)
  • Docker 容器加固 (SEC-005)
• ✅ 487 個全面測試，包括廣泛的安全覆蓋
• ✅ 修復 CI 計時測試，以實現可靠的跨平臺測試
• ✅ 修復所有測試文件的 TypeScript 編譯問題
• ✅ 解決所有安全漏洞（0 個活動警報）

v1.2.1 - 2025 年 7 月 8 日

• ✅ 關鍵數據保護錯誤修復：
  • 默認角色採用寫時複製 (問題 #145)
  • 備份中包含用戶角色 (問題 #144)
• ✅ 要求 Node.js 20+，以實現 npm 發佈兼容性
• ✅ 372 個全面測試，涵蓋所有功能
• ✅ 增強安全性，解決所有漏洞
• ✅ 改進文檔，明確先決條件

v1.2.0 - 2025 年 7 月 7 日

• ✅ 實現速率限制，防止 API 濫用
• ✅ GPG 簽名驗證，確保版本真實性
• ✅ 集成 GitHub Advanced Security
• ✅ 309 個測試，改進 CI 環境覆蓋
• ✅ 優化包大小，達到 279.3 kB

v1.1.0 - 2025 年 7 月 4 日

• ✅ 特定平臺徽章，顯示 Windows、macOS、Linux 支持情況
• ✅ GitHub 項目管理，包含問題模板和里程碑
• ✅ 修復 ARM64 Docker 問題，從 Alpine 基礎鏡像切換到 Debian
• ✅ 100% 工作流可靠性（除 Docker ARM64 外）
• ✅ 首次 GitHub 發佈，包含 CHANGELOG.md
• ✅ 發佈時共有 21 個 MCP 工具

階段 2B+ - 2025 年 7 月 3 日

• ✅ 企業級自動更新系統，包含 4 個新的 MCP 工具
• ✅ 50 個全面測試，涵蓋所有功能
• ✅ 安全加固 - 消除所有命令注入漏洞
• ✅ 跨平臺支持 - Windows、macOS、Linux，通過 CI/CD 測試
• ✅ Docker 容器化，包含生產和開發配置
• ✅ 共有 21 個 MCP 工具，支持備份/回滾和依賴驗證

階段 2B - 2025 年 7 月 1 - 2 日

• ✅ 完成基於聊天的角色管理
• ✅ 集成 GitHub 市場
• ✅ 用戶身份和歸屬系統
• ✅ 實時驗證和編輯
• ✅ 企業級 GitHub Actions 安全

階段 1 - 2025 年 7 月 1 日

• ✅ 全新的 AGPL-3.0 許可倉庫
• ✅ 增強的唯一 ID 系統
• ✅ 支持匿名用戶
• ✅ 市場就緒的元數據模式

---

🎭 藉助角色的力量改變你的 AI 交互體驗

如需支持，請 提交問題 或訪問我們的 集合。