MCP Custom Tools

Servidor MCP Custom Tools

Um servidor MCP (Model Context Protocol) personalizado com um conjunto completo de ferramentas para data/hora, manipulação de arquivos, informações do sistema, processamento de texto e operações web.

Características

• ✅ Servidor MCP completo implementado do zero
• ✅ Gerenciamento moderno de dependências com pyproject.toml
• ✅ 30+ ferramentas personalizadas organizadas por categorias
• ✅ Comunicação assíncrona com suporte para stdio
• ✅ Logging configurável e tratamento de erros robusto
• ✅ CLI integrado com opções flexíveis

Ferramentas Disponíveis

🕒 Data e Hora (datetime_tools)

• current_time - Obter data e hora atual
• format_timestamp - Formatar timestamp para formato legível
• calculate_age - Calcular idade a partir da data de nascimento
• days_between - Calcular dias entre duas datas
• month_calendar - Gerar calendário mensal

📁 Manipulação de Arquivos (file_tools)

• read_file - Ler conteúdo de arquivo (async/sync)
• file_info - Obter informações detalhadas do arquivo
• list_directory - Listar conteúdo do diretório
• calculate_hash - Calcular hash MD5/SHA256 de arquivo
• search_files - Buscar arquivos por padrão

💻 Sistema (system_tools)

• system_info - Informações gerais do sistema
• cpu_info - Informações detalhadas da CPU
• memory_info - Informações de memória RAM
• disk_info - Informações de discos e armazenamento
• network_info - Informações de interfaces de rede
• process_list - Lista de processos em execução
• environment_vars - Variáveis de ambiente do sistema

📝 Processamento de Texto (text_tools)

• word_count - Contar palavras, linhas e caracteres
• search_replace - Busca e substituição com regex
• extract_emails - Extrair endereços de email
• extract_urls - Extrair URLs de texto
• text_analysis - Análise detalhada de texto
• encode_decode - Codificação/decodificação de texto
• generate_hash - Gerar hash de texto
• split_text - Dividir texto em chunks

🌐 Web (web_tools)

• http_request - Realizar requisições HTTP
• parse_url - Parsear e analisar URLs
• build_url - Construir URLs a partir de componentes
• url_encode_decode - Codificar/decodificar URLs
• validate_url - Validar formato e acessibilidade
• extract_domain - Extrair informações de domínio

Instalação

Pré-requisitos

• Python 3.10+
• uv (gerenciador de pacotes e ambientes virtuais moderno)

Instalação a partir do código-fonte

# Clonar el repositorio
git clone <repository-url>
cd mcp-custom-tools

# Instalar uv (si no lo tienes)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Instalar dependencias y crear entorno virtual automáticamente
uv sync

# Instalar dependencias de desarrollo
uv sync --group dev

# Verificar instalación
uv run mcp-server --help

Uso

Executar o servidor

# Método recomendado - usando el script instalado
uv run mcp-server

# Con nivel de logging específico
uv run mcp-server --log-level DEBUG

# Con configuración personalizada
uv run mcp-server --log-level INFO --name "Mi Servidor MCP" --version "1.0.0"

# Método alternativo - usando módulo Python
uv run python -m mcp_custom_tools.server

# Con configuración personalizada usando módulo
uv run python -m mcp_custom_tools.server --log-level INFO --name "Custom Server"

Opções de CLI

• --log-level - Nível de logging (DEBUG, INFO, WARNING, ERROR)
• --name - Nome do servidor MCP
• --version - Versão do servidor
• --help - Mostrar ajuda

⚠️ Importante: Usar sempre uv run

No Windows, os scripts instalados com uv não estão disponíveis globalmente no PATH. Sempre use:

# ✅ Correcto
uv run mcp-server

# ❌ Error - No funciona
mcp-server

Integração com clientes MCP

O servidor usa comunicação stdio e é compatível com qualquer cliente MCP padrão.

Configuração JSON:

{
  "mcpServers": {
    "mcp-custom-tools": {
      "command": "uv",
      "args": [
        "run",
        "mcp-server",
        "--log-level",
        "INFO"
      ],
      "cwd": "/path/to/mcp-custom-tools"
    }
  }
}

Exemplos de caminhos por sistema operacional:

