FolioSpace Library 1.11

FolioSpace Library 1.11 · MCP 1.04

Library 1.11 adds the APIs for library lookup, stored diagnostics, and a
preview-and-confirm workflow for single-video metadata. Standalone MCP 1.04 adds
nine tools, bringing its total to 71 while retaining the previous 62 tools and
their response envelopes. Existing reader, game, video and MCP features remain
available. 1.10 release history.

Capabilities and compatibility

Check the boolean capabilities from GET /api/client/info before using a new
workflow; do not infer support from version strings or successful MCP discovery.

Capability	New MCP tools
catalogSearchV1	foliospace.list_books, foliospace.browse_comics, foliospace.search_library
storedDiagnosticsV1	foliospace.diagnose_book, foliospace.diagnose_game
videoMetadataWorkflowV1	foliospace.search_video_metadata, foliospace.get_video_metadata_job, foliospace.preview_video_metadata, foliospace.apply_video_metadata

Official Library 1.10 does not contain these routes or capabilities, and MCP
1.03.1 does not contain these nine tools. Update both packages for the new
workflows. On an older server, the new tools return capability-unsupported
without a potentially mutating fallback. Existing tools remain compatible.

Lookup and pagination

• Book listing and cross-media search apply SQL filters and counts before
  pagination. Results expose shared catalog metadata, without profile notes,
  favorites or reading/playback state.
• Book listing includes comics and uses offset pagination ordered by title and
  ID ascending, or creation time and ID descending. Restart pagination after
  catalog changes.
• Comic navigation returns paged folders and collections, with validated relative
  paths. It builds and pages navigation nodes after SQL collection aggregation;
  its totals count navigation entries, not individual books.
• Cross-media search uses keyset pagination ordered by book, game, video, then
  ID; it is not relevance ranking. The first page captures maximum IDs, so later
  inserts are excluded and deletions are skipped. Metadata edits can still change
  matches and result fields: this is not an immutable snapshot. total is
  recomputed within those ID bounds. Continue with the same query, format and
  profile context, and restart without a cursor to refresh.
• (assetType, id) identifies a result. Comics appear in the book namespace;
  games can include dependency records; videos are physical file/version records,
  not unique films or series.

Page sizes are bounded to 1–100, with a default of 20. Profiles select state
context within the shared instance; they are not separate authentication or
access-control boundaries. See the full workflow contract.

Stored diagnostics

Book and game diagnostics read recorded evidence only. Responses explicitly say
source: "stored" and filesystemVerified: false. They do not open media,
validate archives, scan, generate checksums or thumbnails, repair files, or
contact providers. Missing evidence remains unknown; absence of a recorded error
does not prove a file is healthy. A stored ready launch profile does not prove
current device/runtime compatibility. Responses use status codes and counts,
without raw filesystem paths or diagnostic messages.

Single-video metadata

The new workflow supports TMDB candidates for one movie file or one explicitly
selected series episode. It uses the operator's configured provider and token;
no shared TMDB credential, bulk matching, media download, artwork download or
provider configuration tool is included.

1. Search sends the explicitly supplied query to TMDB through a provider job.
   It writes job/state records and never applies a match automatically.
2. Read the job to inspect stored status and candidates without cache purging.
3. Preview shows current/proposed values, field changes and locked manual
   overrides. It changes no persisted media data, but creates a non-idempotent
   in-memory receipt valid for ten minutes; restart invalidates it.
4. Apply requires the exact receipt and confirm: true after the user has
   reviewed the preview and explicitly confirmed it. The server revalidates the
   job and current metadata transactionally. A matched confirmation attempt
   consumes the receipt; obtain a fresh preview after failure or changed data.

Apply writes shared metadata and can replace the target file's association; it
is not idempotent. Manual overrides, including intentionally cleared titles and
years, are preserved. Existing shared work metadata and private playback records
remain unchanged, and unsafe changes to sibling display metadata or shared
episode representatives are rejected. Reassociation can change computed playback
identity; review playbackIdentityMayChange in the preview.

All four workflow tools require an explicit valid profile context. Their HTTP
routes require a configured API/admin token and a valid Bearer header, even if
other catalog reads are allowed without authentication. Metadata remains shared
across the library. Search only when the user requests an external lookup; a tool
schema or candidate alone does not establish confirmation to apply.

TMDB remains optional and requires your own token and compliance with its terms
and attribution requirements. See setup and licensing ·
中文.

Upgrade

docker pull funland/foliospace-library:1.11

The Docker release targets Linux AMD64 and ARM64. The Compose default is pinned
to 1.11; pin versions for repeatable deployments. Separately update the MCP
binary to 1.04 on the machine running your agent client and reload that client's
MCP connection. MCP installation and usage.

These workflows reuse the existing database schema and introduce no new DDL.
This does not disable ordinary startup processing or migrations needed by older
installations. Normal startup can process existing background jobs and update
stored state; metadata search and confirmed application also write state.

