Zipline Mcp

Zipline MCP 服务

这是一个专为与 Zipline 交互而设计的 MCP（Model Context Protocol）服务，可让你将文件上传到兼容 Zipline 的主机。此服务提供上传文件、验证文件和生成上传命令的工具。

功能

• 将文件上传到 Zipline 实例
• 上传前验证文件
• 预览上传命令
• 上传后仅获取下载 URL
• 列出并搜索存储在 Zipline 服务上的用户文件
• 列出并管理 Zipline 服务上的远程文件夹
• 支持多种文件类型，包括：
  • 文本/代码：txt、md、gpx、html、json、xml、csv、js、css、py、sh、yaml、yml
  • 图像：png、jpg、jpeg、gif、webp、svg、bmp、tiff、ico、heic、avif

安装

全局安装

若要全局安装服务，以便通过 npx 使用：

npm install -g zipline-mcp

本地安装

若要将服务安装为项目依赖项：

npm install zipline-mcp

用法

使用 npx

如果已全局安装服务，可以直接运行：

npx zipline-mcp

添加到 MCP 客户端配置

若要将此服务与 MCP 客户端（如 Claude Desktop）搭配使用，需要将其添加到客户端的配置文件中。

MCP-Zipline 集成指南

快速入门配置

将以下最简配置添加到 MCP 客户端（例如 Claude Desktop）：

# YAML format
mcpServers:
  zipline:
    command: npx
    args: ['-y', 'zipline-mcp']
    environment:
      ZIPLINE_TOKEN: 'your-api-token-here'
      ZIPLINE_ENDPOINT: 'http://localhost:3000'

// JSON format
{
  "mcpServers": {
    "zipline": {
      "command": "npx",
      "args": ["-y", "zipline-mcp"],
      "environment": {
        "ZIPLINE_TOKEN": "your-api-token-here",
        "ZIPLINE_ENDPOINT": "http://localhost:3000"
      }
    }
  }
}

详细配置选项

必需设置

• command：要运行的可执行文件（通常为 "npx"）
• args：包含 ["zipline-mcp"] 的数组
• environment.ZIPLINE_TOKEN：你的 Zipline API 令牌
• environment.ZIPLINE_ENDPOINT：Zipline 服务的 URL（默认为 "http://localhost:3000"）

可选设置

• environment.ZIPLINE_FORMAT：文件命名格式。支持的值："random"、"uuid"、"date"、"name"、"gfycat"（"random-words" 的别名）、"random-words"。默认为 "random"。
• environment.ZIPLINE_ENDPOINT：自定义 Zipline 服务 URL
• environment.ZIPLINE_DISABLE_SANDBOXING：为 tmp_file_manager 工具禁用按用户隔离。设为 "true" 即可禁用隔离，并为所有用户使用共享的 ~/.zipline_tmp 目录。默认为 "false"（已启用隔离）。
• environment.ALLOWED_EXTENSIONS：覆盖允许上传和验证的文件扩展名列表。 提供以逗号分隔的列表（例如 .txt,.md,.pdf,.docx）。设置后，此列表将取代默认的允许扩展名列表。适用于限制或扩展部署中支持的文件类型。
• environment.ZIPLINE_ALLOWED_ROOTS：upload_file_to_zipline 和 validate_file 可读取的目录。 以逗号分隔的绝对路径（例如 /home/me/uploads,/var/zipline/inbox）。每个路径及文件都会通过 realpath 解析。仅当符号链接的目标仍位于这些目录中时，才会接受该符号链接。不存在的条目会被忽略并写入服务日志，且不会增加任何可读取路径。未设置时，唯一允许的目录是运行服务的用户的主目录。

安全最佳实践

1. 将 API 令牌存储在环境变量中，而不是配置文件中
2. 与 Zipline 服务的所有连接都使用 HTTPS
3. 将 ZIPLINE_ALLOWED_ROOTS 设置为 Agent 应该从中上传文件的目录。服务会拒绝所有其他路径，包括指向这些目录之外的符号链接。
4. download_external_url 会在每次请求和每次重定向时解析 DNS。如果任何地址属于回环、私有、链路本地或云元数据地址，就会拒绝下载。连接使用该次查询返回的地址，因此后续查询无法将其重定向到其他地址。

常见问题排查

身份验证失败

• 症状："Invalid authorization token" 错误
• 解决方案：
  • 验证令牌是否有效
  • 检查 ZIPLINE_TOKEN 的值是否有拼写错误
  • 确保通过环境变量传递令牌

架构概览

Zipline MCP Server 充当 MCP 客户端与 Zipline 文件托管服务之间的桥梁。以下是各组件的交互方式：

graph LR
    A[MCP Client] --> B[MCP Server]
    B --> C[Zipline API]
    C --> D[(Zipline Storage)]

关键组件

1. MCP 客户端：发起文件上传请求（例如 Claude Desktop）
2. MCP 服务：
   • 在本地验证文件
   • 生成上传命令
   • 处理与 Zipline 的身份验证
3. Zipline API：处理上传请求并返回 URL
4. Zipline 存储：持久化文件存储系统

典型工作流

