# mcp-contenido-redes

Un servidor MCP básico para hacer contenido de redes sociales a partir de tu voz: grabas una idea, la IA la transcribe, la convierte en guion con una fuente para cada dato y te deja todo listo para animar y programar.

Está pensado para que lo clones, lo pruebes en una tarde y lo adaptes a tu manera de trabajar.

## Qué es un MCP

MCP (Model Context Protocol) es un estándar abierto que permite que un asistente de IA, como Claude, use herramientas que viven fuera de él: leer un archivo, guardar una nota o ejecutar un programa en tu equipo. Un **servidor MCP** es un programa pequeño que ofrece esas herramientas; tú lo instalas una vez y el asistente lo llama cuando lo necesita.

## El flujo

```
 Grabas una idea          transcribir_audio      guardar_idea
 en una nota de voz  ──►  (texto, pausas y   ──►  (banco de ideas)
                           palabras dudosas)
                                                      │
                                                      ▼
 calendario_agregar  ◄──  plantilla_copy     ◄──  plantilla_guion
 (fecha y estado)         (descripción del        (la IA escribe el guion
                           post)                   con fuentes)
```

Animar el guion queda fuera de este servidor: la plantilla incluye una sección «Notas para animar» para que la lleves a la herramienta que uses.

## Las herramientas

| Herramienta | Qué hace | Dónde guarda |
|---|---|---|
| `transcribir_audio(ruta)` | Transcribe una nota de voz con faster-whisper, en tu computador. Devuelve el texto, las pausas largas y las palabras que el modelo no entendió bien. | No guarda nada |
| `guardar_idea(texto, etiquetas)` | Guarda una idea con sus etiquetas. | `ideas.json` |
| `listar_ideas()` | Muestra las ideas guardadas, de la más reciente a la más antigua. | — |
| `plantilla_guion(formato)` | Entrega la plantilla y las reglas de un guion corto (`reel`, `carrusel` o `historia`) para que la IA lo escriba. | — |
| `plantilla_copy()` | Lo mismo, para la descripción de la publicación. | — |
| `calendario_agregar(fecha, pieza, estado)` | Agrega una pieza al calendario o actualiza su estado si ya existe en esa fecha. | `calendario.csv` |
| `calendario_listar()` | Muestra el calendario ordenado por fecha. | — |

Las reglas del guion son estas:

1. Una sola idea por pieza.
2. Un gancho (la frase del comienzo que hace que alguien se quede) de 6 palabras o menos.
3. Cada término técnico se explica en palabras simples.
4. Primero un ejemplo concreto y después el concepto.
5. Cada dato lleva su fuente. Si no hay fuente verificable, el dato se quita o se marca `[SIN FUENTE]`, y la pieza no se publica así.
6. El cierre es un paso concreto o una pregunta real, no un «¿qué opinas?».

Las plantillas no escriben por ti: le dan a la IA la estructura y las reglas, y la IA redacta a partir de tu idea. Si quieres otras reglas, edita `src/mcp_contenido_redes/plantillas.py`.

## Qué necesitas

- **Python 3.10 o superior.** Para saber si lo tienes, abre una terminal (en Windows, «PowerShell»; en Mac, «Terminal») y escribe `python --version`.
- **Git**, para clonar el repositorio. También puedes descargarlo como ZIP desde GitHub.
- **Espacio en disco:** las dependencias más el modelo de transcripción. El modelo `small`, el que viene por defecto, ocupa unos 460 MB y se descarga solo la primera vez que transcribes.
- **Claude Desktop o Claude Code**, u otro cliente compatible con MCP.

No necesitas tarjeta gráfica ni instalar ffmpeg aparte.

## Instalación

Un **entorno virtual** es una carpeta donde Python instala las dependencias de este proyecto sin mezclarlas con las de otros. Se crea una vez.

**Windows (PowerShell):**

```powershell
git clone https://github.com/freyesperales/mcp-contenido-redes.git
cd mcp-contenido-redes
python -m venv .venv
.venv\Scripts\python -m pip install -e .
```

**Mac o Linux:**

```bash
git clone https://github.com/freyesperales/mcp-contenido-redes.git
cd mcp-contenido-redes
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```

Al terminar, el programa del servidor queda en:

- Windows: `.venv\Scripts\mcp-contenido-redes.exe`
- Mac o Linux: `.venv/bin/mcp-contenido-redes`

Copia la ruta completa de ese archivo; la vas a necesitar en el paso siguiente.

## Conectarlo a Claude

### Claude Desktop

1. Abre Claude Desktop y entra en **Configuración → Desarrollador → Editar configuración**. Se abre el archivo `claude_desktop_config.json`.
2. Agrega el servidor dentro de `mcpServers` con la ruta que copiaste. En Windows las barras invertidas van dobles:

```json
{
  "mcpServers": {
    "contenido-redes": {
      "command": "C:\\ruta\\a\\mcp-contenido-redes\\.venv\\Scripts\\mcp-contenido-redes.exe",
      "env": {
        "WHISPER_IDIOMA": "es"
      }
    }
  }
}
```

En Mac o Linux, `command` sería algo como `/ruta/a/mcp-contenido-redes/.venv/bin/mcp-contenido-redes`.

3. Cierra Claude Desktop por completo y vuelve a abrirlo. En el chat, el ícono de herramientas debería mostrar las siete de `contenido-redes`.

### Claude Code

Desde cualquier carpeta:

```bash
claude mcp add contenido-redes -e WHISPER_IDIOMA=es -- "/ruta/a/mcp-contenido-redes/.venv/bin/mcp-contenido-redes"
```

