# 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](https://docs.astral.sh/uv/) (gestor de paquetes y entornos virtuales moderno)

### Instalación desde código fuente

```bash
# 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

```bash
# 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:

```bash
# ✅ 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:**

```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:**

```json
// 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:

```json
{
  "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.

```bash
# ❌ 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:**

```bash
# 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

```bash
# 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:

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

2. Registrar en función de registro:

```python
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