1. 客户端将文件路径发送到 MCP 服务
2. 服务验证文件类型和大小
3. 服务构建经过身份验证的 API 请求
4. Zipline 处理上传并返回 URL
5. 服务为 MCP 客户端整理响应

格式选项

format 参数用于控制上传文件在 Zipline 服务上的命名方式。以下是支持的格式：

random

生成由字符组成的随机文件名，长度由服务配置指定。这是默认格式。

uuid

生成基于 UUID 的文件名（例如，550e8400-e29b-41d4-a716-446655440000）。

date

使用当前日期/时间，并按服务的默认日期格式进行格式化。日期格式完全由 Zipline 服务处理。

name

使用不带扩展名的原始文件名（例如，document.txt 会变为 document）。

gfycat

random-words 的别名。生成易读的“随机单词”风格文件名。

random-words

使用随机单词生成易读的文件名（例如，happy-purple-elephant）。

格式规范化与验证

• 不区分大小写：所有格式值均不区分大小写（例如，UUID、uuid 和 Uuid 等效）。
• 别名处理：gfycat 会自动映射为 random-words。
• 错误处理：无效的格式值会导致“Invalid format”错误。
• 默认行为：如果省略 format 参数，服务会使用其配置的默认格式（通常为 random）。

示例

# Use UUID format
upload_file_to_zipline(filePath: "document.txt", format: "uuid")

# Use human-readable format (via alias)
upload_file_to_zipline(filePath: "document.txt", format: "gfycat")

# Case-insensitive usage
upload_file_to_zipline(filePath: "document.txt", format: "RANDOM-WORDS")

增强型上传选项

Zipline MCP Server 现在支持额外的可选标头，以便更灵活地控制文件上传。这些标头会以 x-zipline-* 标头的形式发送到 Zipline 服务。

x-zipline-deletes-at

控制上传的文件何时自动删除。

格式：

• 相对时长：如“1d”（1 天）、“2h”（2 小时）、“30m”（30 分钟）
• 绝对日期：带有“date=”前缀的 ISO-8601 格式，例如“date=2025-12-31T23:59:59Z”

示例：

// Delete after 24 hours
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: '1d',
});

// Delete at specific date
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: 'date=2025-12-31T23:59:59Z',
});

验证：

• 相对时长必须为正数，并使用有效单位（d、h、m）
• 绝对日期必须采用 ISO-8601 格式，且指定未来日期
• 无效格式会被拒绝，并返回详细的错误消息

x-zipline-password

使用密码保护上传的文件。提供此标头后，用户需要输入密码才能访问文件。

格式：

• 非空字符串值

示例：

uploadFile({
  filePath: 'secret.txt',
  format: 'random',
  password: 'my-secret-password',
});

验证：

• 密码必须是非空字符串
• 仅包含空白字符的密码会被拒绝
• 安全性：绝不会记录密码，也不会在错误消息中泄露密码

x-zipline-max-views

限制文件变为不可用前可被查看的次数。每次成功查看都会使计数器减 1。

格式：

• 非负整数（0 或更大）

示例：

// Allow 10 views
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  maxViews: 10,
});

// Allow single view (disposable link)
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  maxViews: 1,
});

验证：

• 必须是整数 ≥ 0
• 负数和非整数值会被拒绝
• 计数器达到 0 时，文件将可以被移除

x-zipline-folder

指定上传文件应放入的文件夹 ID。该文件夹必须存在于 Zipline 服务上。

格式：

• 字母数字字符串（仅包含字母和数字）

示例：

uploadFile({
  filePath: 'document.txt',
  format: 'random',
  folder: 'myfolder123',
});

验证：

• 必须是非空的字母数字字符串
• 特殊字符和空白字符会被拒绝
• 如果指定的文件夹不存在，上传将失败

组合多个标头

你可以组合多个标头，以实现更精细的控制：

uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: '7d', // Delete after 7 days
  password: 'secret123', // Password protect
  maxViews: 5, // Allow 5 views
  folder: 'shared', // Place in "shared" folder
});

错误处理

所有标头都会在发送上传请求到服务端之前进行本地验证。如果任何标头无效：

• 上传会立即中止
• 返回描述性错误消息
• 不会向 Zipline 服务发送 HTTP 请求
• 错误消息会准确说明需要修正的内容

向后兼容性

所有增强标头都是可选的。不使用这些标头的现有代码将继续按原样运行。只有在你明确提供这些参数时，新功能才会启用。

可用工具

此服务提供以下工具：

upload_file_to_zipline

将文件上传到 Zipline 服务，并返回详细的成功消息。

• filePath：要上传的文件路径。该路径必须解析到 ZIPLINE_ALLOWED_ROOTS 范围内（未设置该变量时为主目录）。服务端会在解析符号链接后读取真实路径。支持的扩展名：txt、md、gpx、html、json、xml、csv、js、css、py、sh、yaml、yml、png、jpg、jpeg、gif、webp、svg、bmp、tiff、ico、heic、avif。只有文件内容能够表明其类型时，才接受二进制类型。如果文件字节内容是复合文件二进制容器，则接受旧版 Word、Excel 和 PowerPoint 文件。如果文件字节内容是 AVI 容器（video/vnd.avi），则接受 AVI。如果文件字节内容是 Matroska（video/matroska），则接受 Matroska；如果是 WebM，则接受 WebM。如果 Matroska 或 WebM 文件以 EBML 标头开头，但文档类型位于前 4100 个字节之后，服务端会继续读取该文件，直到识别出类型。仅凭扩展名不足以判定文件类型。只有文件字节内容不含 NUL 时，才接受文本类型。NUL 字节不会跳过机密内容扫描。
• originalName：（可选）要在下载时保留的原始文件名。此参数会作为 x-zipline-original-name 标头发送到 Zipline 服务。下载文件时会使用原始文件名，而非存储文件时使用的文件名。必须是非空字符串，且不能包含路径分隔符。

