Search for YouTube videos by query string.

Searches YouTube and returns video results with titles, descriptions,
thumbnails, channels, and URLs. Results are cached for 6 hours to
minimize API quota usage.

Args:
    query: Search query (e.g., "NixOS tutorials", "vimjoyer nix").
    max_results: Maximum results to return (1-50, default 5).

Returns:
    List of video results with video_id, title, description, url,
    thumbnail, channel_title, and published_at.

Example:
    >>> results = _search_videos("vimjoyer garbage collection", 10)
    >>> print(results[0]["title"])

Note:
    - Search costs 100 quota units per request
    - Results cached for 6 hours in youtube.search namespace
    - Use get_cached_result() to paginate large result sets

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Search for YouTube channels by query string.

Searches YouTube and returns channel results with names, descriptions,
thumbnails, and URLs. Results are cached for 6 hours to minimize
API quota usage.

Args:
    query: Search query (e.g., "Vimjoyer", "NixOS channels").
    max_results: Maximum results to return (1-50, default 5).

Returns:
    List of channel results with channel_id, title, description,
    url, thumbnail, and published_at.

Example:
    >>> results = _search_channels("vimjoyer", 5)
    >>> print(results[0]["title"])

Note:
    - Search costs 100 quota units per request
    - Results cached for 6 hours in youtube.search namespace
    - Use get_cached_result() to paginate large result sets

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get detailed information about a YouTube video.

Retrieves comprehensive video metadata including title, description,
statistics (views, likes, comments), duration, tags, and channel info.
Cached for 24 hours to minimize API quota usage.

Args:
    video_id: YouTube video ID (from URL or search results, e.g., "dQw4w9WgXcQ")

Returns:
    Video details dictionary with:
    - title, description, video_id, url, thumbnail
    - view_count, like_count, comment_count
    - duration (ISO 8601 format like "PT15M30S")
    - tags, channel_title, published_at

Example:
    >>> details = _get_video_details("nLwbNhSxLd4")
    >>> print(details["title"])
    "Full NixOS Guide"

Note:
    - Costs 1 quota unit per request (100x cheaper than search)
    - Cached for 24h in youtube.api namespace
    - Use after search to get full details

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get detailed information about a YouTube channel.

Retrieves channel metadata including title, description, statistics
(subscribers, videos, total views), and branding information.
Cached for 24 hours to minimize API quota usage.

Args:
    channel_id: YouTube channel ID (from search results, e.g., "UCuAXFkgsw1L7xaCfnd5JJOw")

Returns:
    Channel info dictionary with:
    - title, description, channel_id, url, thumbnail
    - subscriber_count, video_count, view_count
    - published_at

Example:
    >>> info = _get_channel_info("UCuAXFkgsw1L7xaCfnd5JJOw")
    >>> print(info["title"])
    "Vimjoyer"

Note:
    - Costs 1 quota unit per request (100x cheaper than search)
    - Cached for 24h in youtube.api namespace
    - Use after channel search to get full details

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

List all available transcript languages for a YouTube video.

Discovers which transcript languages are available for a video,
including both manual and auto-generated transcripts.
Cached permanently as available transcripts don't change.

Args:
    video_id: YouTube video ID (from URL or search, e.g., "dQw4w9WgXcQ")

Returns:
    AvailableTranscripts dictionary with:
    - video_id: The video ID
    - available_languages: List of language codes (e.g., ["en", "es", "fr"])
    - transcript_info: Detailed info for each (language, is_generated, etc.)

Example:
    >>> transcripts = list_available_transcripts("nLwbNhSxLd4")
    >>> print(transcripts["available_languages"])
    ["en", "de", "es"]

Note:
    - Uses no YouTube API quota (third-party transcript API)
    - Cached permanently in youtube.content namespace
    - Call this first before requesting specific transcript

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get a preview of a YouTube video transcript.

Retrieves the first N characters of a video transcript for quick preview.
Useful for deciding if you need the full transcript.
Cached permanently as transcript content doesn't change.

Args:
    video_id: YouTube video ID (e.g., "dQw4w9WgXcQ")
    language: Language code (e.g., "en"). If empty, uses first available
    max_chars: Maximum characters to return (default: 2000)

