创建最小权限 Key
写入一次在 DROP Developer Portal 创建 Personal API Key。完整 Key 只显示一次,请直接放入本地环境或客户端配置。
projects:read
projects:write
deployments:write
DROP MCP 是一个本地 stdio MCP 服务器。让 Codex、Claude Desktop、Cursor
或兼容客户端读取站点目录,检查连接,并通过 MCP 工具完成创建或原子替换。
$ npx -y @micropue/drop-mcp
stdio 不是远程 HTTP API。客户端负责启动进程,stdout 只承载协议消息。
slug + (path | files)
准备一个只含 HTML、CSS、JavaScript 的静态目录,然后让客户端完成剩余工作。
MCP 进程通过 npx 启动,无需全局安装。
至少包含读项目、写项目和部署权限。
在 DROP Developer Portal 创建 Personal API Key。完整 Key 只显示一次,请直接放入本地环境或客户端配置。
projects:read
projects:write
deployments:write
先让模型调用 drop_whoami;确认成功后调用 drop_publish_site。最终只信任工具返回的 url。
先调用 drop_whoami 检查连接,再把 /absolute/path/to/site 发布为 slug hello-drop,并打开返回的 URL 确认可访问。
slug 必填,path 与 files 必须且只能提供一个。新建项目时才会使用 name。
{
"slug": "hello-drop",
"name": "Hello DROP",
"path": "/absolute/path/to/site",
"message": "first deployment from DROP MCP"
}
所有客户端都运行同一个本地命令。推荐设置 DROP_ALLOWED_ROOTS,把可发布范围限制到专用站点目录。
[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。目录必须是绝对路径。
{
"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。
DROP_ALLOWED_ROOTS 的多个目录使用 ; 分隔;macOS / Linux 使用 :。
保存配置后重启整个 MCP 客户端。只重开对话通常不会重新加载 MCP 配置。
只要支持 stdio MCP,并使用上面的 command、args 与 env 结构即可接入。
查询工具只读取 DROP;只有 drop_publish_site 会创建项目或替换文件快照。
drop_whoami验证 Key、连接状态、账号、scopes 和限制。
最轻量的连通性检查。应在首次配置、Key 轮换或发布失败后优先调用。
调用 drop_whoami,确认 DROP 连接和 scopes。
drop_list_projects搜索和分页列出当前账号的项目。
| 参数 | 类型 | 约束 |
|---|---|---|
query | string | 可选,按项目名称或 slug 搜索 |
page | integer | 可选,页码从 1 开始 |
perPage | integer | 可选,每页 1–100 条 |
sort | enum | updated_desc · created_desc · name_asc |
{ "query": "mcp", "sort": "updated_desc" }
drop_get_project获取一个项目详情及其完整文件快照。
projectId
项目 UUID。
slug
当前账号下的项目 slug。
projectId 与 slug 必须且只能提供一个。
{ "slug": "my-site" }
drop_publish_site创建项目,或原子替换已有项目的文件快照。
| 参数 | 必填 | 类型与约束 |
|---|---|---|
slug | 是 | string;1–40 位小写字母、数字或连字符,不能以连字符开头或结尾 |
name | 否 | string;1–80 字符,仅在首次创建项目时使用 |
path | 二选一 | 绝对目录路径,必须位于 DROP_ALLOWED_ROOTS 内 |
files | 数组,1–20 项;每项为 { path, content } | |
ignoreUnsupported | 否 | boolean;仅跳过不受支持的文件,不会转换资源 |
message | 否 | string;最多 200 字符,用于本次发布说明 |
path{
"slug": "my-site",
"name": "My Site",
"path": "/absolute/path/to/sites/my-site",
"message": "deploy from MCP"
}
files{
"slug": "hello-drop",
"files": [
{
"path": "index.html",
"content": "<!doctype html><h1>Hello DROP</h1>"
}
]
}
五个环境变量足够控制认证、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 进程当前目录解析 |
env 或系统环境变量优先。.env。.env。DROP_ENV_FILE 时读取指定文件;已存在的变量不会被覆盖。DROP_API_KEY=YOUR_DROP_API_KEY
DROP_ALLOWED_ROOTS=/absolute/path/to/sites
DROP_REQUEST_TIMEOUT_MS=20000
DROP_ALLOWED_ROOTS 是文件系统边界。不要指向主目录、仓库根目录或整个磁盘。
不要提交 .env,也不要把真实 Key 写进 README、截图、日志或客户端分享配置。
推荐先确认身份,再决定创建或替换;工具返回成功后仍应实际打开公开地址。
drop_whoami检查 Key、连接和 scopes。
list / get确认 slug 是否已存在及是否为预期项目。
publish_site创建或原子替换完整文件快照。
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": []
}
必须为 true。同时确认 publiclyAccessible 为 true,并读取 warnings。
新项目及首个部署已创建。deployed 表示已有项目的快照被替换。
这是本次实际公开地址。不要自行拼接,也不要把文档中的示例域名当成固定模板。
成功时应为空数组。若非空,必须逐条检查并把实际警告告知用户,不要报告“完全无问题”。
已有项目按 revision 使用乐观并发控制。遇到 412 revision_conflict 时,MCP 会重新读取项目并自动重试一次。
created vs deployedcreated 表示首次创建项目;deployed 表示在既有项目上替换文件。两者成功后内容都已生效。
检查 code、status、detail 和 requestId;参数校验错误还可能包含 errors[].path 与 errors[].message。
DROP v1 托管纯文本静态文件。先让构建产物符合限制,比事后跳过文件更可靠。
至少 1 个文件。
按 UTF-8 文本字节计算。
所有文件合计。
显式目录数量上限。
扩展名必须小写。
.html.css.js/ 开头或结尾.、.. 或连续 /默认忽略非代码文件。
node_modulesignoreUnsupportedpath 必须位于允许根目录之内先看 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;持续失败时交给平台侧排查。 |
确认 Node.js 版本、配置文件语法与 JSON 路径;完整重启客户端,再让模型列出 MCP 工具。
把 DROP_ALLOWED_ROOTS 和 path 都改成绝对路径,并确认目标目录位于允许根目录内。
检查构建产物是否含 SVG、JSON、字体、图片或 source map。DROP v1 不会托管这些文件。