Referência de ferramentas MCP

O servidor MCP do Tube Search fornece 10 ferramentas para pesquisar, ler e analisar dados arquivados do YouTube.

search_channel

Encontre todos os vídeos conhecidos de um canal do YouTube pesquisando em arquivos web.

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	URL do canal, @handle ou Channel ID (ex.: `UC...`)

Retorna um array de metadados de vídeo incluindo status (LIVE, DELETED, CHECKING).

A pesquisa por canal consulta primeiro o cache do banco de dados. Se o canal nunca foi pesquisado antes, executa uma indexação completa dos arquivos que pode levar 1-2 minutos.

search_videos

Pesquisa de texto completo em títulos e descrições de vídeos arquivados.

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Consulta de pesquisa (suporta linguagem natural)
`limit`	number	Não	Máx. resultados (padrão: 20, máx.: 100)
`status`	string	Não	Filtrar por status: `live`, `deleted`, `all`
`sort`	string	Não	`relevance` (padrão) ou `date-desc`
`hasSubtitles`	boolean	Não	Apenas vídeos com legendas
`hasSummary`	boolean	Não	Apenas vídeos com resumos IA

get_video

Obter metadados de um vídeo específico.

Parâmetro	Tipo	Obrigatório	Descrição
`videoId`	string	Sim	ID do vídeo do YouTube (11 caracteres)

Retorna: title, description, channelId, channelTitle, duration, uploadDate, viewCount, status, thumbnailUrl, subtitleStatus, hasSummary. Para vídeos enriquecidos via nosso pipeline de proveniência do Yandex.Video, a resposta inclui também um objeto yandex aninhado com as chaves internal_id, attribution, preview_url e scanned_at — veja a subseção «Proveniência do enriquecimento do Yandex» abaixo.

Proveniência do enriquecimento do Yandex

Quando get_video retorna um objeto yandex aninhado, o campo yandex.attribution assume um de três valores de nível de confiança. Use a tabela abaixo para decidir se deve citar diretamente um fato sobre este vídeo ou buscar uma segunda fonte.

Nível (valor de `yandex.attribution`)	Ação recomendada	Justificativa
`db_match`	Citar diretamente	O ID do YouTube já existia em nosso banco de dados atribuído a este canal; o Yandex forneceu metadados suplementares (title, duration, upload_date) via preenchimento de campos NULL. Confiança máxima.
`yt_dlp_confirmed`	Citar diretamente	O ID do YouTube foi descoberto pela primeira vez via Yandex; o `yt-dlp` confirmou de forma independente a atribuição ao canal contra os metadados ao vivo do YouTube. Corroboração por duas fontes independentes.
`name_unique_anchor_passed`	Corroborar primeiro	O ID do YouTube foi descoberto pela primeira vez via Yandex; o `yt-dlp` falhou ou expirou; a atribuição se apoia em heurísticas de unicidade do nome e verificação por âncora (pelo menos 2 de K correspondências de títulos de vídeos LIVE). Sinal mais fraco — confirme com uma segunda fonte antes de citar.

Quando yandex.preview_url não é null, ele aponta para um clipe MP4 animado curto (~5 s) de pré-visualização, espelhado a partir do snapshot do Yandex — útil para confirmação visual de como era o vídeo excluído, mas não equivalente ao conteúdo original completo. Quando preview_url é null, os campos de metadados (title, duration, uploadDate) e attribution permanecem válidos; apenas o espelhamento do clipe de pré-visualização não foi bem-sucedido.

get_subtitles

Obter a transcrição completa de um vídeo como texto legível.

Parâmetro	Tipo	Obrigatório	Descrição
`videoId`	string	Sim	ID do vídeo do YouTube

Retorna a transcrição sem marcações de tempo, formatada em parágrafos legíveis. Funciona para vídeos ativos e excluídos que possuam legendas arquivadas.

get_summary

Obter o resumo gerado por IA de um vídeo.

Parâmetro	Tipo	Obrigatório	Descrição
`videoId`	string	Sim	ID do vídeo do YouTube

Retorna: tldr, keyPoints (com marcações de tempo), detailedSummary, tags, language. Retorna um erro se não existir resumo — use generate_summary para criar um.

generate_summary

Gerar um resumo IA para um vídeo que tenha legendas.

Parâmetro	Tipo	Obrigatório	Descrição
`videoId`	string	Sim	ID do vídeo do YouTube

Inicia a geração e aguarda a conclusão (até 60 s). Retorna o resumo se o vídeo já tiver um. Conta para seu limite diário de geração de resumos.

generate_stenogram

Gera um estenograma privado (diálogo palavra por palavra com marcação de falantes) a partir do transcript de um vídeo. Requer nível L3+ (plano MCP + API). O resultado fica em seu espaço de usuário e é visível apenas para você.

Parâmetro	Tipo	Obrigatório	Descrição
`videoId`	string	Sim	ID do vídeo do YouTube (11 caracteres)
`language`	enum	Não	`auto` (padrão), `en`, `ru`, `es`, `de`, `pt`

Retorna: { stenogram, metadata: { llmModel, tokensUsed, promptVersion, generatedAt, language, generationTimeMs } }. Requer transcrição já disponível (legendas arquivadas ou AI). Emite notifications/progress se o cliente enviar progress token. Conta em apiStenogramsPerDay (contador compartilhado com a rota REST).

generate_stenogram fica oculto em tools/list para clientes L<3; qualquer chamada direta com chave abaixo de L3 retorna FORBIDDEN.

browse_summaries

Explorar resumos IA existentes com filtros opcionais.

Parâmetro	Tipo	Obrigatório	Descrição
`tag`	string	Não	Filtrar por tag (ex.: "music", "education")
`channelId`	string	Não	Filtrar por canal
`language`	string	Não	Filtrar por idioma (ex.: "en", "pt")
`page`	number	Não	Número da página (padrão: 1)
`limit`	number	Não	Resultados por página (padrão: 20)

get_video_status_history

Visualizar o histórico de alterações de status de um vídeo.

Parâmetro	Tipo	Obrigatório	Descrição
`videoId`	string	Sim	ID do vídeo do YouTube

Retorna um array de transições de status: [{ status, previousStatus, changedAt, source }], mais recentes primeiro.

get_usage

Verificar os contadores atuais de uso da API e os limites restantes.

Sem parâmetros. Retorna os contadores e limites atuais para pesquisas, consultas FTS, downloads de legendas e gerações de resumos.

← Voltar ao guia MCP