Returns:
    TranscriptPreview dictionary with:
    - video_id, language, preview text
    - total_length: Total characters in full transcript
    - is_truncated: Whether preview is truncated

Example:
    >>> preview = get_video_transcript_preview("nLwbNhSxLd4", max_chars=500)
    >>> print(preview["preview"][:50])
    "Welcome to this NixOS tutorial..."

Note:
    - Uses no YouTube API quota
    - Cached permanently in youtube.content namespace
    - Use list_available_transcripts first to see language options

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get the complete transcript for a YouTube video.

Retrieves the full transcript with all entries and timestamps.
For large transcripts (>2KB), RefCache automatically returns a preview
with a reference that can be paginated using get_cached_result.
Cached permanently as transcript content doesn't change.

Args:
    video_id: YouTube video ID (e.g., "dQw4w9WgXcQ")
    language: Language code (e.g., "en"). If empty, uses first available

Returns:
    FullTranscript dictionary with:
    - video_id, language
    - transcript: List of entries with text, start time, duration
    - full_text: Complete transcript as plain text

Example:
    >>> full = get_full_transcript("nLwbNhSxLd4", language="en")
    >>> print(len(full["transcript"]))
    150
    >>> print(full["full_text"][:100])

Note:
    - Uses no YouTube API quota
    - Cached permanently in youtube.content namespace
    - RefCache may return preview + reference for large transcripts
    - Use get_transcript_chunk for entry-by-entry pagination

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get a chunk of transcript entries for pagination.

Retrieves a subset of transcript entries for large transcripts.
Useful for iterating through transcripts entry-by-entry.
Cached permanently as transcript content doesn't change.

Args:
    video_id: YouTube video ID (e.g., "dQw4w9WgXcQ")
    start_index: Starting entry index (0-based, default: 0)
    chunk_size: Number of entries to return (default: 50)
    language: Language code (e.g., "en"). If empty, uses first available

Returns:
    TranscriptChunk dictionary with:
    - video_id, language, start_index, chunk_size
    - entries: List of transcript entries in this chunk
    - total_entries: Total entries in full transcript
    - has_more: Whether more entries available after this chunk

Example:
    >>> chunk = get_transcript_chunk("nLwbNhSxLd4", start_index=0, chunk_size=10)
    >>> print(len(chunk["entries"]))
    10
    >>> print(chunk["has_more"])
    True
    >>> # Get next chunk
    >>> chunk2 = get_transcript_chunk("nLwbNhSxLd4", start_index=10, chunk_size=10)

Note:
    - Uses no YouTube API quota
    - Cached permanently in youtube.content namespace
    - Use for iterating through large transcripts

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get top comments for a YouTube video with engagement metrics.

Retrieves top-level comments (no replies) sorted by relevance.
Comments are cached for 5 minutes. Returns empty list if comments
are disabled for the video.

Args:
    video_id: YouTube video ID (e.g., "dQw4w9WgXcQ")
    max_results: Maximum comments to return (1-100, default: 20)

Returns:
    Dictionary with video_id, comments list, and total_returned.
    Each comment includes author, text, like_count, published_at.

Example:
    >>> comments = get_video_comments("nLwbNhSxLd4", max_results=10)
    >>> print(comments["comments"][0]["author"])

Note:
    - Costs 1 quota unit per request
    - Cached for 5 minutes in youtube.comments namespace
    - Returns empty list if comments disabled (not an error)

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Search for currently live YouTube videos.

Searches for videos that are currently streaming live, filtering results
to only active broadcasts. Results are cached for 6 hours.

Args:
    query: Search query (e.g., "gaming live", "news live now").
    max_results: Maximum results to return (1-50, default 5).

Returns:
    List of live video results with video_id, title, description, url,
    thumbnail, channel_title, and published_at.

Example:
    >>> results = search_live_videos("gaming", max_results=10)
    >>> print(results[0]["title"])
    'Live Gaming Stream - Fortnite'

Note:
    - Search costs 100 quota units per request
    - Results cached for 6 hours in youtube.search namespace
    - Use is_live() to check if a specific video is currently live
    - Use get_live_chat_messages() to monitor chat

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Check if a YouTube video is currently live.

