DevSpace Local Artifacts

DevSpace Local Artifacts is a self-hosted MCP server for operating on approved local workspaces from ChatGPT, Claude, or another MCP-capable host. This release keeps the server local and adds guarded binary-artifact support for Windows plus a Base64 fallback for hosts that cannot send native file parameters.

What this release adds

• download_artifact on Linux and Windows, with traversal, overwrite, symlink/junction, size, and publication-integrity checks.

• write_binary for strict Base64 strings and Base64 data URLs (maximum 32 MiB per inline payload).

• bounded MCP JSON parsing so oversized binary requests fail with a clear response instead of consuming unbounded memory.

• focused artifact, server-order, file-tool, performance, typecheck, and build checks.

Related MCP server: mcp-devtools

与上游 Waishnav/devspace v1.0.5 的差异

Word 和 PDF 并不是被工具排除的格式。上游版本和本定制版都会把文件作为 二进制字节保存，不会转换或编辑文档内容；真正的差异在于平台支持和文件输入方式：

• 上游 v1.0.5 的 download_artifact 仅在 Linux 注册，Windows 上不能通过原生 MCP 文件对象保存附件。

• 本定制版将 download_artifact 扩展到 Linux 和 Windows，并保留工作区边界、 路径穿越、覆盖、符号链接/ junction、大小和发布完整性检查。因此，在 Windows 上可以保存 MCP 主机提供的 .pdf、.docx 等文件。

• 本定制版新增 write_binary，当 MCP 主机不能传递原生文件对象时，可用完整的 Base64 字符串或 data:*;base64 URL 写入二进制文件；单个内联负载上限为 32 MiB。

保存 Word/PDF 的前提是设置 DEVSPACE_ARTIFACTS=1、先调用 open_workspace，并 使用工作区内新的相对路径。download_artifact 不接受任意下载 URL，也不会读取浏览器 下载目录；如果聊天客户端没有把附件作为原生文件传给 MCP，这属于客户端能力限制， 应改用 write_binary 或客户端支持的文件适配器。服务只负责保存字节，不负责生成、 解析或编辑 Word/PDF 内容。

Requirements

• Node.js >=22.19 <27

• npm and Git

• Bash on Windows (Git Bash, WSL, MSYS2, or Cygwin)

• ngrok CLI only when a remote MCP host must reach the local server

The complete Node dependency graph is committed in package-lock.json. better-sqlite3 is a native dependency and node-pty is optional.

Install from GitHub

git clone https://github.com/cooky-dance/devspace-local-artifacts.git
Set-Location devspace-local-artifacts
npm ci
npm run build
npm install -g .

The global install exposes the devspace command. To work from the checkout, use npm run dev instead.

中文使用指南：安装后会不会自动运行？

不会。npm install -g . 只安装命令，不会注册 Windows 服务、计划任务， 也不会自动启动 ngrok。DevSpace 和 ngrok 是两个需要分别运行的前台进程。

DevSpace 自身有一个方便的首次启动行为：

• devspace（不带参数）和 devspace serve 都会先检查配置；在可交互的终端 中，如果尚未配置，会自动进入初始化向导，然后启动服务器。

• 在非交互终端中不会自动提问，而是报错并提示先运行 devspace init，或提供 DEVSPACE_OAUTH_OWNER_TOKEN 与 DEVSPACE_ALLOWED_ROOTS。

• devspace init 会询问允许访问的本地根目录、监听端口和公网基础 URL，并创建： %USERPROFILE%\.devspace\config.json 与 %USERPROFILE%\.devspace\auth.json。如果设置了 DEVSPACE_CONFIG_DIR，实际位置 以该目录为准。

• devspace serve 在当前终端前台运行；按 Ctrl+C 会停止它。ngrok 必须在另一个 终端单独运行。

因此，安装完成后并不会“开机自启”。如果确实需要开机启动，可以自行用 Windows 任务计划程序或一个受保护的 PowerShell 启动脚本注册两个进程；项目本身不会替你 创建任务，也不要把 ngrok 令牌或 Owner password 写进脚本。

Windows 推荐启动顺序（端口 3003 示例）

下面的 3003 只是示例；你也可以使用默认的 7676，但 DevSpace 监听端口和 ngrok 目标端口必须完全一致。

一次性安装和初始化：

npm install -g .
.\scripts\install-ngrok.ps1
ngrok config add-authtoken <YOUR_NGROK_TOKEN>

$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
devspace init

初始化时，公网基础 URL 只填 origin，例如 https://your-tunnel-host.example.com，不要填 /mcp。如果此时还没有固定的 ngrok 地址，可以先填本机 origin，等隧道启动后在启动服务器时用环境变量覆盖。 临时隧道在 DevSpace 尚未启动时可能先显示 502；只要它和 DevSpace 最终指向同一 端口，服务器启动后 502 就会消失：

