# MCP Toolkit Server — Ciberseguridad para Claude

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io/)
[![Tests](https://img.shields.io/badge/tests-53%20passed-brightgreen)](#tests)
[![Tools](https://img.shields.io/badge/tools-17-orange)](#herramientas)

> **Convertí a Claude en tu asistente de ciberseguridad.** Este servidor MCP expone 17 herramientas de red, criptografía y análisis de seguridad directamente en tus conversaciones con Claude Desktop o Claude Code, sin salir del chat.

---

## ¿Qué es MCP y por qué importa?

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) es el estándar abierto de Anthropic para conectar modelos de IA con herramientas y fuentes de datos externas. Funciona como un "conector universal": en lugar de integrar cada herramienta a mano, un servidor MCP las expone todas a la vez para cualquier cliente compatible.

**Lo que esto significa en la práctica:** podés preguntarle a Claude _"¿el certificado SSL de mi servidor vence esta semana?"_ o _"analizá este JWT y decime si tiene vulnerabilidades"_ y Claude ejecuta las herramientas, interpreta los resultados y te da una respuesta contextualizada, todo dentro de la conversación.

---

## ¿Por qué este servidor?

Este proyecto nació como parte de una ruta de aprendizaje en **ciberseguridad**. El objetivo es doble:

1. **Práctica real**: implementar herramientas que se usan en auditorías, reconocimiento web y análisis de tokens, entendiendo cada detalle por dentro.
2. **Productividad con IA**: potenciar el flujo de trabajo cotidiano en seguridad integrando estas capacidades directamente con Claude.

Las herramientas no son wrappers de otras CLIs — están implementadas en Python puro usando la stdlib más `dnspython`, para entender exactamente qué pasa en cada operación.

---

## Herramientas incluidas

### Sistema y Archivos

| Herramienta | Descripción |
|---|---|
| `info_sistema` | SO, versión, arquitectura, Python, hora UTC |
| `espacio_disco(ruta)` | Espacio total / usado / libre en GB |
| `calcular_hash(archivo, algoritmo)` | SHA-256 / SHA-1 / MD5 de un archivo — verificación de integridad |
| `listar_directorio(ruta)` | Lista archivos y carpetas con tipo |

### Red y Reconocimiento Web

| Herramienta | Descripción |
|---|---|
| `verificar_certificado_ssl(dominio)` | Validez, días hasta expiración, emisor, protocolo, cifrado, SANs |
| `verificar_headers_seguridad(url)` | Auditoría de HSTS, CSP, X-Frame-Options, MIME, Referrer-Policy. Score /6 |
| `hacer_request_http(url, metodo, headers, body)` | HTTP client completo — probar APIs, analizar respuestas |
| `consultar_dns(dominio, tipo)` | Registros A, AAAA, MX, NS, TXT, CNAME |
| `whois_dominio(dominio)` | Registrante, fechas de creación/expiración, nameservers |

### Ciberseguridad

| Herramienta | Descripción |
|---|---|
| `escanear_puertos(host)` | ~35 puertos TCP en paralelo. Detecta servicios críticos expuestos (Docker, Redis, MongoDB, SMB...) con consejos de hardening |
| `verificar_fortaleza_password(password)` | Análisis de entropía en bits, diversidad de charset, patrones débiles comunes |

### Criptografía y Tokens

| Herramienta | Descripción |
|---|---|
| `generar_password_seguro(longitud, ...)` | Contraseña segura con `secrets` — muestra entropía calculada |
| `generar_token_aleatorio(longitud, formato)` | API keys, secrets, session IDs en hex / base64 / urlsafe |
| `calcular_hash_texto(texto, algoritmo)` | Hash de strings — sha256, sha512, md5, blake2b, sha3_256 |
| `analizar_jwt(token)` | Decodifica header + payload, detecta: expiración, `alg:none`, claims de seguridad |
| `codificar_base64(texto)` | Codificación base64 standard o URL-safe |
| `decodificar_base64(texto)` | Decodificación base64 con autodetección de padding |

---

## Casos de uso reales

```
"¿El certificado SSL de api.miempresa.com está por vencer?"
→ verificar_certificado_ssl("api.miempresa.com")
  Estado: ADVERTENCIA — expira en 12 días
  Emisor: Let's Encrypt
  SANs: api.miempresa.com, www.api.miempresa.com
```

```
"Auditá los headers de seguridad de nuestro panel de admin"
→ verificar_headers_seguridad("https://admin.miempresa.com")
  Score: 2/6 — Bajo
  [OK] Strict-Transport-Security: max-age=31536000
  [OK] X-Content-Type-Options: nosniff
  [--] Content-Security-Policy
  [--] X-Frame-Options  ← ¡expuesto a clickjacking!
  Fuga: Server: nginx/1.18.0  ← versión expuesta
```

```
"Decodificá este JWT del login y decime si tiene algo raro"
→ analizar_jwt("eyJhbGci...")
  Algoritmo: HS256
  ⚠  TOKEN EXPIRADO — venció el 2024-03-15 10:00 UTC
  Claim 'role': admin
  Claim 'sub': user_1337
```

```
"Chequeá qué puertos tiene abiertos mi VPS en producción"
→ escanear_puertos("203.0.113.42")
  22/tcp  SSH
  80/tcp  HTTP
  6379/tcp Redis ← CRÍTICO: Redis sin autenticación — activar requirepass
  27017/tcp MongoDB ← CRÍTICO: expone toda la base de datos
```

```
"Generame un API key para el nuevo microservicio"
→ generar_token_aleatorio(32, "hex")
  a3f8c2e1d9b7045f6a2c8e4d1f0b3a9c7e2d5f8b1a4c7e0d3f6b9a2c5e8d1f4
  Entropía: 256 bits
```

---

## Instalación

```bash
git clone https://github.com/GonzaBot/mcp-toolkit-server.git
cd mcp-toolkit-server
pip install -e .
```

Dependencias: `mcp>=1.0.0`, `dnspython>=2.0.0`. El resto es stdlib de Python 3.10+.

---

## Conectar con Claude Desktop

Editá el archivo de configuración de Claude Desktop:

| SO | Ruta |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "mcp-toolkit-server": {
      "command": "mcp-toolkit-server"
    }
  }
}
```

Reiniciá Claude Desktop. Las 17 herramientas aparecen automáticamente disponibles en la conversación.

---

## Conectar con Claude Code

```bash
claude mcp add mcp-toolkit-server mcp-toolkit-server
```

O en modo proyecto, editá `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "mcp-toolkit-server": {
      "command": "mcp-toolkit-server"
    }
  }
}
```

---

## Estructura del proyecto

```
mcp-toolkit-server/
├── src/mcp_toolkit_server/
│   ├── server.py          # Punto de entrada — registra las 17 tools con FastMCP
│   └── tools/
│       ├── system.py      # Info del SO y espacio en disco
│       ├── files.py       # Hash de archivos y listado de directorios
│       ├── security.py    # Escaneo de puertos y análisis de contraseñas
│       ├── network.py     # SSL, headers HTTP, requests, DNS, WHOIS
│       └── crypto.py      # Passwords, tokens, hashing, JWT, Base64
├── tests/
│   └── test_tools.py      # 53 tests — 47 offline + 6 con internet
├── examples/
│   └── claude_desktop_config.json
└── pyproject.toml
```

---

## Tests

```bash
# Instalar dependencias de desarrollo
pip install -e ".[dev]"