Queries the YouTube Data API to determine if a video is currently
broadcasting live. Returns live status with viewer count and timing information.
Cached for 30 seconds since live status changes quickly.

Args:
    video_id: YouTube video ID to check (e.g., "dQw4w9WgXcQ").

Returns:
    Dictionary with:
    - video_id: YouTube video ID
    - is_live: Boolean indicating if video is currently live
    - viewer_count: Current concurrent viewers (None if not live)
    - scheduled_start_time: ISO 8601 scheduled start time (None if not scheduled)
    - actual_start_time: ISO 8601 actual start time (None if not started)
    - active_live_chat_id: Live chat ID (None if no chat or not live)

Example:
    >>> status = is_live("dQw4w9WgXcQ")
    >>> if status["is_live"]:
    ...     print(f"Live now with {status['viewer_count']} viewers!")

Note:
    - Costs 1 quota unit per request
    - Cached for 30 seconds in youtube.api namespace
    - Use search_live_videos() to find live streams

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get the live chat ID for a currently streaming video.

Retrieves the active live chat ID required for fetching chat messages.
This ID remains constant throughout the stream's duration.
Cached for 5 minutes since chat ID doesn't change during stream.

Args:
    video_id: YouTube video ID of the live stream.

Returns:
    Dictionary with:
    - video_id: YouTube video ID
    - live_chat_id: Active live chat ID
    - is_live: Boolean confirming video is live

Example:
    >>> result = get_live_chat_id("dQw4w9WgXcQ")
    >>> chat_id = result["live_chat_id"]

Note:
    - Costs 1 quota unit per request
    - Cached for 5 minutes in youtube.api namespace
    - Raises error if video is not live or chat disabled
    - Use is_live() first to check if video is broadcasting

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get recent live chat messages from a streaming video.

Fetches live chat messages with pagination support for efficient polling.
Use the returned next_page_token in subsequent calls to get only new messages.
Cached for 30 seconds for near real-time monitoring.

Args:
    video_id: YouTube video ID of the live stream.
    max_results: Maximum messages to return (1-2000, default 200).
    page_token: Pagination token from previous call (None for first call).

Returns:
    Dictionary with:
    - video_id: YouTube video ID
    - messages: List of messages with author, text, published_at, author_channel_id
    - total_returned: Number of messages in this response
    - next_page_token: Token for next page (None if no more)
    - polling_interval_millis: YouTube's recommended polling interval

Example:
    >>> # First call - get latest messages
    >>> result = get_live_chat_messages("dQw4w9WgXcQ", max_results=50)
    >>> print(f"Got {result['total_returned']} messages")
    >>>
    >>> # Second call - get only new messages since first call
    >>> result2 = get_live_chat_messages(
    ...     "dQw4w9WgXcQ",
    ...     max_results=50,
    ...     page_token=result["next_page_token"]
    ... )

Note:
    - Costs 1 quota unit per request
    - Cached for 30 seconds in youtube.comments namespace
    - Polling Pattern:
      1. First call: No page_token → Get latest messages + next_page_token
      2. Store next_page_token
      3. Subsequent calls: Pass page_token → Get only NEW messages
      4. Repeat step 3 every 30-60 seconds for continuous monitoring
    - MCP Limitation: Agent must manually call this tool repeatedly to see new messages

Caching Behavior:

• Parameters that accept reference strings can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Ref input compatibility: Support depends on the tool's input schema/validation. Some strictly typed parameters may reject string ref_ids before resolution.

Full retrieval: Use get_cached_result(ref_id, full=True) to get the complete value.

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Pre-load the embedding model and vector store for semantic search.

Call this before your first semantic search to avoid timeout. Downloads and initializes the Nomic embedding model (~270MB) and creates the vector store connection.

The warmup process:

1. Downloads the embedding model (if not cached)

2. Loads the model into memory

3. Runs a test embedding to warm up inference

4. Initializes the vector store connection

Returns: Dictionary with warmup status: - status: "ready" if successful - model: Name of the embedding model loaded - dimensionality: Embedding dimensions configured - inference_mode: How embeddings are computed (local/remote) - test_embedding_size: Size of test embedding (confirms model works) - warmup_time_seconds: Time taken to warm up

