MCP e ferramentas

O que é o MCP

O Model Context Protocol é o padrão que permite ao modelo chamar ferramentas externas. No Heimdall-ai, os servidores são escritos em Python com a biblioteca FastMCP e o LiteLLM os expõe em http://<host>:9000/mcp para os clientes.

Servidores MCP
Nome	Função	Endereço	Transporte
`heimdall`	Ferramentas do Mac (admin)	http://localhost:8000/mcp	http
`heimdall_public`	Ferramentas públicas (convidados)	http://localhost:8001/mcp	http
`aws_docs`	Documentação oficial da AWS	uvx (stdio)	stdio

Os grupos de ferramentas são separados de propósito: o Open WebUI dos convidados se conecta só ao grupo público (porta 8001), e o grupo do Mac fica restrito ao administrador.

Ferramentas públicas

Seguras para convidados. Servidas na porta 8001.

`search_searxng`

search_searxng(query)

Pesquisa informações recentes, notícias ou dados na web usando o SearXNG local.

`calculate_expression`

calculate_expression(expression)

Calcula uma expressão matemática. Aceita + - * / // % ** ^, parênteses, pi, e e as funções sqrt, sin, cos, tan, log, log10, exp, abs, round.

`get_system_timestamp`

get_system_timestamp()

Retorna a data e a hora atuais do sistema.

`get_hackernews_top_stories`

get_hackernews_top_stories()

Busca as 5 principais histórias em alta no Hacker News.

`search_reddit_posts`

search_reddit_posts(subreddit, query='')

Busca posts em um subreddit (ex: Python, MachineLearning). Com query pesquisa; sem query lista os posts em alta.

`fetch_rss_feed`

fetch_rss_feed(feed_url)

Lê as últimas notícias de um feed RSS ou Atom, a partir da URL completa do feed (começando com http:// ou https://).

`get_astronomy_apod`

get_astronomy_apod()

Retorna a Astronomia do Dia da NASA (APOD): título, explicação e link da mídia.

`get_youtube_transcript`

get_youtube_transcript(video, language='pt', offset=0)

Obtém a transcrição (legendas) de um vídeo do YouTube a partir da URL ou do ID. language é o idioma preferido (pt, en, es...). Para vídeos longos, a resposta vem em partes: use offset com o valor indicado no final para continuar.

`fetch_url`

fetch_url(url, offset=0)

Lê o texto de uma página da web (HTML, texto ou JSON) a partir da URL completa. Para páginas longas, a resposta vem em partes: use offset com o valor indicado no final para continuar.

Ferramentas do Mac (administrador)

Acessam arquivos, métricas e memória do computador. Servidas na porta 8000; só para o dono.

`list_directory`

list_directory(path='')

Lista arquivos e subpastas dentro da pasta do usuário no Mac. Sem argumento, lista a pasta raiz do usuário.

`read_file`

read_file(file_path)

Lê o conteúdo de um arquivo de texto na pasta do usuário no Mac (até 6000 caracteres).

`write_file`

write_file(file_path, content)

Escreve ou sobrescreve um arquivo de texto na pasta do usuário no Mac. Não grava em pastas ocultas (começam com ponto).

`get_system_metrics`

get_system_metrics()

Retorna o uso atual de RAM, swap e CPU do Mac (host do Heimdall).

`get_disk_usage`

get_disk_usage()

Retorna o espaço total, usado e livre do disco principal do Mac.

`check_ollama_models`

check_ollama_models()

Lista os modelos carregados agora na memória pelo Ollama local.

`memory_save`

memory_save(text, tags='')

Guarda uma informação duradoura (preferência, fato, decisão) para lembrar em conversas futuras. Use somente quando o usuário pedir para lembrar algo. Nunca guarde senhas, chaves ou dados sensíveis.

`memory_search`

memory_search(query='', limit=5)

Busca nas memórias guardadas por palavras-chave. Sem query, lista as mais recentes.

`memory_forget`

memory_forget(memory_id)

Apaga uma memória pelo id (mostrado por memory_search).

`rag_search`

rag_search(query, top_k=4, tema='')

Busca trechos relevantes nos documentos pessoais do usuário (base de conhecimento). Use para perguntas sobre notas, PDFs e arquivos que o usuário indexou. O parâmetro tema (opcional) restringe a busca a uma subpasta de knowledge/; veja os nomes com rag_temas.

`rag_temas`

rag_temas()

Lista os temas (subpastas de knowledge/) da base de conhecimento e quantos trechos cada um tem. Use antes do rag_search quando quiser buscar só em um assunto.

Como testar

Testa os dois grupos direto e pelo LiteLLM

venv/bin/python test_mcp.py

Testa pelo IP do Tailscale

venv/bin/python test_mcp.py <IP-do-Tailscale>

Como criar uma ferramenta nova

Escreva a função em heimdall_tools.py, com anotação de tipos e um docstring claro (é o que o modelo lê para decidir quando usar).
Acrescente-a a PUBLIC_TOOLS (segura para convidados) ou MAC_TOOLS (acessa o Mac).
Reinicie o sistema e rode test_mcp.py.
Rode python3 gerar_docs.py: esta página se atualiza sozinha.