# MCP Venezuela FakeNews

Servidor MCP (Model Context Protocol) para combatir desinformación sobre Venezuela. Integra patrones reales de fake news identificados en investigación (junio 2026) con búsqueda web actualizada vía Tavily.

## Key Features

- **4 herramientas MCP** para verificar claims, buscar fuentes oficiales, listar patrones y generar reportes
- **Conocimiento base embebido** de 6 patrones reales de desinformación venezolana (videos descontextualizados, contenido IA, usurpación de canales, falsos anuncios, operaciones YouTube, desinformación salarial)
- **Búsqueda Tavily opcional** — sin API key funciona solo con el conocimiento base
- **Ligero** — sin dependencias pesadas, compila a un solo archivo JS

## Tech Stack

- **Runtime**: Node.js 18+
- **Lenguaje**: TypeScript 6.0 (compilado a ES2022)
- **Framework MCP**: `@modelcontextprotocol/sdk` ^1.29
- **Validación**: Zod ^4.4
- **Búsqueda web**: Tavily Search API (opcional)
- **Entorno**: dotenv para configuración local

## Prerequisites

- Node.js 18 o superior (20+ recomendado)
- npm
- (Opcional) Una API key de [Tavily](https://tavily.com) — la misma que usas en opencode

## Getting Started

### 1. Clonar e instalar

```bash
git clone <repo-url> ~/mcp-venezuela-fakenews
cd ~/mcp-venezuela-fakenews
npm install
```

### 2. Configurar variable de entorno (opcional)

Copia `.env.example` a `.env` y agrega tu API key de Tavily:

```bash
cp .env.example .env
# Edita .env con tu clave real:
# TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Sin API key las herramientas funcionan igual, pero las búsquedas web devuelven un aviso para que la configures.

### 3. Compilar

```bash
npm run build
```

Esto produce `dist/index.js`, `dist/index.js.map` y `dist/index.d.ts`.

### 4. Probar con el inspector MCP

```bash
npm run inspect
```

Esto abre una UI web local donde puedes probar cada herramienta interactivamente.

## Architecture Overview

### Directory Structure

```
mcp-venezuela-fakenews/
├── src/
│   └── index.ts          # Código fuente único (server + tools + lógica)
├── dist/                 # Compilado (generado por tsc)
│   ├── index.js
│   ├── index.js.map
│   └── index.d.ts
├── .env                  # Variables de entorno local (git-ignorado)
├── .env.example          # Plantilla para .env
├── package.json
├── tsconfig.json
└── README.md
```

### Request Lifecycle

1. El host MCP (opencode, Claude Desktop, etc.) inicia `dist/index.js` como subproceso via **STDIO transport**
2. El servidor se conecta al transporte y registra sus 4 herramientas
3. Cada llamada a tool es un mensaje JSON-RPC sobre STDIO
4. La herramienta ejecuta su lógica: consulta patrones embebidos y/o llama a Tavily API
5. Devuelve un `content` block con tipo `text`

### Conocimiento embebido (sin base de datos)

El servidor no necesita base de datos externa. Los patrones de desinformación y datos clave están hardcodeados en `src/index.ts`:

- **`PATTERNS`**: array de 6 objetos con nombre, descripción, ejemplos y método de detección
- **`KEY_FACTS`**: objeto con 5 categorías (política, economía, terremotos, migración, desinformación)

Esto permite que el MCP funcione offline sin dependencias externas.

### Tavily Search (opcional)

La función `tavilySearch()` en `src/index.ts:62`:
- Lee `TAVILY_API_KEY` del entorno
- Hace POST a `https://api.tavily.com/search` con query mejorada (agrega "Venezuela" y filtros de fuentes confiables)
- Retorna resultados estructurados o un error manejable
- Todas las tools manejan graceful degradation si no hay API key

### Herramientas expuestas

| Tool | Input | Output |
|------|-------|--------|
| `get_fakenews_patterns` | Ninguno | Lista completa de 6 patrones con ejemplos y detección |
| `verify_claim` | `claim` (string), `context?` (string) | Análisis del claim + patrones coincidentes + búsqueda web |
| `search_official_sources` | `topic` (string), `max_results?` (number, default 6) | Resultados de fuentes confiables (USGS, IOM, Reuters, etc.) |
| `generate_factcheck_report` | `topic` (string) | Reporte estructurado borrador con datos clave del cuaderno |

## Environment Variables

| Variable | Requerida | Default | Descripción |
|----------|-----------|---------|-------------|
| `TAVILY_API_KEY` | No | — | API key de Tavily para búsquedas web. Sin ella las tools funcionan con conocimiento base solamente. |

## Available Scripts

| Comando | Descripción |
|---------|-------------|
| `npm run build` | Compila TypeScript a JS con `tsc` |
| `npm run start` | Ejecuta `dist/index.js` directamente |
| `npm run dev` | Watch mode: compila automáticamente en cada cambio (`tsc -w`) |
| `npm run inspect` | Abre el inspector MCP para probar herramientas |

## Configuración en OpenCode

Agrega esto a tu `~/.config/opencode/opencode.json` o al `opencode.json` del proyecto:

```json
{
  "mcpServers": {
    "venezuela-fakenews": {
      "command": "node",
      "args": ["/Users/josecastro/mcp-venezuela-fakenews/dist/index.js"]
    }
  }
}
```

Reinicia opencode o recarga la configuración.

## Uso

### Listar patrones de desinformación

```
Usa la herramienta get_fakenews_patterns
```

### Verificar un claim

```
Usa verify_claim con:
  claim: "Delcy Rodríguez anunció aumento de salario a $800 mensuales"
  context: "salario"
```

### Buscar fuentes oficiales

```
Usa search_official_sources con:
  topic: "terremotos junio 2026 víctimas oficiales"
```

### Generar reporte

```
Usa generate_factcheck_report con:
  topic: "Situación económica de Venezuela post-terremotos"
```

## Testing

El proyecto actualmente no tiene suite de tests. Para verificar manualmente:

```bash
# Compila sin errores
npm run build

# Prueba con el inspector
npm run inspect
```

## Deployment

### Como servidor MCP local (recomendado)

No necesita deployment — se ejecuta como subproceso del host MCP. Solo compilar y apuntar la configuración MCP al `dist/index.js`.

### Como servicio remoto (experimental)

Si quisieras ejecutarlo como servidor remoto:
1. Cambiar `StdioServerTransport` por `SSEServerTransport` del SDK
2. Desplegar en cualquier plataforma Node (Railway, Fly.io, Render)
3. Configurar el host MCP con la URL del SSE endpoint

## Troubleshooting

### `TAVILY_API_KEY no configurada`

Las tools funcionan sin API key, pero las búsquedas web no estarán disponibles. Configúrala en `.env` o exporta la variable:

```bash
export TAVILY_API_KEY="tvly-tu-clave-aqui"
```

### Error de compilación

```bash
# Asegúrate de tener TypeScript 6+
npx tsc --version

# Reinstala dependencias
rm -rf node_modules && npm install
```

### El MCP no se conecta

- Verifica que `dist/index.js` existe (`npm run build`)
- Verifica la ruta absoluta en la configuración MCP
- Ejecuta directamente para ver errores: `node dist/index.js`
- El servidor escribe logs a STDERR (visible en los logs del host MCP)

## Contributing

Este proyecto nace de una investigación sobre desinformación en Venezuela (junio 2026). Las contribuciones son bienvenidas:

- Agregar más patrones a `PATTERNS` en `src/index.ts`
- Mejorar la detección automática de claims en `verify_claim`
- Conectar con el cuaderno de Obsidian para lectura dinámica
- Agregar tests

## License

MIT