Drop MCP
只需要一句话,免费、快速的把静态网站部署至公共网络,并为你生成链接提供访问。
Documentation
DROP MCP Server
把本地静态站点发布到 DROP 的 MCP 服务器。它通过 MCP 工具完成:
- 检查 DROP API Key 和账号信息。
- 查询已有项目。
- 按 slug 自动创建项目,或原子替换已有项目的内容快照。
- 返回可访问的公开地址。
服务使用 MCP stdio 传输,适合 Codex、Claude Desktop、Cursor 等支持 MCP 的客户端。
工作机制
MCP 服务器本质上是一个由宿主启动的进程:
- 客户端通过 stdin 发送 JSON-RPC 消息,通过 stdout 接收响应。
- 服务器声明名称、版本和能力,并注册工具及其 JSON Schema 输入参数。
- 模型先读取
tools/list,再按工具 schema 生成tools/call参数。 - 本服务器校验参数和本地目录,调用 DROP REST API,最后把文本和结构化结果返回客户端。
stdout只用于 MCP 协议;诊断日志只能写入stderr,否则会破坏协议。
已提供的工具
| 工具 | 作用 | 是否读写 |
|---|---|---|
drop_whoami | 检查 Key 是否可用,返回账号、Key scopes 和限制 | 只读 |
drop_list_projects | 按名称/slug 搜索项目,支持分页和排序 | 只读 |
drop_get_project | 按 projectId 或 slug 获取项目及文件 | 只读 |
drop_publish_site | 创建静态站点,返回公开 URL;复用已有 slug 时兼容更新 | 写入 |
drop_update_site | 更新一个已存在的项目,返回公开 URL | 写入 |
建议发布前先调用一次 drop_whoami,确认 Key 具备:
projects:readprojects:writedeployments:write
环境要求
- Node.js 20 或更高版本
- 一个可用的 DROP API Key
安装
包已发布为 @micropue/drop-mcp 时,不需要全局安装。在 MCP 客户端中通过 npx 启动:
{
"mcpServers": {
"drop": {
"command": "npx",
"args": ["-y", "@micropue/drop-mcp"],
"env": {
"DROP_API_KEY": "your-api-key",
"DROP_ALLOWED_ROOTS": "/path/to/sites"
}
}
}
}
也可以在本地开发目录中执行 npm install 后使用 npm run build。构建入口为 dist/index.js。
本地开发
cd "/Users/micropue/Desktop/MICROPUE服务中心/drop-MCP"
npm install
npm run build
不构建时可以直接运行 npm run dev。发布 npm 包前会通过 prepack 自动重新构建 dist/。
配置
| 环境变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
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.example 为 .env 并填入 Key。服务器启动时会优先读取入口文件相邻的项目根目录 .env,然后尝试当前目录 .env。已经存在的进程环境变量优先级更高;也可以通过 DROP_ENV_FILE 指定其他文件。
macOS/Linux 上多个允许目录用 : 分隔:
export DROP_ALLOWED_ROOTS="/Users/micropue/Desktop/sites:/private/tmp/builds"
Windows 使用 ; 分隔。
Codex
在 ~/.codex/config.toml 中增加:
[mcp_servers.drop]
command = "npx"
args = ["-y", "@micropue/drop-mcp"]
env = { DROP_API_KEY = "your-api-key", DROP_ALLOWED_ROOTS = "/path/to/sites" }
startup_timeout_sec = 20
Claude Desktop
在 claude_desktop_config.json 中增加:
{
"mcpServers": {
"drop": {
"command": "npx",
"args": ["-y", "@micropue/drop-mcp"],
"env": {
"DROP_API_KEY": "your-api-key",
"DROP_ALLOWED_ROOTS": "/path/to/sites"
}
}
}
}
修改配置后重启客户端。Key 也可以放在启动目录的 .env 中;不要把该文件提交到 Git。
发布站点
发布本地构建目录
让模型调用:
{
"slug": "my-site",
"name": "My Site",
"path": "/Users/micropue/Desktop/MICROPUE服务中心/my-site/dist",
"message": "deploy from MCP"
}
path 必须位于 DROP_ALLOWED_ROOTS 中。建议始终使用绝对路径,因为相对路径会相对于 MCP 服务器进程的当前目录解析。
更新已有站点
更新站点时调用 drop_update_site,并继续使用原来的 slug。它会复用已有项目并
原子替换完整文件快照,结果中的 action 为 deployed。该工具不会创建新项目:
如果 slug 不存在,会返回 project_not_found。已有项目的名称、可见性和启用状态
不会改变。
{
"slug": "my-site",
"path": "/Users/micropue/Desktop/MICROPUE服务中心/my-site/dist",
"message": "update site"
}
因此,模型应按用户意图区分:
- 用户说“更新”“重新部署”或“修改已有站点”时,调用
drop_update_site;若不知道slug,先用drop_list_projects搜索或drop_get_project查询。 - 用户明确要求创建一个独立的新项目时,调用
drop_publish_site并使用新的slug。
drop_publish_site 为兼容旧调用仍支持复用已有 slug,但模型面对已有站点时应优先
选择语义更明确的 drop_update_site。
使用内联文件
{
"slug": "hello-drop",
"files": [
{
"path": "index.html",
"content": "<!doctype html><html><body><h1>Hello DROP</h1></body></html>"
}
]
}
path 与 files 必须且只能提供一个。name 仅在首次创建项目时使用。
成功结果包含:
{
"ok": true,
"action": "created",
"url": "https://dropcontent.micropue.com.cn/username/my-site/",
"projectId": "项目 UUID",
"slug": "my-site",
"revision": 1,
"deploymentId": "部署 ID",
"fileCount": 1,
"totalBytes": 68
}
action 为 created 表示新建,deployed 表示替换了已有项目的文件快照。
部署行为
- 如果 slug 不存在,先
POST /projects创建项目和首个部署。 - 如果 slug 已存在,用
POST /projects/{id}/deploy原子替换文件;旧快照在失败时保持不变。 drop_update_site要求项目已存在;slug 不存在时返回project_not_found,不会创建新项目。- 已有项目通过
If-Match: "rev-N"做乐观并发控制。 - 遇到
412 revision_conflict时重新读取项目并重试一次。 - 创建时遇到
409会重新按 slug 查询,以处理并发创建竞争。 - 写请求都带
Idempotency-Key。 - 不会修改已有项目的名称、可见性或启用状态;若项目被停用或设置了密码,结果中会给出警告。
DROP 限制
- 每个项目 1–20 个文件。
- 单文件最大 512 KiB。
- 项目总大小最大 1 MiB。
- 最多 50 个目录。
- 文件路径最长 120 个字符,目录路径最长 100 个字符。
- 只接受
.html、.css、.js,扩展名必须小写。 - 文件必须是有效 UTF-8 文本。
- 路径不能以
/开头或结尾,不能包含.、..或连续/。 - 目录发布默认跳过隐藏文件和
node_modules。 - 目录中出现符号链接时直接拒绝,避免读取允许根目录之外的内容。
典型前端构建目录可能包含 .svg、.json、.ico、字体或 source map。DROP v1 不能托管这些文件,因此需要先调整构建产物,或者显式设置:
{
"ignoreUnsupported": true
}
ignoreUnsupported 只会跳过文件,不会转换资源。若页面依赖被跳过的文件,站点可能无法正常工作。
调试
运行 MCP Inspector:
npm run build
npm run inspector
手动启动服务器:
node dist/index.js
服务器的 stdout 是 JSON-RPC 通道,不要在业务代码中向 stdout 打印日志。错误请使用 console.error 写入 stderr。
验证
npm run typecheck
npm test
npm run build
测试使用模拟 HTTP 响应,不会调用真实 DROP API。真实发布验证需要配置有效 Key。
npm 自动发布
.github/workflows/build-publish.yml 只会在推送 v* 标签时运行。工作流通过
GitHub Actions OIDC 使用 npm Trusted Publishing 发布,不需要 NPM_TOKEN,并会自动生成
npm provenance。
第一次手动发布
npm 必须先存在至少一个已发布版本,包设置页才会提供 Trusted Publisher 配置入口。
因此第一次发布必须在本地手动完成。首次手动发布的版本是 0.1.1。
- 提交并推送准备发布的代码到
main。首次手动发布不需要推送 Git 标签。 - 登录 npm 并确认当前用户:
npm login
npm whoami
- 在仓库根目录执行首次发布:
npm publish --access public
开启 npm 2FA 时,命令可能需要一次性验证码:
npm publish --access public --otp=123456
配置 Trusted Publisher
首次发布成功后,在 npmjs.com 打开 @micropue/drop-mcp 的包设置,找到
Trusted Publisher,选择 GitHub Actions,并严格按以下值填写:
| 字段 | 值 |
|---|---|
| Organization or user | Micropue |
| Repository | micropue-drop-MCP |
| Workflow filename | build-publish.yml |
| Environment name | 留空 |
| Allowed actions | 勾选 Allow npm publish |
这些字段区分大小写,必须与 GitHub 仓库完全一致。新建的 Trusted Publisher 配置需要在 2 天内完成一次成功发布,否则会过期。因此配置完成后应尽快发布下一个版本。
后续自动发布
不要复用或移动已经存在的标签。先把 package.json 和 package-lock.json 中的版本改成
一个从未使用过的新版本,例如 0.1.2,提交并推送代码,然后创建并推送同名标签:
npm version 0.1.2 --no-git-tag-version
git add package.json package-lock.json
git commit -m "release: v0.1.2"
git push origin main
git tag v0.1.2
git push origin v0.1.2
工作流会执行测试与构建、生成 npm tarball、上传 GitHub Actions artifact,然后通过 OIDC 发布到 npm。工作流会拒绝版本与标签不一致、或 npm 上已存在的同版本包。
常见错误
| 错误 | 处理方式 |
|---|---|
missing_api_key | 在项目 .env 或 MCP 客户端 env 中配置 DROP_API_KEY |
| HTTP 401 | Key 无效、过期或被撤销,请重新创建 |
| HTTP 403 | 给 Key 增加读项目和部署所需 scopes |
| HTTP 409 | slug 已被其他项目占用,或并发创建发生冲突 |
| HTTP 412 | 项目 revision 已变化;服务器会自动重试一次 |
| HTTP 413 | 文件数量或大小超过 DROP 限制 |
| HTTP 422 | 文件类型、路径或项目参数未通过校验 |
| HTTP 429 | 触发限流,按返回的 Retry-After 稍后重试 |
| HTTP 503 | DROP 服务暂时不可用,稍后重试 |
代码结构
| 文件 | 职责 |
|---|---|
src/index.ts | stdio 入口和进程关闭处理 |
src/server.ts | MCP 工具注册、参数校验和结果转换 |
src/drop/client.ts | DROP HTTP 客户端、认证、超时和错误映射 |
src/publish.ts | 创建/部署 upsert 与并发冲突重试 |
src/site.ts | 静态目录扫描、路径安全和 DROP 限制校验 |
src/config.ts | 环境变量解析 |
src/errors.ts | 可读错误模型 |