DROP MCP / DEVELOPER DOCS

把本地静态站点交给 AI,一句话发布到 DROP。

DROP MCP 是一个本地 stdio MCP 服务器。让 Codex、Claude Desktop、Cursor 或兼容客户端读取站点目录,检查连接,并通过 MCP 工具完成创建或原子替换。

由 MCP 客户端启动
$ npx -y @micropue/drop-mcp

stdio 不是远程 HTTP API。客户端负责启动进程,stdout 只承载协议消息。

AT A GLANCE npm latest
传输stdio · 本地进程
运行时Node.js ≥ 20.12
输出可立即访问的公开 URL
最小发布参数 slug + (path | files)
查看 npm 包
QUICK START

三步把站点交给 MCP

准备一个只含 HTML、CSS、JavaScript 的静态目录,然后让客户端完成剩余工作。

Node.js 20.12+

MCP 进程通过 npx 启动,无需全局安装。

DROP API Key

至少包含读项目、写项目和部署权限。

01

创建最小权限 Key

写入一次

在 DROP Developer Portal 创建 Personal API Key。完整 Key 只显示一次,请直接放入本地环境或客户端配置。

projects:read projects:write deployments:write
打开 API Keys
02

配置客户端并重启

stdio

把启动命令、Key 和允许发布的根目录写入客户端的 MCP 配置。配置修改后必须重启客户端。

查看 Codex / JSON 配置
03

检查连接,然后发布

read → write

先让模型调用 drop_whoami;确认成功后调用 drop_publish_site。最终只信任工具返回的 url。

你可以这样对 AI 说

先调用 drop_whoami 检查连接,再把 /absolute/path/to/site 发布为 slug hello-drop,并打开返回的 URL 确认可访问。

最小可运行发布参数

slug 必填,path 与 files 必须且只能提供一个。新建项目时才会使用 name。

drop_publish_site · path 模式
{
  "slug": "hello-drop",
  "name": "Hello DROP",
  "path": "/absolute/path/to/site",
  "message": "first deployment from DROP MCP"
}
CLIENT SETUP

客户端配置

所有客户端都运行同一个本地命令。推荐设置 DROP_ALLOWED_ROOTS,把可发布范围限制到专用站点目录。

Codex

config.toml

~/.codex/config.toml
TOML
[mcp_servers.drop]
command = "npx"
args = ["-y", "@micropue/drop-mcp"]
env = { DROP_API_KEY = "YOUR_DROP_API_KEY", DROP_ALLOWED_ROOTS = "/absolute/path/to/sites" }
startup_timeout_sec = 20

把示例 Key 换成你自己的 Key。目录必须是绝对路径。

Claude Desktop · Cursor

MCP JSON

client-specific
JSON
{
  "mcpServers": {
    "drop": {
      "command": "npx",
      "args": ["-y", "@micropue/drop-mcp"],
      "env": {
        "DROP_API_KEY": "YOUR_DROP_API_KEY",
        "DROP_ALLOWED_ROOTS": "/absolute/path/to/sites"
      }
    }
  }
}

Claude Desktop 使用 claude_desktop_config.json;Cursor 使用 ~/.cursor/mcp.json 或项目级 .cursor/mcp.json。

Windows

DROP_ALLOWED_ROOTS 的多个目录使用 ; 分隔;macOS / Linux 使用 :。

重启

保存配置后重启整个 MCP 客户端。只重开对话通常不会重新加载 MCP 配置。

通用客户端

只要支持 stdio MCP,并使用上面的 command、args 与 env 结构即可接入。

TOOL REFERENCE

四个工具,一条发布链路

查询工具只读取 DROP;只有 drop_publish_site 会创建项目或替换文件快照。

01

drop_whoami

验证 Key、连接状态、账号、scopes 和限制。

只读 · 无参数

最轻量的连通性检查。应在首次配置、Key 轮换或发布失败后优先调用。

返回账号 Key scopes 项目限制
调用意图 调用 drop_whoami,确认 DROP 连接和 scopes。
02

