# MCP BCR

Servidor MCP (Model Context Protocol) para la Base de Datos del Banco Central de Reserva del Perú (BCRP).

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Descripción

Este servidor MCP permite consultar indicadores económicos oficiales del Perú en tiempo real a través de la API del BCRP. Incluye almacenamiento de contexto, memoria persistente con embeddings reales, knowledge graph, búsqueda híbrida (semántica + FTS5), caché histórico de series, análisis estadístico/econométrico, comparación internacional vía Banco Mundial, y RAG sobre documentos/PDFs para análisis económico avanzado.

## Características

- **API del BCRP**: Consulta en tiempo real de indicadores económicos, con caché histórico local en SQLite
- **Almacenamiento de Contexto**: Guardar y recuperar datos económicos
- **Memoria Persistente**: Búsqueda híbrida (FTS5 + embeddings reales con `@xenova/transformers`, modelo multilingüe con soporte de español, sin API key)
- **Knowledge Graph**: Relacionar indicadores y conceptos económicos
- **Búsqueda Vectorial**: Búsqueda semántica por similitud de coseno sobre embeddings reales
- **Análisis Estadístico**: Variación %, media móvil, correlación, regresión lineal/proyección, deflactación
- **Banco Mundial**: Comparación de indicadores de Perú frente a otros países
- **RAG de Documentos**: Ingesta de PDFs/URLs/texto y búsqueda semántica con cita de fuente

## Instalación

```bash
# Clonar el repositorio
git clone https://github.com/rodrigocapiz67-tech/mcp-bcr.git
cd mcp-bcr

# Instalar dependencias
npm install

# Compilar
npm run build
```

## Uso

### Como servidor MCP

El servidor se ejecuta en stdio y puede ser configurado en cualquier cliente MCP compatible.

### Configuración .mcp.json (Antigravity IDE u otros)

```json
{
  "mcpServers": {
    "mcp-bcr": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "env": {}
    }
  }
}
```

### Configuración en Claude Desktop

Añade lo siguiente a tu archivo `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-bcr": {
      "command": "node",
      "args": ["C:/source/mcp-bcr/dist/index.js"]
    }
  }
}
```

### Herramientas BCRP

#### Consultas Directas
- `bcrp_get_series`: Consultar cualquier serie del BCRP
- `bcrp_tipo_cambio`: Tipo de cambio SOL/USD
- `bcrp_inflacion`: Inflación (IPC)
- `bcrp_pbi`: Producto Bruto Interno
- `bcrp_tasas_interes`: Tasas de interés
- `bcrp_reservas`: Reservas internacionales
- `bcrp_buscar_series`: Buscar series disponibles
- `bcrp_series_disponibles`: Listar series predefinidas
- `bcrp_historial`: Historial completo cacheado localmente de una serie (sin red)

#### Análisis Estadístico/Econométrico
- `bcrp_estadisticas`: Variación %, media móvil y desviación estándar de una serie
- `bcrp_correlacion`: Correlación de Pearson entre dos series
- `bcrp_proyeccion`: Regresión lineal simple y proyección a futuro
- `bcrp_deflactar`: Ajustar una serie nominal por un índice de precios (valores reales)

#### Banco Mundial
- `worldbank_indicador`: Consultar un indicador para uno o más países (ISO-2)
- `worldbank_comparar_paises`: Comparar Perú vs. otros países (último valor y tendencia a 10 años)

#### RAG de Documentos
- `docs_ingest`: Ingerir un PDF/URL/texto plano (se trocea y embebe)
- `docs_search`: Búsqueda semántica sobre documentos ingeridos, con fuente para citar
- `docs_list`: Listar documentos ingeridos

#### Contexto
- `context_get`: Obtener un valor de contexto por clave
- `context_set`: Establecer un valor de contexto
- `context_delete`: Eliminar una entrada de contexto
- `context_list`: Listar todas las entradas de contexto

#### Memoria
- `memory_store`: Almacenar una entrada de memoria
- `memory_recall`: Buscar y recuperar recuerdos
- `memory_get`: Obtener una memoria específica por ID
- `memory_delete`: Eliminar una entrada de memoria
- `memory_find_by_tag`: Encontrar memorias por etiqueta
- `memory_find_similar`: Encontrar memorias similares

#### Knowledge Graph
- `graph_add_node`: Agregar un nodo al grafo
- `graph_get_node`: Obtener un nodo del grafo
- `graph_add_edge`: Agregar una arista entre nodos
- `graph_get_edges`: Obtener aristas de un nodo
- `graph_find_path`: Encontrar un camino entre nodos
- `graph_get_neighbors`: Obtener nodos vecinos
- `graph_find_by_type`: Encontrar nodos por tipo
- `graph_get_subgraph`: Obtener un subgrafo

#### Búsqueda Vectorial
- `vector_search`: Buscar contenido similar
- `vector_add`: Agregar contenido al índice vectorial
- `vector_similarity`: Calcular similitud entre textos
- `embeddings_reindex`: Recalcular todos los embeddings con el modelo actual (usar tras cambiar de modelo)

> El modelo de embeddings (`Xenova/paraphrase-multilingual-MiniLM-L12-v2`) es multilingüe e incluye español. Si en el futuro se cambia de modelo, el servidor avisa por stderr al arrancar si detecta que lo indexado quedó desactualizado — en ese caso hay que correr `embeddings_reindex` una vez.

## Series Predefinidas

| Código | Nombre |
|--------|--------|
| PD04635PD | Tipo de Cambio Promedio |
| PD04645PD | Tipo de Cambio Venta |
| PN02537MA | IPC Mensual |
| PN02538MA | IPC Anual |
| PN02521PA | PIB Trimestral |
| PD05462PM | Tasa Corto Plazo |
| PD04662PM | Reservas Internacionales |

## API del BCRP

Documentación: https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/api

Ejemplo de consulta:
```
https://estadisticas.bcrp.gob.pe/estadisticas/series/api/PN01270PM/json
```

## Arquitectura

```
mcp-bcr/
├── src/
│   ├── index.ts          # Punto de entrada
│   ├── server.ts         # Configuración del servidor MCP
│   ├── bcrp/
│   │   └── client.ts     # Cliente API del BCRP (+ caché local)
│   ├── worldbank/
│   │   └── client.ts     # Cliente API del Banco Mundial
│   ├── analysis/
│   │   └── stats.ts      # Funciones estadísticas/econométricas puras
│   ├── embeddings/
│   │   └── embedder.ts   # Embeddings locales (@xenova/transformers)
│   ├── rag/
│   │   └── ingest.ts     # Descarga/extracción/chunking de documentos
│   ├── db/
│   │   └── manager.ts    # Gestor de base de datos SQLite (+ FTS5)
│   ├── memory/
│   │   └── store.ts      # Sistema de memoria persistente
│   ├── graph/
│   │   └── graph.ts      # Knowledge Graph
│   └── tools/
│       ├── bcrp.ts       # Herramientas BCRP
│       ├── context.ts    # Herramientas de contexto
│       ├── memory.ts     # Herramientas de memoria
│       ├── graph.ts      # Herramientas de grafo
│       ├── vector.ts     # Herramientas vectoriales
│       ├── analysis.ts   # Herramientas de análisis estadístico
│       ├── worldbank.ts  # Herramientas de comparación internacional
│       └── rag.ts        # Herramientas de ingesta/búsqueda de documentos
├── package.json
├── tsconfig.json
└── .mcp.json
```

## Licencia

MIT