Kompressr

@kompressr/mcp-server

面向 MCP Agent 的 Kompressr 工具：上传文件、等待处理、生成私有链接、分页查看上传内容，以及永久删除明确指定的资源 ID。文件操作使用单独的 @kompressr/sdk 包。应用可以直接使用该 SDK，无需启动 MCP。

需要 Node.js 22 或更高版本。对于支持 MCPB 扩展的桌面客户端，从 GitHub Releases 下载 Kompressr MCP bundle，并参阅桌面安装指南。

设置

创建 Kompressr 账户，并开始 30 天图像上传试用或选择付费计划。在 Dashboard → Projects 中打开项目，然后选择 API Keys。项目密钥和主密钥仅用于受信任的计算机；单个应用或 Agent 运行时请使用限定范围的密钥。项目 UUID 仅在列出上传内容时需要。

配置 MCP 客户端以运行此软件包：

{
  "mcpServers": {
    "kompressr": {
      "command": "npx",
      "args": ["-y", "@kompressr/[email protected]"],
      "env": {
        "KOMPRESSR_API_KEY": "YOUR_PROJECT_OR_SCOPED_KEY",
        "KOMPRESSR_PROJECT_ID": "YOUR_PROJECT_UUID"
      }
    }
  }
}

列出上传内容需要 KOMPRESSR_PROJECT_ID；上传、查询状态、签名和删除只需要密钥。若要从源码构建，请按照 CONTRIBUTING.md 操作，然后配置 node，并提供此软件包中已构建的 dist/index.js 的绝对路径。

配置和迁移

设置	含义
KOMPRESSR_API_KEY	不透明的项目密钥、主密钥或限定范围的密钥；API 权限仍具有最终效力
KOMPRESSR_PROJECT_ID	项目 UUID，list_assets 必需
KOMPRESSR_API_URL	管理端源，默认值为 https://kompressr.com
KOMPRESSR_UPLOAD_BASE_URL	上传内容源覆盖值
KOMPRESSR_REMOTE_ALLOWED_HOSTS	以逗号分隔的主机名，明确允许其提供私有/本地远程来源地址

生产环境的管理端默认使用 https://kompressr.com，上传内容默认使用 https://uploads.kompressr.com。对于其他部署，请从私有运行时配置提供 KOMPRESSR_API_URL 和 KOMPRESSR_UPLOAD_BASE_URL。若未覆盖，自定义管理端源会使用相同的上传源。源必须使用 HTTP(S)，且不能包含凭据、路径、查询参数或片段。

保存的配置仍位于 ~/.kompressr/config.json：

{
  "api_key": "YOUR_KEY",
  "project_id": "YOUR_PROJECT_UUID",
  "api_url": "https://kompressr.com",
  "upload_url": "https://uploads.kompressr.com"
}

环境设置会覆盖保存的值。不同的环境密钥不会继承保存的项目或端点，以避免混用账户；使用自定义源时，请明确提供这些值。更改管理端源后，除非提供上传覆盖值，否则会重新推导上传源。旧的已保存值 https://api.kompressr.com 会在内存中迁移为生产环境地址。新配置会以原子替换方式保存，目录权限为 0700，文件权限为 0600；仅加载配置不会重写现有文件。请勿将密钥和配置提交到源代码管理中。

文件工作流

1. 调用 upload_asset，并且必须恰好提供 file_path 或 file_url 其中之一。保存返回的数字 asset_id。
2. 调用 wait_for_asset 或 get_asset_status。已接收上传请求且存在待处理 URL，并不表示文件已就绪；对于活跃资源，请仅使用当前已处理的响应。
3. 分享已处理的公开 URL，或在应用中授权私有接收方，然后调用 generate_private_url 生成新的限时链接。
4. 等待超时后，使用已保存的 ID 继续操作。不要为了应对轮询超时而重新上传。

30 天免费试用总共包含 100 次图像上传，API、SDK、MCP 和控制面板共用此额度。该额度不会按月续期。支持的格式、大小、视频质量和私有内容交付方式取决于计划/项目。SDK 会按流式 API 的要求，先发送所有 multipart 选项，再发送文件。

工具

历史状态／列表记录中缺失或空白的文件名仍然有效；列表会显示“未命名文件”，但不会更改响应元数据。

所有文件工具都会返回可读文本、JSON 文本块和 structuredContent；失败时会设置 isError。数值 ID 必须是正的安全整数（单 ID 工具也接受数字字符串）。