# 终端 2：先启动隧道并记下输出的域名；此时后端尚未启动，短暂 502 是正常的
ngrok http 3003

# 终端 1：把 <YOUR_NGROK_DOMAIN> 换成上一步输出的域名
$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
$env:DEVSPACE_PUBLIC_BASE_URL = "https://<YOUR_NGROK_DOMAIN>"
devspace serve

如果 ngrok 每次生成的新域名不同，必须同步更新 DEVSPACE_PUBLIC_BASE_URL 并重启 DevSpace；否则 Host allowlist 和 OAuth resource 仍然指向旧地址。服务器启动后可用 http://127.0.0.1:3003/healthz 检查本地是否返回 HTTP 200。

远程 MCP 客户端使用的地址永远是公网 origin 加 /mcp： https://<YOUR_NGROK_DOMAIN>/mcp。同一台电脑上的本地客户端可以直接访问 http://127.0.0.1:3003/mcp，不需要公网隧道。

本地运行方式（不使用公网隧道）

如果 MCP 客户端/Agent 就运行在同一台 Windows 电脑上，可以只启动 DevSpace， 不启动 ngrok。此时客户端使用：

http://127.0.0.1:3003/mcp

使用全局安装的 devspace 命令

在 PowerShell 中运行：

$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
devspace init

首次初始化时，允许访问的根目录只选择确实需要给 Agent 使用的文件夹；公网基础 URL 可以填写：

http://127.0.0.1:3003

初始化完成后，在同一个终端启动服务：

$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
devspace serve

看到 devspace listening on http://127.0.0.1:3003/mcp 后，另开一个 PowerShell 检查服务：

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:3003/healthz
devspace doctor

健康检查返回 HTTP 200 后，把 http://127.0.0.1:3003/mcp 填入同机 MCP 客户端。 服务会在当前窗口前台运行，停止时按 Ctrl+C。本地客户端能连接时不需要 ngrok， 但 ChatGPT 网页端这类云端客户端仍然需要公网 HTTPS 隧道。

从源码目录运行

如果你想修改 DevSpace 本身，直接在源码目录运行：

Set-Location C:\path\to\devspace-local-artifacts
npm ci
npm run build

$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
npm run dev

npm run dev 会监视 src 目录，代码变化或进程崩溃后自动重启服务器。首次运行 前仍然需要先执行一次 devspace init；如果当前目录没有全局命令，可以用已构建 的 CLI 初始化：

node dist/cli.js init

更稳妥的方式是从已经完成全局安装的终端执行 devspace init，因为初始化文件默认 保存在当前 Windows 用户的 %USERPROFILE%\.devspace 下。

ChatGPT 网页端：添加自定义 MCP

ChatGPT 的菜单名称会随网页版本变化，通常位于 Settings → Apps/Connectors → Create custom app（或类似的“自定义连接器”入口）。连接流程如下：

1. 先确认 DevSpace 和 ngrok 都在运行，并且本地 /healthz 返回 200。

2. 在自定义 MCP/Connector 的连接地址中填写完整端点： https://<YOUR_NGROK_DOMAIN>/mcp。

3. 高级设置中的 OAuth Client ID/Secret 如果标为可选，可以留空，让客户端使用 DevSpace 的动态注册；不要把 Owner password 填进 Client ID 或 Secret。若客户端 明确要求固定 Client ID/Secret，应使用该客户端自己生成的值，不要伪造 DevSpace 的值。

4. 点击下一步后，浏览器会跳转到 DevSpace 的 “Connect DevSpace”/登录授权页。 这里输入的是 Owner password，不是 ngrok 令牌，也不是 ChatGPT 密码。

5. 授权成功后回到 ChatGPT，在聊天中启用这个自定义应用即可。服务器重启、隧道 域名变化或 OAuth 会话过期后，如果界面显示“已禁用”或“重新连接”，先确认两 个进程和地址无误，再点击“重新连接”刷新授权和工具列表。

连接成功后的使用方式：在聊天中 Add plugin

连接器创建并完成 Owner password 授权后，日常使用不需要再次填写 MCP 地址。建议 在 普通聊天模式 中打开一个对话，点击输入框附近的 Add plugin/添加插件 （不同版本可能显示为“添加应用”“Apps”或“工具”），选择 DevSpace，然后直接在 聊天框描述任务。

这样做的重点是：添加插件本身不会把整个本地工作区预先塞进对话，也不会因为 连接插件本身消耗 context 额度。只有真正调用工具后返回的文件内容、差异或命令 输出会进入当前对话上下文；一次要求读取超大文件、整个目录或大量图片，仍可能按 ChatGPT 当前规则占用上下文。因此，先让 DevSpace open_workspace，再按任务读取 必要文件，通常最省上下文。

