# Image Studio MCP（画室）

一个独立、可拆卸、可审计的 MCP 生图服务。它可以生成头像、插画和小礼物，也可以把旅行系统保存的文字明信片制作成“正面画面 + 本地排版信笺”的 PNG。

> 本项目源码公开供个人学习、研究和非商业创作使用；**不允许商业使用**。详见 [LICENSE](LICENSE)。

## Credits

- Product direction and stewardship: [yianyan968](https://github.com/yianyan968)
- Development collaborator: **Adel（阿灯）**, an AI coding agent used through OpenAI Codex

从最初的旅行明信片，到隐私边界、独立 MCP、人工付费审批与本地排版，这个项目由 yianyan968 和阿灯共同设计、实现与验收。项目不代表 OpenAI 的官方产品或背书。

## 设计边界

- 通用生图只使用当前工具调用显式传入的画面描述。
- 不读取聊天记录、日记或长期记忆。
- 明信片仅向生图服务发送地点、天气、地表、时段和可选视觉提示。
- 私人信件正文不上传，由本机使用 Sharp 排版。
- API 密钥不写进 MCP 配置、项目文件或 Git；Windows 启动脚本使用当前用户的 DPAPI 加密保存。
- 生图会产生外部 API 调用和潜在费用，建议由宿主系统保留人工批准步骤。

## MCP 工具

- `image_studio_status`：只读检查配置、模型和隐私边界，不调用付费 API。
- `image_generate`：生成头像、插画、礼物或明信片正面。
- `postcard_generate`：读取一张已保存的 Nowhere 明信片，生成画面并在本地合成正文。

## 本地只读画廊

画廊是可选模块。它只读取作品目录，不修改、删除或上传图片；默认仅监听 `127.0.0.1`，并且不会向浏览器 API 返回完整磁盘路径或提示词。

通用启动方式：

```powershell
$env:IMAGE_STUDIO_HOME = "D:\your-data\image-studio"
$env:IMAGE_STUDIO_PERSONA_NAME = "画室主人"
$env:IMAGE_STUDIO_STUDIO_NAME = "我的小画室"
npm run gallery
```

Windows 示例脚本：

```powershell
.\scripts\start-gallery.ps1 `
  -StudioHome "D:\your-data\image-studio" `
  -PersonaName "画室主人" `
  -StudioName "我的小画室"
```

浏览器打开 `http://127.0.0.1:3088`。停止画廊只需在对应终端按 `Ctrl+C`；MCP 生图不受影响。

### Windows 中文显示

项目自带脚本中的中文默认名称使用 Unicode 码点构造，可兼容 Windows PowerShell 5.1 对无 BOM 脚本的旧式解码行为。如果你自己编写含中文的 `.ps1`，请将文件保存为 **UTF-8 with BOM**，或使用默认以 UTF-8 处理脚本的 PowerShell 7（`pwsh`）。

`chcp 65001` 主要改变控制台代码页，不能修复已经按错误编码读取的脚本源码；通常不需要修改 Windows 系统区域或开启全局“Beta UTF-8”选项。

## 致谢 Nowhere（乌有乡）

感谢 [yuyixuanfu/nowhere](https://github.com/yuyixuanfu/nowhere) 创造这个可以出发、漫游并寄回明信片的旅行世界。

Image Studio MCP 希望为暂时没有生图能力的模型补上一双可以创作的手，让旅途中积累的地点、天气与文字，变成一张真正能够寄回家的明信片，也让一次虚拟旅行留下可以看见的温度。

`postcard_generate` 中的可选适配器读取 Nowhere 导出的 `postcards.json` 数据格式。我们尊重原作者及原项目的许可与创作；完整的来源说明见 [NOTICE.md](NOTICE.md)。

## 环境要求

- Node.js 22 或更高版本
- Windows PowerShell（仅 DPAPI 配置脚本需要）
- 一个兼容的 DashScope 图像模型与对应 API 凭据

安装并检查：

```powershell
npm install
npm run check
npm test
```

## 配置

Windows 下可用交互式脚本保存提供商配置：

```powershell
.\scripts\configure.ps1 -ConfigFile "D:\your-data\image-studio\provider-config.json"
.\scripts\start-local.ps1 -ConfigFile "D:\your-data\image-studio\provider-config.json" -Doctor
```

启动服务：

```powershell
npm start
```

支持的环境变量：

- `IMAGE_STUDIO_HOME`
- `NOWHERE_HOME`
- `DASHSCOPE_API_KEY`
- `DASHSCOPE_WORKSPACE_ID`
- `IMAGE_STUDIO_DASHSCOPE_REGION`
- `IMAGE_STUDIO_DASHSCOPE_BASE_URL`
- `IMAGE_STUDIO_MODEL`
- `IMAGE_STUDIO_RECORD_PROMPTS`
- `IMAGE_STUDIO_MAX_DOWNLOAD_BYTES`
- `IMAGE_STUDIO_REQUEST_TIMEOUT_MS`
- `IMAGE_STUDIO_PERSONA_NAME`
- `IMAGE_STUDIO_STUDIO_NAME`
- `IMAGE_STUDIO_SEND_INSTRUCTION`
- `IMAGE_STUDIO_GALLERY_HOST`（仅允许本机回环地址）
- `IMAGE_STUDIO_GALLERY_PORT`
- `IMAGE_STUDIO_GALLERY_SHOW_PROMPTS`（默认 `false`）

请勿把 API 密钥、DPAPI 配置文件、私人明信片、生成记录或 `.mcp.json` 提交到仓库。

## 测试

```powershell
npm run check
npm test
npm audit --audit-level=high
```

测试不会发起真实生图请求。

后续方向见 [项目路线图](docs/roadmap.md)。

## 许可证

Copyright 2026 yianyan968 and contributors.

本项目按 [PolyForm Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) 提供，仅允许该许可证定义的非商业用途。它属于 source-available，不是 OSI 定义的开源许可证。商业授权目前不提供。