面向用户的提示词示例：

• “将文件 '/path/to/document.pdf' 上传到 Zipline”
• “上传我位于 '/home/user/images/photo.jpg' 的文件，并保留原始名称”
• “我想上传 '/path/to/data.csv'，并将原始名称设为 'sales-data.csv'”
• “将文件 '/path/to/script.py' 上传到 Zipline”
• “你能帮我上传 '/path/to/report.docx' 吗？”

validate_file

检查文件是否存在且适合上传。

• filePath：要验证的文件路径。上传时适用相同的 ZIPLINE_ALLOWED_ROOTS 规则：解析符号链接后的真实路径必须位于某个允许的目录内。支持的扩展名：txt、md、gpx、html、json、xml、csv、js、css、py、sh、yaml、yml、png、jpg、jpeg、gif、webp、svg、bmp、tiff、ico、heic、avif。上传时适用的内容规则同样适用，包括复合文件、AVI、Matroska 和 WebM 的情况。对于无法识别的非文本内容，即使扩展名匹配，也会拒绝接受，而不会信任该文件。

面向用户的提示词示例：

• “检查 '/path/to/document.pdf' 是否适合上传”
• “验证位于 '/home/user/images/photo.jpg' 的文件”
• “'/path/to/data.csv' 适合上传到 Zipline 吗？”
• “你能帮我验证 '/path/to/script.py' 吗？”
• “检查是否可以上传 '/path/to/report.docx'”

list_user_files

列出并搜索你之前上传到 Zipline 服务的文件。使用此工具查找文件 ID，之后可将其用于 get_user_file、update_user_file 和 delete_user_file 工具。如果你已知文件名，也可以使用 get_user_file 获取文件 ID。

• page：（可选）分页页码（默认值：1）
• perPage：（可选）每页项目数（默认值：20）
• searchField：（可选）要搜索的字段（例如，“name”、“originalName”、“type”）
• searchQuery：（可选）搜索查询字符串
• filter：（可选）按文件类型或其他条件筛选
• sort：（可选）排序字段（例如，“createdAt”、“size”、“name”）
• order：（可选）排序顺序（“asc” 或 “desc”，默认值：“desc”）

用户提示词示例：

• “列出我在 Zipline 上的所有文件”
• “显示我上传文件的第一页”
• “搜索名称中包含‘document’的文件”
• “查找我上传的所有 PDF 文件”
• “按创建日期排序列出我的文件，最新的排在最前面”
• “每页显示 10 个文件，显示第 2 页”
• “搜索原始名称中包含‘report’的文件”
• “按大小排序列出我的文件，最大的排在最前面”
• “查找我上传的所有图像文件”

tmp_file_manager

提供精简的沙盒文件管理功能，并按用户隔离。每位用户都会根据自己的 ZIPLINE_TOKEN 获得独立的沙盒目录。仅允许使用纯文件名（不允许子目录或路径遍历）。所有操作都严格限制在用户自己的沙盒中。

• command：以下命令之一：
  • LIST — 列出用户沙盒中的所有文件
  • CREATE <filename> — 创建或覆盖文件（可选提供 content）
  • OPEN <filename> 或 READ <filename> — 读取文件内容（最大 1MB）
  • PATH <filename> — 获取沙盒中文件的绝对路径
  • DELETE <filename> — 从沙盒中删除文件
• content：（可选）用于 CREATE 的字符串内容

示例：

• LIST
• CREATE notes.txt（可提供或不提供内容）
• OPEN notes.txt
• READ notes.txt
• PATH notes.txt
• DELETE notes.txt

用户提示词示例：

• “列出我沙盒中的所有文件”
• “创建名为‘notes.txt’的文件，内容为‘今天的会议记录’”
• “读取‘config.json’的内容”
• “获取‘data.csv’的绝对路径”
• “删除文件‘temp.txt’”
• “显示我临时目录中的所有文件”
• “创建一个名为‘draft.md’的新文件并写入一些内容”
• “打开并读取‘settings.json’文件”
• “‘output.txt’的完整路径是什么？”
• “从我的沙盒中移除‘old_file.txt’”

沙盒配置：

• 默认启用按用户隔离的沙盒
• 若要禁用沙盒并让所有用户共用 ~/.zipline_tmp 目录，请在环境中设置 ZIPLINE_DISABLE_SANDBOXING=true
• 禁用沙盒后，也会禁用会话锁定和 TTL 清理

按用户隔离的沙盒（启用时）：

