mcpbcn by PSValley - MCP Server

🏛️ BCNOpen MCP Server

Servidor MCP para consultar normativa legal chilena - Integración completa con DATOS.BCN.CL y LeyChile.

🎯 Características

🔍 Búsqueda avanzada de normas legales usando SPARQL
📄 Descarga automática de PDFs vía LeyChile Scraper
📝 Extracción de texto con detección de artículos y estructura
💾 Cache inteligente de 3 niveles (Memoria + SQLite + Files)
🚀 Integración MCP nativa para Claude y otros LLMs
⚡ Alta performance con cache hits >70%

🚀 Quick Start

Tienes dos opciones para ejecutar BCNOpen:

Opción A: Docker (Recomendado) 🐳

cd C:\Users\rampa\mcpbcn

# Copiar variables de entorno
cp .env.example .env

# Crear red compartida con el scraper
docker network create bcn-network
docker network connect bcn-network scraper-leychile

# Levantar BCNOpen
docker-compose up -d

# Ver logs
docker-compose logs -f

Ver documentación completa:

Opción B: Node.js Local

1. Prerequisitos

Node.js >= 18.0.0
LeyChile Scraper corriendo en localhost:2437
Acceso a Internet (para DATOS.BCN.CL)

2. Instalación

```bash cd C:\Users\rampa\mcpbcn npm install ```

3. Configuración

Edita config/default.json y ajusta los paths:

```json { "scraper": { "baseUrl": "http://localhost:2437", "downloadsPath": "C:/Users/rampa/chapalapachala/scraper-system/volumes/downloads/leychile" } } ```

4. Build

```bash npm run build ```

5. Ejecutar

```bash

Modo desarrollo

npm run dev

Modo producción

npm start ```

🔧 Configuración en Claude Desktop

Edita el archivo de configuración de Claude:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Agrega:

```json { "mcpServers": { "bcnopen": { "command": "node", "args": ["C:\Users\rampa\mcpbcn\dist\index.js"] } } } ```

Reinicia Claude Desktop.

🛠️ Herramientas Disponibles

1. `search_normas`

Buscar normas por palabra clave, tipo, organismo o fecha.

Ejemplo: ```typescript { query: "educación", tipoNorma: "ley", limite: 10 } ```

Retorna: ```json { "resultados": [ { "uri": "http://datos.bcn.cl/recurso/...", "titulo": "Ley General de Educación", "numero": "20370", "tipo": "ley", "leychile": { "code": "1006043", "url": "https://www.bcn.cl/leychile/navegar?idNorma=1006043" } } ], "total": 1 } ```

2. `get_norma_details`

Obtener metadatos completos de una norma específica.

Ejemplo: ```typescript { leychileCode: "235507" } ```

Retorna:

Título completo
Número y tipo
Organismo emisor
Fechas de publicación y promulgación
Versiones disponibles
Palabras clave

3. `get_norma_texto`

Obtener texto completo de una norma (descarga PDF y extrae texto).

Ejemplo: ```typescript { leychileCode: "235507", formato: "texto", incluirEstructura: true } ```

Retorna: ```json { "norma": { "titulo": "Ley 20000", "numero": "20000", "leychileCode": "235507" }, "contenido": { "formato": "texto", "texto": "Artículo 1°.- El que..." }, "estructura": { "articulos": [ { "numero": "1", "texto": "El que, sin la competente autorización..." } ] }, "metadata": { "paginas": 45, "fechaDescarga": "2025-01-12T10:30:00Z" } } ```

⏱️ Performance:

Primera consulta (cold cache): ~20-25s
Consultas posteriores (cached): <100ms

4. `get_cache_stats`

Obtener estadísticas del sistema de cache.

Retorna: ```json { "memory": { "size": 45, "maxSize": 1000 }, "database": { "pdfs": 120, "texts": 98, "totalSizeMB": 345.67 } } ```

📊 Arquitectura

``` ┌─────────────────────────────────────┐ │ CLAUDE / LLM │ └──────────────┬──────────────────────┘ │ MCP Protocol ┌──────────────▼──────────────────────┐ │ BCNOpen MCP Server │ │ ┌───────────────────────────────┐ │ │ │ SPARQL Client │ Scraper │ │ │ │ PDF Extractor │ Cache Mgr │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────┘ │ │ ┌───────▼──────┐ ┌──────▼────────┐ │ DATOS.BCN.CL │ │ LeyChile │ │ (SPARQL) │ │ Scraper │ └──────────────┘ └───────────────┘ ```

