Olá a todos,
Hoje vamos falar sobre algo que preocupa muitos dos utilizadores de AI, especialmente para quem se preocupa com privacidade e precisão: o Docs MCP Server.
Para quem me conhece, sabem que sou um defensor ferrenho de soluções self-hosted que nos dão controlo total sobre os nossos dados e processos. E esta ferramenta é exactamente isso – uma solução privada e local que transforma qualquer assistente de IA numa fonte de informação sempre actualizada e precisa que evita alucinações e está sempre atualizada em termos de código e respostas que apresenta, desde que tenhamos a disciplina de a a manter atualizada.
O Problema Real dos Assistentes de IA no desenvolvimento ou administração de sistemas.
Antes de mergulharmos na solução, sejamos honestos sobre os problemas que todos enfrentamos diariamente com os assistentes de IA:
O conhecimento desactualizado é provavelmente o mais frustrante. Os modelos de linguagem são treinados com snapshots da internet, rapidamente ficando para trás das novas versões de bibliotecas e mudanças de API. Quantas vezes já receberam sugestões de código que funcionavam… há dois anos? É como consultar um manual técnico de 2022 para resolver problemas de 2025.
Depois temos as alucinações de código ou comandos. A IA pode inventar código/comandos que parecem plausíveis, com aparência de sintaxe correcto, mas ou não funciona corretamente ou utiliza APIs e opções que simplesmente não existem – isto é cada vez mais visível com perguntas técnicas ao chatgpt.
É como aquele colega que fala com muita confiança sobre algo que não sabe realmente. O resultado? Gastamos tempo a debuggar código que nunca poderia funcionar.
A ambiguidade de versões é outro problema subtil mas devastador. As respostas genéricas raramente consideram as dependências específicas do vosso projecto, levando a bugs subtis e incompatibilidades. Por examplo para quem trabalha com React 18 sabe que não é igual a trabalhar com React 17, mas a maior parte das IA’s genericas nem sempre faz essa distinção. E quando faz, frequentemente mistura sintaxe e conceitos de versões diferentes.
Tudo isto leva a tempestade perfeita que é um enorme overhead de verificação de código ou procedimentos. Passamos tempo valioso a verificar as sugestões da IA contra a documentação oficial, perdendo uma das principais vantagens que esperávamos ter – a velocidade. Acabamos por ter a IA como um primeiro rascunho que precisa sempre de fact-checking.
Enter Docs MCP Server: A Solução Self-Hosted
Agora que vimos qual o problema, qual uma das soluções? O Docs MCP Server resolve este problema actuando como uma base de conhecimento pessoal e sempre actualizada para o vosso assistente de IA. O seu objectivo principal é indexar documentação de terceiros – as bibliotecas que realmente usam no vosso código.
Por exemplo, no meu caso, e já falei disto no passado tenho a minha própria Knowledge base interna de coisas, código, scripts e notas que guardei nos últimos 30 anos em que trabalho.
Coisas tão básicas como scripts em ksh da altura do HPUX, a ioscan’s, a tanta nota e pensamento que escrevi. Tudo isto indexado e lido pela minha IA pessoal que me oferece uma perspectiva muito própria do problema que lhe apresento.
Como Funciona a coisa?
Esta ferramenta é, na essência, um sistema inteligente de indexação e pesquisa. Primeiro, extrai documentação directamente da fonte, seja de websites, repositórios GitHub, gestores de pacotes como npm ou PyPI, ou até ficheiros locais. Depois processa e indexa semanticamente toda essa informação, dividindo a documentação em chunks semânticos e gerando embeddings que permitem pesquisas muito mais inteligentes.
O sistema fornece pesquisa híbrida, combinando similaridade vectorial com pesquisa de texto completo. Isto significa que não só encontra correspondências exactas, mas também compreende o contexto e a intenção das vossas queries. Por fim, integra-se via Model Context Protocol (MCP), disponibilizando as ferramentas de pesquisa directamente no nosso assistente de IA. É como dar ao nosso assistente acesso directo à documentação mais recente de todas as bibliotecas que usam.
Porquê Self-Hosted? Porquê Privado?
Para quem me conhece, sabem que tenho uma obsessão saudável com privacidade e controlo do código que corro e onde o corro. O Docs MCP Server corre inteiramente na nossa máquina, o que significa privacidade total – os nossos dados e queries ficam locais. Temos controlo completo sobre que documentação indexar e como o sistema funciona. Não há dependências externas que possam desaparecer ou mudar de políticas, e podem customizar tudo às necessidades específicas do vosso projecto.
Inclusive, sendo os dados locais, podem isolar complemente o vosso ambiente por rede se for isso que vos descansada mais a alma.
Principais Funcionalidades que Fazem a Diferença
Conhecimento Sempre Actualizado
Como a ferramenta obtém documentação directamente da fonte, garantindo que têm sempre a informação mais recente, os dados e informação que ela possui é sempre atualizado. Quando uma biblioteca lança uma nova versão, podem re-indexar e ter acesso imediato às mudanças. Isto elimina completamente o problema do conhecimento desactualizado que plageia os assistentes de IA tradicionais ditos mainstream.
Pesquisa Consciente de Versões
Outra das funcionalidades mais poderosas é a capacidade de fazer queries específicas para versões exactas. Por exemplo, podemos perguntar especificamente sobre [email protected] vs [email protected]. Isto garante que as respostas são relevantes para as dependências específicas do vosso projecto, eliminando a confusão entre versões diferentes.
Redução Dramática de Alucinações
Ao fundamentar o LLM em documentação real e verificada, o sistema reduz drasticamente as “invenções” da IA. Em vez de adivinhar como uma API funciona, a IA baseia-se em informação verificada directamente da fonte oficial. É a diferença entre especular e saber. No more guess work, no more Woodstock vibes.
Interface Web Intuitiva
Além da integração com assistentes de IA – por exemplo o openwebui – , a ferramenta oferece uma interface web para pesquisar e gerir documentação directamente no browser. Isto é especialmente útil para explorar documentação ou verificar rapidamente algo sem precisar de abrir o vosso assistente de IA, afinal de contas a informação só é boa quando é verdadeiramente acessivel.
Compatibilidade Ampla
O sistema suporta múltiplas fontes de documentação. Podemos indexar websites de documentação oficial, repositórios GitHub inteiros, gestores de pacotes como npm ou PyPI, e até directórios de ficheiros locais ou Wiki’s (wiki ou dokuwiki). Esta flexibilidade significa que podemos criar uma base de conhecimento verdadeiramente abrangente, como falei acima em relação a minha knowledge base.
Flexibilidade de Modelos
O Docs MCP Server suporta múltiplos fornecedores de embeddings, incluindo OpenAI (e APIs compatíveis como Ollama), Google Gemini/Vertex AI, Azure OpenAI, AWS Bedrock, e outros via APIs compatíveis. Esta flexibilidade permite-vos escolher o modelo que melhor se adapta às vossas necessidades, orçamento ou desejo de privacidade.
Implementação Prática: Mãos à Obra
Vamos ao que interessa – como implementar esta solução no nosso ambiente.
Para uma implementação robusta e fácil de gerir, recomendo o Docker Compose. Esta abordagem simplifica a gestão de dependências e garante que tudo funciona out-of-the-box (se bem que todas as recomendações do passado se aplicam):
# docker-compose.yml
version: '3.8'
services:
docs-mcp-server:
image: ghcr.io/arabold/docs-mcp-server:latest
environment:
- OPENAI_API_KEY=your-api-key-here
- DOCS_MCP_EMBEDDING_MODEL=text-embedding-3-small
volumes:
- docs-mcp-data:/data
ports:
- "6280:6280"
- "6281:6281"
restart: unless-stopped
volumes:
docs-mcp-data:
Configuração no Vosso Assistente de IA
Para Claude, Cline, ou Roo, adicionem a seguinte configuração ao vosso settings:
{
"mcpServers": {
"docs-mcp-server": {
"url": "http://localhost:6280/sse",
"disabled": false,
"autoApprove": []
}
}
}
Para Openwebui, adicionem e utilizem o método tradicional de MCP/Tools server:
Primeiro Uso: Indexar Documentação
O processo inicial é bastante simples. Acedem à interface web em http://localhost:6281 e começam a adicionar documentação. Por exemplo, para indexar a documentação do React, introduzem a URL https://react.dev/reference/react, definem o nome da biblioteca como “react” e especificam a versão “18.2.0”. A interface mostra o progresso do job de indexação, e podem repetir este processo para cada biblioteca que usam nos vossos projectos.
O resto fica dependente da vossa imaginação e do que querem fazer. É irem adicionando dados para scraping e referencia. Quantos mais, mais memoria será usada, mas a qualidade do que a vossa AI produz terá saltos qualitativos.
Casos de Uso Práticos
Para Equipas de Desenvolvimento
Numa equipa, esta ferramenta resolve múltiplos problemas de uma só vez. Durante o onboarding, novos membros têm acesso imediato a toda a documentação das tecnologias usadas, eliminando a curva de aprendizagem típica. Toda a equipa trabalha com a mesma base de conhecimento, garantindo consistência nas implementações. E claro, reduz drasticamente o tempo gasto em pesquisas manuais, permitindo que a equipa se concentre na resolução de problemas reais.
Para Ambientes Restritivos
Para organizações com requisitos de segurança rigorosos, a ferramenta funciona completamente offline após a indexação inicial. Cumpre requisitos de privacidade e segurança porque tudo fica local, e não há dependências de serviços externos que possam comprometer a segurança ou disponibilidade.
Para Equipas de Administração de Sistemas.
Em organizações com bases de dados maciças de conhecimento, procedimentos – confluence, wiki’s e afins -, listas de contactos globais onde não se sabe bem quem faz o que, ter um sistema que responda a perguntas, por exemplo indicando as referencias onde consultar a informação é extremamente util.
Em Projectos Complexos
Em projectos com múltiplas tecnologias, podem indexar documentação de todas as bibliotecas do projecto, criando uma base de conhecimento centralizada. A capacidade de manter documentação para versões exactas das dependências é crucial para evitar incompatibilidades. E podem até automatizar a re-indexação quando actualizarem dependências, mantendo sempre tudo sincronizado.
E Sobre Vantagens Competitivas?
Comparado com Soluções SaaS
A diferença mais óbvia é a privacidade – todos os dados ficam locais. Não há custos recorrentes ou limites de utilização impostos por terceiros. Podem personalizar completamente a ferramenta às vossas necessidades específicas, e não dependem de serviços externos que podem falhar ou mudar de políticas e a atualização dos vossos dados são vão depender de vocês, ao invés de snapshots corridos por terceiros.
Comparado com Pesquisa Manual
A velocidade é incomparável – pesquisa instantânea através de IA em vez de navegar manualmente por documentação. As respostas são integradas directamente no vosso fluxo de trabalho, sem necessidade de alternar entre janelas. E a pesquisa semântica é muito mais eficaz que simples keywords, compreendendo contexto e intenção.
Comparado com Documentação Offline
A actualização é muito mais simples – basta re-indexar quando necessário. A pesquisa inteligente vai muito além do tradicional Ctrl+F, compreendendo relações semânticas entre conceitos. E tudo se integra directamente no vosso assistente de IA, eliminando fricção no fluxo de trabalho.
Configurações Avançadas
Embedding Models Locais com Ollama
Para quem prefere total independência, podem usar o Ollama para embeddings locais. Primeiro configurem o Ollama localmente e fazem pull do modelo de embeddings. Depois configuram o Docs MCP Server para usar o endpoint local. Esta abordagem elimina completamente dependências externas, incluindo para os embeddings.
# Configurar Ollama localmente
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec -it ollama ollama pull nomic-embed-text
# Configurar Docs MCP Server
OPENAI_API_BASE=http://localhost:11434/v1
DOCS_MCP_EMBEDDING_MODEL=nomic-embed-text
Indexação Automática
Para ambientes de produção, recomendo criar scripts que automatizem a indexação. Podem integrar isto nos vossos pipelines de CI/CD para garantir que a documentação está sempre actualizada quando as dependências mudam.
#!/bin/bash
# update-docs.sh
docker run --rm \
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
-v docs-mcp-data:/data \
ghcr.io/arabold/docs-mcp-server:latest \
docs-cli scrape https://react.dev/reference/react react 18.2.0
Nota: a parte a reter no exemplo anterior é o docs-cli que faz scans e retreivel a nova informação que desejam atualizar.
Considerações de Performance
Gestão de Recursos
Como em qualquer sistema que trabalha com embeddings, há considerações importantes de performance. Os embeddings consomem RAM, por isso monitorizem o uso de memória, especialmente se indexarem muita documentação. A documentação indexada ocupa espaço em disco, e a indexação inicial pode ser intensiva em termos de CPU/GPU compute.
Optimizações
A chave está na indexação selectiva – só indexem o que realmente precisam. Executem re-indexação fora do horário de trabalho para minimizar impacto na performance. E implementem logging adequado para identificar problemas antes que se tornem críticos.
Documentos .txt (no caso da documentação local são vossos amigos – se forem como eu e carregarem compêndios inteiros de tips and tricks for advanced bash programming, convertam o ebook para txt, tirem os dados que não vos interessam, por exemplo capas, contra capaz e agradecimentos, e destilem ao máximo o que querem que o vosso LLM carregue.
Roadmap e Futuro
Esta ferramenta está em desenvolvimento activo, com funcionalidades prometedoras no horizonte. Uma extensão VS Code está planeada para integração nativa no editor. O suporte para mais fornecedores de embeddings está em expansão, juntamente com melhorias contínuas de performance. A API também está a ser expandida para permitir integrações mais profundas.
Próximos Passos
Se este artigo vos interessou, recomendo que experimentem numa máquina de teste primeiro. Comecem por indexar uma ou duas bibliotecas familiares para perceber como funciona. Depois integrem com o vosso assistente de IA preferido e avaliem o impacto na qualidade das respostas.
Para os Mais Aventureiros
Para quem quer ir mais longe, considerem contribuir para o projecto – é open-source e aceita contribuições. Podem também customizar a ferramenta às necessidades específicas da vossa organização, ou expandir a integração com outras ferramentas do vosso pipeline de desenvolvimento.
E chegamos ao fim de mais um post semanal. O Docs MCP Server representa exactamente o tipo de solução que acredito que devemos abraçar: poderosa, privada, e sob o nosso controlo. Não é apenas uma ferramenta – é uma filosofia de como devemos interagir com a IA no desenvolvimento.Vivemos numa era onde a assistência de IA é inevitável, mas isso não significa que devemos sacrificar privacidade ou precisão. Com soluções como esta, podemos ter o melhor dos dois mundos: a conveniência da IA com a confiança de dados verificados e locais.
O Docs MCP Server não é apenas mais uma ferramenta – é uma forma muito pratica de afinar e fazer com que a IA trabalhe para nós, em vez de contra nós. Ao manter o controlo sobre os dados e garantir precisão, podemos finalmente confiar nas respostas que recebemos.
Para mim, esta é a direcção certa: soluções que nos empoderam sem nos comprometer. Self-hosted, privado, preciso, e sempre actualizado.
Que acham? Experimentem. Garanto que não se irão arrepender.
Até ao próximo post, aquele abraço e ja sabem, se notarem algo menos correcto, já sabem onde me encontrar.
Nuno Higgs