Note: - First call downloads ~270MB model (takes 30-60 seconds) - Subsequent calls are instant (model cached on disk) - Model stays in memory for fast inference after warmup

Search transcripts using natural language with automatic indexing.

Performs semantic similarity search over video transcripts. Automatically indexes any missing transcripts before searching, providing a seamless experience without requiring explicit indexing calls.

Args: query: Natural language search query (e.g., "Nix garbage collection generations"). channel_ids: Optional list of YouTube channel IDs to scope the search. Videos from these channels will be auto-indexed if not already indexed. video_ids: Optional list of specific video IDs to scope the search. These videos will be auto-indexed if not already indexed. k: Number of results to return (default: 10). language: Preferred transcript language code (default: "en"). max_videos_per_channel: Maximum videos to fetch per channel (default: 50). min_score: Optional minimum similarity score threshold (lower is better).

Returns: Dictionary with search results including: - query: The original search query - results: List of matches with video info, text, timestamps, and scores - total_results: Number of results returned - indexing_stats: Statistics about auto-indexing performed - scope: Description of search scope applied

Note: - First search on new content will be slower due to indexing (~1-2 min for 50 videos) - Subsequent searches are fast (already indexed) - If neither channel_ids nor video_ids provided, searches all indexed content - Results include timestamp URLs for direct playback at matching segments

Pre-index all video transcripts from a YouTube channel.

This is an optional tool for pre-warming the semantic search index. You don't need to call this before searching - semantic_search_transcripts automatically indexes missing videos. Use this only if you want to explicitly prepare a channel's content for faster first searches.

Args: channel_id: YouTube channel ID (e.g., "UCuAXFkgsw1L7xaCfnd5JJOw"). max_videos: Maximum number of videos to index (default: 50). language: Preferred transcript language code (default: "en"). force_reindex: If True, re-index videos even if already indexed.

Returns: Dictionary with indexing results: - indexed_count: Number of videos successfully indexed - chunk_count: Total chunks created - skipped_count: Videos skipped (already indexed or no transcript) - error_count: Number of failed videos - errors: List of error messages - video_ids: List of indexed video IDs

Note: - Indexing 50 videos takes ~1-2 minutes - Uses ~1 API quota unit per video (transcripts are free) - Subsequent semantic searches on this channel will be fast

Search comments using natural language with automatic indexing.

Performs semantic similarity search over video comments. Automatically indexes any missing comments before searching, providing a seamless experience without requiring explicit indexing calls.

Args: query: Natural language search query (e.g., "questions about flakes"). channel_ids: Optional list of YouTube channel IDs to scope the search. video_ids: Optional list of specific video IDs to scope the search. k: Number of results to return (default: 10). max_comments_per_video: Maximum comments to index per video (default: 100). max_videos_per_channel: Maximum videos to fetch per channel (default: 50). min_score: Optional minimum similarity score threshold (lower is better).

Returns: Dictionary with search results including: - query: The original search query - results: List of matches with video info, text, author, like_count, scores - total_results: Number of results returned - indexing_stats: Statistics about auto-indexing performed - scope: Description of search scope applied

Note: - First search on new content will be slower due to indexing - Subsequent searches are fast (already indexed) - If neither channel_ids nor video_ids provided, searches all indexed comments

Search across all content types (transcripts and comments).

Performs unified semantic search over both video transcripts and comments. Automatically indexes any missing content before searching.

Args: query: Natural language search query (e.g., "Nix garbage collection"). content_types: List of content types to search: ["transcript", "comment"]. If None, searches all types. channel_ids: Optional list of YouTube channel IDs to scope the search. video_ids: Optional list of specific video IDs to scope the search. k: Number of results to return (default: 10). language: Preferred transcript language code (default: "en"). max_comments_per_video: Maximum comments to index per video (default: 100). max_videos_per_channel: Maximum videos to fetch per channel (default: 50). min_score: Optional minimum similarity score threshold (lower is better).

Returns: Dictionary with search results including: - query: The original search query - results: List of matches with content_type field indicating source - total_results: Number of results returned - indexing_stats: Statistics for both transcripts and comments - content_types_searched: List of content types that were searched

Note: - Results are sorted by relevance score across all content types - Each result includes content_type field ("transcript" or "comment") - Transcript results include timestamp_url, comment results include author

