文档处理与搜索服务器

🚀 MCP Server

Servidor de procesamiento y búsqueda de documentos técnicos construido con Bun, Hono y Orama.

📋 Características

• ✅ Parseo de documentos: Markdown, YAML, JSON
• ✅ Extracción de metadatos: Frontmatter, propiedades, tags
• ✅ Búsqueda full-text: Indexación y búsqueda con Orama
• ✅ API REST: Endpoints para carga y búsqueda de documentos
• ✅ Tipos TypeScript: Completamente tipado
• ✅ Desarrollo rápido: Hot reload con Bun

🛠️ Tecnologías

• Runtime: Bun - JavaScript runtime rápido
• Framework: Hono - Framework HTTP ligero
• Búsqueda: Orama - Motor de búsqueda full-text
• Parseo: gray-matter + js-yaml
• Lenguaje: TypeScript

🚀 Instalación

# Clonar el repositorio
git clone <repository-url>
cd mcp-server

# Instalar dependencias
bun install

# Ejecutar en modo desarrollo
bun dev

El servidor estará disponible en http://localhost:3000

📚 API Endpoints

Documentos

POST /docs

Carga y parsea un documento.

Body:

{
  "content": "# Título\nContenido del documento...",
  "filename": "documento.md"
}

Respuesta:

{
  "status": "ok",
  "document": {
    "id": "uuid",
    "type": "markdown",
    "content": "Contenido del documento...",
    "metadata": {
      "title": "Título",
      "tags": ["tag1", "tag2"]
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "indexed": true
}

Búsqueda

GET /search?q=<query>&limit=<number>&offset=<number>

Búsqueda general en todos los campos.

Ejemplo:

GET /search?q=javascript&limit=10&offset=0

GET /search/type/:type?limit=<number>&offset=<number>

Búsqueda por tipo de documento.

Ejemplo:

GET /search/type/markdown?limit=5

GET /search/tags?tags=<tag1,tag2>&limit=<number>&offset=<number>

Búsqueda por tags.

Ejemplo:

GET /search/tags?tags=javascript,guide&limit=5

GET /search/stats

Obtiene estadísticas del índice.

POST /search/clear

Limpia el índice de búsqueda.

Health Check

GET /health

Verifica el estado del servidor.

🔍 Tipos de Documentos Soportados

Markdown

---
title: "Mi Documento"
description: "Descripción del documento"
tags: ["tag1", "tag2"]
---

# Contenido del documento

YAML

title: "Configuración"
description: "Archivo de configuración"
database:
  host: localhost
  port: 5432

JSON

{
  "title": "Datos",
  "description": "Archivo de datos",
  "items": ["item1", "item2"]
}

🧪 Pruebas

Ejecuta el script de pruebas para verificar la funcionalidad:

# Asegúrate de que el servidor esté corriendo
bun dev

# En otra terminal, ejecuta las pruebas
node test-search.js

El script de pruebas:

1. Carga 5 documentos de ejemplo
2. Prueba búsquedas generales
3. Prueba búsquedas por tags
4. Prueba búsquedas por tipo
5. Muestra estadísticas

📁 Estructura del Proyecto

src/
├── app.ts                 # Aplicación principal Hono
├── index.ts              # Punto de entrada del servidor
├── routes/
│   ├── health.ts         # Health check
│   ├── docs.ts           # Endpoints de documentos
│   └── search.ts         # Endpoints de búsqueda
├── services/
│   ├── DocParserService.ts    # Parseo de documentos
│   └── OramaService.ts        # Búsqueda full-text
└── utils/                # Utilidades

🔧 Desarrollo

Comandos Disponibles

# Desarrollo con hot reload
bun dev

# Ejecutar directamente
bun run src/index.ts

# Instalar dependencias
bun install

# Ver dependencias
bun pm ls

Variables de Entorno

Por ahora el servidor usa configuraciones por defecto:

• Puerto: 3000
• Host: localhost

📊 Estado del Proyecto

🤝 Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

Desarrollado con ❤️ usando Bun, Hono y Orama