MCP 工具使用
FolderSpan 提供 36 个 MCP 工具，用于访问文件、书签、收藏、最近访问、文件任务、设备、网络位置和同步任务。连接 Codex 或 Claude Code 后，不需要手动编写工具参数，直接用自然语言说明目标即可；AI 会选择当前令牌允许使用的 folderspan_ 工具，并把结构化结果整理成回答。
本页说明每类工具适合怎样提问，以及调用后能够返回什么信息。
提问时需要说明什么
一个清楚的提问通常包含以下内容：
- 来源：文件位于当前设备、其他设备、分享来源还是网络位置。
- 位置：给出来源名称和绝对路径；知道稳定 ID 时也可以直接提供。
- 操作：明确要查看、读取、写入、重命名、复制、移动、删除、分享还是运行同步。
- 处理规则：复制或移动时说明同名项目使用
error、skip、overwrite还是rename。 - 确认要求：涉及写入、覆盖、移动、删除、分享或连接时，可以要求 AI 先展示计划，得到确认后再执行。
- 回答格式：如果需要核对原始信息，可以要求 AI 保留 ID、路径、状态、时间和错误码，不要只给摘要。
可以直接使用下面的模板：
请使用 FolderSpan MCP 工具完成以下任务：
- 来源：<Local、Device、Share 或 Network，以及来源名称>
- 路径：<绝对路径>
- 目标：<目标来源和绝对路径，没有则删除本行>
- 操作：<要完成的操作>
- 冲突策略：<error、skip、overwrite 或 rename，没有则删除本行>
- 执行要求：先读取元数据并复述来源、目标和影响范围；涉及修改时等我确认。
- 回答要求：返回实际使用的工具、项目 ID、完整路径、执行状态和失败原因。
不知道设备、网络位置、同步任务或文件任务的 ID 时，直接提供名称并要求 AI “先列出候选项，不要猜测 ID”。AI 可以先查询列表，再使用返回的 ID 执行下一步。
文件位置怎么描述
所有文件工具都通过 protocol、sourceId 和 path 定位项目。调用工具不会切换 FolderSpan 当前显示的目录。
| 来源 | 提问中的说法 | sourceId | path |
|---|---|---|---|
Local | “当前设备”或“本机” | 空字符串 | 当前设备中的绝对路径 |
Device | “设备‘办公室电脑’” | 已连接设备的稳定 ID | 目标设备使用的绝对路径 |
Share | “分享来源 <名称或 ID>” | 当前可用分享来源的稳定 ID | 分享来源使用的绝对路径 |
Network | “网络位置‘备份盘’” | 已连接网络位置的稳定 ID | 远程端点使用的绝对路径 |
例如：
列出当前设备 `/Documents` 的直接子项，返回每项的完整路径、类型、大小和更新时间，不要修改文件。
先列出已配置的网络位置，找到名称为“备份盘”的条目并告诉我它的 ID 和连接状态。先不要连接。
Device、Share 和 Network 来源必须当前可用；否则工具会返回 not_connected 或 not_found。路径必须是对应端点认可的绝对路径，不能包含 .、.. 等路径穿越片段。
如何理解 AI 的回答
FolderSpan 会同时返回文本形式的 JSON 和结构化结果。AI 客户端通常不会原样显示全部 JSON，而是把字段整理成自然语言。需要核对细节时，可以继续说：
请不要省略工具返回字段，列出 ID、protocol、sourceId、path、状态、时间和 nextCursor。
常见返回规则如下：
- 列表结果：返回
items和nextCursor。nextCursor非空表示还有下一页，可以要求 AI “继续读取下一页直到结束”。 - 分页参数：
limit默认为50，范围为1至200；cursor是不透明游标，不应自行编辑。 - 时间字段：
createdAt、updatedAt、lastAccessed、expiresAt等返回时间戳。可以要求 AI 同时转换为本地日期时间。 - 修改结果：创建、编辑、写入或连接成功后，通常返回修改后的完整对象；删除类工具返回布尔值或删除数量。
- 异步文件任务：复制、移动和删除只返回
taskId，需要继续查询任务才能得到进度和失败信息。 - 错误结果：返回
code和message，AI 应说明失败原因，而不是把失败描述成成功。
浏览和读取文件
如何提问
列出本机 `/Documents` 的直接子项，按“目录、文档、其他文件”分组。每项显示完整路径、大小、更新时间和可执行权限；如果还有下一页就继续读取。
读取本机 `/Documents/report.txt`。先返回文件大小和更新时间，再分段读取全文并总结要点；不要修改文件。
工具和返回信息
| 工具 | 所需权限 | 提问用途 | 返回信息 |
|---|---|---|---|
folderspan_files_list | files.read | “列出某目录的直接子项” | items、nextCursor；每项包含名称、路径、是否目录、MIME 类型、大小、创建/更新时间、来源、可用权限、隐藏/符号链接和敏感项信息 |
folderspan_file_info | files.read | “查看这个文件或目录的详细信息” | 单个项目的完整元数据，字段与目录列表中的项目相同 |
folderspan_file_read | files.read | “读取或总结这个文件” | totalSize、offset、returnedLength、hasMore、encoding 和 data |
目录项中的 permissions 会分别说明当前端点是否允许 read、write、rename、delete 和 share。endpoint 会返回实际使用的 protocol 和 sourceId。
folderspan_file_read 默认从 offset=0 开始读取 262144 字节，单次允许读取 1 至 4194304 字节；文本使用 utf8，二进制内容使用 base64。当 hasMore 为 true 时，应使用新的偏移量继续读取。
AI 通常会把结果整理成下面这种回答：
已读取 Local `/Documents/report.txt`：
- 文件总大小：<totalSize> 字节
- 本次范围：从 <offset> 开始，共 <returnedLength> 字节
- 是否还有内容：<hasMore>
- 内容摘要：<根据 data 生成的摘要>
写入、建目录和重命名
如何提问
先读取本机 `/Notes/todo.txt` 的大小和更新时间。确认文件没有变化后，在末尾追加一行“完成备份”，并返回实际写入字节数和新的文件信息。
在本机 `/Documents` 下创建目录 `/Documents/Archive`。如果目录已经存在，只返回现有目录的信息，不要删除或覆盖任何内容。
工具和返回信息
| 工具 | 所需权限 | 提问用途 | 返回信息 |
|---|---|---|---|
folderspan_file_write | files.write | “新建、覆盖或追加文件内容” | entry、bytesWritten、mode；entry 是写入后的完整文件元数据 |
folderspan_directory_create | files.write | “创建一层目录” | 新目录的完整元数据；目录已存在时返回现有目录 |
folderspan_file_rename | files.write | “把文件或目录改名为……” | 重命名后的完整项目元数据 |
写入模式包括 overwrite 和 append，默认为 overwrite。单次解码后的写入内容不能超过 524288 字节。为避免覆盖刚被其他程序修改的文件，可以让 AI 先调用 folderspan_file_info，再把返回的 size 和 updatedAt 作为 expectedSize、expectedUpdatedAt 写入；前提不一致时返回 conflict，不会写入数据。
复制、移动、删除和文件任务
如何提问
把本机 `/Documents/report.pdf` 复制到网络位置“备份盘”的 `/Reports`，同名时使用 `rename`。先检查来源和目标并展示计划，我确认后再执行。创建任务后持续查询，直到结束，再汇总进度和失败项。
准备删除本机 `/Downloads/old.zip`。先返回文件完整路径、大小和更新时间，等我确认后再删除，并查询任务最终状态。
创建任务
| 工具 | 所需权限 | 提问用途 | 首次返回 |
|---|---|---|---|
folderspan_files_copy | files.write | “复制这些文件到目标目录” | taskId |
folderspan_files_move | files.write | “移动这些文件到目标目录” | taskId |
folderspan_files_delete | files.write | “删除这些文件或目录” | taskId |
复制和移动支持 error、skip、overwrite 和 rename 冲突策略。移动任务只会在对应目标项复制完成后删除源项；如果删除源项失败，重试时不会重复复制。
查询和控制任务
| 工具 | 所需权限 | 适合怎样追问 | 返回信息 |
|---|---|---|---|
folderspan_tasks_list | tasks.read | “列出最近的文件任务及进度” | 分页任务列表 |
folderspan_tasks_get | tasks.read | “查询任务 <taskId> 的当前状态” | 单个任务详情 |
folderspan_tasks_pause | tasks.control | “暂停任务 <taskId>” | 操作后的任务详情 |
folderspan_tasks_resume | tasks.control | “继续任务 <taskId>” | 操作后的任务详情 |
folderspan_tasks_cancel | tasks.control | “取消任务 <taskId>” | 操作后的任务详情 |
folderspan_tasks_delete | tasks.control | “删除已经结束的任务记录 <taskId>” | deleted |
任务详情包含：
id、type、status：任务标识、类型和当前状态。protocol、sourceId、values：任务来源和不含令牌、密码的任务参数。progressCurrent、progressTotal：当前进度和总量。failureCount、failurePath、failureMessage：失败数量及最近的失败路径和原因。availableActions：当前允许执行的pause、resume、cancel或delete操作。
运行中或已暂停的任务不能直接删除。可以要求 AI 按 availableActions 判断下一步，不要盲目尝试不允许的操作。
书签
如何提问
列出本机书签，显示书签 ID、名称、类型、路径、排序值和来源是否可用。
在本机创建名为“工作文档”的书签，类型为 `document`，路径为 `/Documents/Work`。创建后返回书签 ID 和完整信息。
工具和返回信息
| 工具 | 所需权限 | 操作 | 返回信息 |
|---|---|---|---|
folderspan_bookmarks_list | bookmarks.read | 查看指定 protocol 和 sourceId 下的书签 | items、nextCursor |
folderspan_bookmarks_create | bookmarks.write | 创建书签 | 新建书签的完整信息 |
folderspan_bookmarks_update | bookmarks.write | 按书签 ID 修改名称、类型、路径、图标或排序 | 修改后的完整书签信息 |
folderspan_bookmarks_delete | bookmarks.write | 按书签 ID 删除 | deleted |
每条书签包含 id、protocol、sourceId、name、type、path、icon、sort、createdAt、updatedAt 和 sourceAvailable。书签类型可使用 home、image、audio、video、document、download 或 custom。
收藏和最近访问
如何提问
列出全部收藏，优先显示已置顶项目；每项返回 ID、文件位置、类型、大小和更新时间。
把本机 `/Documents/manual.pdf` 加入收藏。先读取文件信息，成功后返回收藏 ID；如果已经收藏，只返回现有记录。
收藏工具
| 工具 | 所需权限 | 操作 | 返回信息 |
|---|---|---|---|
folderspan_favorites_list | favorites.read | 查看收藏 | items、nextCursor |
folderspan_favorites_add | favorites.write、files.read | 按文件位置添加收藏 | 新建或已有收藏的完整信息 |
folderspan_favorites_remove | favorites.write、files.read | 按文件位置移除收藏 | removed |
folderspan_favorites_pin | favorites.write | 按收藏 ID 置顶或取消置顶 | 修改后的完整收藏信息 |
收藏记录包含 id、locator、name、isDirectory、mimeType、size、createdAt、updatedAt 和 pinned。其中 locator 包含来源端点和完整路径。
最近访问工具
| 工具 | 所需权限 | 适合怎样提问 | 返回信息 |
|---|---|---|---|
folderspan_recents_list | recents.read | “列出最近访问记录” | items、nextCursor；每项包含 ID、位置、名称、类型、大小、创建/更新时间和 lastAccessed |
folderspan_recents_delete | recents.write | “删除这些最近访问记录 ID” | deletedCount |
folderspan_recents_clear | recents.write | “清空全部最近访问记录” | deletedCount |
最近访问工具只管理已有记录，不会创建虚假的访问记录。清空操作影响全部记录，应先让 AI 返回当前数量并等待确认。
HTTP 设备和 WebRTC 设备
如何提问
列出当前发现的 HTTP 设备，按“已连接、连接中、等待对方批准、已发现”分组，显示设备 ID、名称、地址、平台和状态。先不要连接。
查看和连接工具
| 工具 | 所需权限 | 操作 | 返回信息 |
|---|---|---|---|
folderspan_devices_list | devices.read | 查看当前在线的 HTTP 设备 | 按连接状态分组的设备列表 |
folderspan_device_connect | devices.connect | 按设备 ID 连接 HTTP 设备 | 连接后的设备详情 |
folderspan_webrtc_devices_list | devices.read | 查看当前发现的 WebRTC 设备 | 按连接状态分组的设备列表 |
folderspan_webrtc_device_connect | devices.connect | 按设备 ID 连接 WebRTC 设备 | 连接后的设备详情 |
设备工具只使用 FolderSpan 已经发现的在线设备，不会主动扫描网段。设备列表按 connected、connecting、approvalRequired 和 discovered 分组。每台设备包含 id、name、host、port、platform、transport 和 status。连接工具不会绕过证书检查或对方设备的审批。
网络位置
如何提问
列出已配置的网络位置，显示 ID、名称、协议、Host、稳定来源 ID、是否已连接和是否已保存。不要返回任何凭据。
在网络位置列表中找到名称为“备份盘”的唯一条目。先告诉我 ID 和当前状态；我确认后再测试并连接。
| 工具 | 所需权限 | 操作 | 返回信息 |
|---|---|---|---|
folderspan_networks_list | networks.read | 查看已配置网络位置 | items、nextCursor |
folderspan_network_connect | networks.connect | 按网络位置 ID 验证根目录并连接 | 连接后的网络位置详情 |
每个网络位置包含 id、sourceId、name、protocol、host、connected 和 persisted。工具不会返回保存的用户名、密码、私钥或其他凭据。连接失败时返回 not_connected。
同步任务
如何提问
列出同步任务，找到名称为“文档备份”的任务，返回任务 ID、启用状态、来源、目标、最近状态、上次运行时间和下次运行时间。先不要执行。
运行同步任务“文档备份”。先通过列表确认只有一个同名任务并告诉我来源和目标，我确认后再运行；返回触发后的状态。
| 工具 | 所需权限 | 操作 | 返回信息 |
|---|---|---|---|
folderspan_sync_list | sync.read | 查看同步任务 | items、nextCursor |
folderspan_sync_run | sync.run | 立即运行一个空闲任务 | 触发后的同步任务详情 |
同步任务详情包含 id、name、enabled、sourceType、sourceRef、sourcePath、targetType、targetRef、targetPath、lastStatus、lastRunAt 和 nextRunAt。folderspan_sync_run 触发后立即返回，不会等待整次同步完成；任务已经排队或运行时返回 conflict。
分享文件
如何提问
为本机 `/Public/manual.pdf` 创建限时局域网链接分享，不显示隐藏文件、不允许上传。返回全部访问地址、过期时间和 HTTPS 安全指纹。
先列出已连接的 HTTP 设备。找到名称为“平板”的唯一设备后，把本机 `/Public/manual.pdf` 分享给它，不包含隐藏文件，并返回操作 ID 和接收状态。
| 工具 | 所需权限 | 操作 | 返回信息 |
|---|---|---|---|
folderspan_files_share_link | files.share、files.read | 创建限时局域网链接 | urls、expiresAt、allowHidden、allowUpload、fileCount、tlsFingerprintSha256 |
folderspan_files_share_device | files.share、files.read | 分享到已连接的 HTTP 设备 | operationId、deviceId、status、fileCount |
链接分享启用上传时，令牌还需要 files.write，并且 FolderSpan 主机必须已经允许上传。符号链接或端点不允许分享的项目会被拒绝。设备分享只接受当前在线且已连接的 HTTP 设备。
错误返回和继续提问
工具失败时会返回 code 和 message。常见错误码如下：
| 错误码 | 含义 | 建议追问 |
|---|---|---|
invalid_argument | 参数、路径、编码、读取范围或端口不合法 | “指出哪个参数不合法，并用列表结果中的真实值重试。” |
not_found | 文件、记录、任务、工具或来源不存在 | “重新列出候选项，返回 ID 和路径，不要猜测。” |
permission_denied | 令牌权限不足，或端点、路径、敏感项不允许该操作 | “说明缺少哪个权限；不要尝试绕过限制。” |
conflict | 目标已存在、写入前提变化，或同步任务已在运行 | “重新读取当前状态并告诉我冲突项，不要覆盖。” |
invalid_state | 当前任务状态不允许请求的控制操作 | “返回 availableActions，只建议允许的操作。” |
not_connected | 设备、分享来源或网络位置未连接 | “先列出连接状态，找到正确来源后再询问是否连接。” |
unsupported | 当前端点或平台不支持该能力 | “说明哪个端点不支持，并给出可用替代操作。” |
io_error | 端点发生文件读写错误 | “保留失败路径和消息，停止后续修改。” |
cancelled | 操作已取消 | “返回取消前的任务进度和剩余操作。” |
internal_error | 服务内部操作失败 | “保留错误码和操作上下文，不要重复执行破坏性操作。” |
安全使用建议
- 把访问令牌配置在 MCP 客户端中，不要把完整令牌写入聊天提示词。
- 首次接入先使用
仅查看权限；确认来源、路径和返回内容正确后，再增加修改或控制权限。 - 删除、覆盖、移动、分享和设备连接前，让 AI 复述目标、影响范围和冲突策略并等待确认。
- 要求 AI 使用列表工具取得真实 ID，不要根据名称猜测
sourceId、设备 ID、任务 ID 或网络位置 ID。 - 如果 AI 看不到某个工具，检查令牌是否具备对应权限，再让客户端刷新工具列表。
- 大文件应分段读取；当
hasMore为true时使用返回的偏移量继续，不要一次请求超出限制。