• 每位用户都会在 ~/.zipline_tmp/users/{hash} 中获得一个唯一的沙盒目录，其中 hash 是用户 ZIPLINE_TOKEN 的 SHA-256 哈希值
• 为确保安全，系统会自动创建权限为 0700 的沙盒
• 所有文件操作均限制在用户自己的沙盒中
• 超过 24 小时的沙盒会自动清理

会话锁定（启用沙盒时）：

• 执行操作期间，每位用户的沙盒都会被锁定，以防并发访问
• 锁定会在 30 分钟后自动过期
• 多个客户端访问同一沙盒时，系统会防止发生竞态条件

安全性：

• 仅允许使用纯文件名（不允许 /、\、.. 或绝对路径）
• 任何尝试访问用户沙盒之外内容的操作都会被拒绝，并返回明确的错误
• 无法读取大于 1MB 的文件
• 不支持子目录
• 启用沙盒时，每位用户的沙盒彼此隔离

download_external_url

新增了一个工具：download_external_url。它可让 MCP 服务（从而也让模型）将外部 HTTP(S) URL 下载到调用者的沙箱中，并返回保存文件的绝对文件系统路径。

• 工具名称：download_external_url
• 用途：将外部 HTTP(S) 资源下载到每位用户的沙箱中，并返回文件的保存绝对路径。
• 输入架构：
  • url（字符串）— 必填 — 要下载的 HTTP 或 HTTPS URL
  • timeoutMs（数字）— 可选 — 请求超时时间，单位为毫秒（默认值：30000）
  • maxFileSizeBytes（数字）— 可选 — 允许的最大文件大小，单位为字节（默认值：100 _ 1024 _ 1024 = 100 MB）
• 行为：
  • 验证提供的 URL，只允许使用 http: 和 https: 协议。
  • 使用 AbortController 强制执行配置的超时时间。
  • 如果存在 Content-Length 标头，则检查该值；若声明的文件大小超过配置的上限，则拒绝下载。
  • 将文件下载到用户的沙箱目录（与 tmp_file_manager 工具使用同一个沙箱），并返回绝对路径，例如 /home/user/.zipline_tmp/users/<hash>/file.ext。
  • 如果远程资源未提供文件名，则使用安全且确定性的名称。
  • 如果下载失败，则清理部分下载的文件，避免在沙箱中留下不完整的文件。
  • 通过现有的沙箱日志记录机制生成结构化日志，以便监控。

使用示例（MCP 工具调用）

• 输入示例： { "url": "https://example.com/files/document.pdf", "timeoutMs": 30000, "maxFileSizeBytes": 104857600 }
• 成功响应内容示例： "✅ DOWNLOAD COMPLETE\n\nLocal path: /home/user/.zipline_tmp/users/abc123/document.pdf"

安全注意事项

• 只接受 http 和 https。其他协议（ftp、file 等）均会被拒绝。
• 每次建立连接前（包括重定向后），服务都会解析主机名；如果解析结果中包含任何环回、私有、链路本地或云元数据地址（例如 127.0.0.1、10.0.0.0/8、169.254.169.254），则拒绝下载。
• 套接字会连接到查询返回的地址。原始主机名会作为 Host 标头和 TLS 服务器名称发送。检查完成后发生的 DNS 变更不会影响连接目标。
• 默认文件大小上限：100 MB。你可以通过 maxFileSizeBytes 覆盖该值，但请谨慎操作。
• 下载器会跟随重定向，但会在代码中限制重定向行为（避免重定向循环）。每次重定向都会重新解析并检查目标地址。
• 远程服务返回错误状态时，只保留响应正文的前 1 MiB。成功下载仍受 maxFileSizeBytes 限制（默认值为 100 MB）。
• 所有下载都会保存在每位用户的沙箱中；文件名会按照与 tmp_file_manager 相同的规则进行验证和清理（不允许路径分隔符、点号路径段或绝对路径）。
• 服务会记录下载活动，并对路径进行清理（屏蔽用户部分）以便监控；绝不会记录机密信息（例如令牌）。
• 如果需要通过域名允许列表限制服务可下载内容的来源，可考虑在生产环境启用此工具之前，在 MCP 服务配置层添加主机名白名单。

面向用户的提示词示例：

• “将 ‘https://example.com/document.pdf’ 中的 PDF 下载到我的沙箱”
• “下载 ‘https://example.com/data.csv’，超时时间设为 60 秒”
• “下载 ‘https://example.com/image.jpg’ 中的图片，文件大小上限为 50MB”
• “下载 ‘https://example.com/report.pdf’ 中的文件并保存到我的沙箱”
• “你能帮我下载 ‘https://example.com/config.json’ 吗？”
• “下载 ‘https://example.com/archive.zip’，自定义超时时间为 45 秒”
• “我需要下载 ‘https://example.com/data.json’，文件大小上限为 10MB”

list_user_files

新增了一个工具：list_user_files。它可以列出和搜索你之前上传到 Zipline 服务的文件。

• 工具名称：list_user_files
• 用途：列出和搜索存储在 Zipline 服务上的用户文件，支持分页、筛选、排序和搜索。
• 输入架构：
  • page（number）— 可选 — 分页页码（默认值：1）
  • perPage（number）— 可选 — 每页项目数（默认值：20）
  • searchField（string）— 可选 — 搜索字段（例如，“name”、“originalName”、“type”）
  • searchQuery（string）— 可选 — 搜索查询字符串
  • filter（string）— 可选 — 按文件类型或其他条件筛选
  • sort（string）— 可选 — 排序字段（例如，“createdAt”、“size”、“name”）
  • order（string）— 可选 — 排序顺序（“asc” 或 “desc”，默认值：“desc”）