Get list of videos that have been indexed for semantic search.

Retrieves all indexed video IDs with optional filtering by channel and/or content type. Useful for understanding what content is available.

Args: channel_id: Optional filter by YouTube channel ID. content_type: Optional filter by content type ("transcript" or "comment").

Returns: Dictionary with: - video_ids: List of indexed video IDs - total_count: Total number of indexed videos - channel_filter: Channel ID filter if applied - content_type_filter: Content type filter if applied

Delete a video's content from the semantic search index.

Removes indexed content (transcripts, comments, or both) for a specific video. Useful for re-indexing or cleaning up the index.

Args: video_id: YouTube video ID to remove from the index. content_type: Optional content type to delete ("transcript" or "comment"). If None, deletes all content types for the video.

Returns: Dictionary with: - video_id: The deleted video ID - transcripts_deleted: Number of transcript chunks removed - comments_deleted: Number of comment chunks removed - total_deleted: Total chunks removed - success: Whether the deletion was successful

Enable or disable test context mode for Langfuse attribution demos.

When enabled, all traces will include user_id, session_id, and metadata from the MockContext. This allows testing Langfuse filtering and aggregation without a real FastMCP authentication setup.

Args: enabled: Whether to enable test context mode (default: True).

Returns: Status dict with current test mode state and context values.

Set test context values for Langfuse attribution demos.

Changes here affect what user_id, session_id, and metadata are sent to Langfuse traces. Use this to test filtering by different users or sessions in the Langfuse dashboard.

Args: user_id: User identity (e.g., "alice", "bob"). org_id: Organization identity (e.g., "acme", "globex"). session_id: Session identifier for grouping traces. agent_id: Agent identity (e.g., "claude", "gpt4").

Returns: Updated context state and example of Langfuse attributes.

Reset test context to default demo values.

Returns: Reset context state.

Get information about the current Langfuse trace and context.

Returns metadata about Langfuse tracing status and current context values for debugging.

Returns: Dict with Langfuse configuration and current context.

Retrieve a cached result, optionally with pagination.

Use this to:

• Get a preview of a cached value

• Paginate through large lists

• Access the full value of a cached result

All cache operations are traced to Langfuse with hit/miss status.

Args: ref_id: Reference ID to look up. page: Page number (1-indexed). page_size: Items per page. max_size: Maximum preview size (overrides defaults). full: If True, return the complete cached value without preview truncation. Bypasses all preview generation. Use when you need the entire value (e.g. full transcripts).

Returns: The cached value or a preview with pagination info.

Caching: Large results are returned as references with previews.

Pagination: Use page and page_size to navigate results.

Full retrieval: Use full=True to get the complete value.

References: This tool accepts ref_id from previous tool calls.

Check server health status.

Returns: Health status information including Langfuse tracing status.

List cached references with optional filtering.

⚠️ ADMIN ONLY - Requires elevated permissions.

Args: namespace: Filter by namespace (e.g., 'public', 'user:alice'). include_expired: Include expired references in results. include_preview: Include value previews in results. limit: Maximum number of results (default: 50, max: 100). offset: Offset for pagination.

Returns: Dictionary with references list and pagination info.

Get detailed information about a cached reference.

⚠️ ADMIN ONLY - Requires elevated permissions.

Args: ref_id: The reference ID to look up.

Returns: Dictionary with detailed reference information (value not included).

Delete a specific cached reference.

⚠️ ADMIN ONLY - Requires elevated permissions. ⚠️ DESTRUCTIVE - This action cannot be undone.

Args: ref_id: The reference ID to delete.

Returns: Confirmation of deletion or error.

Clear all references in a namespace.

⚠️ ADMIN ONLY - Requires elevated permissions. ⚠️ DESTRUCTIVE - This action cannot be undone.

Args: namespace: The namespace to clear (e.g., 'user:alice'). include_children: Also clear child namespaces (default: True).

Returns: Confirmation with count of deleted references.

Get detailed cache statistics.

⚠️ ADMIN ONLY - Requires elevated permissions.

Returns: Dictionary with cache statistics including: - Total references and counts by namespace - Active vs expired reference counts - Value type breakdown - Cache configuration