# Social Broadcast MCP

Servidor MCP **open source (MIT)** para publicar en redes sociales (Facebook, Instagram, YouTube) usando las **APIs oficiales** de cada plataforma, con **tus propias credenciales OAuth**.

Sin servicio central. Sin planes. Sin límites artificiales. Sin intermediarios de pago.

## ¿Por qué existe?

Las herramientas SaaS (SocialCannon, PostFast, Buffer...) cobran una suscripción mensual y ponen límites (cuentas, posts, subidas de media). Este proyecto hace lo mismo —publicar desde un agente de IA (Hermes, Claude, etc.)— pero **cada usuario conecta sus propias cuentas** con sus propias apps de desarrollador. Gratis para siempre.

> ⚠️ **Diferencia clave con los SaaS**: ellos ya tienen apps aprobadas por Meta/Google con revisión completa. Aquí **tú** creas tu app (gratis) y la usas para tus propias cuentas. Eso es válido para uso personal/negocio propio, y evita la revisión de Meta (App Review) que solo se exige para acceso público a cuentas de terceros.

## Plataformas

| Plataforma | Estado | API | Media | Notas |
|-----------|--------|-----|-------|-------|
| Facebook | ✅ | Meta Graph API | imagen, video | Página o perfil con `pages_manage_posts` |
| Instagram | ✅ | Meta Graph API | imagen, video, Reels, Stories | Requiere cuenta Business/Creator vinculada a una página FB |
| YouTube | ✅ | YouTube Data API v3 | video | Sube con visibilidad `private`/`unlisted`/`public` |
| TikTok | 🔜 | Content Posting API | video | Requiere auditoría de TikTok (2-6 semanas); patrón documentado en `docs/` |
| X/Twitter | 🔜 | API v2 | imagen, video | El free tier de X es muy limitado; documentado en `docs/` |

## Instalación

```bash
git clone https://github.com/tu-usuario/social-broadcast-mcp.git
cd social-broadcast-mcp
npm install
npm run build
```

## Configuración en Hermes (o cualquier cliente MCP)

```yaml
# ~/.hermes/config.yaml (o config del perfil)
mcp_servers:
  social-broadcast:
    command: "node"
    args: ["/ruta/a/social-broadcast-mcp/dist/index.js"]
```

O en cualquier cliente MCP compatible:

```json
{
  "mcpServers": {
    "social-broadcast": {
      "command": "node",
      "args": ["/ruta/a/social-broadcast-mcp/dist/index.js"]
    }
  }
}
```

## Uso

### 1. Conectar Facebook + Instagram

Necesitas crear una app en [developers.facebook.com](https://developers.facebook.com) (ver `docs/SETUP_META.md`) y obtener:
- **App ID** (clientId)
- **App Secret** (clientSecret, solo necesario en modo desarrollo)

Luego, desde el agente:

```
connect_meta(clientId: "TU_APP_ID", clientSecret: "TU_APP_SECRET")
```

Se abre el navegador → autorizas con tu cuenta → las cuentas quedan guardadas localmente en `~/.social-broadcast-mcp/`.

### 2. Conectar YouTube

Crea un proyecto en [Google Cloud Console](https://console.cloud.google.com) con la YouTube Data API v3 (ver `docs/SETUP_YOUTUBE.md`):

```
connect_youtube(clientId: "TU_CLIENT_ID", clientSecret: "TU_CLIENT_SECRET")
```

### 3. Ver cuentas conectadas

```
list_accounts()
```

### 4. Publicar

```
publish_post(
  accountId: "fb:533433607139839",
  content: "🌀 CREA TU PROPIO GONG 🌀\nUn gong hecho por ti, para ti, como tú.",
  mediaUrls: ["https://tudominio.com/imagen.jpg"],
  platformOptions: { "mediaType": "REELS" }  // para Reels de IG
)
```

Para programar en vez de publicar ya, añade `scheduledAt: "2026-09-01T18:00:00+01:00"`.

> **Nota sobre media**: la API acepta URLs públicas. Para subir archivos locales, alójalo en cualquier sitio accesible (un bucket S3/GCS, tu web, o un servidor local expuesto) y pasa su URL. Un helper de subida directa está en el roadmap.

## Documentación

- [`docs/SETUP_META.md`](docs/SETUP_META.md) — crear la app de Meta paso a paso
- [`docs/SETUP_YOUTUBE.md`](docs/SETUP_YOUTUBE.md) — proyecto Google Cloud + OAuth
- [`docs/TIKTOK.md`](docs/TIKTOK.md) — cómo sería la integración con TikTok (auditoría requerida)
- [`docs/SECURITY.md`](docs/SECURITY.md) — gestión local de tokens y buenas prácticas

## Seguridad

- Los tokens se guardan **localmente** en `~/.social-broadcast-mcp/` con permisos `0600`.
- Nunca se envían a ningún servidor externo.
- No hay telemetría. No hay analytics. No hay nada que llame a casa.
- Revisa `src/auth/store.ts` para ver exactamente qué se guarda.

## Licencia

MIT — libre para usar, copiar, modificar y redistribuir. Hecho para la comunidad, a partir de la experiencia real publicando el calendario del Templo del Gong (Vilagarcía de Arosa).

## Disclaimer

Este proyecto no está afiliado con Meta, Google, TikTok ni X Corp. Las marcas son de sus respectivos dueños. El uso de las APIs está sujeto a los términos de servicio de cada plataforma.