En Windows, usa la ruta del `.exe`. Para comprobar que quedó conectado, escribe `/mcp` dentro de Claude Code.

## Configuración

Todo se ajusta con variables de entorno, en la sección `env` del archivo de configuración o con `-e` en Claude Code. Ninguna es obligatoria.

| Variable | Por defecto | Para qué sirve |
|---|---|---|
| `WHISPER_MODELO` | `small` | Modelo de transcripción: `tiny`, `base`, `small`, `medium`, `large-v3` o la ruta de un modelo descargado. Los más grandes entienden mejor, pero son más lentos y pesados. |
| `WHISPER_IDIOMA` | detección automática | Código del idioma de tus audios, por ejemplo `es`. Fijarlo evita errores en audios cortos. |
| `WHISPER_DISPOSITIVO` | `cpu` | `cuda` si tienes una tarjeta NVIDIA configurada para usarla. |
| `WHISPER_PRECISION` | `int8` | Precisión de cálculo. `int8` es la más liviana para la CPU. |
| `PAUSA_MINIMA_SEGUNDOS` | `0.8` | Desde cuántos segundos de silencio se informa una pausa. |
| `UMBRAL_DUDA` | `0.5` | Bajo esta seguridad (de 0 a 1), una palabra se marca como dudosa. |
| `AUDIO_TAMANO_MAXIMO_MB` | `500` | Tamaño máximo de archivo que acepta. |
| `CONTENIDO_REDES_CARPETA_AUDIOS` | sin límite | Si la defines, solo se transcriben archivos que estén dentro de esa carpeta. Recomendado. |
| `CONTENIDO_REDES_DATOS` | `contenido-redes-datos` en tu carpeta de usuario | Dónde se guardan `ideas.json` y `calendario.csv`. |

## Un ejemplo de principio a fin

Grabas una nota de voz en el teléfono mientras caminas, la pasas al computador y le escribes a Claude:

> Transcribe `C:\Users\tu-usuario\Audios\idea-mcp.m4a`.

Claude llama a `transcribir_audio` y te devuelve el texto. Además te avisa de las palabras dudosas, por ejemplo: «[MCP] con 31 % de seguridad, en "hoy hablamos de [MCP] y de cómo…"». Corriges lo que haga falta.

> Guárdala como idea con las etiquetas ia y herramientas.

Claude llama a `guardar_idea`. La idea queda en `ideas.json` con un número.

> Conviértela en un guion de reel.

Claude llama a `plantilla_guion("reel")`, recibe la estructura y las reglas, y escribe el guion: un gancho de 6 palabras o menos, un ejemplo, el concepto explicado, un cierre y una lista de fuentes. Si un dato no tiene fuente, lo marca `[SIN FUENTE]`. Tú revisas que cada fuente exista y diga lo que el guion afirma.

> Ahora escribe la descripción del post.

Claude llama a `plantilla_copy()` y redacta la descripción con su primera línea, el cierre, las fuentes y un texto alternativo para la portada.

> Agéndalo para el 24 de noviembre, estado guion.

Claude llama a `calendario_agregar("2026-11-24", "Reel: qué es un MCP", "guion")`. Cuando grabes, le pides cambiar el estado a `grabado`, y así hasta `publicado`. El calendario es un CSV, así que también lo puedes abrir en Excel o Google Sheets.

## Dónde quedan tus datos

Todo queda en tu computador. El audio no se envía a ningún servicio: la transcripción ocurre en tu CPU. La única conexión a internet es con Hugging Face, el sitio desde donde se descarga el modelo la primera vez; después, cada vez que se carga, solo consulta si hay una versión nueva. Si no quieres ni esa consulta, agrega la variable `HF_HUB_OFFLINE` con el valor `1` cuando el modelo ya esté descargado.

Las ideas y el calendario son archivos de texto normales que puedes abrir, respaldar o borrar cuando quieras.

## Límites

- **No publica en redes sociales** ni se conecta a ninguna cuenta. No guarda contraseñas ni claves de acceso.
- **La transcripción se equivoca**, sobre todo con nombres propios, cifras y siglas. Para eso están las palabras dudosas: revísalas siempre.
- **En CPU es lenta.** Con el modelo `small`, una nota de un par de minutos puede tardar desde unos segundos hasta más de un minuto, según tu equipo. La primera vez tarda más por la descarga del modelo.
- **No verifica las fuentes.** Las plantillas obligan a citar y prohíben inventar, pero comprobar que una fuente existe y dice lo que se le atribuye te toca a ti, o a una IA con búsqueda web, antes de publicar.
- **No anima ni edita video.** Deja las notas para que lo hagas en tu herramienta de siempre.
- **Es para una persona.** Los archivos locales no están pensados para que varias personas los editen al mismo tiempo.

## Siguiente paso

Cuando el flujo te funcione, puedes sumar la programación de publicaciones con las API oficiales de cada red (Meta, TikTok, LinkedIn, YouTube). Eso implica crear una aplicación de desarrollador en cada plataforma y manejar permisos y claves de acceso con cuidado, por eso no viene incluido.

## Pruebas

```bash
.venv/bin/python -m pip install -e ".[dev]"     # en Windows: .venv\Scripts\python
.venv/bin/python -m pytest
```

La prueba que transcribe de verdad se salta si el modelo no está descargado. Las demás funcionan sin modelo.

## Licencia

MIT. Puedes usarlo, modificarlo y compartirlo, también con fines comerciales, manteniendo el aviso de copyright. Ver [LICENSE](LICENSE).