• 行为：
  • 使用指定的参数从 Zipline API 获取文件
  • 支持分页，以处理大量文件
  • 支持使用 searchField 和 searchQuery 搜索特定字段
  • 支持筛选和排序结果
  • 返回包含文件信息和分页元数据的结构化响应

使用示例（MCP 工具调用）

• 示例输入：

  {
    "page": 1,
    "perPage": 10,
    "searchField": "name",
    "searchQuery": "document",
    "sort": "createdAt",
    "order": "desc"
  }
  

• 成功响应内容示例：

  📁 USER FILES (Page 1 of 3)
  
  1. ⭐ document.pdf
     🆔 ID: file123
     📅 Created: 1/15/2025
     📊 Size: 1.2 MB
     🏷️ Type: application/pdf
     👁️ Views: 5
     🔗 URL: https://zipline.example.com/u/file123
  
  2. image.png
     🆔 ID: img456
     📅 Created: 1/14/2025
     📊 Size: 2.1 MB
     🏷️ Type: image/png
     👁️ Views: 12
     🔗 URL: https://zipline.example.com/u/img456
  
  3. data.csv
     🆔 ID: csv789
     📅 Created: 1/13/2025
     📊 Size: 500.0 KB
     🏷️ Type: text/csv
     👁️ Views: 3
     🔗 URL: https://zipline.example.com/u/csv789
  
  Total files: 25 | Showing: 3
  

  注意： 响应中的 URL 会进行规范化处理，确保无论 ZIPLINE_ENDPOINT 配置如何，都能正确格式化。规范化会处理末尾的斜杠，并确保 URL 构造一致。

文件模型

该工具返回的文件具有以下结构：

• id：文件的唯一标识符（用于 get_user_file、update_user_file 和 delete_user_file 等操作）
• name：服务器上存储的文件名
• originalName：上传时的原始文件名
• size：文件大小（以字节为单位）
• type：文件的 MIME 类型
• url：用于访问文件的直接 URL
• createdAt：文件上传时间（ISO 8601 格式）
• expiresAt：文件到期时间（如适用）
• maxViews：最大查看次数限制（如适用）
• views：当前查看次数

搜索和筛选选项

该工具提供强大的搜索和筛选功能：

• 搜索：使用 searchField 和 searchQuery 搜索特定字段
  • 支持的搜索字段：“name”、“originalName”、“type”
  • 搜索不区分大小写，并支持部分匹配
• 筛选：使用 filter 参数按文件类型或其他条件筛选
• 排序：使用 sort 和 order 对结果按任意字段排序
  • 支持的排序字段：“createdAt”、“size”、“name”、“views”
  • 排序顺序可以是“asc”（升序）或“desc”（降序）

集成说明

• 此工具由 MCP 服务导出，可由 MCP 客户端或模型以编程方式调用。
• 实现位于 src/userFiles.ts，MCP 注册位于 src/index.ts。
• 已在 src/userFiles.test.ts 下添加测试，用于验证分页、搜索、筛选、排序和错误处理。

get_user_file

工具信息：get_user_file。此工具可获取 Zipline 服务器上某个文件的详细信息。使用 list_user_files 或文件名查找此工具所需的文件 ID。

• 工具名称：get_user_file
• 用途：获取 Zipline 服务器上某个文件的详细信息
• 输入架构：
  • id（string）— 必填 — 要获取信息的文件 ID。请从 list_user_files 工具中获取。
• 行为：
  • 使用文件 ID 从 Zipline API 获取文件信息
  • 返回全面的文件元数据，包括大小、类型、浏览次数、收藏状态等
  • 处理文件 ID 中特殊字符的 URL 编码

用法示例（MCP 工具调用）

• 示例输入：

  {
    "id": "file123"
  }
  

• 示例成功响应内容：

  📁 FILE INFORMATION
  
  📁 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5
  🔗 URL: http://localhost:3000/u/file123
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

  注意： 响应中的 URL 会经过规范化，以确保无论 ZIPLINE_ENDPOINT 配置如何，格式都正确。规范化会处理尾部斜杠，并确保 URL 构造一致。

面向用户的提示词示例：

• “获取 ID 为 ‘abc123’ 的文件的详细信息”
• “向我显示文件 ‘document.pdf’ 的详细信息”
• “我需要查看文件 ‘xyz789’ 的元数据”
• “文件名为 ‘my-image.jpg’ 的文件有哪些属性？”
• “获取 ID 为 ‘file123’ 的文件信息”

update_user_file

工具信息：update_user_file。此工具可更新 Zipline 服务器上某个文件的属性。使用 list_user_files 或文件名查找此工具所需的文件 ID。