可直接复制的使用案例

1. 只检查项目，不修改文件

在聊天模式中添加 DevSpace 后发送：

请使用 DevSpace 打开 C:\Projects\my-app。
先只检查根目录、README.md 和 package.json，告诉我项目用途和可运行的测试命令；
不要修改任何文件，也不要读取 .env、密钥或凭据文件。

2. 修改代码并验证

请在当前已打开的 DevSpace 工作区中修复登录页面的这个错误：<描述错误>。
先读取相关文件并说明计划，再做最小修改；修改后运行相关测试，最后列出改动文件、
测试结果和仍需我确认的事项。

3. 将当前聊天中的一张图片保存到本地

启用 DEVSPACE_ARTIFACTS=1 后，可以发送：

请使用 DevSpace 把我刚刚发送的图片保存到当前工作区
public/images/generated-001.png。
先调用 open_workspace；如果这是聊天提供的原生图片附件，使用 download_artifact；
目标文件已存在时不要覆盖，改用新的文件名。完成后只返回工作区相对路径、文件大小
和校验结果。

4. 逐张保存当前对话中可用的多张图片

请把当前对话中所有可下载的图片逐张保存到
public/images/chat-history/，按 generated-001.png、generated-002.png 的顺序命名。
每保存一张就确认一次；不要覆盖已有文件，也不要把远程 URL 当成本地文件下载。
如果某张图片不是可用的原生附件，请列出它的编号并暂停，不要猜测图片地址。

图片保存的实际调用链是 open_workspace → download_artifact → 普通 read/write/edit 工具。若客户端无法提供原生附件，才使用 write_binary 和完整 Base64 数据；DevSpace 不会接受任意粘贴的下载 URL，也不会读取聊天平台之外的图片。

使用时的几个小习惯

• 每个新聊天先确认工具栏中已经选中了 DevSpace；如果没有，点击 Add plugin/添加插件 后再发送任务，不必重新创建连接器。

• 让模型先打开一个明确的工作区，再读取必要文件；不要一上来要求“读取整个项目”。

• 保存图片时使用新的相对路径，避免覆盖已有文件；完成后让模型返回路径和大小，方便 在资源管理器中核对。

• 如果网页显示插件被禁用或“重新连接”，先恢复 DevSpace/ngrok，再点击重新连接； 不要在聊天中反复粘贴 Owner password。

操作截图

第一张实际操作图如下：ChatGPT 普通聊天模式中，dev-bin 插件已经列出 7 个工具， 其中包含 download_artifact 和 write_binary，说明图片文件写入能力已启用。

第二张实际操作图如下：在聊天模式中询问“我的工作目录有哪些”，DevSpace 调用 open_workspace 并返回已打开的本地工作区。

仍待补充：

3. 图片保存成功后返回本地相对路径的结果。

Owner password 在哪里？

devspace init 完成时会在终端显示 Owner password: ...，并显示保存路径。默认 文件是：

C:\Users\<你的用户名>\.devspace\auth.json

其中 JSON 字段名是 ownerToken。可以只在自己的电脑上查看：

Get-Content "$env:USERPROFILE\.devspace\auth.json"

不要把这个文件、终端截图、密码或令牌提交到 Git、发到聊天中或粘贴到第三方 网站。“未授权创建” 只表示创建连接器时不要求预先批准；DevSpace 运行时仍然 要求在授权页输入 Owner password。忘记密码时，先从当前 auth.json 取值；如果要 轮换密码，应先备份文件，再显式设置新的 DEVSPACE_OAUTH_OWNER_TOKEN 并保持后续启动也使用同一值，然后让所有客户端重新 连接。不要通过关闭 OAuth 来绕过认证。

Gemini 或其他自定义插件：连接方式

在 Gemini 的“设置自定义的关联应用”（或对应的自定义 MCP/插件页面）中：

点击“下一步”后按跳转页面完成 Owner password 授权，再回到 Gemini 启用该关联 应用。不要把 https://<YOUR_NGROK_DOMAIN>（不带 /mcp）直接当作 MCP 端点， 也不要把 http://127.0.0.1:3003/mcp 填到云端 Gemini；云端只能访问公网 HTTPS 地址。如果 Gemini 报“redirect_uri 不允许”或类似错误，查看错误中显示的回调域名， 把它加入允许列表后重启 DevSpace（保留默认值）：

$env:DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS = "chatgpt.com,localhost,127.0.0.1,<GEMINI_REDIRECT_HOST>"
devspace serve

