video-research-mcp

Analyze a video (YouTube URL or local file) with any instruction.

Provide exactly one of url or file_path. Uses Gemini's structured output for reliable JSON responses. Pass a custom output_schema to control the response shape, or use the default VideoResult schema.

When strict_contract=True, runs the full contract pipeline: analysis with strict Pydantic models, parallel strategy/concept-map generation, artifact rendering, and quality gates. Returns richer output but takes longer.

Args: url: YouTube video URL. file_path: Path to a local video file. instruction: What to analyze or extract from the video. output_schema: Optional JSON Schema dict for custom output shape. thinking_level: Gemini thinking depth. use_cache: Whether to use cached results. strict_contract: Run strict contract pipeline with quality gates.

Returns: Dict matching VideoResult schema (default), custom output_schema, or strict contract output with analysis, strategy, concept_map, artifacts.

Create a persistent session for multi-turn video exploration.

Provide exactly one of url or file_path. When download=True and the source is YouTube, the video is downloaded via yt-dlp, uploaded to the Gemini File API, and context-cached for fast multi-turn use.

Args: url: YouTube video URL. file_path: Path to a local video file. description: Optional focus area for the session. download: Download YouTube video for cached sessions.

Returns: Dict with session_id, status, video_title, source_type, cache/download status, and optional local_filepath when a local file is available.

Continue analysis within an existing video session.

Args: session_id: Session ID returned by video_create_session. prompt: Follow-up question about the video.

Returns: Dict with response text and turn_count.

Analyze all video files in a directory concurrently.

Scans the directory for supported video files (mp4, webm, mov, avi, mkv, mpeg, wmv, 3gpp), then analyzes each with the given instruction using bounded concurrency (3 parallel Gemini calls).

Args: directory: Path to a directory containing video files. instruction: What to analyze in each video. glob_pattern: Glob to filter files (default "*" matches all). output_schema: Optional JSON Schema dict for each result. thinking_level: Gemini thinking depth. max_files: Maximum number of files to process.

Returns: Dict with directory, counts, and per-file results.

Run multi-phase deep research with evidence-tier labeling.

Phases: Scope Definition -> Evidence Collection -> Synthesis. Every claim is labeled CONFIRMED, STRONG INDICATOR, INFERENCE, SPECULATION, or UNKNOWN.

Args: topic: Research question or subject area. scope: Research depth — "quick", "moderate", "deep", or "comprehensive". thinking_level: Gemini thinking depth.

Returns: Dict with topic, scope, executive_summary, findings, open_questions.

Generate a multi-agent research orchestration plan.

Returns a phased blueprint with task decomposition and model assignments. Does NOT spawn agents — provides the blueprint for the caller.

Args: topic: Research question or subject area. scope: Research depth. available_agents: Number of agents the caller can deploy (1-50).

Returns: Dict with topic, scope, phases, and task_decomposition.

Assess a claim against sources, returning evidence tier and confidence.

Args: claim: Statement to verify. sources: List of evidence sources. context: Optional background for the assessment.

Returns: Dict with claim, tier, confidence, and reasoning.

Run multi-phase deep research grounded in source documents.

Phases: Document Mapping -> Evidence Extraction -> Cross-Reference -> Synthesis. Every claim is labeled with evidence tiers and cited back to source documents.

Args: instruction: Research question or what to analyze across documents. file_paths: Local paths to PDF or text files. urls: URLs to downloadable documents. scope: Research depth -- quick, moderate, deep, comprehensive. thinking_level: Gemini thinking depth.

Returns: Dict with document_sources, executive_summary, findings, cross_references.

Launch a Gemini Deep Research Agent for autonomous web-grounded research.

The agent plans its own research, searches the web (~80-160 queries), reads sources, and produces a cited markdown report. Runs in background; poll with research_web_status. Costs $2-5 per task, takes 10-20 minutes.

Args: topic: Research brief — include specific questions, scope, hypotheses. output_format: Optional report structure instructions.

Returns: Dict with interaction_id and status, or error via make_tool_error().

Poll or retrieve a Deep Research task.