// Windows
"cwd": "C:\\Users\\TuUsuario\\mcp-custom-tools"

// macOS/Linux  
"cwd": "/home/tuusuario/mcp-custom-tools"
// o
"cwd": "~/mcp-custom-tools"

Configuração para outros clientes MCP

Para outros clientes que suportem MCP, usar a seguinte configuração base:

{
  "name": "mcp-custom-tools",
  "command": ["uv", "run", "mcp-server"],
  "args": ["--log-level", "INFO"],
  "cwd": "/path/to/mcp-custom-tools"
}

Verificar a configuração

1. Reinicie o Claude Desktop após modificar a configuração
2. Abra uma nova conversa no Claude
3. Verifique as ferramentas escrevendo: "Quais ferramentas você tem disponíveis?"
4. Teste uma ferramenta como: "Que horas são agora?"

Solução de problemas

Se o comando 'mcp-server' não for reconhecido:

Este é o erro mais comum no Windows. O script é instalado no ambiente virtual, mas não está no PATH global.

# ❌ Error común
mcp-server
# Error: 'mcp-server' no se reconoce como comando

# ✅ Solución
uv run mcp-server

Se o servidor não conectar:

1. Verificar se "cwd" aponta para o diretório correto do projeto
2. Verificar uv: Verificar se o uv está instalado: uv --version
3. Sincronizar projeto: Executar uv sync no diretório do projeto
4. Revisar logs: Verificar logs no Claude Desktop (Ver > Ferramentas de desenvolvedor)
5. Testar manualmente: uv run mcp-server --log-level DEBUG a partir do diretório do projeto

Logs e debugging:

# Probar el servidor directamente
uv run mcp-server --log-level DEBUG

# Verificar herramientas disponibles
uv run python -c "from mcp_custom_tools.tools import get_available_tools; print(list(get_available_tools().keys()))"

# Verificar que uv funciona correctamente
uv run python --version

# Verificar instalación del paquete
uv run python -c "import mcp_custom_tools; print('Instalación OK')"

Desenvolvimento

Estrutura do Projeto

mcp-custom-tools/
├── src/
│   └── mcp_custom_tools/
│       ├── __init__.py
│       ├── server.py
│       └── tools/
│           ├── __init__.py
│           ├── datetime_tools.py
│           ├── file_tools.py
│           ├── system_tools.py
│           ├── text_tools.py
│           └── web_tools.py
├── pyproject.toml
├── README.md
└── .gitignore

Configuração de Desenvolvimento

# Instalar dependencias de desarrollo
uv sync --group dev

# Ejecutar linting
black src/
isort src/
flake8 src/
mypy src/

# Ejecutar tests
pytest

# Ejecutar tests con cobertura
pytest --cov=mcp_custom_tools

Adicionar Novas Ferramentas

1. Criar nova função de ferramenta:

def my_new_tool(args: Dict[str, Any]) -> str:
    """Mi nueva herramienta."""
    # Implementación
    return "resultado"

2. Registrar na função de registro:

def register_my_tools(tools: Dict[str, Dict[str, Any]]) -> None:
    tools["my_tool"] = {
        "description": "Descripción de mi herramienta",
        "handler": my_new_tool,
        "inputSchema": {
            "type": "object",
            "properties": {
                "param": {"type": "string", "description": "Parámetro"}
            },
            "required": ["param"]
        }
    }

3. Importar e registrar em tools/__init__.py

Dependências

Principais

• mcp - Protocolo MCP core
• httpx - Requisições HTTP async
• aiofiles - Operações de arquivo async
• psutil - Informações do sistema
• click - CLI framework

Desenvolvimento

• black - Formatação de código
• isort - Ordenação de imports
• mypy - Type checking
• flake8 - Linting
• pytest - Testing framework

Licença

Licença MIT - ver arquivo LICENSE para detalhes.

Contribuir

1. Fork o projeto
2. Criar branch de feature (git checkout -b feature/AmazingFeature)
3. Commit das alterações (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abrir Pull Request

Suporte

Para reportar bugs ou solicitar funcionalidades, criar uma issue no GitHub.

Changelog

v1.0.0

• Implementação inicial do servidor MCP
• 30+ ferramentas personalizadas
• Gerenciamento com pyproject.toml
• CLI integrado
• Documentação completa