# Tests offline (sin internet)
pytest -k "not network"

# Tests completos (incluye verificaciones contra google.com, httpbin.org)
pytest -m network

# Todo junto
pytest -v
```

**53 tests** cubriendo: happy path, casos de error, valores criptográficos conocidos (hash SHA-256 de string vacío, MD5 de "hello"), JWTs expirados, algoritmo `none`, Base64 con y sin padding, tokens hex/base64/urlsafe.

---

## Cómo agregar tu propia herramienta

1. Agregá la función al módulo correspondiente en `tools/` (o creá uno nuevo).
2. Registrala en `server.py` con `@mcp.tool()`.
3. Escribí un docstring claro — Claude lo usa para saber cuándo y cómo invocarla.

```python
# tools/network.py
def mi_herramienta_nueva(parametro: str) -> str:
    """Descripción clara de qué hace y cuándo usarla.

    Args:
        parametro: qué representa
    """
    return resultado

# server.py
@mcp.tool()
def mi_herramienta_nueva(parametro: str) -> str:
    """Descripción clara de qué hace y cuándo usarla.

    Args:
        parametro: qué representa
    """
    return network.mi_herramienta_nueva(parametro)
```

---

## Uso ético

Las herramientas de reconocimiento de red (`escanear_puertos`, `whois_dominio`, `consultar_dns`, `verificar_certificado_ssl`) deben usarse únicamente sobre:
- Sistemas propios
- Sistemas sobre los que tenés autorización explícita del propietario

Escanear sistemas de terceros sin permiso puede ser ilegal según la jurisdicción.

---

## Roadmap

- [ ] Transporte HTTP/SSE para acceso remoto (correr el servidor en un VPS)
- [ ] `verificar_ip_reputacion` — consultar AbuseIPDB / VirusTotal
- [ ] `auditar_dependencias` — integrar pip-audit para detectar CVEs en proyectos Python
- [ ] `detectar_tecnologias` — fingerprinting de stack tecnológico por headers y respuestas
- [ ] GitHub Actions con tests en CI/CD
- [ ] Tests de integración con cliente MCP simulado

---

## Licencia

MIT © Gonzalo D. Rodríguez de Mello