• 工具名称：update_user_file
• 用途：更新 Zipline 服务器上某个文件的属性
• 输入架构：
  • id（string）— 必填 — 要更新的文件 ID。请从 list_user_files 工具中获取。
  • favorite（boolean）— 可选 — 将文件设为收藏或取消收藏
  • maxViews（number）— 可选 — 允许的最大浏览次数（>= 0）
  • password（string | null）— 可选 — 设置密码（string），移除密码（null）
  • originalName（string）— 可选 — 设置或更新原始文件名
  • type（string）— 可选 — 设置或更新文件 MIME 类型
  • tags（string[]）— 可选 — 要为此文件设置的标签 ID 数组
  • name（string）— 可选 — 重命名文件
• 行为：
  • 使用 PATCH 请求通过 Zipline API 更新文件属性
  • 仅更新明确提供的字段（忽略值为 undefined 的字段）
  • 支持传入 string 或 null 来设置或移除密码
  • 返回更新后的文件信息

用法示例（MCP 工具调用）

• 示例输入：

  {
    "id": "file123",
    "favorite": true,
    "maxViews": 10,
    "password": "secret123"
  }
  

• 示例成功响应内容：

  ✅ FILE UPDATED SUCCESSFULLY!
  
  ⭐🔒 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5/10
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

  注意： 响应中不包含 URL 字段。若要获取包含 URL 的更新后文件信息，请使用 get_user_file 工具。

面向用户的提示词示例：

• “将文件 ‘abc123’ 设为收藏”
• “将文件 ‘document.pdf’ 的最大浏览次数设为 10”
• “为文件 ‘xyz789’ 添加密码保护，密码为 ‘secret123’”
• “移除文件 ‘file123’ 的密码”
• “将文件 ‘abc123’ 的原始名称改为 ‘my-updated-document.pdf’”
• “将文件 ‘xyz789’ 重命名为 ‘new-name.pdf’”
• “将文件 ‘file123’ 的 MIME 类型设为 ‘application/pdf’”
• “为文件 ‘abc123’ 添加标签 ['tag1', 'tag2']”
• “将文件 ‘xyz789’ 设为收藏，最大浏览次数设为 5，密码设为 ‘secure’”

delete_user_file

新增了一个工具：delete_user_file。它允许你删除存储在 Zipline 服务上的指定文件。使用 list_user_files 或文件名查找此工具所需的文件 ID。

• 工具名称：delete_user_file
• 用途：删除存储在 Zipline 服务上的指定文件
• 输入架构：
  • id（字符串）— 必填 — 要删除的文件 ID。请通过 list_user_files 工具获取。
• 行为：
  • 使用 DELETE 请求调用 Zipline API 删除文件
  • 返回已删除文件的信息（用于确认）
  • 处理文件 ID 中特殊字符的 URL 编码

使用示例（MCP 工具调用）

• 输入示例：

  {
    "id": "uniqueid123"
  }
  

• 成功响应内容示例：

  ✅ FILE DELETED SUCCESSFULLY!
  
  ⭐🔒 document.pdf
  🆔 ID: uniqueid123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5/10
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

  注意： 由于文件已删除，响应中不包含 URL 字段。

面向用户的提示词示例：

• “删除 ID 为 'abc123' 的文件”
• “从服务器中移除文件 'document.pdf'”
• “删除名为 'my-image.jpg' 的文件”
• “永久删除文件 'xyz789'”
• “我想删除 ID 为 'file123' 的文件”

remote_folder_manager

新增了一个工具：remote_folder_manager。它允许你列出和管理 Zipline 服务上的远程文件夹。

• 工具名称：remote_folder_manager
• 用途：列出和管理 Zipline 服务上的远程文件夹
• 输入架构：
  • command（字符串）— 必填 — 要执行的命令。支持：
    • LIST — 列出 Zipline 服务上的所有文件夹及其完整详情
    • ADD <name> — 创建一个指定名称的新文件夹
    • EDIT <id> — 编辑指定 ID 的现有文件夹
    • INFO <id> — 按 ID 获取指定文件夹的详细信息
    • DELETE <id> — 删除指定 ID 的现有文件夹
  • id（字符串）— 可选 — 要编辑的文件夹 ID（EDIT 命令必填）
  • name（字符串）— 可选 — 文件夹名称（ADD 命令必填，EDIT 命令可选）
  • isPublic（布尔值）— 可选 — 文件夹是否公开（默认值：false；用于 ADD 命令和 EDIT 命令）
  • allowUploads（布尔值）— 可选 — 是否允许向文件夹上传文件（用于 EDIT 命令）
  • fileId（字符串）— 可选 — 要添加到文件夹的文件 ID（用于 EDIT 命令）
  • files（字符串数组）— 可选 — 要包含在文件夹中的文件 ID 数组（用于 ADD 命令）
  • id（字符串）— 可选 — 要获取信息的文件夹 ID（INFO 命令必填）
• 行为：
  • 对于 LIST：从 Zipline API 获取文件夹，并返回包含完整文件夹详情的结构化响应，包括 ID、名称、公开状态、创建/更新时间戳和文件数量
  • 对于 ADD：使用指定名称和可选参数创建新文件夹
  • 对于 EDIT：使用指定 ID 和可选参数修改现有文件夹
    • 提供 fileId 时：将指定文件添加到文件夹
    • 提供 name、isPublic 或 allowUploads 时：更新文件夹属性
  • 对于 INFO：按 ID 获取指定文件夹的详细信息，包括所有文件夹属性
  • 对于 DELETE：永久删除指定 ID 的现有文件夹，并返回已删除文件夹的信息
  • 返回全面的文件夹信息，包括所有可用字段
  • 验证输入参数并提供清晰的错误消息
  • 对于 INFO 命令，必须提供有效的文件夹 ID（而非文件夹名称）

