Local Utilities

Fornece ferramentas utilitárias essenciais para processamento de texto, operações de arquivos e tarefas do sistema.

GitHubExperimente este MCPPatrocinado

Documentação

🛠️ Servidor MCP de Utilitários Locais

Um servidor completo de Model Context Protocol (MCP) construído com FastMCP que fornece ferramentas utilitárias essenciais para processamento de texto, operações de arquivo, tarefas do sistema e muito mais.

Python 3.8+ FastMCP License: MIT

🌟 Recursos

🌡️ Conversão de Temperatura

  • Converter entre Celsius e Fahrenheit
  • Cálculos de alta precisão com 2 casas decimais

📁 Operações de Arquivo

  • Ler arquivos de texto com exibição de conteúdo completo
  • Escrever conteúdo em arquivos com criação automática de diretórios
  • Listar conteúdos de diretórios com tamanhos de arquivo e ícones

🔐 Segurança e Hash

  • Calcular hashes MD5, SHA1, SHA256
  • Aplicar hash a strings de texto ou conteúdos de arquivos inteiros
  • Base64 codificação e decodificação

📊 Análise de Texto

  • Contar palavras, caracteres e linhas
  • Calcular estatísticas detalhadas de texto
  • Média de palavras por linha e caracteres por palavra

🕒 Data e Hora

  • Obter informações atuais de data e hora
  • Formatação personalizada com Python strftime
  • Discriminação detalhada (ano, mês, dia, dia da semana, etc.)

🔑 Geração de Senhas

  • Gerar senhas seguras com opções personalizáveis
  • Controlar comprimento e conjuntos de caracteres
  • Incluir/excluir maiúsculas, minúsculas, números, símbolos

🚀 Início Rápido

Pré-requisitos

  • Python 3.8 ou superior
  • Cliente MCP compatível (LM Studio, Claude Desktop, etc.)

Instalação

  1. Clone o repositório:

    git clone https://github.com/aiforhumans/local-utils-mcp.git
cd local-utils-mcp

  2. Crie e ative um ambiente virtual:

    python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

  3. Instale as dependências:

    pip install -r requirements.txt

Executando o Servidor

Inicie o servidor MCP:

python server.py

O servidor roda no transporte stdio por padrão, que é compatível com a maioria dos clientes MCP.

🔧 Configuração

Integração com LM Studio

Adicione esta configuração ao seu arquivo mcp.json do LM Studio:

{
  "mcpServers": {
    "local-utils": {
      "command": "python",
      "args": ["path/to/your/server.py"],
      "env": {}
    }
  }
}

Integração com Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "local-utils": {
      "command": "python",
      "args": ["path/to/your/server.py"]
    }
  }
}

📖 Referência da API

Ferramentas Disponíveis

convert_temp(value: float, unit: str)

Converter temperatura entre Celsius e Fahrenheit.

Parâmetros:

  • value: Valor da temperatura a converter
  • unit: "C" para Celsius para Fahrenheit, "F" para Fahrenheit para Celsius

Exemplo:

convert_temp(25, "C") → "77.00 °F"
convert_temp(77, "F") → "25.00 °C"

read_file(file_path: str)

Ler e retornar o conteúdo de um arquivo de texto.

Parâmetros:

  • file_path: Caminho absoluto ou relativo para o arquivo

Retorna: Conteúdo do arquivo com informações do caminho

write_file(file_path: str, content: str)

Escrever conteúdo em um arquivo de texto com criação automática de diretórios.

Parâmetros:

  • file_path: Caminho onde escrever o arquivo
  • content: Conteúdo de texto a escrever

list_directory(directory_path: str = ".")

Listar conteúdos de um diretório com tamanhos de arquivos.

Parâmetros:

  • directory_path: Caminho para o diretório (padrão: diretório atual)

Retorna: Lista formatada com ícones de arquivos/pastas e tamanhos

calculate_hash(text_or_path: str, hash_type: str = "sha256", is_file: bool = False)

Calcular hash criptográfico de texto ou conteúdo de arquivo.

Parâmetros:

  • text_or_path: String de texto ou caminho de arquivo para aplicar hash
  • hash_type: "md5", "sha1" ou "sha256" (padrão)
  • is_file: Defina como true ao aplicar hash em um arquivo

base64_encode_decode(text: str, operation: str = "encode")

Codificar ou decodificar texto usando Base64.

Parâmetros:

  • text: Texto para codificar/decodificar
  • operation: "encode" ou "decode"

get_datetime_info(format_string: str = "%Y-%m-%d %H:%M:%S")

Obter informações abrangentes de data e hora atuais.

Parâmetros:

  • format_string: String de formato strftime do Python para formatação personalizada

text_stats(text: str)

Calcular estatísticas detalhadas para o texto fornecido.

Parâmetros:

  • text: Texto para analisar

Retorna: Linhas, palavras, caracteres e médias

generate_password(length: int = 12, include_uppercase: bool = True, include_lowercase: bool = True, include_numbers: bool = True, include_symbols: bool = False)

Gerar uma senha aleatória segura.

Parâmetros:

  • length: Comprimento da senha (padrão: 12)
  • include_uppercase: Incluir A-Z (padrão: verdadeiro)
  • include_lowercase: Incluir a-z (padrão: verdadeiro)
  • include_numbers: Incluir 0-9 (padrão: verdadeiro)
  • include_symbols: Incluir caracteres especiais (padrão: falso)

🧪 Teste

Execute o conjunto de testes para verificar a funcionalidade:

python test.py

Isso testará todas as funções principais e verificará se o servidor pode ser importado corretamente.

🔨 Desenvolvimento

Adicionando Novas Ferramentas

Para estender o servidor com ferramentas adicionais:

  1. Crie uma nova função com o decorador @mcp.tool():
@mcp.tool(
    description="Your tool description here"
)
async def your_new_tool(param1: str, param2: int = 10) -> str:
    """
    Your tool implementation.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2 with default value
    
    Returns:
        String result of the tool operation
    """
    try:
        # Your tool logic here
        result = f"Processed {param1} with value {param2}"
        return result
    except Exception as e:
        return f"Error: {str(e)}"
  1. Adicione tratamento de erros adequado e mensagens de retorno significativas
  2. Atualize o README com documentação para sua nova ferramenta
  3. Teste sua ferramenta para garantir que funcione corretamente

Estrutura do Projeto

local-utils-mcp/
├── server.py              # Main MCP server
├── requirements.txt       # Python dependencies  
├── README.md             # This file
├── .gitignore           # Git ignore rules
├── test.py              # Test suite
└── .venv/               # Virtual environment (not in git)

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças significativas, por favor abra uma issue primeiro para discutir o que gostaria de alterar.

  1. Faça um fork do repositório
  2. Crie sua branch de recursos (git checkout -b feature/AmazingFeature)
  3. Faça commit de suas alterações (git commit -m 'Add some AmazingFeature')
  4. Envie para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

📋 Requisitos

  • Python 3.8+
  • FastMCP 2.9.0+
  • MCP 1.9.4+

Veja requirements.txt para a lista completa de dependências.

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🔗 Projetos Relacionados

⭐ Suporte

Se você achar este projeto útil, considere dar uma estrela no GitHub!

Feito com ❤️ para a comunidade MCP