drop_list_projects

搜索和分页列出当前账号的项目。

只读
参数类型约束
querystring可选,按项目名称或 slug 搜索
pageinteger可选,页码从 1 开始
perPageinteger可选,每页 1–100 条
sortenumupdated_desc · created_desc · name_asc
示例 { "query": "mcp", "sort": "updated_desc" }
03

drop_get_project

获取一个项目详情及其完整文件快照。

只读
按 ID projectId

项目 UUID。

按 slug slug

当前账号下的项目 slug。

二选一

projectId 与 slug 必须且只能提供一个。

示例 { "slug": "my-site" }
04

drop_publish_site

创建项目,或原子替换已有项目的文件快照。

写入 · 部署

这是唯一写入工具。已存在的 slug 会被完整快照替换,而不是增量合并;失败时旧快照保持不变。

参数必填类型与约束
slug是string;1–40 位小写字母、数字或连字符,不能以连字符开头或结尾
name否string;1–80 字符,仅在首次创建项目时使用
path二选一绝对目录路径,必须位于 DROP_ALLOWED_ROOTS 内
files数组,1–20 项;每项为 { path, content }
ignoreUnsupported否boolean;仅跳过不受支持的文件,不会转换资源
message否string;最多 200 字符,用于本次发布说明
发布目录path
path · 推荐
{
  "slug": "my-site",
  "name": "My Site",
  "path": "/absolute/path/to/sites/my-site",
  "message": "deploy from MCP"
}
提交内联文件files
files · 少量文件
{
  "slug": "hello-drop",
  "files": [
    {
      "path": "index.html",
      "content": "<!doctype html><h1>Hello DROP</h1>"
    }
  ]
}
ENVIRONMENT

配置与环境变量

五个环境变量足够控制认证、API 地址、请求超时、发布边界和 env 文件位置。

变量必填默认值说明
DROP_API_KEY 是 无 DROP Personal API Key
DROP_API_BASE 否 https://drop.micropue.com.cn/v1 DROP API Base URL
DROP_REQUEST_TIMEOUT_MS 否 20000 请求超时,范围 1000–120000 毫秒
DROP_ALLOWED_ROOTS 否 MCP 进程当前目录 允许发布的本地根目录;多个目录使用系统路径分隔符
DROP_ENV_FILE 否 项目根目录 .env 指定其他 env 文件;相对路径按 MCP 进程当前目录解析

已有进程环境优先,文件配置作为补充

  1. 客户端配置中的 env 或系统环境变量优先。
  2. 启动时先读取入口文件相邻的项目根目录 .env。
  3. 然后尝试当前工作目录的 .env。
  4. 设置 DROP_ENV_FILE 时读取指定文件;已存在的变量不会被覆盖。
.env · 本地文件补充
DROP_API_KEY=YOUR_DROP_API_KEY
DROP_ALLOWED_ROOTS=/absolute/path/to/sites
DROP_REQUEST_TIMEOUT_MS=20000
限制发布根目录

DROP_ALLOWED_ROOTS 是文件系统边界。不要指向主目录、仓库根目录或整个磁盘。

Key 与 .env 不入库

不要提交 .env,也不要把真实 Key 写进 README、截图、日志或客户端分享配置。

PUBLISH & VERIFY

发布流程与结果

推荐先确认身份,再决定创建或替换;工具返回成功后仍应实际打开公开地址。

01
drop_whoami

检查 Key、连接和 scopes。

02
list / get

确认 slug 是否已存在及是否为预期项目。

03
publish_site

创建或原子替换完整文件快照。

04
GET url

验证实际公开地址与警告。

成功结果
{
  "ok": true,
  "action": "created",
  "url": "https://dropcontent.micropue.com.cn/username/my-site/",
  "projectId": "项目 UUID",
  "slug": "my-site",
  "revision": 1,
  "deploymentId": "部署 ID",
  "fileCount": 3,
  "totalBytes": 42000,
  "publiclyAccessible": true,
  "warnings": []
}
ok