<GEMINI_REDIRECT_HOST> 必须替换为 Gemini 实际使用的 hostname，不要凭猜测填写 第三方域名。

结合实际使用遇到的错误

• ngrok 502 Bad Gateway：通常表示隧道目标端口没有服务，或端口不一致。比如 DevSpace 监听 3003 时必须运行 ngrok http 3003，不能指向 3030；先检查 http://127.0.0.1:3003/healthz，再检查 ngrok 命令。

• 401、Owner password 不接受：说明 OAuth 授权没有完成，或者输入的不是当前 auth.json 中的 ownerToken。完成授权后回到客户端并重新连接。

• 网页端显示连接被禁用/出现“重新连接”：常见于服务器重启、隧道域名变化或 会话过期。确认 DEVSPACE_PUBLIC_BASE_URL 与当前 ngrok origin 一致、端点带 /mcp，然后点击重新连接；只有在进程本身停止或端口改变时才需要重启两项服务。

• 找不到 devspace 命令：说明 npm 全局 bin 目录没有在当前 PowerShell 的 PATH 中。重新打开终端，或改用项目目录中的 npm run dev/npx 命令验证安装。

Install and configure ngrok

On Windows, run the bundled installer:

.\scripts\install-ngrok.ps1

It uses the official Winget package ngrok.ngrok when ngrok is not already on PATH. Token configuration is intentionally separate and interactive:

ngrok config add-authtoken <YOUR_NGROK_TOKEN>

ngrok 需要先注册账号并在 Dashboard 获取 AuthToken；免费计划会自动分配一个 *.ngrok-free.app 开发域名。运行 ngrok http 3003 后，终端会显示本次隧道的 公网 HTTPS origin，不需要另外购买或注册域名。免费计划不能自定义域名；如需固定的 自定义域名，应使用支持该功能的付费计划。

The token, ngrok.yml, OAuth password, local paths, and tunnel URL are runtime data and must not be committed.

Start DevSpace and the tunnel

Initialize once and choose only the local roots that the MCP host may open. The initialization prompt stores the public origin without /mcp:

$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
devspace init

Start the tunnel and note its HTTPS origin. A temporary tunnel may show 502 until the local server is listening:

ngrok http 3003

Start the server in a second terminal, targeting the same port and, when the tunnel URL is not already persisted, overriding the public origin:

$env:PORT = "3003"
$env:DEVSPACE_ARTIFACTS = "1"
$env:DEVSPACE_PUBLIC_BASE_URL = "https://<YOUR_NGROK_DOMAIN>"
devspace serve

The MCP client endpoint is that origin plus /mcp. A public tunnel is not required when the MCP client runs on the same machine.

Artifact workflow

1. Call open_workspace for an approved project directory.

2. For a host-provided native file, call download_artifact with the returned workspaceId and an unused relative destination such as public/images/generated.png.

3. If the host cannot provide a native file, call write_binary with a complete Base64 string or data:image/png;base64,... URL.

Both tools refuse absolute paths, traversal, existing destinations, and unsafe parent directories. The feature is opt-in; keep DEVSPACE_ARTIFACTS unset or 0 when binary writes are not needed.

Verification

npm run typecheck
npm test
npm run build
npm pack --dry-run

See docs/dependencies.md, docs/setup.md, docs/configuration.md, docs/artifact-exchange.md, and docs/security.md for detailed setup and safety boundaries.

也可以让 Agent 教你使用

如果不想手动记这些命令，可以把项目链接直接粘贴给你使用的 Agent，并发送类似 下面的请求：

请先阅读这个 DevSpace 项目的 README，告诉我在 Windows 上如何本地安装、初始化、
启动 MCP 服务，并说明 ChatGPT 网页端、普通聊天模式 Add plugin 和本地 MCP 客户端
分别应该填什么地址。请只给出步骤和命令，不要读取、输出或保存我的 auth.json、
Owner password、ngrok 令牌、Cookie 或其他凭据。

当前这份带本地文件写入说明的版本：

https://github.com/cooky-dance/devspace-local-artifacts

上游原项目：

https://github.com/Waishnav/devspace

本仓库的 Windows 文件写入、Word/PDF 保存差异和本文档中的定制说明以本 README 为准。无论使用哪个 Agent，都不要把 %USERPROFILE%\.devspace\auth.json 的内容粘贴给它。

上游归属与许可证

本仓库是基于 Waishnav/devspace v1.0.5 的 公开定制版，不是上游官方发行版，也不代表上游作者背书。上游的 MIT 版权声明和许可 文本保留在 LICENSE 中；发布包含上游代码的副本或衍生版本时，请一并保留 该文件，并另外核对依赖项各自的许可证。

License

MIT. See LICENSE.