工具	参数和行为
upload_asset	必须且只能提供一个 file_path／file_url；可选的 quality（480p、720p、1080p、4k）、visibility（public／private）、private_url_expires_in（60–604800 秒）、data（最多五个标量字段；键最长 64 字节／字符串值最长 512 个 UTF-8 字节，编码后的 multipart JSON 最长 4096 字节）。返回接收状态和 ready。
get_asset_status	asset_id；处理、可见性、删除状态、字节大小、节省量和就绪状态。
wait_for_asset	asset_id，可选的 timeout_ms（1–120000，默认 120000）；有界轮询。超时／错误时仍会保留 ID。取消 MCP 请求会停止等待，但不会停止服务端任务。私有资源就绪后仍需重新调用签名接口。
list_assets	可选的 page（默认 1）、limit（1–100，默认 20）、visibility、external_id、status（pending、processing、processed、failed、unprocessable）、deletion_status（active、deleting、deleted、legacy_deleted）、字符串 data 筛选条件。列出配置项目中的上传内容，并返回 next_page。
generate_private_url	asset_id，可选的 expires_in（60–604800 秒，默认 3600）、variant（webp／avif，默认 webp）。应用必须先授权访问。过期不会删除资源。
get_asset_deletion_status	asset_id；处理／删除状态和记录的存储抵扣额。移除完成并不能证明所有缓存都已清除。
delete_asset	asset_id；永久删除，不可撤销或取消。接受请求后会开始后台清理。需要删除权限。
bulk_delete_assets	asset_ids（1–100 个明确指定的数值 ID）；返回各项结果和计数。HTTP 请求成功时仍可能包含失败项。无法选择删除全部资源。
register	email、password（至少 8 个字符）；创建账户并发送验证邮件。已配置运行时中会拒绝执行。
verify_email	token；验证邮箱，并在有凭据时保存凭据。已配置运行时中会拒绝执行；工具输出绝不会返回原始密钥。试用版或付费套餐的限制仍然适用。

处理状态和删除状态彼此独立。永久删除会在之后移除文件；缓存、已下载和离线副本可能仍会保留。重试同一个旧 ID 无法删除具有新 ID 的替代资源。批量删除会保留部分失败结果，不会自动扩大选择范围或重试。storage_credited_mb 是以 MB 计的已记录存储抵扣额，不是现金退款。其他大小字段的单位均为字节。

读取工具带有只读注解；删除工具带有破坏性操作注解。注解用于说明行为；访问权限由服务端授权和 MCP 客户端的审批控制机制执行。

密钥、错误和远程文件

为单个客户/Agent 运行时使用范围受限的密钥。服务会强制执行身份、允许的文件类型/可见性和操作范围。默认范围不包括 delete；配置密钥时必须选择启用该权限。范围受限的密钥无法调用平台管理或 URL Prepend/源站优化功能。请通过可信后端，使用 SDK 的 client.platform 分组或现有平台 API 配置身份和密钥。MCP 不会添加主密钥管理工具。

安全的 GET 请求遇到网络错误/429/502/503/504 时，最多重试两次，且必须在 30 秒请求时限内完成，并遵循 Retry-After。上传的默认时限为 10 分钟；写入操作绝不会自动重放。结构化错误会保留 code、kind、HTTP 状态，以及在相关情况下的 assetId/mayHaveSucceeded。已发送但中断或返回格式错误的 JSON/数据的写入操作可能已成功；再次执行前请先检查结果。不会暴露任意错误和原始网关响应正文。

file_url 会先在 MCP 机器上下载，再上传本地临时文件。MCP 取消/断开连接（包括 stdin EOF）会中止传输，并会在开始上传前再次检查。发送上传请求前不会创建资源；请求发送后，服务器已接受的上传无法通过客户端取消回滚。数据会流式写入磁盘，传输上限为 2 GiB，下载时限为 5 分钟，最多允许 5 次重定向。HTTPS 不得降级为 HTTP。数值 CIDR 检查允许普通的全球单播 IPv6 地址，并保守排除 IETF 协议、过渡技术和文档用途地址范围，包括其压缩形式。每个目标都会解析为经过验证的允许地址，并使用这些地址建立连接；私有/本地目标必须在 KOMPRESSR_REMOTE_ALLOWED_HOSTS 中精确列出主机名。重定向目标会再次检查。源站不会使用 Kompressr 凭据。临时文件会受到限制，并在成功/失败后清理。传输上限不覆盖你的套餐限制或磁盘容量；远程下载和上传各有独立时限。服务器端 URL 导入不属于此 SDK/MCP 集成的一部分。

请参阅 CHANGELOG.md 和贡献指南。本地 HTTP/协议检查无法证明已部署环境中的身份验证、处理或 CDN 行为正常。源代码验证命令使用本地测试夹具，不会发布软件包。