Returns the full report with sources when completed, or current status if still in progress. Auto-stores completed reports to Weaviate.

Args: interaction_id: The interaction ID from research_web.

Returns: Dict with status and report (if completed), or error.

Ask a follow-up question about a completed Deep Research report.

Uses previous_interaction_id to maintain context from the original research. Synchronous — follow-ups are fast (no background needed).

Args: interaction_id: The completed interaction ID. question: Follow-up question.

Returns: Dict with new interaction_id, previous_interaction_id, and response.

Cancel a running Deep Research task.

Sends a cancel request to the Interactions API and cleans up local tracking state. Useful for aborting expensive ($2-5) tasks early.

Args: interaction_id: The interaction ID from research_web.

Returns: Dict with interaction_id and status, or error via make_tool_error().

Search academic papers on Semantic Scholar.

Returns papers with metadata, abstracts, citation counts, and TL;DR summaries. Supports filtering by field of study, year range, and open access availability.

Args: query: Search terms (title, abstract, keywords). fields_of_study: Filter by academic fields. year_range: Year or year range filter. open_access_only: Only open access papers. limit: Maximum number of papers.

Returns: Dict with total count and list of papers.

Get detailed metadata for a specific paper.

Accepts Semantic Scholar IDs, DOIs (prefix with DOI:), or ArXiv IDs (prefix with ArXiv:).

Args: paper_id: Paper identifier in any supported format.

Returns: Dict with full paper metadata.

Get citations or references for a paper.

Args: paper_id: Paper identifier. direction: 'citations' for papers citing this one, 'references' for this paper's bibliography. limit: Maximum number of papers.

Returns: Dict with paper_id, direction, and list of related papers.

Get paper recommendations based on seed papers.

Uses Semantic Scholar's recommendation engine to find related papers.

Args: seed_paper_ids: One or more paper IDs as seeds. limit: Maximum recommendations.

Returns: Dict with seed IDs and recommended papers.

Search for academic authors on Semantic Scholar.

Returns author profiles with affiliation, paper count, citation count, and h-index.

Args: query: Author name or partial name. limit: Maximum authors to return.

Returns: Dict with list of author profiles.

Analyze content (file, URL, or text) with any instruction.

Provide exactly one of file_path, url, or text. Uses Gemini's structured output for reliable JSON responses. Pass a custom output_schema to control the response shape, or use the default ContentResult schema.

Args: instruction: What to analyze or extract from the content. file_path: Path to a local PDF or text file. url: URL to fetch and analyze. text: Raw text content. output_schema: Optional JSON Schema dict for custom output shape. thinking_level: Gemini thinking depth.

Returns: Dict matching ContentResult schema (default) or the custom output_schema.

Extract structured data from content using a JSON Schema.

Uses Gemini's response_json_schema for guaranteed structured output.

Args: content: Source text to extract data from. schema: JSON Schema describing the desired output structure.

Returns: Dict matching the provided schema, or error dict on parse failure.

Analyze multiple content files from a directory or explicit file list.

Supports two modes: 'compare' sends all files to Gemini in a single call for cross-document analysis, 'individual' analyzes each file separately with bounded concurrency (3 parallel calls).

Args: instruction: What to analyze or extract from the content. directory: Directory to scan for content files. file_paths: Explicit list of file paths to analyze. glob_pattern: Glob to filter files in directory mode. mode: 'compare' or 'individual' analysis mode. output_schema: Optional JSON Schema dict for custom output shape. thinking_level: Gemini thinking depth. max_files: Maximum number of files to process.

Returns: Dict with file counts, per-file items, and optional comparison result.

Search the web using Gemini's built-in Google Search grounding.

Args: query: Search terms. num_results: How many results to return (1-20).

Returns: Dict with query, response text, and grounding sources.

Manage the analysis cache — stats, list, clear, or inspect context cache state.

Args: action: Cache operation — "stats", "list", "clear", or "context". content_id: When action is "clear", limit deletion to this content ID.

Returns: Dict with operation-specific results (file_count, entries, removed count, or context cache diagnostics).