使用示例（MCP 工具调用）

LIST 命令示例：

• 输入示例：

  {
    "command": "LIST"
  }
  

• 成功响应内容示例：

  📁 REMOTE FOLDERS
  
  1. Documents
     🆔 ID: folder123
     🔒 Private
     📅 Created: 2025-01-15T10:30:45.123Z
     📝 Updated: 2025-01-20T14:45:30.456Z
     📄 Files: 5
  
  2. Images
     🆔 ID: folder456
     🔒 Public
     📅 Created: 2025-01-10T09:15:22.789Z
     📝 Updated: 2025-01-18T16:20:11.012Z
     📄 Files: 12
  
  3. Public
     🆔 ID: No ID
     🔒 Public
     📅 Created: 2025-01-05T08:00:00.000Z
     📝 Updated: 2025-01-05T08:00:00.000Z
     📄 Files: 0
  
  Total folders: 3
  

ADD 命令示例：

• 输入示例（使用参数）：

  {
    "command": "ADD",
    "name": "My New Folder",
    "isPublic": false
  }
  

• 输入示例（使用命令参数）：

  {
    "command": "ADD My New Folder"
  }
  

• 成功响应内容示例：

  ✅ FOLDER CREATED SUCCESSFULLY!
  
  📁 My New Folder
     🆔 ID: folder789
     🔒 Private
     📄 Files: 0
  

  注意： Zipline 服务可能不会为某些文件夹分配 ID。工具会妥善处理这种情况，对于没有 ID 的文件夹显示“No ID”。

EDIT 命令示例：

• 输入示例（更新文件夹属性）：

{
  "command": "EDIT",
  "id": "folder123",
  "name": "Updated Folder Name",
  "isPublic": true,
  "allowUploads": true
}

• 示例输入（向文件夹添加文件）：

{
  "command": "EDIT",
  "id": "folder123",
  "fileId": "file456"
}

• 成功响应内容示例（更新属性）：

✅ FOLDER UPDATED SUCCESSFULLY!

📁 Updated Folder Name
   🆔 ID: folder123
   🔒 Public
   📤 Uploads Allowed
   📄 Files: 3

• 成功响应内容示例（添加文件）：

✅ FILE ADDED TO FOLDER SUCCESSFULLY!

📁 Documents
   🆔 ID: folder123
   🔒 Private
   📄 Files: 4

注意： EDIT 命令支持两种操作模式：

1. 属性编辑：提供 name、isPublic 或 allowUploads 时，会通过 PATCH 请求更新文件夹属性。
2. 添加文件：提供 fileId 时，会通过 PUT 请求将指定文件添加到文件夹。

这两种模式可以单独使用，也可以在同一条命令中同时使用。

INFO 命令示例：

• 输入示例：

  {
    "command": "INFO",
    "id": "folder123"
  }
  

• 成功响应内容示例：

  📁 FOLDER INFORMATION
  
  📁 Documents
     🆔 ID: folder123
     🔒 Private
     📅 Created: 2025-01-15T10:30:45.123Z
     📝 Updated: 2025-01-20T14:45:30.456Z
     📄 Files: 5
     📋 Files (IDs): file123, file456, file789, fileabc, filexyz
  

  注意： INFO 命令需要有效的文件夹 ID，而不是文件夹名称。使用 LIST 命令查找要获取信息的文件夹 ID。

DELETE 命令示例：

• 输入示例：

{
  "command": "DELETE",
  "id": "folder123"
}

• 成功响应内容示例：

✅ FOLDER DELETED SUCCESSFULLY!

📁 Documents
   🆔 ID: folder123
   🔒 Private
   📅 Created: 2025-01-15T10:30:45.123Z
   📝 Updated: 2025-01-20T14:45:30.456Z
   📄 Files: 5

注意： DELETE 命令需要有效的文件夹 ID，而不是文件夹名称。使用 LIST 命令查找要删除的文件夹 ID。文件夹删除后无法恢复。

文件夹模型

工具返回的文件夹具有以下结构：

• id：文件夹的唯一标识符（可选，并非所有文件夹都会包含）
• name：文件夹名称
• public：文件夹是否公开（true/false）
• createdAt：文件夹的创建时间（ISO 8601 格式）
• updatedAt：文件夹的上次更新时间（ISO 8601 格式）
• files：文件夹中包含的文件 ID 数组

集成者须知

• 此工具由 MCP 服务导出，可由 MCP 客户端或模型以编程方式调用。
• 实现位于 src/remoteFolders.ts，MCP 注册位于 src/index.ts。
• 在 src/remoteFolders.test.ts 下添加了测试，用于验证 LIST 和 ADD 命令的成功情况、分页、错误处理和边缘情况。

面向用户的提示词示例：

