# 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
