# cantkeepupwithai-mcp

Prototipo de servidor MCP (Model Context Protocol) que expone los datos de
[cantkeepupwithai.com](https://cantkeepupwithai.com) — trends de IA, digest
diario, toolbox y stats del pipeline — a asistentes compatibles con MCP como
Claude Desktop.

Es un cliente delgado: cada herramienta hace una petición HTTP al backend real
(`cantkeepupwithai/backend`, Express + Prisma) corriendo en local, y devuelve
la respuesta tal cual como JSON.

## Herramientas expuestas

| Herramienta | Descripción | Endpoint del backend |
|---|---|---|
| `get_trending_topics` | Lista los trends de IA rankeados por menciones (últimos 30 días), con sparkline de 7 días. Filtro opcional por `tag`. | `GET /api/trends` |
| `get_trend_detail` | Detalle completo de un trend por `id`: resumen, por qué importa, historial y referencias/fuentes. | `GET /api/trends/:id` |
| `get_daily_digest` | El digest diario de noticias de IA. Sin `date` devuelve el último publicado; con `date` (YYYY-MM-DD) devuelve el de ese día. | `GET /api/digests/latest` o `GET /api/digests/:date` |
| `list_digest_archive` | Lista paginada de digests pasados (fecha, número de issue, cantidad de historias). | `GET /api/digests` |
| `search_toolbox` | Búsqueda de texto completo sobre trends, historias del digest y el toolbox de herramientas de IA. | `GET /api/search` |
| `get_pipeline_stats` | Stats de la última corrida del pipeline de ingesta (fuentes revisadas, posts leídos, etc). | `GET /api/pipeline/stats` |

## Requisitos

- Node.js 20+
- El backend de `cantkeepupwithai` corriendo en local (por defecto en
  `http://localhost:4000`), con su base de datos accesible. Ver
  `cantkeepupwithai/backend/README.md` para levantarlo.

## Instalación y build

```bash
cd cantkeepupwithai-mcp
npm install
npm run build
```

Esto compila `src/` a `dist/index.js`, que es el entrypoint del servidor MCP
(transporte **stdio**).

## Probarlo suelto (sin Claude Desktop)

Con el backend corriendo en `localhost:4000`, podés levantar el servidor y
hablarle por stdio con el [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Eso abre una UI en el navegador donde podés listar las herramientas y
ejecutarlas contra datos reales.

## Configurarlo en Claude Desktop

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

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Y agregá una entrada en `mcpServers` (ajustá la ruta absoluta a donde clonaste
este repo):

```json
{
  "mcpServers": {
    "cantkeepupwithai": {
      "command": "node",
      "args": [
        "/Users/pablolarraz/Desktop/dev/ckuwai/cantkeepupwithai-mcp/dist/index.js"
      ],
      "env": {
        "CKUWAI_API_BASE_URL": "http://localhost:4000"
      }
    }
  }
}
```

Reiniciá Claude Desktop. El servidor debería aparecer con el ícono de
herramientas (🔨), y podés pedirle cosas como *"¿qué trends de IA están
subiendo esta semana según cantkeepupwithai?"* o *"dame el digest de hoy de
cantkeepupwithai"*.

**Importante:** el backend de `cantkeepupwithai` debe estar corriendo en
local (`npm run dev` dentro de `cantkeepupwithai/backend`) para que las
herramientas devuelvan datos — este servidor MCP no incluye lógica de
negocio propia, solo reenvía las peticiones.

## Variables de entorno

| Variable | Default | Descripción |
|---|---|---|
| `CKUWAI_API_BASE_URL` | `http://localhost:4000` | URL base del backend contra la que se hacen las peticiones. |
| `MCP_AUTH_TOKEN` | — | Solo lo usa `api/mcp.ts` (despliegue remoto). Token que el cliente debe mandar como `Authorization: Bearer <token>`. Sin transporte stdio no aplica. |

## Despliegue remoto (Vercel)

Además del transporte stdio para uso local, el repo incluye `api/mcp.ts`: el
mismo servidor MCP expuesto por **Streamable HTTP** (el transporte estándar
de MCP para servidores remotos), como función serverless de Vercel. Está
desplegado en:

```
https://cantkeepupwithai-mcp.vercel.app/api/mcp
```

apuntando al backend de producción real (`https://cantkeepupwithai-backend.vercel.app`).

Cada request HTTP crea una instancia nueva y sin estado del servidor MCP
(`sessionIdGenerator: undefined`) — apropiado para funciones serverless, que
no garantizan que dos requests caigan en el mismo proceso.

**Autenticación:** el endpoint exige `Authorization: Bearer <MCP_AUTH_TOKEN>`
en cada request; sin el header (o con un token incorrecto) devuelve 401. El
valor real del token vive como variable de entorno en el proyecto de Vercel
(`vercel env ls`), no está en este repo.

Para conectar un cliente MCP remoto (ej. Claude Desktop con soporte de
conectores HTTP, o cualquier cliente MCP que hable Streamable HTTP):

```json
{
  "mcpServers": {
    "cantkeepupwithai-remote": {
      "url": "https://cantkeepupwithai-mcp.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}
```

Para redesplegar cambios:

```bash
npx vercel --prod
```

### Próximos pasos para una versión remota más madura

- El token compartido actual es suficiente para un prototipo de un solo
  usuario, pero no escala a múltiples usuarios/organizaciones — la spec de
  MCP recomienda OAuth 2.1 para servidores remotos multi-tenant.
- No hay rate limiting propio en el servidor MCP (más allá del que ya tiene
  el backend real por IP) — un token filtrado podría generar tráfico
  excesivo contra el backend de producción.
- Solo se exponen operaciones de **lectura**. El backend también tiene
  endpoints de escritura (votar/reportar herramientas del toolbox, crear
  herramientas desde un repo, suscribirse al newsletter) que deliberadamente
  no se expusieron en este prototipo — habría que decidir caso por caso si
  tiene sentido darle a un asistente IA la capacidad de escribir datos.