Back up persistent /config and choose an idle maintenance window before
deliberately replacing your container. Preserve its token, media mounts,
environment and profile data, including
FOLIOSPACE_PRESERVE_GAME_CATALOG_ON_START=1 if already configured. Retain the
previous image and a consistent backup; do not restore an older database over
newer user progress without reconciliation. After upgrading, verify
/api/client/info and normal reading/game/video operations.

Publishing or pulling an image does not automatically replace an existing
container. This release does not publish native App Store clients or include
personal media, database snapshots or access tokens.

简体中文

Library 1.11 为资料库检索、已存储诊断和单视频元数据工作流提供新 API；独立 MCP
1.04 新增 9 个工具，总计 71 个，保留此前 62 个工具及其响应格式。阅读、游戏、
视频和既有 MCP 功能继续兼容。1.10 历史说明 保留。

请通过 GET /api/client/info 检查 catalogSearchV1、storedDiagnosticsV1 和
videoMetadataWorkflowV1 三项能力。官方 Library 1.10 没有这些新接口，MCP 1.03.1
没有这 9 个新工具；使用新工作流需同时升级两者。旧服务器会收到明确的
capability-unsupported，不会回退执行可能写入的操作；仅发现工具不代表服务器支持。

检索和诊断

书目列表与跨媒体检索在 SQL 中先筛选、计数再分页。书目包含漫画，按标题/ID 升序或
创建时间/ID 降序进行 offset 分页；目录变更后应重新开始。漫画浏览先聚合目录再构建、
筛选和分页导航节点，返回文件夹与合集，数量不等于书籍数量。

跨媒体检索按“书籍、游戏、视频，再按 ID”排序，使用 keyset 游标，不是相关度排名。
首请求记录各表最大 ID，后续新增条目不进入本次遍历，删除项被跳过；元数据修改仍可能
改变匹配结果，不能当作不可变快照。total 是该 ID 边界内重新计算的匹配数量。续页需
保持查询、格式和 profile 一致；去掉游标重新检索可刷新结果。条目由 (assetType, id)
联合标识；游戏可能包含依赖记录，视频结果对应实体文件/版本。每页默认 20，允许 1–100。
结果只含共享目录信息，不含私人笔记、收藏和阅读/播放状态。profile 是状态分区，
不是独立身份认证或权限边界。

书籍/游戏诊断只读取已存储证据，并返回 source: "stored"、
filesystemVerified: false。不打开媒体、不检查压缩包、不扫描、计算校验值、生成
缩略图、修复或访问提供商；无错误记录不等于文件健康，已存储的 ready 状态也不保证
当前设备能运行。返回状态码和数量，不返回原始文件路径或诊断消息。

视频候选、预览与确认应用

工作流仅面向单个电影文件或明确选择的一集剧集，使用部署者配置的 TMDB。检索会创建
任务并向提供商发送用户明确给出的查询，不会自动应用候选；读取任务是只读操作。
预览展示当前值、拟修改值及锁定的手动覆盖，不写入持久媒体数据，但生成有效期十分钟
的内存回执，服务重启后失效，因此预览不是幂等操作。

展示完整预览并取得用户明确确认后，才可携带有效回执和 confirm: true 应用。服务器
在事务中复核任务及当前元数据；匹配的确认尝试会消耗回执，失败或数据变化后需重新预览。
应用会写入共享元数据、可能替换目标文件关联，不是幂等操作。保留手动覆盖，包括有意
清空的标题和年份；不覆盖既有共享作品元数据或私人播放记录，并拒绝影响其他关联文件
显示或共享剧集代表文件的不安全变更。重新关联仍可能改变计算出的播放身份，请查看
预览中的 playbackIdentityMayChange。

四个视频工具均要求明确且有效的 profile；对应 HTTP 路由要求已配置 API/admin token
及有效 Bearer header，即使其他目录查询允许匿名访问。元数据仍属于共享资料库。
仅在用户要求时发起外部检索，不以候选存在或工具参数代替用户确认。本次不增加整库
匹配、媒体/封面下载或提供商配置工具；TMDB 需自备令牌并遵守许可及署名要求。

升级注意事项

镜像为 funland/foliospace-library:1.11，面向 Linux AMD64/ARM64；Compose 默认固定
为 1.11。另行把 Agent 所在机器的 MCP 二进制更新至 1.04，并重新加载客户端 MCP 连接。

新增工作流复用现有数据库结构，没有新 DDL；这不代表关闭旧版本所需迁移或既有启动
任务。正常启动可能处理既有后台任务并更新状态，元数据检索和确认应用也会写入状态。
请常规备份持久 /config，选择空闲维护窗口，保留 token、媒体挂载、环境、profile
及已配置的 FOLIOSPACE_PRESERVE_GAME_CATALOG_ON_START=1。保留旧镜像与一致性备份，
不要直接用旧数据库覆盖新产生的进度。升级后检查 /api/client/info 和常用阅读、游戏、
视频操作。发布或拉取镜像不会自动替换用户容器，也不代表 App Store 客户端更新。