Skip to main content
Glama
DROP MCP Server

DROP MCP Server

by Micropue

DROP MCP Server

把本地静态站点发布到 DROP 的 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,否则会破坏协议。

Related MCP server: publish-artifacts-mcp

已提供的工具

工具

作用

是否读写

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 启动:

{
  "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 服务器进程的当前目录解析。

使用内联文件

{
  "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 原子替换文件;旧快照在失败时保持不变。

  • 已有项目通过 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。

  1. 提交并推送准备发布的代码到 main。首次手动发布不需要推送 Git 标签。

  2. 登录 npm 并确认当前用户:

npm login
npm whoami
  1. 在仓库根目录执行首次发布:

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

可读错误模型

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers