MCP Custom Tools Server

Un servidor MCP (Model Context Protocol) personalizado con un conjunto completo de herramientas para fecha/hora, manejo de archivos, información del sistema, procesamiento de texto y operaciones web.

Características

• ✅ Servidor MCP completo implementado desde cero
• ✅ Gestión moderna de dependencias con pyproject.toml
• ✅ 30+ herramientas personalizadas organizadas por categorías
• ✅ Comunicación asíncrona con soporte para stdio
• ✅ Logging configurable y manejo de errores robusto
• ✅ CLI integrado con opciones flexibles

Herramientas Disponibles

🕒 Fecha y Hora (datetime_tools)

• current_time - Obtener fecha y hora actual
• format_timestamp - Formatear timestamp a formato legible
• calculate_age - Calcular edad a partir de fecha de nacimiento
• days_between - Calcular días entre dos fechas
• month_calendar - Generar calendario mensual

📁 Manejo de Archivos (file_tools)

• read_file - Leer contenido de archivo (async/sync)
• file_info - Obtener información detallada de archivo
• list_directory - Listar contenido de directorio
• calculate_hash - Calcular hash MD5/SHA256 de archivo
• search_files - Buscar archivos por patrón

💻 Sistema (system_tools)

• system_info - Información general del sistema
• cpu_info - Información detallada de CPU
• memory_info - Información de memoria RAM
• disk_info - Información de discos y almacenamiento
• network_info - Información de interfaces de red
• process_list - Lista de procesos en ejecución
• environment_vars - Variables de entorno del sistema

📝 Procesamiento de Texto (text_tools)

• word_count - Contar palabras, líneas y caracteres
• search_replace - Búsqueda y reemplazo con regex
• extract_emails - Extraer direcciones de email
• extract_urls - Extraer URLs de texto
• text_analysis - Análisis detallado de texto
• encode_decode - Codificación/decodificación de texto
• generate_hash - Generar hash de texto
• split_text - Dividir texto en chunks

🌐 Web (web_tools)

• http_request - Realizar peticiones HTTP
• parse_url - Parsear y analizar URLs
• build_url - Construir URLs desde componentes
• url_encode_decode - Codificar/decodificar URLs
• validate_url - Validar formato y accesibilidad
• extract_domain - Extraer información de dominio

Instalación

Prerrequisitos

• Python 3.10+
• uv (gestor de paquetes y entornos virtuales moderno)

Instalación desde código fuente

# 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

Ejecutar el 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"

Opciones de CLI

• --log-level - Nivel de logging (DEBUG, INFO, WARNING, ERROR)
• --name - Nombre del servidor MCP
• --version - Versión del servidor
• --help - Mostrar ayuda

⚠️ Importante: Usar siempre uv run

En Windows, los scripts instalados con uv no están disponibles globalmente en PATH. Siempre usa:

# ✅ Correcto
uv run mcp-server

# ❌ Error - No funciona
mcp-server

Integración con clientes MCP

El servidor usa comunicación stdio y es compatible con cualquier cliente MCP estándar.

Configuración JSON:

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

Ejemplos de rutas por sistema operativo:

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

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

Configuración para otros clientes MCP

Para otros clientes que soporten MCP, usar la siguiente configuración base:

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

Verificar la configuración

1. Reinicia Claude Desktop después de modificar la configuración
2. Abre una nueva conversación en Claude
3. Verifica las herramientas escribiendo: "¿Qué herramientas tienes disponibles?"
4. Prueba una herramienta como: "¿Qué hora es ahora?"

Solución de problemas

Si el comando 'mcp-server' no se reconoce:

Este es el error más común en Windows. El script se instala en el entorno virtual pero no está en PATH global.

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

# ✅ Solución
uv run mcp-server

Si el servidor no se conecta:

1. Verificar que "cwd" apunte al directorio correcto del proyecto
2. Verificar uv: Comprobar que uv esté instalado: uv --version
3. Sincronizar proyecto: Ejecutar uv sync en el directorio del proyecto
4. Revisar logs: Verificar logs en Claude Desktop (Ver > Herramientas de desarrollador)
5. Probar manualmente: uv run mcp-server --log-level DEBUG desde el directorio del proyecto

Logs y 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')"

Desarrollo

Estructura del Proyecto

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

Configuración de Desarrollo

# 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

Añadir Nuevas Herramientas

1. Crear nueva función de herramienta:

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

2. Registrar en función 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 y registrar en tools/__init__.py

Dependencias

Principales

• mcp - Protocolo MCP core
• httpx - Peticiones HTTP async
• aiofiles - Operaciones de archivo async
• psutil - Información del sistema
• click - CLI framework

Desarrollo

• black - Formateo de código
• isort - Ordenamiento de imports
• mypy - Type checking
• flake8 - Linting
• pytest - Testing framework

Licencia

MIT License - ver archivo LICENSE para detalles.

Contribuir

1. Fork el proyecto
2. Crear rama de feature (git checkout -b feature/AmazingFeature)
3. Commit cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abrir Pull Request

Soporte

Para reportar bugs o solicitar features, crear un issue en GitHub.

Changelog

v1.0.0

• Implementación inicial del servidor MCP
• 30+ herramientas personalizadas
• Gestión con pyproject.toml
• CLI integrado
• Documentación completa