DROP MCP Server
by Micropue
README.md
# DROP MCP Server
把本地静态站点发布到 [DROP](https://drop.micropue.com.cn) 的 MCP 服务器。它通过 MCP 工具完成:
1. 检查 DROP API Key 和账号信息。
2. 查询已有项目。
3. 按 slug 自动创建项目,或原子替换已有项目的内容快照。
4. 返回可访问的公开地址。
服务使用 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 | 写入 |
建议发布前先调用一次 `drop_whoami`,确认 Key 具备:
- `projects:read`
- `projects:write`
- `deployments:write`
## 环境要求
- Node.js 20 或更高版本
- 一个可用的 DROP API Key
## 安装
包已发布为 `@micropue/drop-mcp` 时,不需要全局安装。在 MCP 客户端中通过 `npx` 启动:
```json
{
"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`。
## 本地开发
```bash
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 上多个允许目录用 `:` 分隔:
```bash
export DROP_ALLOWED_ROOTS="/Users/micropue/Desktop/sites:/private/tmp/builds"
```
Windows 使用 `;` 分隔。
### Codex
在 `~/.codex/config.toml` 中增加:
```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` 中增加:
```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。
## 发布站点
### 发布本地构建目录
让模型调用:
```json
{
"slug": "my-site",
"name": "My Site",
"path": "/Users/micropue/Desktop/MICROPUE服务中心/my-site/dist",
"message": "deploy from MCP"
}
```
`path` 必须位于 `DROP_ALLOWED_ROOTS` 中。建议始终使用绝对路径,因为相对路径会相对于 MCP 服务器进程的当前目录解析。
### 使用内联文件
```json
{
"slug": "hello-drop",
"files": [
{
"path": "index.html",
"content": "<!doctype html><html><body><h1>Hello DROP</h1></body></html>"
}
]
}
```
`path` 与 `files` 必须且只能提供一个。`name` 仅在首次创建项目时使用。
成功结果包含:
```json
{
"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` 原子替换文件;旧快照在失败时保持不变。
- 已有项目通过 `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 不能托管这些文件,因此需要先调整构建产物,或者显式设置:
```json
{
"ignoreUnsupported": true
}
```
`ignoreUnsupported` 只会跳过文件,不会转换资源。若页面依赖被跳过的文件,站点可能无法正常工作。
## 调试
运行 MCP Inspector:
```bash
npm run build
npm run inspector
```
手动启动服务器:
```bash
node dist/index.js
```
服务器的 stdout 是 JSON-RPC 通道,不要在业务代码中向 stdout 打印日志。错误请使用 `console.error` 写入 stderr。
## 验证
```bash
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`。
1. 提交并推送准备发布的代码到 `main`。首次手动发布不需要推送 Git 标签。
2. 登录 npm 并确认当前用户:
```bash
npm login
npm whoami
```
3. 在仓库根目录执行首次发布:
```bash
npm publish --access public
```
开启 npm 2FA 时,命令可能需要一次性验证码:
```bash
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`,提交并推送代码,然后创建并推送同名标签:
```bash
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` | 可读错误模型 |
## License
[MIT](./LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data