• “列出我的 Zipline 服务上的所有文件夹”
• “显示可用的文件夹”
• “服务上有哪些文件夹？”
• “列出所有远程文件夹”
• “创建一个名为 'Documents' 的新文件夹”
• “在我的 Zipline 服务上添加一个名为 'Images' 的文件夹”
• “创建一个名为 'Shared Files' 的公开文件夹”
• “添加一个名为 'Projects' 的新文件夹”
• “创建一个名为 'Archive' 的文件夹，并将其设为私有”
• “编辑文件夹 'folder123'，将其重命名为 'New Documents'”
• “更新文件夹 'folder456'，将其设为公开并允许上传”
• “将文件 'file789' 添加到文件夹 'folder123'”
• “将文件夹 'folder789' 设为私有并禁用上传”
• “将文件夹 'folder456' 重命名为 'Archive' 并设为公开”
• “获取文件夹 'folder123' 的详细信息”
• “显示 ID 为 'folder789' 的文件夹的所有详细信息”
• “文件夹 'folder456' 有哪些属性？”
• “获取名为 'Documents' 的文件夹的信息（先使用 LIST 获取 ID）”
• “删除 ID 为 'folder123' 的文件夹”
• “从服务中移除名为 'Old Documents' 的文件夹”
• “删除 ID 为 'folder456' 的文件夹”
• “永久删除文件夹 'folder789'”
• “我想删除 ID 为 'folder123' 的文件夹”

沙盒路径解析

tmp_file_manager 工具使用安全的路径解析机制，确保所有文件操作都在沙盒边界内进行。该机制通过 resolveSandboxPath 函数实现，并提供以下安全保障：

路径验证：

• 文件名验证：验证所有文件名，防止路径遍历攻击
• 绝对路径解析：将相对文件名转换为沙盒内的绝对路径
• 边界强制执行：确保解析后的路径不会越出沙盒目录
• 错误处理：出现违规时抛出 SandboxPathError，并提供清晰的错误消息

安全功能：

• 输入清理：拒绝包含路径分隔符（/、\）、点号片段（..）或绝对路径的文件名
• 路径规范化：将路径解析为其规范形式，防止符号链接攻击
• 包含关系验证：验证最终解析后的路径位于沙盒边界内
• 审计日志记录：记录所有沙盒操作，并对路径进行清理以便安全监控

实现详情：

// Example of secure path resolution
function resolveSandboxPath(filename: string): string {
  const userSandbox = getUserSandbox();

  // Validate filename first
  const validationError = validateFilename(filename);
  if (validationError) {
    throw new SandboxPathError(validationError);
  }

  const resolved = path.resolve(userSandbox, filename);

  // Security: Ensure resolved path is within sandbox
  if (!resolved.startsWith(userSandbox)) {
    throw new SandboxPathError(`Path traversal attempt: ${filename}`);
  }

  return resolved;
}

错误示例：

• CREATE ../evil.txt → 错误：文件名不得包含路径分隔符、点号片段或为空。仅允许使用 ~/.zipline_tmp 中的纯文件名。
• OPEN /etc/passwd → 错误：文件名不得包含路径分隔符、点号片段或为空。仅允许使用 ~/.zipline_tmp 中的纯文件名。
• READ ../../system/file → 错误：路径遍历尝试：../../system/file

日志记录与审计：

所有沙盒操作都会记录日志，并对敏感安全信息进行清理：

[2025-01-15T10:30:45.123Z] SANDBOX_OPERATION: FILE_CREATED - notes.txt - Path: /home/user/.zipline_tmp/users/[HASH] - Size: 42 bytes

用户专属路径会替换为 [HASH]，以防止日志中泄露令牌，同时保留可追溯性。

开发

前置条件

• Node.js（v18 或更高版本）
• npm 或 yarn

设置

1. 克隆仓库：

git clone https://github.com/dorogoy/zipline-mcp.git
cd zipline-mcp

2. 安装依赖：

npm install

脚本

• npm run build：构建 TypeScript 项目。
• npm run start：运行构建后的服务。
• npm run dev：使用 tsx 以开发模式运行服务。
• npm run test：以监视模式运行测试。
• npm run test:run：运行一次测试。
• npm run lint：使用 ESLint 检查代码库。
• npm run lint:fix：尽可能自动修复 lint 错误。
• npm run format：使用 Prettier 格式化代码库。
• npm run format:check：检查代码库是否已格式化。

Lint 检查

在本地运行 Lint

检查 lint 错误：

npm run lint

自动修复可修复的问题：

npm run lint:fix

或者使用 Makefile：

make lint

在 CI 中运行 Lint

• 每次拉取请求和每次发布前都会自动运行 lint 检查。
• 如果存在任何 lint 错误，CI 将失败。
• 合并 PR 时必须通过 lint 检查。

解读 Lint 结果

• 错误会显示在终端或 CI 日志中。
• 使用 npm run lint:fix 在本地修复错误，或根据提示编辑代码。
• 警告不会阻止 CI 通过，但为保证代码质量，仍应处理。

Makefile

为方便使用，项目提供了 Makefile：

make install      # Install dependencies
make build       # Build the project
make test        # Run tests
make lint        # Lint the code
make format      # Format the code
make clean       # Clean build artifacts
make publish     # Publish to npm

许可证

MIT