mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-11-19 10:22:56 +08:00
1301 lines
86 KiB
Python
1301 lines
86 KiB
Python
"""从业务 OpenAPI 构建 moviepilot_api 的外部 MCP 输入合同。"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import re
|
||
from copy import deepcopy
|
||
from typing import Any, Mapping, Sequence
|
||
|
||
OPERATION_DESCRIPTIONS = {
|
||
"config.identifiers.get": "Read the complete custom media-recognition identifier list.",
|
||
"config.identifiers.update": "Replace the complete custom media-recognition identifier list.",
|
||
"config.system.list": "List compact machine-readable contracts for registered system settings.",
|
||
"config.system.describe": "Read one exact system setting contract, current value, and revision.",
|
||
"config.system.get": "Discover registered system settings or read one exact setting.",
|
||
"config.system.update": "Update one exact registered system setting.",
|
||
"download.add": "Submit one torrent to MoviePilot's normal download workflow.",
|
||
"download.artist_collection": "Submit one artist-wide music torrent to MoviePilot's collection download workflow.",
|
||
"download.clients": "List enabled downloader instance names and provider types without credentials.",
|
||
"download.history.list": "Page MoviePilot download-history records in reverse chronological order.",
|
||
"download.history.delete": "Delete one MoviePilot download-history record.",
|
||
"download.paths": "List configured downloader save-path URIs that may be passed to download.add.",
|
||
"download.tasks.active": "List currently downloading MoviePilot tasks with their canonical media context.",
|
||
"filter.builtin": "List built-in torrent filter rules.",
|
||
"filter.custom": "List user-defined torrent filter rules.",
|
||
"filter.custom.add": "Create one user-defined torrent filter rule.",
|
||
"filter.custom.delete": "Delete one user-defined torrent filter rule.",
|
||
"filter.custom.update": "Update one user-defined torrent filter rule.",
|
||
"filter.group.add": "Create one named filter-rule group.",
|
||
"filter.group.delete": "Delete one named filter-rule group.",
|
||
"filter.group.update": "Update or rename one named filter-rule group.",
|
||
"filter.groups": "List named filter-rule groups.",
|
||
"library.exists": "Check configured media servers for one canonical media identity.",
|
||
"library.latest": "List recently added items from one configured media-server instance for the current user.",
|
||
"media.detail": "Read canonical media details from one selected metadata source.",
|
||
"media.cache.get": "Inspect the administrator-only TMDB recognition cache and summary counts.",
|
||
"media.cache.delete": "Delete one administrator-only TMDB recognition-cache entry by exact key.",
|
||
"media.cache.clear": "Clear the complete administrator-only TMDB recognition cache.",
|
||
"media.episode_schedule": "Read TMDB episode release information for one season.",
|
||
"media.person.credits": "Read one person's credits from the selected metadata source.",
|
||
"media.person.search": "Search people and music artists across selected metadata sources.",
|
||
"media.recognize": "Recognize media identity from a title, subtitle, or custom rule context.",
|
||
"media.scrape": "Generate or refresh metadata for one storage item.",
|
||
"media.search": "Search canonical media across selected metadata sources.",
|
||
"music.album.get": "Read one album's details, tracks, releases, and aligned artist names and IDs.",
|
||
"music.album.related": "Browse albums related to one source-native album identity.",
|
||
"music.artist.albums": "Browse one artist's albums, singles, EPs, or another exact release-group type.",
|
||
"music.artist.get": "Read one artist's canonical details from the selected music metadata source.",
|
||
"music.artist.related": "Browse artists related to one source-native artist identity.",
|
||
"music.cache.clear": "Clear the complete administrator-only MusicBrainz recognition cache.",
|
||
"music.cache.delete": "Delete one administrator-only MusicBrainz recognition-cache entry by exact key.",
|
||
"music.cache.get": "Inspect the administrator-only MusicBrainz recognition cache and summary counts.",
|
||
"music.explore": "Browse MusicBrainz charts or fresh releases, or Douban Music tag categories.",
|
||
"music.recognize": "Resolve one recording or album from an exact music source and source-native ID.",
|
||
"plugin.capabilities": "Inspect the runtime capabilities exposed by installed plugins.",
|
||
"plugin.config.get": "Read one loaded plugin's configuration form and its defaults merged with saved values.",
|
||
"plugin.config.update": "Replace one installed plugin's complete configuration and apply it immediately.",
|
||
"plugin.data": "Read a bounded preview of one plugin's persisted data.",
|
||
"plugin.install": "Install or update one plugin from an approved source.",
|
||
"plugin.installed": "List installed plugins and their runtime status.",
|
||
"plugin.market": "List plugins available from configured marketplaces.",
|
||
"plugin.reload": "Reload one installed plugin into the running process.",
|
||
"plugin.source.change": "Switch an installed plugin to one explicitly selected online source revision.",
|
||
"plugin.source.install": "Install an unbound plugin from one explicitly selected online source.",
|
||
"plugin.source.options": "Inspect source candidates and the current immutable source identity before installation or source change.",
|
||
"plugin.uninstall": "Uninstall one plugin and remove it from the installed set.",
|
||
"recommendation.list": "Read personalized media or music recommendations.",
|
||
"scheduler.list": "List registered scheduler jobs and their current state.",
|
||
"scheduler.run": "Run one registered scheduler job immediately.",
|
||
"search.results": "Read the most recent torrent-search context and result set.",
|
||
"search.torrents": "Search torrent sites for one canonical media identity.",
|
||
"site.cookie.update": "Log in to one site and refresh its stored authentication cookie.",
|
||
"site.cookie.set": "Persist a browser-obtained authentication cookie and optional User-Agent for one site without replacing other settings.",
|
||
"site.list": "List configured sites with status/name filters; authentication fields are returned only to a superuser.",
|
||
"site.test": "Test connectivity and authentication for one configured site.",
|
||
"site.update": "Update one configured site's complete settings.",
|
||
"site.userdata": "Read the latest account statistics collected from one site.",
|
||
"slash.list": "List slash commands that the Agent may dispatch.",
|
||
"slash.run": "Execute one complete slash command through MoviePilot messaging.",
|
||
"storage.list": "List files or directories from one configured storage location.",
|
||
"storage.settings": "Read configured directory or storage settings.",
|
||
"subscription.add": "Create one movie, TV, or music subscription.",
|
||
"subscription.delete": "Delete one active subscription.",
|
||
"subscription.history": "List completed or archived subscription records.",
|
||
"subscription.list": "List active subscriptions.",
|
||
"subscription.popular": "List globally popular subscriptions with filters and pagination.",
|
||
"subscription.search": "Run an immediate search for one existing subscription.",
|
||
"subscription.shares": "List shared subscriptions with filters and pagination.",
|
||
"subscription.update": "Update one existing movie, TV, or music subscription.",
|
||
"system.restart": "Restart the running MoviePilot process.",
|
||
"system.update.check": "Check for the latest stable MoviePilot v3 application release and current-platform site resources.",
|
||
"system.update.download": "Start downloading and verifying one selected application or site-resource update in the background.",
|
||
"system.update.install": "Install one selected already downloaded and verified application or site-resource update, then restart MoviePilot.",
|
||
"system.update.status": "Read application and site-resource update checks, downloads, verification, or install state.",
|
||
"system.upgrade.dev": "Update to the current v3 development branch and restart MoviePilot.",
|
||
"system.versions": "List available MoviePilot GitHub releases.",
|
||
"transfer.file": "Run MoviePilot's manual file-transfer and organization workflow.",
|
||
"transfer.history": "List file-transfer history with filters and pagination.",
|
||
"transfer.history.delete": "Delete one transfer-history record and optionally remove files.",
|
||
"workflow.list": "List configured workflows and their execution state.",
|
||
"workflow.run": "Run one configured workflow from the beginning or resume point.",
|
||
"dashboard.cpu": "Read the current host CPU utilization percentage.",
|
||
"dashboard.downloader": "Read aggregate downloader task counts, speeds, and free-space information.",
|
||
"dashboard.media.statistics": "Read aggregate movie, TV, episode, and music library counts.",
|
||
"dashboard.memory": "Read current MoviePilot process and host memory utilization.",
|
||
"dashboard.network": "Read the current host network receive and transmit counters.",
|
||
"dashboard.processes": "List host processes visible to the MoviePilot runtime.",
|
||
"dashboard.storage": "Read local filesystem capacity and free-space information.",
|
||
"dashboard.system": "Read MoviePilot host, runtime, platform, and uptime summary information.",
|
||
"dashboard.transfer.statistics": "Read aggregate file-transfer counts grouped by time period.",
|
||
"database.backups.create": "Create, verify, and atomically publish a managed database backup.",
|
||
"database.backups.delete": "Delete one exact managed database backup artifact.",
|
||
"database.backups.list": "List managed database backup artifacts without exposing host paths.",
|
||
"database.backups.verify": "Verify the integrity of one exact managed database backup artifact.",
|
||
"filter.test": "Test one title and optional subtitle against an exact named filter-rule group.",
|
||
"media.classification.fields": "Read the media-classification field catalog and source capabilities.",
|
||
"media.classification.policy.get": "Read the active automatic media-classification policy.",
|
||
"media.classification.policy.update": "Validate and publish a complete automatic media-classification policy.",
|
||
"media.classification.policy.validate": "Validate an unpublished automatic media-classification policy without saving it.",
|
||
"media.classification.policy.preview": "Preview automatic media classification for selected media or normalized facts.",
|
||
"media.classification.policy.impact": "Estimate how an unpublished media-classification policy changes bounded recent samples.",
|
||
"media.classification.policy.history": "Read the bounded history of published media-classification policies.",
|
||
"media.classification.policy.rollback": "Publish a selected historical media-classification policy as a new revision.",
|
||
"media.episode_group.seasons": "List seasons defined by one exact TMDB episode-group identity.",
|
||
"media.episode_groups": "List alternate TMDB episode groups available for one TV media identity.",
|
||
"media.recognize_file": "Recognize canonical media identity from one exact filename and optional path context.",
|
||
"media.seasons": "List seasons for one exact media identity or a title-and-year fallback.",
|
||
"media.sources": "List metadata sources currently registered for MoviePilot media operations.",
|
||
"plugin.clone": "Create a configurable clone of one installed plugin; leave suffix empty to let the server allocate the next free instance ID, and reusing the suffix of a disabled clone re-enables that clone together with its stored configuration.",
|
||
"plugin.clone.restorable": "List one plugin's disabled clones whose configuration is still stored and can be brought back by creating a clone with the same suffix.",
|
||
"plugin.history": "Read marketplace update notes and history for one plugin.",
|
||
"plugin.market.sync_wiki": "Refresh the configured plugin marketplace repositories from the MoviePilot Wiki.",
|
||
"plugin.rating": "Read the current aggregate rating for one plugin.",
|
||
"plugin.rating.submit": "Submit or replace the current user's rating for one plugin.",
|
||
"plugin.ratings": "Read aggregate ratings for a requested plugin set.",
|
||
"plugin.releases": "List available release versions for one plugin source.",
|
||
"plugin.reset": "Delete one plugin's saved configuration and data, then restore its default runtime state.",
|
||
"plugin.runtime.status": "Read plugin runtime convergence, loading, and failure state.",
|
||
"plugin.statistics": "Read public installation statistics for plugins.",
|
||
"scheduler.progress": "Read current progress for one exact scheduler job.",
|
||
"search.recommend": "Use the configured recommendation model to rank or recommend torrent search results.",
|
||
"search.title": "Search torrent sites directly from a free-form title and optional media filters.",
|
||
"site.add": "Create one configured site with its complete authentication and search settings.",
|
||
"site.auth.options": "List site-account authentication providers and their required input definitions.",
|
||
"site.authenticate": "Authenticate a supported site account and persist the resulting site authorization state.",
|
||
"site.category": "List torrent categories supported by one configured site.",
|
||
"site.cookiecloud.sync": "Start a CookieCloud synchronization of configured sites.",
|
||
"site.delete": "Delete one configured site by persistent site ID.",
|
||
"site.mapping": "Read the configured site-domain to site-name mapping.",
|
||
"site.priorities.update": "Replace priorities for the supplied configured site IDs.",
|
||
"site.reset": "Delete all configured sites and start a fresh CookieCloud synchronization.",
|
||
"site.resource": "Browse torrent resources from one configured site with category and keyword filters.",
|
||
"site.rss": "List configured sites selected for RSS subscription processing.",
|
||
"site.searchable": "List active configured sites supporting one exact media type.",
|
||
"site.statistic": "Read account and traffic statistics for one exact configured site domain.",
|
||
"site.statistics": "Read the latest account and traffic statistics for all configured sites.",
|
||
"site.supporting": "List indexer definitions supported by the installed MoviePilot resources.",
|
||
"site.userdata.latest": "Read the latest collected account statistics for every configured site.",
|
||
"site.userdata.refresh": "Refresh and return account statistics for one configured site.",
|
||
"storage.delete": "Delete one exact file or directory from a configured storage provider.",
|
||
"storage.manage": "Run one provider-defined management action against an exact configured storage target.",
|
||
"storage.mkdir": "Create a named child directory below one exact storage directory item.",
|
||
"storage.rename": "Rename one exact storage item, optionally applying media-aware recursive renaming.",
|
||
"subscription.delete_by_media": "Delete accessible subscriptions matching one canonical media identity.",
|
||
"subscription.files": "Read local library and transfer-file coverage for one accessible subscription.",
|
||
"subscription.execution.list": "List recent durable subscription-search batches visible to the current user.",
|
||
"subscription.execution.get": "Read one durable subscription-search batch visible to the current user.",
|
||
"subscription.execution.cancel": "Request cancellation of one durable subscription-search batch before its download side-effect boundary.",
|
||
"subscription.find": "Find one accessible subscription by canonical media identity and optional season.",
|
||
"subscription.follow.add": "Follow one subscription-sharing user by exact share user ID.",
|
||
"subscription.follow.delete": "Stop following one subscription-sharing user by exact share user ID.",
|
||
"subscription.follow.list": "List subscription-sharing user IDs followed by the current user.",
|
||
"subscription.fork": "Create a local subscription from one shared subscription definition.",
|
||
"subscription.get": "Read one accessible subscription by persistent subscription ID.",
|
||
"subscription.history.delete": "Delete one accessible subscription-history record.",
|
||
"subscription.metadata.refresh": "Start a system-wide refresh of subscription TMDB metadata.",
|
||
"subscription.refresh": "Start the configured system-wide subscription refresh job.",
|
||
"subscription.reset": "Reset one accessible subscription so it can be processed again.",
|
||
"subscription.search_all": "Start immediate searches for all subscriptions accessible to the current user.",
|
||
"subscription.share": "Publish one accessible subscription to the MoviePilot sharing service.",
|
||
"subscription.share.delete": "Delete one shared-subscription publication by share ID.",
|
||
"subscription.share.statistics": "Read aggregate contribution and reuse counts for subscription sharers.",
|
||
"subscription.status.update": "Set one accessible subscription to running, paused, or stopped state.",
|
||
"subscription.user.list": "List public subscriptions owned by one accessible MoviePilot username.",
|
||
"subtitle.search.media": "Search subtitle providers for one canonical media identity and optional season or episode.",
|
||
"subtitle.search.title": "Search subtitle providers from a free-form title and optional media filters.",
|
||
"system.module.list": "List enabled MoviePilot module IDs and localized names.",
|
||
"system.module.catalog": "List MoviePilot host modules and service-type options for UI selectors.",
|
||
"system.module.settings": "List built-in MoviePilot modules that can be enabled or disabled by an administrator.",
|
||
"system.module.test": "Run the built-in availability test for one enabled MoviePilot module.",
|
||
"system.network.targets": "List approved network-test targets with sanitized destination addresses, without exposing request paths, query parameters, or credentials.",
|
||
"system.network.test": "Test connectivity to one approved target or the legacy constrained URL input.",
|
||
"torrent.cache.clear": "Delete every cached torrent context.",
|
||
"torrent.cache.delete": "Delete one cached torrent context by site domain and cache hash.",
|
||
"torrent.cache.get": "Inspect cached torrent contexts and their recognized media identities.",
|
||
"torrent.cache.refresh": "Refresh torrent caches from configured RSS or spider sources.",
|
||
"torrent.cache.reidentify": "Replace or recompute the media identity for one cached torrent context.",
|
||
"transfer.episode_format.recommend": "Recommend an episode-number extraction template from supplied file samples.",
|
||
"transfer.history.clear": "Delete legacy transfer-history records while leaving files and durable failed-task records untouched.",
|
||
"transfer.history.redo": "Start AI-assisted reorganization for one transfer-history record.",
|
||
"transfer.history.redo_batch": "Start AI-assisted reorganization for an explicit list of transfer-history records.",
|
||
"transfer.manual_history": "Check whether supplied storage items already have successful transfer history.",
|
||
"transfer.manual_review": "Read one durable transfer task awaiting manual review.",
|
||
"transfer.manual_review.resolve": "Record the authorized decision for one durable transfer manual-review operation.",
|
||
"transfer.manual_reviews": "Page durable transfer tasks awaiting manual review or retry recovery.",
|
||
"transfer.name": "Preview the organized destination name for one source path and media identity.",
|
||
"transfer.queue": "List items waiting in the file-transfer queue.",
|
||
"transfer.queue.delete": "Remove one exact storage item from the file-transfer queue and stop its transfer.",
|
||
"transfer.target_path": "Resolve the configured transfer destination for supplied source storage items.",
|
||
"workflow.actions": "List built-in workflow action definitions and their parameter contracts.",
|
||
"workflow.create": "Create one workflow from a complete workflow definition.",
|
||
"workflow.delete": "Delete one configured workflow by persistent workflow ID.",
|
||
"workflow.event_types": "List event types that can trigger workflows.",
|
||
"workflow.fork": "Create a local workflow from one shared workflow definition.",
|
||
"workflow.get": "Read one complete configured workflow definition.",
|
||
"workflow.pause": "Disable automatic execution of one configured workflow.",
|
||
"workflow.plugin.actions": "List workflow actions contributed by installed plugins, optionally filtered by plugin ID.",
|
||
"workflow.reset": "Reset one configured workflow definition and execution state.",
|
||
"workflow.share": "Publish one configured workflow to the MoviePilot sharing service.",
|
||
"workflow.share.delete": "Delete one shared-workflow publication by share ID.",
|
||
"workflow.shares": "List shared workflows with name and pagination filters.",
|
||
"workflow.start": "Enable automatic execution of one configured workflow.",
|
||
"workflow.update": "Replace one configured workflow definition.",
|
||
"config.user.get": "Read current-user feature flags, runtime capabilities, and effective permissions.",
|
||
"config.public.get": "Read one explicitly public system setting by exact key.",
|
||
"system.usage.statistics": "Read the installation version and runtime usage report available to the current user.",
|
||
"plugin.folders.get": "Read the complete administrator plugin-folder grouping configuration.",
|
||
"plugin.folders.update": "Replace the complete administrator plugin-folder grouping configuration.",
|
||
"plugin.folder.create": "Create one named plugin folder.",
|
||
"plugin.folder.update": "Incrementally rename one plugin folder or update its presentation settings.",
|
||
"plugin.folder.delete": "Delete one named plugin folder without uninstalling its plugins.",
|
||
"plugin.folder.plugins.update": "Replace the ordered plugin IDs assigned to one named plugin folder.",
|
||
"plugin.folder.plugin.assign": "Move one installed plugin into one named folder and remove its other folder assignments.",
|
||
"plugin.folder.plugin.remove": "Remove one installed plugin from one named folder without uninstalling it.",
|
||
"plugin.loglevel.get": "List one plugin's instances, including the plugin itself, with each instance's configured and effective log level.",
|
||
"plugin.loglevel.set": "Set one plugin instance's log-level override, taking effect immediately without following the global log level.",
|
||
"plugin.loglevel.clear": "Clear one plugin instance's log-level override so it immediately follows the global log level again.",
|
||
"plugin.default_target.set": "Set one plugin instance as the plugin's default call target, automatically clearing any previous default.",
|
||
"plugin.default_target.clear": "Clear one plugin instance's default-call-target flag, only if it is the plugin's current default.",
|
||
"plugin.instance.set_enabled": "Enable or disable one plugin instance, host or clone; disabling only stops it running and keeps its configuration for a later re-enable.",
|
||
"plugin.instance.purge": "Permanently delete one plugin instance's selected data: saved configuration, plugin data rows, its own database and its data directory; a clone also loses its instance record. Nothing is deleted unless explicitly selected.",
|
||
}
|
||
|
||
|
||
FIELD_DESCRIPTIONS = {
|
||
"action_name": "Exact action name whose capability contract should be returned.",
|
||
"allow_unrecognized": "Allow a download when MoviePilot cannot resolve a canonical media identity.",
|
||
"album": "Album title associated with a music recording or subscription.",
|
||
"album_id": "Source-native album ID returned by music search, exploration, or artist-album browsing.",
|
||
"album_type": "MusicBrainz release-group type filter: album, single, ep, broadcast, other, compilation, soundtrack, live, or remix.",
|
||
"apikey": "Site API key used by sites that support API-key authentication.",
|
||
"area": "Optional region filter applied by the torrent search workflow.",
|
||
"artist_id": "Source-native artist ID returned by music search or an album detail response.",
|
||
"artist_name": "Artist name preserved as the identity label for an artist-wide music collection.",
|
||
"audio_format": "Requested or recorded audio container or codec, such as FLAC or MP3.",
|
||
"audio_lossless": "Whether the recorded audio result is lossless.",
|
||
"audio_quality": "Subscription audio-quality rule, such as hires, lossless, or lossy.",
|
||
"backdrop": "Backdrop image URL stored with the media or subscription.",
|
||
"background": "Run the transfer asynchronously and return before completion.",
|
||
"batch_id": "Stable subscription search batch identifier.",
|
||
"basename": "Base filename without its parent path.",
|
||
"best_version": "Enable normal best-version upgrading when set to 1.",
|
||
"best_version_full": "Enable full best-version upgrading when set to 1.",
|
||
"bit_depth": "Recorded audio bit depth in bits.",
|
||
"bitrate": "Recorded audio bitrate in bits per second.",
|
||
"body": (
|
||
"Request value for the selected operation. Match the exact operation oneOf branch; "
|
||
"scalar and object request bodies are not interchangeable."
|
||
),
|
||
"category": "MoviePilot media category or filter-group category, depending on the operation.",
|
||
"cache_key": "Exact recognition-cache key returned by the corresponding recognition-cache get operation.",
|
||
"channel": "Message channel that originally submitted the download.",
|
||
"children": "Child storage items nested below this item.",
|
||
"code": "Two-factor verification code or site-specific authentication secret.",
|
||
"command": "Complete slash command, including the leading slash and all arguments.",
|
||
"completed_episode": "Highest episode number already completed for the subscription.",
|
||
"completed_tracks": "Number of distinct album tracks accepted for the subscription so far.",
|
||
"current_site_id": "Configured site ID currently handling the subscription execution.",
|
||
"cookie": "Site authentication cookie. Treat this value as a secret.",
|
||
"configured_level": "Plugin instance's own configured log-level override, null when unset or expired.",
|
||
"count": "Maximum number of records to return on the requested page.",
|
||
"current_audio_format": "Audio format of the best version currently held.",
|
||
"current_bit_depth": "Bit depth of the best version currently held.",
|
||
"current_bitrate": "Bitrate of the best version currently held.",
|
||
"current_priority": "Calculated priority of the best version currently held.",
|
||
"current_sample_rate": "Sample rate of the best version currently held.",
|
||
"custom_words": "Custom recognition or rename words applied to this media workflow.",
|
||
"classification_policy_revision": "Policy revision that produced the persisted classification snapshot.",
|
||
"classification_rule_id": "Stable rule ID that selected the persisted classification category.",
|
||
"classification_source": "Selection source recorded with the persisted classification snapshot.",
|
||
"date": "Record creation or completion timestamp used by the history item.",
|
||
"date_elapsed": "Human-readable age of the torrent publication date.",
|
||
"days": "Recommendation time window in days.",
|
||
"deletedest": "Also delete the organized destination files when deleting transfer history.",
|
||
"deletesrc": "Also delete the recorded source files when deleting transfer history.",
|
||
"description": "Human-readable media, torrent, or subscription description.",
|
||
"dest": "Organized destination path recorded in transfer history.",
|
||
"dest_fileitem": "Serialized destination storage item recorded by the transfer.",
|
||
"dest_storage": "Configured storage name containing the organized destination.",
|
||
"directory_type": "Directory configuration subtype to return.",
|
||
"domain": "Site hostname or domain used for matching and requests.",
|
||
"download_hash": "Provider-native torrent hash associated with the record.",
|
||
"downloader": "Configured downloader instance name.",
|
||
"downloadvolumefactor": "Torrent download-volume multiplier reported by the site.",
|
||
"douban_sort": "Douban Music category order: U for comprehensive, S for rating, R for newest, or O for hottest.",
|
||
"drive_id": "Provider-native storage drive identifier.",
|
||
"effect": "Video or release-effect filter expression used by the subscription.",
|
||
"effective_level": "Plugin instance's actual log level after resolving its override and expiry against the global log level.",
|
||
"error": "Human-readable workflow, provider, or execution error message.",
|
||
"entity": "Music exploration entity: recording for tracks or album for release groups.",
|
||
"enclosure": "Torrent download URL or enclosure supplied by the indexer result.",
|
||
"episode_detail": "Episode mapping details used by manual transfer.",
|
||
"episode_format": "Episode-number formatting rule used by manual transfer.",
|
||
"episode_group": "TMDB episode-group identifier used for alternate episode ordering.",
|
||
"episode_offset": "Integer offset added to detected episode numbers.",
|
||
"episode_part": "Episode part number used when one episode is split across files.",
|
||
"episode_priority": "Per-episode best-version priority state.",
|
||
"episodes": "Episode-number expression recorded in history, such as E01-E03.",
|
||
"errmsg": "Error message recorded for a failed transfer.",
|
||
"expected_revision": "Current revision from a preceding read, used to reject concurrent state changes.",
|
||
"expires_at": "Expiry timestamp for a plugin instance's log-level override; null means it never expires. A timestamp without a timezone is read as UTC.",
|
||
"exclude": "Regular expression or filter expression that rejects matching releases.",
|
||
"extension": "Filename extension, including or excluding the leading dot as returned by storage.",
|
||
"fileid": "Provider-native storage item identifier.",
|
||
"fileitem": "One complete source storage item returned by storage.list.",
|
||
"fileitems": "Additional source storage items included in the same manual transfer.",
|
||
"files": "Serialized list of files recorded by the history item.",
|
||
"filter": "Named filter rule or rule expression applied to this site or subscription.",
|
||
"filter_groups": "Ordered filter-rule group names applied to the subscription.",
|
||
"force": "Force a marketplace refresh or plugin installation when true.",
|
||
"freedate": "Torrent freeleech expiration timestamp reported by the site.",
|
||
"freedate_diff": "Seconds remaining until the torrent freeleech period ends.",
|
||
"fresh_sort": "Freshness ordering used by the recommendation source.",
|
||
"from_begin": "Restart the workflow from its first action instead of resuming progress.",
|
||
"from_history": "Treat the transfer input as originating from an existing history record.",
|
||
"future": "Include future recommendation periods when supported.",
|
||
"genre_id": "Genre identifier used to filter shared or popular subscriptions.",
|
||
"grabs": "Number of completed downloads reported for the torrent.",
|
||
"group": "Registered setting group used for dynamic setting discovery.",
|
||
"hit_and_run": "Whether the torrent is subject to hit-and-run requirements.",
|
||
"id": "Persistent database identifier of the supplied record.",
|
||
"identifiers": "Complete ordered list of custom recognition identifier rules.",
|
||
"image": "Image URL stored with the history record.",
|
||
"include": "Regular expression or filter expression that a release must match.",
|
||
"include_group_refs": "Include custom rules referenced only through rule groups.",
|
||
"include_usage": "Include the subscriptions or defaults that reference each rule group.",
|
||
"include_values": "Return complete setting values instead of discovery summaries.",
|
||
"instance_id": "Exact plugin instance ID returned by plugin.loglevel.get.",
|
||
"config": "Purge scope flag: delete this plugin instance's saved configuration values.",
|
||
"plugin_data": "Purge scope flag: delete this plugin instance's rows in the shared plugin data table.",
|
||
"own_database": "Purge scope flag: destroy this plugin instance's own database.",
|
||
"data_directory": "Purge scope flag: delete this plugin instance's entire data directory; its own database is always destroyed first.",
|
||
"is_default_target": "Whether this plugin instance is the plugin's default call target, used when a caller does not specify an instance.",
|
||
"enabled": "Target enabled state; false stops the instance while keeping its configuration and display information.",
|
||
"is_active": "Whether the configured site is enabled.",
|
||
"jobid": "Exact scheduler job ID returned by scheduler.list.",
|
||
"key": "Optional exact plugin data key used to narrow the returned preview.",
|
||
"keyword": "Case-insensitive substring used to discover settings or filter storage entries.",
|
||
"level": "Target log level, one of DEBUG, INFO, WARNING, ERROR, or CRITICAL.",
|
||
"labels": "Labels attached to the media, classification result, or torrent result.",
|
||
"lack_episode": "Number of episodes still missing from the subscription.",
|
||
"last_update": "Timestamp of the subscription's most recent update.",
|
||
"library_category_folder": "Create or use a category-level folder in the target library.",
|
||
"library_type_folder": "Create or use a media-type folder in the target library.",
|
||
"limit_count": "Maximum number of site requests allowed in one rate-limit interval.",
|
||
"limit_interval": "Number of requests in the site's rate-limit window.",
|
||
"limit_seconds": "Site rate-limit window length in seconds.",
|
||
"limit": "Maximum number of recent subscription-search batches to return.",
|
||
"logid": "One download-history or transfer-log identifier used by manual transfer.",
|
||
"logids": "Multiple download-history or transfer-log identifiers included in manual transfer.",
|
||
"match_field": "Object field used to match one list item during an upsert or removal.",
|
||
"match_value": "Exact value compared against match_field during a list-item update.",
|
||
"max_chars": "Maximum number of serialized plugin-data characters to return.",
|
||
"max_results": "Optional upper bound on plugin catalog results, from 1 to 200; omit it for the complete catalog.",
|
||
"max_rating": "Maximum rating used to filter shared or popular subscriptions.",
|
||
"media_category": "MoviePilot library category assigned to the media.",
|
||
"media_category_id": "Stable classification category ID; preserve it separately from the current category path snapshot.",
|
||
"media_id": "Source-native media ID. Always pair it with the exact media_source returned by search.",
|
||
"media_source": "Metadata source identifier. Preserve the exact value returned with media_id.",
|
||
"media_type": "MoviePilot media type used to filter recommendations or rule groups.",
|
||
"min_bit_depth": "Minimum acceptable audio bit depth in bits.",
|
||
"min_bitrate": "Minimum acceptable audio bitrate in bits per second.",
|
||
"min_filesize": "Minimum source file size accepted by manual transfer, in bytes.",
|
||
"min_listen_count": "Minimum listen count required for a music recommendation.",
|
||
"min_rating": "Minimum rating used to filter shared or popular subscriptions.",
|
||
"min_sample_rate": "Minimum acceptable audio sample rate in hertz.",
|
||
"min_sub": "Minimum subscriber count used to filter popular subscriptions.",
|
||
"mode": "Operation mode; music.explore accepts chart or fresh, while transfer history records move, copy, link, or softlink.",
|
||
"modify_time": "Storage item modification timestamp.",
|
||
"mtype": "MoviePilot media type or subscription-history category required by the operation.",
|
||
"music_type": "Music identity level: recording, album, or artist where supported.",
|
||
"include_candidates": "Include unconfirmed music resources and related albums for manual review. Defaults to false; candidates have no target media identity and must not be used for automatic download.",
|
||
"name": "Human-readable name of the site, storage item, subscription, or rule group.",
|
||
"new_name": "Replacement name for the existing filter-rule group.",
|
||
"new_rule_id": "Replacement stable ID for the existing custom filter rule.",
|
||
"next_run_at": "Next scheduled subscription search time. Null when no future execution is planned.",
|
||
"note": "Structured auxiliary metadata stored with the record.",
|
||
"operation": "Setting update mode: replace, merge_dict, upsert_list_item, or remove_list_item.",
|
||
"operation_id": "Exact allowlisted MoviePilot operation ID selecting this oneOf branch.",
|
||
"page": "One-based result page number.",
|
||
"page_url": "Public details page for the torrent result.",
|
||
"parent_fileid": "Provider-native identifier of the parent storage directory.",
|
||
"password": "Site login password. Treat this value as a secret.",
|
||
"past": "Include past recommendation periods when supported.",
|
||
"path": "Storage or history path represented by this record.",
|
||
"path_params": (
|
||
"Resource identities inserted only into the selected operation's fixed route placeholders. "
|
||
"Use the exact names and types in its oneOf branch."
|
||
),
|
||
"peers": "Number of downloading peers reported for the torrent.",
|
||
"person_id": "Source-native person ID returned by person search.",
|
||
"pickcode": "115 storage pickcode associated with the item.",
|
||
"plugin_id": "Exact installed or marketplace plugin ID.",
|
||
"poster": "Poster image URL stored with the media or subscription.",
|
||
"preview": "Validate and preview manual-transfer output without committing file changes.",
|
||
"pri": "Site search priority; lower or higher ordering follows the existing site API convention.",
|
||
"pri_order": "Indexer priority order assigned to the torrent result.",
|
||
"proxy": "Whether the site uses MoviePilot's configured proxy.",
|
||
"public": "Whether the site is treated as a public indexer.",
|
||
"pubdate": "Torrent publication timestamp.",
|
||
"publish_time": "Release-age filter expression for a custom filter rule.",
|
||
"quality": "Video or release quality filter expression.",
|
||
"query": (
|
||
"Filters and control values sent in the query string. Use the exact names, types, "
|
||
"defaults, and enums in the selected operation's oneOf branch."
|
||
),
|
||
"range_name": "Named recommendation time range.",
|
||
"release_version": "Exact plugin release version to install when one is required.",
|
||
"remove_keys": "Object keys removed after merge_dict applies its supplied value.",
|
||
"render": "Whether site requests require browser rendering.",
|
||
"reorganize": "Allow manual transfer to organize an item that was already processed.",
|
||
"repo_url": "Approved plugin repository URL used to resolve the installation source.",
|
||
"resolution": "Video resolution filter expression, such as 1080p or 2160p.",
|
||
"rss": "Site RSS feed URL.",
|
||
"rule_id": "Stable custom filter-rule ID.",
|
||
"rule_string": "Ordered filter-rule expression stored in the group.",
|
||
"sample_rate": "Recorded audio sample rate in hertz.",
|
||
"save_path": "Configured downloader-side save path for the download or subscription.",
|
||
"scrape": "Generate metadata and images after manual transfer.",
|
||
"search_interval": "Scheduled search interval in whole hours (1-8760); null uses the system interval.",
|
||
"last_search": "Read-only UTC timestamp of the most recent subscription search attempt.",
|
||
"search_imdbid": "Use IMDb identity during subscription search when set to 1.",
|
||
"season": "Season number used by the media, search, subscription, or transfer operation.",
|
||
"seasons": "Season-number expression recorded in history.",
|
||
"seeders": "Minimum seeder expression for a filter rule, or the torrent's seeder count.",
|
||
"server": "Exact configured media-server instance name returned by the media-server instance list.",
|
||
"setting_key": "Exact registered setting key returned by config.system.get discovery.",
|
||
"show_secrets": "Return unredacted secret values; use only with explicit authorization.",
|
||
"site": "Source site identifier associated with the torrent result.",
|
||
"site_cookie": "Site cookie bundled with the torrent result. Treat this value as a secret.",
|
||
"site_downloader": "Downloader instance selected by the source site.",
|
||
"site_id": "Persistent site ID returned by site.list.",
|
||
"site_name": "Human-readable source site name.",
|
||
"site_order": "Source site's configured search order.",
|
||
"site_proxy": "Whether the torrent's source site uses the configured proxy.",
|
||
"site_ua": "User-Agent associated with the source site.",
|
||
"sites": "Exact site IDs included in the search or subscription scope.",
|
||
"size": "File or torrent size in bytes.",
|
||
"size_range": "Accepted torrent size range expression for a custom filter rule.",
|
||
"sort": "Storage-list sort field or ordering expression.",
|
||
"sort_by": "Recommendation field used for ordering results.",
|
||
"sort_type": "Ascending or descending order used by shared or popular subscriptions.",
|
||
"source": "Exact metadata or recommendation source selected by the operation.",
|
||
"src": "Source path recorded in transfer history.",
|
||
"src_fileitem": "Serialized source storage item recorded by the transfer.",
|
||
"src_storage": "Configured storage name containing the transfer source.",
|
||
"start_episode": "First episode number requested by the subscription.",
|
||
"state": "Current site, subscription, marketplace, or transfer state filter.",
|
||
"status": "Transfer success status used to filter history or describe a record.",
|
||
"storage": "Configured storage name or storage type used by the operation.",
|
||
"storage_type": "Configured storage provider type to return.",
|
||
"stype": "Popular-subscription category requested by the endpoint.",
|
||
"subscribe_id": "Persistent subscription ID returned by subscription.list.",
|
||
"subtitle": "Optional subtitle text used together with title during media recognition.",
|
||
"target_path": "Destination path used by manual transfer.",
|
||
"target_storage": "Configured storage name receiving the manual transfer.",
|
||
"tags": "Comma-separated Douban Music category tags; use only with a Douban Music exploration source.",
|
||
"template": "Pass default to read the built-in media-classification policy template; omit it to read the active policy.",
|
||
"thumbnail": "Thumbnail URL returned by the storage provider.",
|
||
"timeout": "Per-request site timeout in seconds.",
|
||
"title": "Media, torrent, subscription, or history title used by the operation.",
|
||
"tmdbid": "TMDB media ID returned by media search or detail.",
|
||
"token": "Site authentication token. Treat this value as a secret.",
|
||
"torrent_description": "Torrent release description recorded in download history.",
|
||
"torrent_in": "Complete torrent candidate returned by search.results or search.torrents.",
|
||
"torrent_name": "Torrent release name recorded in download history.",
|
||
"torrent_site": "Source site name recorded in download history.",
|
||
"total_episode": "Expected total episode count for the subscription.",
|
||
"total_tracks": "Expected or recorded track count for a music item.",
|
||
"transfer_task_id": "Stable durable transfer-task ID associated with the history record.",
|
||
"transfer_type": "Manual-transfer mode, such as move, copy, link, or softlink.",
|
||
"trigger_type": "Workflow trigger filter: timer, event, manual, or all.",
|
||
"type": "MoviePilot media or storage item type required by the selected operation.",
|
||
"type_name": "Explicit media type name used when source IDs alone are ambiguous.",
|
||
"ua": "Site User-Agent string used for authenticated requests.",
|
||
"uploadvolumefactor": "Torrent upload-volume multiplier reported by the site.",
|
||
"url": "Site, storage, or torrent URL represented by this field.",
|
||
"userid": "Message-channel user ID recorded with download history.",
|
||
"username": "MoviePilot or site username required by the selected operation.",
|
||
"value": "Complete replacement value, object fragment, or one list item for the selected update mode.",
|
||
"volume_factor": "Combined upload/download volume-factor label shown for the torrent.",
|
||
"vote": "Media vote average stored with the subscription.",
|
||
"with_cover": "Require recommendation results to include cover artwork.",
|
||
"workdate": "Date used when retrieving one site's historical user statistics.",
|
||
"workflow_id": "Persistent workflow ID returned by workflow.list.",
|
||
"year": "Release or premiere year used to disambiguate the media title.",
|
||
}
|
||
|
||
FIELD_DESCRIPTIONS.update(
|
||
{
|
||
"all": "Child conditions that must all match.",
|
||
"action": "Exact provider or workflow action identifier required by the selected operation.",
|
||
"actions": "Ordered workflow action definitions executed by this workflow or flow.",
|
||
"add_time": "Timestamp when the workflow definition was created.",
|
||
"animated": "Whether the workflow connection is rendered as animated in the editor.",
|
||
"any": "Child conditions where at least one condition must match.",
|
||
"attempt": "Current execution-attempt number for this workflow node.",
|
||
"attempts": "Attempt counters keyed by workflow node or operation identity.",
|
||
"auto_paused": "Whether a failed transfer automatically paused the related subscription.",
|
||
"backoff": "Retry backoff multiplier applied after each failed workflow action attempt.",
|
||
"branch_policy": "Workflow branch policy controlling selected downstream paths.",
|
||
"cat": "Exact site category identifier returned by site.category.",
|
||
"check_only": "Validate or preview the recommendation without applying search-result filtering.",
|
||
"can_cancel": "Whether the current subscription execution can be cancelled.",
|
||
"categories": "Complete ordered media-category definitions in the classification policy.",
|
||
"category_id": "Stable media-category ID targeted by a classification rule or selection.",
|
||
"companies": "Production companies or studios associated with the media.",
|
||
"concurrency_key": "Workflow expression used to serialize actions sharing the same runtime key.",
|
||
"content_rating": "Content rating assigned to the media.",
|
||
"countries": "Normalized country or region codes used by classification rules.",
|
||
"condition": "Workflow branch or flow condition expression evaluated at runtime.",
|
||
"context": "Persisted workflow execution context available to later actions.",
|
||
"current_action": "Identifier of the workflow action currently selected or executing.",
|
||
"cleanup_error": "Error recorded while cleaning up a transfer source or destination.",
|
||
"cleanup_status": "Current status of transfer-file cleanup after an operation.",
|
||
"data": "Serialized workflow action configuration or runtime payload.",
|
||
"decision": "Manual-review decision selected from the endpoint's declared enum.",
|
||
"episode": "Episode number used to narrow a subtitle or media search.",
|
||
"enrichment_mode": "Metadata enrichment mode used to populate classification facts.",
|
||
"errors": "Workflow execution errors keyed or ordered by action identity.",
|
||
"enabled": "Whether this category or classification rule participates in evaluation.",
|
||
"entity_type": "Music entity type used by classification rules.",
|
||
"example_limit": "Maximum number of representative impact examples to return.",
|
||
"execution_status": "Current subscription execution status returned with the subscription snapshot.",
|
||
"event_conditions": "Additional workflow event-filter conditions.",
|
||
"event_type": "Exact event type returned by workflow.event_types.",
|
||
"execution_config": "Workflow runtime limits, concurrency, and failure-policy configuration.",
|
||
"execution_state": "Persisted resumable workflow execution state.",
|
||
"fail_policy": "Workflow failure policy controlling stop, continue, or branch behavior.",
|
||
"failure_stage": "Transfer or workflow stage at which the operation failed.",
|
||
"fallbacks": "Fallback category or label actions used when no classification rule matches.",
|
||
"facts": "Normalized media facts to evaluate during a classification preview.",
|
||
"field": "Normalized classification fact field referenced by a condition.",
|
||
"field_aliases": "Optional aliases mapping source-specific fields to normalized classification fields.",
|
||
"field_sources": "Source provenance for normalized classification facts.",
|
||
"filetype": "Media file type used to preview the organized destination name.",
|
||
"filtered_indices": "Zero-based search-result indices selected by the recommendation model.",
|
||
"finished_actions": "Workflow action IDs already completed in the persisted execution state.",
|
||
"finished_at": "Timestamp when the workflow node or execution finished.",
|
||
"flows": "Workflow connection definitions linking action nodes.",
|
||
"folder_name": "Exact plugin folder name returned by plugin.folders.get.",
|
||
"extensions": "Additional normalized classification facts supplied by extensions.",
|
||
"genre_keys": "Normalized MoviePilot genre keys used by classification rules.",
|
||
"genre_names": "Source-provided genre names used as classification facts.",
|
||
"genres": "Normalized music genre values used by classification rules.",
|
||
"genre_ids": "Genre identifiers accepted by the automatic category rule.",
|
||
"history_id": "Persistent transfer- or subscription-history ID returned by a history operation.",
|
||
"history_ids": "Explicit persistent transfer-history IDs included in one batch redo request.",
|
||
"icon": "Icon name or URL used by a workflow, network target, plugin, or category.",
|
||
"identity": "Stable source-native media identity used by classification facts.",
|
||
"inputs": "Named input bindings consumed by this workflow action.",
|
||
"interval": "Retry delay in seconds before the next workflow action attempt.",
|
||
"input": "Media or normalized-facts input used for a classification preview.",
|
||
"album_type": "Music album or release-group type used by classification rules.",
|
||
"artist_country": "Country or region associated with the music artist.",
|
||
"artists": "Music artist names associated with the classified entity.",
|
||
"adult": "Whether the media is marked as adult content.",
|
||
"job_id": "Exact scheduler job ID returned by scheduler.list.",
|
||
"join_policy": "Workflow fan-in policy controlling when downstream execution may continue.",
|
||
"language": "Normalized media language code used by classification rules.",
|
||
"last_time": "Timestamp of the workflow's most recent execution.",
|
||
"kind": "Classification rule or preview-input kind selected by the request.",
|
||
"max_attempts": "Maximum number of attempts allowed by the workflow retry policy.",
|
||
"max_workers": "Maximum concurrent workflow actions allowed by the execution configuration.",
|
||
"message": "Human-readable workflow runtime or provider result message.",
|
||
"media": "Media metadata input used for a classification preview.",
|
||
"media_types": "Media types to which a classification rule applies.",
|
||
"moduleid": "Exact loaded module ID returned by system.module.list.",
|
||
"movie": "Automatic movie-category rules evaluated in order.",
|
||
"music": "Music-specific normalized facts used by classification rules.",
|
||
"music_release_regions": "Optional ISO 3166-1 release-region priority for music organization.",
|
||
"music_release_scripts": "Optional ISO 15924 script priority for music organization.",
|
||
"networks": "Television networks or streaming platforms associated with the media.",
|
||
"node_states": "Persisted runtime states keyed by workflow node identity.",
|
||
"nodes": "Persisted workflow node runtime states keyed by action identity.",
|
||
"not": "Child condition group that must not match.",
|
||
"operator": "Comparison operator used to evaluate one classification condition.",
|
||
"origin_country": "Production-country code matched by an automatic category rule.",
|
||
"original_language": "Original-language code matched by an automatic category rule.",
|
||
"outputs": "Named output mappings produced by this workflow action.",
|
||
"page_size": "Maximum records returned on one page.",
|
||
"phase": "Current phase of a subscription execution.",
|
||
"params": "Provider-defined JSON parameters for the selected authentication or storage action.",
|
||
"policy": "Complete or draft automatic media-classification policy.",
|
||
"plugin_ids": "Exact plugin IDs whose aggregate ratings should be returned.",
|
||
"position": "Workflow editor coordinates for one action node.",
|
||
"provider_id": "Provider-native identifier that supplied a classification fact.",
|
||
"provider_name": "Human-readable provider name that supplied a classification fact.",
|
||
"production_countries": "Production-country codes matched by an automatic category rule.",
|
||
"priority": "Classification rule ordering priority persisted by the server.",
|
||
"progress": "Current numeric or structured workflow execution progress.",
|
||
"rating": "Numeric plugin rating accepted by the endpoint's declared bounds.",
|
||
"reason": "Human-readable justification recorded with a manual-review decision.",
|
||
"recursive": "Apply media-aware renaming recursively to child files when true.",
|
||
"recovery_action": "Recovery action reported for a failed or partially completed transfer.",
|
||
"release_year": "Release year matched by an automatic category rule.",
|
||
"result": "Persisted workflow action result value.",
|
||
"revision": "Published classification policy revision or expected revision number.",
|
||
"result_payload": "Structured external-operation result recorded with manual review.",
|
||
"release_status": "Music release status used by classification rules.",
|
||
"rules": "Ordered classification rules evaluated from highest priority to lowest.",
|
||
"restore_previous": "When creating a plugin clone, reuse the stored configuration of a disabled clone that already holds the same suffix; false rebuilds that clone's configuration from the source plugin template.",
|
||
"retry": "Workflow retry-policy definition for this action.",
|
||
"retry_count": "Number of retry attempts already used by the operation.",
|
||
"retry_exhausted": "Whether the operation has used all configured retry attempts.",
|
||
"rulegroup_name": "Exact filter-rule group name returned by filter.groups.",
|
||
"run_count": "Number of times the workflow has been executed.",
|
||
"running_tasks": "Workflow task IDs currently executing.",
|
||
"runtime": "Persisted workflow runtime metadata used for safe resume.",
|
||
"secondary_types": "Secondary music release-group types used by classification rules.",
|
||
"sample_limit": "Maximum number of recent records or samples to inspect for impact analysis.",
|
||
"samples": "Explicit normalized fact samples used for classification impact analysis.",
|
||
"schema_version": "Classification policy schema version expected by the server.",
|
||
"sources": "Metadata source IDs to which a classification rule applies; empty means all sources.",
|
||
"share_comment": "Optional explanatory comment published with a shared item.",
|
||
"share_id": "Persistent MoviePilot Server share ID returned by a share-list operation.",
|
||
"share_title": "Public title used when publishing a subscription or workflow.",
|
||
"share_uid": "Exact MoviePilot Server sharing-user ID to follow or unfollow.",
|
||
"share_user": "Public contributor name used when publishing a subscription or workflow.",
|
||
"skip_success": "Skip files already recorded as successfully organized.",
|
||
"site_url": "Configured site URL or hostname used to select one site's statistics.",
|
||
"updated_at": "Timestamp when the persisted object or execution state was last updated.",
|
||
"started_at": "Timestamp when the workflow node or execution started.",
|
||
"subid": "Persistent subscription ID whose status or processing state will change.",
|
||
"suffix": "File suffix or extension matched by an automatic category rule.",
|
||
"target": "Classification rule output containing a category ID and optional labels.",
|
||
"target_id": "Approved built-in network-test target ID returned by system.network.targets.",
|
||
"task_id": "Stable durable transfer task ID returned by transfer.manual_reviews.",
|
||
"timer": "Workflow timer or cron expression used for scheduled execution.",
|
||
"torrent_hash": "Cache hash returned by torrent.cache.get for one exact site-domain entry.",
|
||
"tv": "Automatic TV-category rules evaluated in order.",
|
||
"version": "Plugin release or schema version selected by the operation.",
|
||
"wiki_url": "Approved MoviePilot Wiki URL used as the plugin-market synchronization source.",
|
||
"when": "Condition group evaluated before a classification rule target is applied.",
|
||
"x": "Horizontal workflow editor coordinate.",
|
||
"y": "Vertical workflow editor coordinate.",
|
||
}
|
||
)
|
||
|
||
|
||
MODEL_DESCRIPTIONS = {
|
||
"AgentCommandRunRequest": "Slash-command execution request.",
|
||
"Body_add_api_v1_download_add_post": "MoviePilot download submission request.",
|
||
"Body_download_artist_collection_api_v1_download_artist_collection_post": (
|
||
"Artist-wide music collection download submission request."
|
||
),
|
||
"CustomFilterRuleCreateRequest": "Custom filter-rule creation request.",
|
||
"CustomFilterRuleUpdateRequest": "Custom filter-rule update request.",
|
||
"CustomIdentifiersUpdateRequest": "Complete custom recognition-identifier replacement request.",
|
||
"DownloadHistory-Input": "One MoviePilot download-history record.",
|
||
"FileItem-Input": "One file or directory returned by a configured storage provider.",
|
||
"FilterRuleGroupCreateRequest": "Filter-rule group creation request.",
|
||
"FilterRuleGroupUpdateRequest": "Filter-rule group update request.",
|
||
"JsonData-Input": "Arbitrary JSON-compatible auxiliary data.",
|
||
"ManualTransferItem": "Manual file-transfer and organization request.",
|
||
"MediaSource": "Canonical metadata source identifier paired with a source-native media ID.",
|
||
"MediaType": "MoviePilot media type.",
|
||
"MusicRecognizeRequest": "Exact source-native recording or album identity to resolve into canonical music metadata.",
|
||
"PluginInstanceEnabledRequest": "One plugin instance's enable-or-disable request; disabling keeps its configuration for a later re-enable.",
|
||
"PluginInstanceLogLevelUpdateRequest": "One plugin instance's log-level override update request.",
|
||
"PluginInstancePurgeRequest": "One plugin instance's purge scope; every listed item is deleted only when explicitly selected.",
|
||
"PluginSourceChangeRequest": "Explicit online-source change request guarded by the current identity revision.",
|
||
"PluginSourceInstallRequest": "Explicit online-source installation request for an unbound plugin.",
|
||
"Site-Input": "Complete site configuration and runtime state.",
|
||
"SiteCookieUpdate": "Site login request used to refresh the stored cookie and User-Agent.",
|
||
"SiteCookieSet": "Browser-obtained site authentication cookie and optional User-Agent to persist without changing other site settings.",
|
||
"Subscribe": "Movie, TV, or music subscription input model.",
|
||
"SystemSettingsUpdateRequest": "One registered system-setting update request.",
|
||
"SystemUpdateRequest": "Selected MoviePilot application or site-resource update target.",
|
||
"SubscriptionExecutionStatus": "Subscription refresh execution status and progress summary.",
|
||
"TorrentInfo": "One torrent candidate returned by MoviePilot search.",
|
||
"TransferHistory-Input": "One MoviePilot file-transfer history record.",
|
||
}
|
||
|
||
MODEL_DESCRIPTIONS.update(
|
||
{
|
||
"ClassificationCategory": "Stable media-category definition with its library path and default labels.",
|
||
"ClassificationCondition": "One leaf condition in an automatic media-classification rule.",
|
||
"ClassificationConditionGroup-Input": "A recursive all, any, or not condition group.",
|
||
"ClassificationFacts": "Normalized media facts evaluated by the automatic classification policy.",
|
||
"ClassificationFactsPreviewInput": "Normalized facts supplied directly for a classification preview.",
|
||
"ClassificationFactSource": "Provider identity for a classification fact filled by another source.",
|
||
"ClassificationIdentityFacts": "Stable source-native identity used by classification evaluation.",
|
||
"ClassificationImpactRequest": "Request to compare an unpublished classification policy against the active policy.",
|
||
"ClassificationMediaFacts": "Normalized movie, TV, or shared media facts used by classification rules.",
|
||
"ClassificationMediaPreviewInput": "A selected media search result supplied for classification preview.",
|
||
"ClassificationMusicFacts": "Music-specific facts used by automatic classification rules.",
|
||
"ClassificationPolicy-Input": "Complete versioned automatic media-classification policy.",
|
||
"ClassificationPolicyPublishRequest": "Request to validate and publish a complete classification policy with CAS revision.",
|
||
"ClassificationPolicyRollbackRequest": "Request to publish a historical classification policy as a new revision.",
|
||
"ClassificationPolicyValidateRequest": "Request to validate a complete classification policy without saving it.",
|
||
"ClassificationPreviewRequest": "Request to preview a classification policy against media or normalized facts.",
|
||
"ClassificationRule-Input": "One ordered automatic media-classification rule.",
|
||
"ClassificationTarget": "Rule output containing an optional category ID and additional labels.",
|
||
"PluginCloneRequest": "Plugin clone identifier and optional display-name request.",
|
||
"PluginMarketSyncRequest": "Approved Wiki source request for plugin-market synchronization.",
|
||
"PluginRatingRequest": "Current user's numeric plugin-rating submission.",
|
||
"PluginFoldersData": "Complete mapping from plugin folder names to ordered plugin IDs or display configuration.",
|
||
"PluginFolderConfigData": "One plugin folder's ordered members and optional presentation settings.",
|
||
"PluginFolderUpdateRequest": "Incremental plugin-folder rename or presentation-settings update request.",
|
||
"PluginFolderPluginsUpdateRequest": "Conditional replacement of one plugin folder's ordered members.",
|
||
"Body_recommend_search_results_api_v1_search_recommend_post": "Torrent search results and recommendation controls supplied to the configured model.",
|
||
"SiteAuth": "Supported site-account authentication provider and its exact parameter values.",
|
||
"SitePriorityUpdate": "One configured site ID and its replacement search priority.",
|
||
"ManageRequest": "Configured storage target, provider-defined action, and action parameters.",
|
||
"SubscribeShare": "Shared subscription definition or publication metadata.",
|
||
"EpisodeFormatRecommendItem": "File samples used to infer an episode-number extraction template.",
|
||
"BatchTransferHistoryRedoRequest": "Explicit transfer-history IDs for AI-assisted batch reorganization.",
|
||
"TransferManualReviewRequest": "Authorized decision and optional result for one durable transfer operation.",
|
||
"Workflow-Input": "Complete workflow definition accepted by create and update operations.",
|
||
"Action-Input": "One executable action node in a workflow definition.",
|
||
"ActionPosition": "Editor coordinates for one workflow action node.",
|
||
"ActionRetry": "Retry limits and timing for one workflow action.",
|
||
"ActionFlow-Input": "One directed connection between workflow action nodes.",
|
||
"WorkflowExecutionConfig": "Workflow concurrency, join, branch, and failure policies.",
|
||
"WorkflowExecutionState-Input": "Persisted resumable workflow execution state.",
|
||
"WorkflowNodeState": "Persisted runtime state for one workflow action node.",
|
||
"WorkflowRuntimeState": "Complete persisted workflow runtime and progress state.",
|
||
"WorkflowShare": "Shared workflow definition or publication metadata.",
|
||
}
|
||
)
|
||
|
||
|
||
def _apply_field_descriptions(schema: Mapping[str, Any]) -> dict[str, Any]:
|
||
"""Attach concrete English guidance without replacing richer endpoint text."""
|
||
rewritten: dict[str, Any] = {}
|
||
for key, value in schema.items():
|
||
if isinstance(value, Mapping):
|
||
rewritten[key] = _apply_field_descriptions(value)
|
||
elif isinstance(value, list):
|
||
rewritten[key] = [
|
||
_apply_field_descriptions(item) if isinstance(item, Mapping) else deepcopy(item) for item in value
|
||
]
|
||
else:
|
||
rewritten[key] = deepcopy(value)
|
||
properties = rewritten.get("properties")
|
||
if isinstance(properties, dict):
|
||
for field_name, field_schema in properties.items():
|
||
if not isinstance(field_schema, dict):
|
||
continue
|
||
existing = field_schema.get("description")
|
||
if isinstance(existing, str) and existing.strip() and not re.search(r"[\u3400-\u9fff]", existing):
|
||
continue
|
||
description = FIELD_DESCRIPTIONS.get(str(field_name))
|
||
if not description:
|
||
raise ValueError(f"MCP field guidance is missing: {field_name}")
|
||
field_schema["description"] = description
|
||
return rewritten
|
||
|
||
|
||
def _rewrite_schema_refs(
|
||
schema: Mapping[str, Any],
|
||
*,
|
||
components: Mapping[str, Any],
|
||
definitions: dict[str, Any],
|
||
) -> dict[str, Any]:
|
||
"""把 OpenAPI components 引用改写为独立 MCP schema 的 $defs 引用。"""
|
||
reference = schema.get("$ref")
|
||
if isinstance(reference, str) and reference.startswith("#/components/schemas/"):
|
||
name = reference.rsplit("/", 1)[-1]
|
||
if name not in definitions:
|
||
definitions[name] = {}
|
||
source = components.get(name)
|
||
if not isinstance(source, Mapping):
|
||
raise ValueError(f"OpenAPI 缺少请求模型: {name}")
|
||
definitions[name] = _rewrite_schema_refs(
|
||
source,
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
return {"$ref": f"#/$defs/{name}"}
|
||
|
||
rewritten: dict[str, Any] = {}
|
||
for key, value in schema.items():
|
||
if isinstance(value, Mapping):
|
||
rewritten[key] = _rewrite_schema_refs(
|
||
value,
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
elif isinstance(value, list):
|
||
rewritten[key] = [
|
||
_rewrite_schema_refs(
|
||
item,
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
if isinstance(item, Mapping)
|
||
else deepcopy(item)
|
||
for item in value
|
||
]
|
||
else:
|
||
rewritten[key] = deepcopy(value)
|
||
return rewritten
|
||
|
||
|
||
def _parameter_object_schema(
|
||
parameters: Sequence[Mapping[str, Any]],
|
||
*,
|
||
location: str,
|
||
components: Mapping[str, Any],
|
||
definitions: dict[str, Any],
|
||
) -> dict[str, Any] | None:
|
||
"""把 OpenAPI path/query 参数投影为网关结构化对象。"""
|
||
selected = [parameter for parameter in parameters if parameter.get("in") == location]
|
||
if not selected:
|
||
return None
|
||
properties: dict[str, Any] = {}
|
||
required: list[str] = []
|
||
for parameter in selected:
|
||
name = str(parameter["name"])
|
||
raw_schema = parameter.get("schema")
|
||
if not isinstance(raw_schema, Mapping):
|
||
raw_schema = {}
|
||
field_schema = _rewrite_schema_refs(
|
||
raw_schema,
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
if parameter.get("description") and "description" not in field_schema:
|
||
field_schema["description"] = parameter["description"]
|
||
properties[name] = field_schema
|
||
if parameter.get("required"):
|
||
required.append(name)
|
||
result: dict[str, Any] = {
|
||
"type": "object",
|
||
"properties": properties,
|
||
"additionalProperties": False,
|
||
}
|
||
if required:
|
||
result["required"] = required
|
||
return result
|
||
|
||
|
||
def _request_body_schema(
|
||
operation: Mapping[str, Any],
|
||
*,
|
||
components: Mapping[str, Any],
|
||
definitions: dict[str, Any],
|
||
) -> tuple[dict[str, Any] | None, bool]:
|
||
"""读取一个 OpenAPI operation 的 JSON 请求体及必填性。"""
|
||
request_body = operation.get("requestBody")
|
||
if not isinstance(request_body, Mapping):
|
||
return None, False
|
||
content = request_body.get("content")
|
||
if not isinstance(content, Mapping):
|
||
return None, bool(request_body.get("required"))
|
||
media = content.get("application/json")
|
||
if not isinstance(media, Mapping):
|
||
media = next((item for item in content.values() if isinstance(item, Mapping)), None)
|
||
raw_schema = media.get("schema") if isinstance(media, Mapping) else None
|
||
if not isinstance(raw_schema, Mapping):
|
||
return None, bool(request_body.get("required"))
|
||
return (
|
||
_rewrite_schema_refs(
|
||
raw_schema,
|
||
components=components,
|
||
definitions=definitions,
|
||
),
|
||
bool(request_body.get("required")),
|
||
)
|
||
|
||
|
||
def _person_credits_operation(openapi: Mapping[str, Any]) -> dict[str, Any]:
|
||
"""合并四个来源端点为稳定 media.person.credits 网关合同。"""
|
||
paths = openapi.get("paths", {})
|
||
source_paths = {
|
||
"douban": "/api/v1/douban/person/credits/{person_id}",
|
||
"tmdb": "/api/v1/tmdb/person/credits/{person_id}",
|
||
"bangumi": "/api/v1/bangumi/person/credits/{person_id}",
|
||
"anilist": "/api/v1/anilist/person/credits/{person_id}",
|
||
}
|
||
for source_path in source_paths.values():
|
||
if source_path not in paths:
|
||
raise ValueError(f"OpenAPI 缺少人物作品端点: {source_path}")
|
||
representative = paths[source_paths["douban"]].get("get")
|
||
responses = deepcopy(representative.get("responses")) if isinstance(representative, Mapping) else {}
|
||
return {
|
||
"summary": "Read person credits",
|
||
"parameters": [
|
||
{
|
||
"name": "source",
|
||
"in": "path",
|
||
"required": True,
|
||
"schema": {"type": "string", "enum": list(source_paths)},
|
||
"description": "Metadata source that owns the person ID.",
|
||
},
|
||
{
|
||
"name": "person_id",
|
||
"in": "path",
|
||
"required": True,
|
||
"schema": {"type": "integer"},
|
||
"description": "Source-native person ID.",
|
||
},
|
||
{
|
||
"name": "page",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {"type": "integer", "minimum": 1, "default": 1},
|
||
},
|
||
{
|
||
"name": "count",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20},
|
||
"description": "Page size used by Bangumi and AniList; other sources ignore it.",
|
||
},
|
||
],
|
||
"responses": responses,
|
||
}
|
||
|
||
|
||
def _resolve_openapi_operation(
|
||
operation_id: str,
|
||
route: Any,
|
||
openapi: Mapping[str, Any],
|
||
) -> Mapping[str, Any]:
|
||
"""按固定路由读取 OpenAPI operation,并处理多来源合成路由。"""
|
||
if operation_id == "media.person.credits":
|
||
return _person_credits_operation(openapi)
|
||
path_item = openapi.get("paths", {}).get(route.path)
|
||
if not isinstance(path_item, Mapping):
|
||
raise ValueError(f"OpenAPI 缺少 operation 路径: {operation_id} -> {route.path}")
|
||
operation = path_item.get(str(route.method).lower())
|
||
if not isinstance(operation, Mapping):
|
||
raise ValueError(f"OpenAPI 缺少 operation 方法: {operation_id} -> {route.method} {route.path}")
|
||
return operation
|
||
|
||
|
||
def _apply_operation_overrides(
|
||
operation_id: str,
|
||
query_schema: dict[str, Any] | None,
|
||
body_schema: dict[str, Any] | None,
|
||
) -> tuple[dict[str, Any] | None, bool | None]:
|
||
"""补充同一路由多 operation 时无法由 FastAPI 自动表达的语义约束。"""
|
||
if operation_id == "media.person.search" and query_schema is not None:
|
||
query_schema["properties"]["type"] = {
|
||
"type": "string",
|
||
"const": "person",
|
||
"description": "Literal person, selecting person search instead of media search.",
|
||
}
|
||
required = query_schema.setdefault("required", [])
|
||
if "type" not in required:
|
||
required.append("type")
|
||
if operation_id in {"plugin.installed", "plugin.market"} and query_schema is not None:
|
||
state = "installed" if operation_id == "plugin.installed" else "market"
|
||
query_schema["properties"]["query"]["description"] = (
|
||
"Optional case-insensitive keyword matched against plugin ID, name, description, and author."
|
||
)
|
||
query_schema["properties"]["state"] = {
|
||
"type": "string",
|
||
"const": state,
|
||
"description": f"Literal {state}, selecting only {state} plugin catalog entries.",
|
||
}
|
||
required = query_schema.setdefault("required", [])
|
||
if "state" not in required:
|
||
required.append("state")
|
||
if operation_id == "music.explore" and query_schema is not None:
|
||
descriptions = {
|
||
"media_source": (
|
||
"Music exploration source. Use musicbrainz for chart/fresh modes or doubanmusic for tag browsing."
|
||
),
|
||
"mode": "MusicBrainz mode: chart reads listening charts; fresh reads new album releases.",
|
||
"entity": "Chart entity: recording for tracks or album for release groups. Fresh results are albums.",
|
||
"range_name": "ListenBrainz chart range: this_week, this_month, this_year, week, month, or year.",
|
||
"sort_by": "ListenBrainz chart order: listen_count.desc or listen_count.asc.",
|
||
"sort": "Fresh-release order accepted by the current ListenBrainz implementation.",
|
||
"days": "Fresh-release lookback/lookahead window, from 1 through the endpoint maximum.",
|
||
"past": "Include releases before today in fresh mode.",
|
||
"future": "Include releases after today in fresh mode.",
|
||
"min_listen_count": "Minimum ListenBrainz listen count in chart mode.",
|
||
"with_cover": "Keep only results with cover artwork when true.",
|
||
"tags": "Comma-separated Douban Music tags used only when media_source is doubanmusic.",
|
||
"douban_sort": "Douban Music order: U comprehensive, S rating, R newest, or O hottest.",
|
||
}
|
||
for field_name, description in descriptions.items():
|
||
field_schema = query_schema["properties"].get(field_name)
|
||
if isinstance(field_schema, dict):
|
||
field_schema["description"] = description
|
||
if operation_id == "plugin.config.update" and body_schema is not None:
|
||
body_schema["minProperties"] = 1
|
||
body_schema["description"] = (
|
||
"Complete plugin configuration object. First call plugin.config.get, copy its returned model, "
|
||
"change only the intended keys, and submit the full resulting object. Omit a key only when it "
|
||
"must be removed. A successful update reinitializes the plugin and refreshes commands, jobs, and routes."
|
||
)
|
||
if operation_id == "system.upgrade.dev":
|
||
return (
|
||
{
|
||
"type": "string",
|
||
"const": "dev",
|
||
"description": "Literal dev. Release updates must use the separate check, download, and install operations.",
|
||
},
|
||
True,
|
||
)
|
||
return body_schema, None
|
||
|
||
|
||
def _resolve_openapi_schema(
|
||
schema: Mapping[str, Any],
|
||
components: Mapping[str, Any],
|
||
) -> Mapping[str, Any]:
|
||
"""解析响应中使用的本地 OpenAPI 引用与可空联合。"""
|
||
reference = schema.get("$ref")
|
||
if isinstance(reference, str) and reference.startswith("#/components/schemas/"):
|
||
resolved = components.get(reference.rsplit("/", 1)[-1])
|
||
if isinstance(resolved, Mapping):
|
||
return _resolve_openapi_schema(resolved, components)
|
||
alternatives = schema.get("anyOf")
|
||
if isinstance(alternatives, list):
|
||
for alternative in alternatives:
|
||
if not isinstance(alternative, Mapping):
|
||
continue
|
||
resolved = _resolve_openapi_schema(alternative, components)
|
||
if resolved.get("type") != "null":
|
||
return resolved
|
||
return schema
|
||
|
||
|
||
def _response_data_schema(
|
||
operation: Mapping[str, Any],
|
||
components: Mapping[str, Any],
|
||
) -> Mapping[str, Any]:
|
||
"""读取统一响应的 data schema,供 MCP 标注集合输出合同。"""
|
||
responses = operation.get("responses")
|
||
if not isinstance(responses, Mapping):
|
||
return {}
|
||
success = responses.get("200") or responses.get(200)
|
||
if not isinstance(success, Mapping):
|
||
return {}
|
||
content = success.get("content")
|
||
if not isinstance(content, Mapping):
|
||
return {}
|
||
media = content.get("application/json")
|
||
if not isinstance(media, Mapping):
|
||
return {}
|
||
raw_schema = media.get("schema")
|
||
if not isinstance(raw_schema, Mapping):
|
||
return {}
|
||
response_schema = _resolve_openapi_schema(raw_schema, components)
|
||
properties = response_schema.get("properties")
|
||
if not isinstance(properties, Mapping):
|
||
return response_schema
|
||
data_schema = properties.get("data")
|
||
if not isinstance(data_schema, Mapping):
|
||
return response_schema
|
||
return _resolve_openapi_schema(data_schema, components)
|
||
|
||
|
||
def _collection_response_contract(
|
||
operation: Mapping[str, Any],
|
||
components: Mapping[str, Any],
|
||
) -> dict[str, Any] | None:
|
||
"""从 OpenAPI 响应声明提取列表或结构化分页结果的机器可读合同。"""
|
||
responses = operation.get("responses")
|
||
success = responses.get("200") if isinstance(responses, Mapping) else None
|
||
if not isinstance(success, Mapping) and isinstance(responses, Mapping):
|
||
success = responses.get(200)
|
||
headers = success.get("headers") if isinstance(success, Mapping) else None
|
||
header_names = {str(name).lower() for name in headers} if isinstance(headers, Mapping) else set()
|
||
data_schema = _response_data_schema(operation, components)
|
||
if data_schema.get("type") == "array":
|
||
has_total = "x-total-count" in header_names
|
||
parameters = operation.get("parameters")
|
||
query_parameters = (
|
||
{
|
||
str(parameter.get("name")): parameter
|
||
for parameter in parameters
|
||
if isinstance(parameter, Mapping) and parameter.get("in") == "query"
|
||
}
|
||
if isinstance(parameters, list)
|
||
else {}
|
||
)
|
||
compatibility_parameters = [
|
||
query_parameters.get("page"),
|
||
query_parameters.get("count"),
|
||
]
|
||
native_window_names = {"limit", "offset", "page_size", "max_results"}
|
||
has_native_window_default = False
|
||
for name in native_window_names:
|
||
parameter = query_parameters.get(name)
|
||
if not isinstance(parameter, Mapping):
|
||
continue
|
||
if parameter.get("required", False):
|
||
has_native_window_default = True
|
||
break
|
||
schema = parameter.get("schema")
|
||
if isinstance(schema, Mapping) and schema.get("default") is not None:
|
||
has_native_window_default = True
|
||
break
|
||
defaults_to_unpaginated = (
|
||
all(
|
||
isinstance(parameter, Mapping)
|
||
and not parameter.get("required", False)
|
||
and isinstance(parameter.get("schema"), Mapping)
|
||
and "default" not in parameter["schema"]
|
||
for parameter in compatibility_parameters
|
||
)
|
||
and not has_native_window_default
|
||
)
|
||
return {
|
||
"body_shape": "list",
|
||
"result_count_field": "collection.result_count",
|
||
"total_count_field": "collection.total_count" if has_total else None,
|
||
"default_pagination": ("unpaginated" if defaults_to_unpaginated else "endpoint-defined"),
|
||
}
|
||
data_properties = data_schema.get("properties")
|
||
if not isinstance(data_properties, Mapping) or "total" not in data_properties:
|
||
return None
|
||
items_field = next(
|
||
(name for name in ("items", "list") if name in data_properties),
|
||
None,
|
||
)
|
||
if items_field is None:
|
||
return None
|
||
return {
|
||
"body_shape": "page_object",
|
||
"items_field": f"data.{items_field}",
|
||
"total_count_field": "data.total",
|
||
"default_pagination": "endpoint-defined",
|
||
}
|
||
|
||
|
||
def _collection_response_guidance(contract: Mapping[str, Any]) -> str:
|
||
"""把集合输出合同转换为 oneOf 分支中的英文自描述说明。"""
|
||
if contract.get("body_shape") == "page_object":
|
||
return (
|
||
f" Collection response: items stay in {contract['items_field']} and the exact total "
|
||
f"stays in {contract['total_count_field']}. For a count-only request, use the smallest "
|
||
"documented page and read that total; do not query the database merely because item "
|
||
"data is truncated."
|
||
)
|
||
if contract.get("total_count_field"):
|
||
if contract.get("default_pagination") != "unpaginated":
|
||
return (
|
||
" Collection response: data remains a list and the endpoint's documented "
|
||
"pagination or limit defaults remain in effect. Successful gateway output adds "
|
||
"collection.result_count and the exact collection.total_count. For a count-only "
|
||
"request, use the smallest valid page and read collection.total_count; do not "
|
||
"query the database merely because item data is truncated."
|
||
)
|
||
return (
|
||
" Collection response: data remains a list; omit both page and count to preserve the "
|
||
"legacy complete result. Successful gateway output adds collection.result_count and "
|
||
"the exact collection.total_count. For a count or summary, send page=1 and count=1, "
|
||
"then read collection.total_count; do not query the database merely because item data "
|
||
"is truncated."
|
||
)
|
||
return (
|
||
" Collection response: data remains a list and successful gateway output adds "
|
||
"collection.result_count. collection.total_count is omitted when the endpoint or its "
|
||
"upstream source does not expose a total."
|
||
)
|
||
|
||
|
||
def build_api_mcp_input_schema(
|
||
*,
|
||
openapi: Mapping[str, Any],
|
||
routes: Mapping[str, Any],
|
||
specs: Sequence[Any],
|
||
) -> dict[str, Any]:
|
||
"""构建全部白名单 operation 的完整 MCP oneOf 输入合同。"""
|
||
components = openapi.get("components", {}).get("schemas", {})
|
||
if not isinstance(components, Mapping):
|
||
components = {}
|
||
definitions: dict[str, Any] = {}
|
||
spec_by_id = {spec.operation_id: spec for spec in specs}
|
||
if set(spec_by_id) != set(routes):
|
||
raise ValueError("API operation 策略与路由注册表不一致")
|
||
|
||
branches: list[dict[str, Any]] = []
|
||
for operation_id in sorted(routes):
|
||
route = routes[operation_id]
|
||
operation = _resolve_openapi_operation(operation_id, route, openapi)
|
||
summary = OPERATION_DESCRIPTIONS.get(operation_id)
|
||
if not summary:
|
||
raise ValueError(f"MCP operation guidance is missing: {operation_id}")
|
||
parameters = operation.get("parameters")
|
||
if not isinstance(parameters, list):
|
||
parameters = []
|
||
path_schema = _parameter_object_schema(
|
||
parameters,
|
||
location="path",
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
query_schema = _parameter_object_schema(
|
||
parameters,
|
||
location="query",
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
body_schema, body_required = _request_body_schema(
|
||
operation,
|
||
components=components,
|
||
definitions=definitions,
|
||
)
|
||
body_schema, required_override = _apply_operation_overrides(
|
||
operation_id,
|
||
query_schema,
|
||
body_schema,
|
||
)
|
||
if required_override is not None:
|
||
body_required = required_override
|
||
|
||
properties: dict[str, Any] = {
|
||
"operation_id": {"type": "string", "const": operation_id},
|
||
}
|
||
required = ["operation_id"]
|
||
if path_schema is not None:
|
||
path_schema["description"] = (
|
||
f"Resource identity placeholders for {operation_id}. {summary} Use only the named fields below."
|
||
)
|
||
properties["path_params"] = path_schema
|
||
if path_schema.get("required"):
|
||
required.append("path_params")
|
||
if query_schema is not None:
|
||
query_schema["description"] = (
|
||
f"Filters and control values for {operation_id}. {summary} Use only the named fields below."
|
||
)
|
||
properties["query"] = query_schema
|
||
if query_schema.get("required"):
|
||
required.append("query")
|
||
if body_schema is not None:
|
||
body_schema.setdefault(
|
||
"description",
|
||
f"Request value for {operation_id}. {summary} Use the exact type and fields below.",
|
||
)
|
||
properties["body"] = body_schema
|
||
if body_required:
|
||
required.append("body")
|
||
|
||
spec = spec_by_id[operation_id]
|
||
collection_contract = _collection_response_contract(operation, components)
|
||
collection_guidance = (
|
||
_collection_response_guidance(collection_contract) if collection_contract is not None else ""
|
||
)
|
||
branch = {
|
||
"type": "object",
|
||
"title": operation_id,
|
||
"description": (
|
||
f"{summary} Method: {route.method}. Path: {route.path}. "
|
||
f"Effect: {spec.effect.value}.{collection_guidance}"
|
||
),
|
||
"properties": properties,
|
||
"required": required,
|
||
"additionalProperties": False,
|
||
}
|
||
if collection_contract is not None:
|
||
branch["x-moviepilot-collection"] = collection_contract
|
||
branches.append(branch)
|
||
|
||
schema: dict[str, Any] = {
|
||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||
"title": "moviepilot_api",
|
||
"type": "object",
|
||
"description": (
|
||
"Select the oneOf branch matching operation_id and send exactly its documented fields. "
|
||
"Collection branches also describe their additive output metadata in "
|
||
"x-moviepilot-collection."
|
||
),
|
||
"properties": {
|
||
"operation_id": {"type": "string", "enum": sorted(routes)},
|
||
"path_params": {"type": "object"},
|
||
"query": {"type": "object"},
|
||
"body": {},
|
||
},
|
||
"required": ["operation_id"],
|
||
"oneOf": branches,
|
||
}
|
||
if definitions:
|
||
for model_name, definition in definitions.items():
|
||
description = MODEL_DESCRIPTIONS.get(model_name)
|
||
if not description:
|
||
raise ValueError(f"MCP model guidance is missing: {model_name}")
|
||
definition["description"] = description
|
||
schema["$defs"] = definitions
|
||
return _apply_field_descriptions(schema)
|
||
|
||
|
||
__all__ = ["build_api_mcp_input_schema"]
|