Flujo típico:

Claude llama search_normas → Query SPARQL
Claude llama get_norma_texto con leychileCode
BCNOpen verifica cache de texto → ❌ No
BCNOpen verifica cache de PDF → ❌ No
BCNOpen llama LeyChile Scraper → Descarga PDF
BCNOpen extrae texto con pdf-parse
BCNOpen cachea PDF + texto
Retorna texto a Claude

Siguiente consulta: Cache hit inmediato (<100ms)

🧪 Testing

```bash

Run tests

npm test

Run tests with UI

npm run test:ui

Run tests with coverage

npm run test -- --coverage ```

📁 Estructura del Proyecto

``` bcnopen-mcp/ ├── src/ │ ├── index.ts # Entry point MCP │ ├── types/ # TypeScript types │ ├── clients/ │ │ ├── sparql.ts # SPARQL client │ │ └── scraper.ts # Scraper client │ ├── extractors/ │ │ └── pdf.ts # PDF text extractor │ ├── cache/ │ │ ├── database.ts # SQLite cache │ │ └── manager.ts # Cache coordinator │ └── tools/ │ └── index.ts # MCP tools implementation ├── config/ │ └── default.json # Configuration ├── cache/ # Cache directory (gitignored) │ ├── pdfs/ # Cached PDF files │ └── database/ # SQLite database ├── tests/ # Test files ├── package.json ├── tsconfig.json └── README.md ```

🔧 Troubleshooting

Error: "LeyChile Scraper service is not running"

Solución: ```bash

Verificar que el scraper esté corriendo

docker ps | grep leychile

Si no está corriendo, iniciarlo

docker start scraper-leychile

Verificar salud

curl http://localhost:2437/health ```

Error: "SPARQL query failed"

Causas posibles:

Sin conexión a Internet
DATOS.BCN.CL está caído (raro)
Query malformada

Solución: ```bash

Verificar conectividad

curl https://datos.bcn.cl/sparql

Ver logs del servidor

npm run dev # Modo desarrollo muestra logs detallados ```

PDFs no se encuentran

Verificar path del scraper: ```bash

Ver dónde guarda el scraper

docker exec scraper-leychile ls /downloads/leychile

Verificar path en config

cat config/default.json | grep downloadsPath ```

El path debe coincidir con el volumen del scraper.

📈 Performance Tips

Cache warm-up: Consulta las normas más comunes primero
Batch operations: Si necesitas múltiples normas, búscalas de una vez
Usar leychileCode: Más rápido que buscar por URI
Cleanup periódico: Ejecuta get_cache_stats y limpia si es necesario

🤝 Integración con Otros Servicios

Uso Programático (sin Claude)

```typescript import { BCNOpenTools } from './tools/index.js';

const tools = new BCNOpenTools(config);

// Buscar normas const results = await tools.searchNormas({ query: 'educación', limite: 5 });

// Obtener texto const texto = await tools.getNormaTexto({ leychileCode: '1006043' });

console.log(texto.contenido.texto); ```

📚 Documentación Adicional

ANALISIS_API_BCN.md - Análisis exhaustivo de DATOS.BCN.CL
ARQUITECTURA_BCNOPEN.md - Diseño detallado del sistema
INTEGRACION_LEYCHILE_SCRAPER.md - Integración con el scraper

🎯 Roadmap

Soporte para búsqueda por palabra clave en texto completo
Índice local con Elasticsearch para búsquedas más rápidas
OCR para PDFs escaneados
API REST opcional (además de MCP)
Dashboard web para monitoreo de cache
Soporte para otros formatos (Markdown, HTML)
Notificaciones de actualizaciones de normas

📄 Licencia

MIT

👤 Autor

Proyecto BCNOpen - MCP Server para Ley Chile

¿Preguntas? ¿Problemas?

Revisa la documentación en los archivos .md del proyecto o abre un issue.

Status: ✅ MVP Implementado - Listo para testing