Kitbag MCP

Kitbag MCP é um servidor único e de código aberto do Model Context Protocol que reúne uma biblioteca selecionada de mais de 50 ferramentas utilitárias de alto valor — conversores de documentos, processadores de OCR, raspadores web, formatadores de dados e utilitários de desenvolvimento para IA — tudo em um só lugar.

Em vez de instalar, configurar e pagar para hospedar uma dúzia de servidores MCP de propósito único, instale o Kitbag MCP uma vez e habilite seletivamente apenas os módulos que você precisa. Ele é executado inteiramente na sua máquina: custo zero de hospedagem, sem chaves de API, sem configuração de servidor.

---

📖 Índice

Clique para expandir

• 🚀 Início Rápido
• ⚙️ Configuração de Clientes
  • Claude Desktop
  • Cursor
  • Windsurf
• 🎛️ Configuração
• 🗺️ Índice de Categorias de Ferramentas
• 📚 Diretório Completo de Ferramentas
  • 📄 Ferramentas de PDF
  • 🌐 Raspagem Web e Redes
  • 📸 Ferramentas de Imagem e OCR
  • 📊 Transformação de Dados
  • 💻 Utilitários para Desenvolvedores
  • 🛠️ Ferramentas Utilitárias
  • 🧠 Fragmentador de IA
• 🏗️ Arquitetura
• 🛠️ Desenvolvimento Local e Contribuições
• ⚖️ Licença

---

🚀 Início Rápido (Zero Configuração)

Execute instantaneamente usando npx (Node.js necessário):

npx kitbag-mcp

Expor Módulos Específicos (Economiza Tokens de Contexto do LLM)

Para evitar que seus agentes de IA fiquem sobrecarregados com opções de ferramentas, habilite apenas o que você precisa:

# Enable PDF and Web scraping modules only
npx kitbag-mcp --enabled-modules pdf,web

---

⚙️ Configuração de Clientes Suportados

1. Claude Desktop

Adicione esta entrada ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "kitbag-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kitbag-mcp",
        "--enabled-modules",
        "pdf,web,image,data,utility,ai"
      ]
    }
  }
}

2. Cursor

1. Vá para Configurações → Recursos Beta → MCP.
2. Clique em + Adicionar Novo Servidor MCP.
3. Configure:
   • Nome: Kitbag MCP
   • Tipo: stdio
   • Comando: npx -y kitbag-mcp --enabled-modules pdf,web,data,utility

3. Windsurf

Adicione esta entrada ao seu mcp_config.json:

{
  "mcpServers": {
    "kitbag-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kitbag-mcp"
      ],
      "env": {
        "KITBAG_ENABLED_MODULES": "pdf,web,data,utility"
      }
    }
  }
}

---

🎛️ Flags de Configuração e Variáveis de Ambiente

O Kitbag MCP pode ser configurado por meio de flags de CLI, variáveis de ambiente ou um arquivo de configuração JSON — o que melhor se adequar ao seu fluxo de trabalho.

Fonte de Configuração	Exemplo de Uso
Flags de CLI	--enabled-modules pdf,web ou --enabled-tools utility.qr_generate
Variáveis de Ambiente	KITBAG_ENABLED_MODULES=pdf,web ou KITBAG_ENABLED_TOOLS=utility.qr_generate
Config JSON	Um arquivo kitbag-config.json no diretório de trabalho atual, ou via --config /path/to/config.json

Esquema kitbag-config.json:

{
  "enabledModules": ["pdf", "web", "image", "data", "utility", "ai", "developer"],
  "enabledTools": [],
  "defaultTimeoutMs": 30000,
  "maxPayloadSizeBytes": 52428800
}

---

🗺️ Índice de Categorias de Ferramentas

---

📚 Diretório Completo de Ferramentas

📄 Ferramentas de PDF (pdf.*)

Analisadores e manipuladores de PDF locais de alto desempenho.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
pdf.convert_to_text	Extrai texto bruto de um documento PDF.	"Extraia o texto de reports/invoice.pdf"
pdf.convert_to_markdown	Analisa o PDF e o formata em Markdown limpo.	"Converta o layout de guide.pdf para markdown"
pdf.extract_images	Extrai imagens brutas incorporadas em um PDF.	"Extraia todas as imagens de slide_deck.pdf"
pdf.extract_tables	Extrai dados estruturados de tabelas de páginas de PDF.	"Extraia todas as tabelas de financial_report.pdf"
pdf.merge	Mescla vários arquivos PDF em ordem.	"Mescle doc1.pdf e doc2.pdf em um único arquivo"
pdf.split	Divide intervalos específicos de páginas de um PDF.	"Me dê as páginas 1 a 3 de main_guide.pdf"

