soulpack-reader

给任何 AI 智能体赋予角色人格、语音、2D 形象和可迁移的灵魂记忆。

> MCP Server + Skill — 兼容 Windsurf、Cursor、Claude Desktop 及任何 MCP 客户端。

---

Soul Pack 只提供素材和使用建议，不做实现层。

智能体本身具备 AI coding 能力。拿到素材（人格设定、语音偏好、头像/表情资产、记忆）后，智能体可以自行编程实现任何功能——换头像、换声音、加表情系统、改 UI 主题色——无需 Soul Pack 替它完成。

我们的角色：素材仓库 + 灵感建议，不是运行时引擎。

| 能力 | 说明 | |------|------| | 角色人格 | 将角色性格、说话风格、规则自动注入 system prompt | | 语音素材 | 提供 TTS 语音偏好配置（OpenAI / ElevenLabs / Edge TTS），智能体按需自行接入 | | 2D 形象素材 | 提供头像 URL、表情图集（default/happy/sad/thinking…），智能体按环境自行消费 | | 灵魂记忆 | 跨会话持久化，可导出/导入/迁移到其他实例 | | AI coding 引导 | 告诉智能体有哪些素材可用，建议它通过编程实现宿主缺失的功能 |

---

在你的 AI 工具中添加 MCP Server 配置：

Windsurf — 编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "soulpack-reader": {
      "command": "npx",
      "args": ["-y", "soulpack-reader"]
    }
  }
}

Cursor — 编辑 ~/.cursor/mcp.json，格式同上。

Claude Desktop — 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，格式同上。

保存后重启 AI 工具即可。npx 会自动下载并运行，不需要手动 clone 或 npm install。

> MCP Server 启动时会自动在 127.0.0.1:18790 开启 HTTP 端口，供网站一键安装使用。无需额外配置。 > 如需关闭，设置环境变量 SOULPACK_HTTP_DISABLE=1。

方式 A：环境变量自动加载

设置 SOULPACK_DEFAULT_PACK 指向 .soulpack.json 文件（见上方配置）。

方式 B：对话中手动加载（本地文件）

soulpack_select({ path: "/path/to/luna.soulpack.json" })

方式 C：通过 URL 直接安装（从网站复制下载链接）

soulpack_install({ url: "https://your-site.com/api/registry/packs/luna-v1/download" })

soulpack_export_state({ outputPath: "/backup/luna-memories.json" })
soulpack_import_state({ source: "/backup/luna-memories.json" })

---

soulpack-reader/
├── README.md
├── SPEC.md                     # Soul Pack JSON 规范
├── package.json
├── tsconfig.json
│
├── src/
│   ├── index.ts                # MCP Server 入口（stdio）
│   ├── types.ts                # 数据类型：Pack / State / Overlay / Voice / Appearance
│   ├── reader.ts               #