Reconfigure the server at runtime — preset, model, thinking level, or temperature.

Changes take effect immediately for all subsequent tool calls.

Args: preset: Named model preset — resolves to a default_model + flash_model pair. model: Gemini model ID (takes precedence over preset's default_model). thinking_level: Thinking depth — "minimal", "low", "medium", or "high". temperature: Sampling temperature (0.0–2.0).

Returns: Dict with current_config, active_preset, and available_presets.

Fetch YouTube video metadata without Gemini analysis.

Returns title, description, view/like/comment counts, duration, tags, channel info, category, and language. Costs 1 YouTube API unit, 0 Gemini units.

Args: url: YouTube video URL.

Returns: Dict matching VideoMetadata schema.

Fetch top YouTube comments sorted by relevance.

Returns comment text, like count, and author for each comment. Costs 1+ YouTube API units, 0 Gemini units.

Args: url: YouTube video URL. max_comments: Maximum number of comments to return.

Returns: Dict with video_id, comments list, and count, or error via make_tool_error().

Get video IDs and titles from a YouTube playlist.

Results can be passed to video_analyze for batch analysis. Costs 1 YouTube API unit per page (max 50 items/page).

Args: url: YouTube playlist URL. max_items: Maximum number of playlist items to return.

Returns: Dict matching PlaylistInfo schema.

Search across knowledge collections using hybrid, semantic, or keyword mode.

Searches specified or all collections. Results are merged and sorted by score. Filters are collection-aware: conditions are skipped for collections that lack the relevant property.

Args: query: Text to search for. collections: Which collections to search (default: all). search_type: Search algorithm — hybrid, semantic (near_text), or keyword (BM25). limit: Maximum total results to return. alpha: Hybrid balance (only used when search_type="hybrid"). evidence_tier: Filter ResearchFindings by evidence tier. source_tool: Filter any collection by originating tool. date_from: Filter objects created on or after this ISO date. date_to: Filter objects created on or before this ISO date. category: Filter VideoMetadata by category label. video_id: Filter by video_id field.

Returns: Dict matching KnowledgeSearchResult schema.

Find semantically related objects using near-object vector search.

Args: object_id: UUID of the source object. collection: Collection the source object belongs to. limit: Maximum number of related results.

Returns: Dict matching KnowledgeRelatedResult schema.

Get object counts per collection, optionally grouped by a property.

Args: collection: Single collection name, or None for all collections. group_by: Text property name to group counts by.

Returns: Dict matching KnowledgeStatsResult schema.

Fetch a single object by UUID from a knowledge collection.

Args: object_id: UUID of the object to retrieve. collection: Collection the object belongs to.

Returns: Dict matching KnowledgeFetchResult schema.

Manually insert data into a knowledge collection.

Properties are validated against the collection schema — unknown keys are rejected with allowed name:type pairs.

Tip: call knowledge_schema(collection=...) first to see expected properties.

Args: collection: Target collection name. properties: Dict of property values matching the collection schema.

Returns: Dict matching KnowledgeIngestResult schema.

Ask a question and get an AI-generated answer grounded in stored knowledge.

Uses Weaviate AsyncQueryAgent in ask mode to synthesize an answer from objects across knowledge collections, with source citations.

Args: query: Natural language question. collections: Which collections to search (default: all).

Returns: Dict matching KnowledgeAskResult schema, or error dict.

[DEPRECATED] Search knowledge store using natural language.

Deprecated: Use knowledge_search instead, which now includes Cohere reranking and Flash summarization for better results with lower token usage.

Uses Weaviate AsyncQueryAgent in search mode for intelligent object retrieval.

Args: query: Natural language search query. collections: Which collections to search (default: all). limit: Maximum number of results.

Returns: Dict matching KnowledgeQueryResult schema, or error dict.

Return property schemas for knowledge collections.

Reads from local CollectionDef objects — no Weaviate connection needed. Use this before knowledge_ingest to discover expected property names and types.

Args: collection: Single collection name, or None for all collections.

Returns: Dict mapping collection names to lists of {name, type, description}.