---

🌐 Raspagem Web e Redes (web.*)

Interaja com documentos web brutos e consulte sistemas de rede.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
web.to_markdown	Raspa uma página web, remove o excesso e converte para Markdown.	"Converta o artigo em https://example.com/blog para markdown"
web.extract_metadata	Extrai título, descrição, tags OG e dados JSON-LD.	"Obtenha metadados para a URL https://news.ycombinator.com"
web.extract_links	Raspa uma página web e lista links internos e externos.	"Encontre todos os links externos na página da Wikipedia sobre IA"
web.rss_parser	Analisa uma URL de feed RSS ou Atom em XML para JSON.	"Obtenha os itens mais recentes do feed de https://github.blog/feed/"
web.sitemap_generator	Busca e analisa uma URL de sitemap.xml, extraindo todas as URLs.	"Busque todas as URLs no sitemap de google.com"
web.dns_lookup	Realiza resolução de DNS (A, AAAA, MX, TXT, etc.).	"Faça uma consulta de registro MX para o domínio gmail.com"
web.youtube_transcript	Extrai transcrições de texto e legendas com carimbos de data/hora.	"Obtenha a transcrição de https://www.youtube.com/watch?v=dQw4w9"

---

📸 Ferramentas de Imagem e OCR (image.*)

Manipule imagens e extraia texto localmente.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
image.ocr	Extrai texto de uma imagem localmente usando OCR Tesseract.	"Extraia texto de screenshot.png"
image.resize	Redimensiona as dimensões de uma imagem (largura e altura).	"Redimensione avatar.png para 200x200 pixels"
image.compress	Comprime o tamanho do arquivo de imagem com qualidade personalizada.	"Comprima banner.jpg com 80% de qualidade"
image.convert_format	Converte imagens entre formatos (PNG, JPEG, WebP, etc.).	"Converta logo.png para o formato webp"
image.exif_metadata	Extrai metadados EXIF de câmera e localização de arquivos de imagem.	"Mostre-me as coordenadas GPS e o modelo da câmera de photo.jpg"

---

📊 Transformação de Dados (data.*)

Conversão rápida e offline entre formatos de dados padrão.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
data.csv_to_json	Converte arquivo CSV ou texto bruto para JSON.	"Analise users.csv e retorne como JSON"
data.json_to_csv	Converte array JSON de objetos para saída CSV.	"Converta este array de usuários para uma tabela CSV"
data.xml_to_json	Converte documentos XML para objetos JSON estruturados.	"Converta este texto XML de configuração para JSON"
data.json_to_xml	Converte objetos JSON para saída XML limpa.	"Exporte este objeto JSON para o formato de tags XML"
data.yaml_to_json	Converte documentos YAML para JSON.	"Converta o yaml de configuração do Kubernetes para JSON"
data.json_to_yaml	Converte objetos JSON para formato YAML limpo.	"Formate este bloco JSON de banco de dados como YAML"
data.deduplicate	Remove duplicatas de arrays de objetos JSON por uma chave específica.	"Remova duplicatas desta lista de objetos de usuário por ID"
data.diff_arrays	Compara dois arrays JSON e lista as diferenças.	"Compare os arrays A e B e mostre-me adições e remoções"

---

💻 Utilitários para Desenvolvedores (developer.*)

Formatos padrão, validação e ferramentas de layout para desenvolvedores.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
developer.json_formatter	Formata e embeleza strings JSON com indentação personalizada.	"Embeleze esta string JSON usando indentação de 4 espaços"
developer.jwt_decoder	Decodifica tokens JWT para ler as claims de payload/cabeçalho.	"Decodifique este token JWT: eyJhbGciOiJI..."
developer.sql_formatter	Formata strings SQL para vários dialetos de banco de dados.	"Formate esta consulta select bagunçada para PostgreSQL"
developer.mermaid_generate	Cria diagramas Mermaid (fluxogramas, sequência, etc.).	"Gere um diagrama de fluxograma representando este fluxo de usuário"
developer.openapi_parser	Analisa e formata arquivos de especificação OpenAPI/Swagger.	"Liste os endpoints e esquemas de requisição deste openapi.yaml"
developer.regex_tester	Testa correspondências de expressões regulares em texto.	"Teste se esta regex de email corresponde a test@example.com"
developer.cron_parser	Analisa expressões Cron e lista os próximos horários de execução.	"Diga-me quando o cron job '0 9 * * 1-5' será executado em seguida"
developer.diff_files	Mostra diferenças de linhas entre arquivos de texto.	"Mostre-me a diferença entre fileA.txt e fileB.txt"
developer.diff_json	Mostra diferenças entre esquemas JSON.	"Destaque mudanças estruturais entre config1.json e config2.json"
developer.code_detector	Detecta linguagem de programação e estrutura de sintaxe.	"Em qual linguagem de programação este código está escrito?"
developer.markdown_lint	Faz lint e valida a formatação em arquivos Markdown.	"Encontre erros de estilo ou espaços no final em index.md"