必须为 true。同时确认 publiclyAccessible 为 true,并读取 warnings。

created

新项目及首个部署已创建。deployed 表示已有项目的快照被替换。

url

这是本次实际公开地址。不要自行拼接,也不要把文档中的示例域名当成固定模板。

warnings

成功时应为空数组。若非空,必须逐条检查并把实际警告告知用户,不要报告“完全无问题”。

失败不会破坏旧内容

已有项目按 revision 使用乐观并发控制。遇到 412 revision_conflict 时,MCP 会重新读取项目并自动重试一次。

created vs deployed

created 表示首次创建项目;deployed 表示在既有项目上替换文件。两者成功后内容都已生效。

失败结果通常来自 DROP Problem 响应

检查 code、status、detail 和 requestId;参数校验错误还可能包含 errors[].path 与 errors[].message。

LIMITS & SAFETY

限制与安全

DROP v1 托管纯文本静态文件。先让构建产物符合限制,比事后跳过文件更可靠。

20 文件 / 项目

至少 1 个文件。

512 KiB 单文件上限

按 UTF-8 文本字节计算。

1 MiB 项目总大小

所有文件合计。

50 目录 / 项目

显式目录数量上限。

文件规则

扩展名必须小写。

  • 允许.html.css.js
  • 编码必须是有效 UTF-8 文本
  • 路径最长 120 字符,不能以 / 开头或结尾
  • 目录路径最长 100 字符;最多 50 个
  • 禁止路径中的 .、.. 或连续 /

目录扫描

默认忽略非代码文件。

  • 跳过隐藏文件与 node_modules
  • 拒绝目录中出现任何符号链接
  • 拒绝不受支持扩展名,除非明确设置 ignoreUnsupported
  • 边界path 必须位于允许根目录之内
  • 注意跳过资源后,页面依赖可能失效

把 Key 和文件系统权限都收窄

只需要发布的自动化 Key 不应包含 projects:delete。MCP 进程只应读取专用站点目录,避免模型误读其他本地文件。

stdio 不开放公网监听端口 stdout 禁止混入诊断日志 Key 可撤销并按需设置过期时间 写入具备状态检查与自动重试
TROUBLESHOOTING

常见错误

先看 MCP 返回的 code、HTTP 状态与 requestId,再根据下面的路径排查。

错误含义处理方式
missing_api_key 进程没有读到 DROP_API_KEY 在客户端 env 或 MCP 启动目录可读取的 .env 中配置 Key,然后重启客户端。
401 Key 无效、过期或已撤销 调用 drop_whoami 复核;必要时在 DROP 创建新 Key 并更新本地配置。
403 Key 有效,但 scopes 不足 确保包含 projects:read、projects:write 和 deployments:write。
409 slug 冲突或并发创建冲突 先用 drop_list_projects / drop_get_project 确认目标;需要替换时使用已存在的实际项目。
412 项目 revision 已变化 重新读取项目后再发布。MCP 内部会自动重试一次;仍失败时不要循环强推。
413 文件数量、单文件或总大小超限 减少文件或压缩构建产物;确保单文件 ≤ 512 KiB、项目总计 ≤ 1 MiB。
422 文件类型、路径或项目参数校验失败 检查小写扩展名、UTF-8、路径分隔符、slug 格式,以及 path / files 是否只提供一个。
429 触发限流 读取响应的 Retry-After,等待后重试;不要并发轰炸发布请求。
503 DROP 依赖暂时不可用 稍后重试并保留 requestId;持续失败时交给平台侧排查。
A

客户端看不到工具

确认 Node.js 版本、配置文件语法与 JSON 路径;完整重启客户端,再让模型列出 MCP 工具。

B

路径被拒绝

把 DROP_ALLOWED_ROOTS 和 path 都改成绝对路径,并确认目标目录位于允许根目录内。

C

站点不完整

检查构建产物是否含 SVG、JSON、字体、图片或 source map。DROP v1 不会托管这些文件。