---

🛠️ Ferramentas Utilitárias (utility.*)

Funções auxiliares de sistema, rede e criptografia.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
utility.qr_generate	Gera um código QR como arquivo ou URL de dados base64.	"Crie um código QR apontando para https://github.com"
utility.qr_read	Lê e decodifica um código QR de um arquivo ou fluxo.	"O que diz o código QR dentro de code.png?"
utility.base64_encode	Converte strings/arquivos para o formato base64.	"Codifique em base64 a string 'Hello World'"
utility.base64_decode	Decodifica strings base64 de volta para texto.	"Decodifique 'SGVsbG8gV29ybGQ='"
utility.uuid_generate	Gera UUIDs seguros (v4/v1) ou senhas seguras.	"Gere uma senha segura de comprimento 16"
utility.file_hash	Calcula hashes md5, sha1 ou sha256 de texto/dados.	"Calcule o hash sha256 desta string"
utility.email_validate	Valida a sintaxe e verifica registros MX de emails.	"Verifique se support@github.com tem registros MX válidos"
utility.ssl_check	Consulta a data de expiração e informações do certificado de qualquer domínio.	"Verifique quando o certificado SSL de google.com expira"
utility.unit_convert	Converte valores entre unidades físicas ou de dados.	"Converta 1024 megabytes para gigabytes"
utility.url_parser	Decompõe URLs em protocolo, domínio, parâmetros, etc.	"Analise esta URL de consulta de pesquisa em seus componentes"
utility.zip_create	Comprime arquivos ou pastas em um único arquivo ZIP.	"Comprima source/ e assets/ em workspace.zip"
utility.zip_extract	Extrai um arquivo ZIP para uma pasta de destino.	"Extraia arquivos de archive.zip para build_dir/"

---

🧠 Fragmentador de IA (ai.*)

Segmenta grandes estruturas de texto dinamicamente para ingestão.

Nome da Ferramenta	Descrição	Exemplo de Prompt para Agente
ai.text_chunker	Fragmenta textos longos usando estratégias de parágrafo/frase/palavra.	"Fragmente este documento de texto em blocos de 500 caracteres com sobreposição de 50 caracteres"

---

🏗️ Como Funciona

flowchart LR
    A[AI Agent / Client] -->|MCP Protocol| B(Kitbag MCP Server)
    B --> C{Enabled Modules}
    C --> D[📄 pdf.*]
    C --> E[🌐 web.*]
    C --> F[📸 image.*]
    C --> G[📊 data.*]
    C --> H[💻 developer.*]
    C --> I[🛠️ utility.*]
    C --> J[🧠 ai.*]
    D & E & F & G & H & I & J --> K[Local Execution<br/>No External API Calls]
    K --> A

O Kitbag MCP é executado como um único processo local. Seu cliente de IA se comunica com ele por meio do protocolo MCP padrão, e apenas os módulos que você habilitar são expostos como ferramentas — mantendo o uso de tokens baixo e seu fluxo de trabalho rápido e privado.

---

🛠️ Desenvolvimento Local e Contribuições

Cada ferramenta é totalmente autônoma. Adicionar uma nova ferramenta é tão simples quanto criar uma pasta dentro de src/tools/<category>/<tool_name>/.

Requisitos para Contribuição

Arquivo	Finalidade
tool.ts	O código principal de execução, exportando um ToolDefinition.
README.md	Documentação direta das ferramentas e descrições de parâmetros.
example.json	Exemplos de entradas e saídas esperadas.
tests.ts	Testes unitários autocontidos, usando mocks quando necessário para execução instantânea.

Guia de Comandos

# Build compiler output
npm run build

# Run all 50 module tests
npm test

# Run real-life execution checks (makes live API and DNS requests)
npx tsx src/tests/run_real_life.ts

---

⚖️ Licença

Distribuído sob a Licença MIT. Consulte LICENSE para mais informações. Totalmente open-source e livre para adaptação para uso pessoal ou comercial.