Akyn AI

akyn-ai

Convierte cualquier fuente de datos en un servidor MCP en 5 minutos.

Crea bases de conocimiento que asistentes de IA como Claude y Cursor puedan consultar directamente. Sin necesidad de infraestructura.

---

¿Qué es esto?

Este SDK te permite crear servidores MCP (Model Context Protocol) a partir de cualquier fuente de datos. Tus documentos, PDFs, sitios web o cualquier texto pueden convertirse en una base de conocimiento consultable que los asistentes de IA pueden acceder directamente.

Casos de uso:

• 📚 Haz que tu documentación sea buscable por Cursor/Claude
• 🔍 Construye pipelines de RAG (Generación Aumentada por Recuperación)
• 🤖 Crea asistentes de IA personalizados con conocimiento de dominio
• 📖 Indexa artículos de investigación, guías o cualquier contenido de texto

---

Inicio Rápido

Instalación

npm install akyn-ai

Uso Básico

import { KnowledgeBase } from 'akyn-ai'

// Create a knowledge base
const kb = new KnowledgeBase({
  name: 'my-docs',
  description: 'My project documentation',
})

// Add your content
await kb.addDirectory('./docs')           // Add all docs from a folder
await kb.addFile('./README.md')           // Add a specific file
await kb.addURL('https://docs.example.com') // Scrape a URL
await kb.addText('Important info here')   // Add raw text

// Serve as MCP server
kb.serveStdio()  // For Cursor/Claude Desktop

Conectar a Cursor

Añade a tu .cursor/mcp.json:

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": ["ts-node", "./my-kb.ts"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Conectar a Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": ["ts-node", "/path/to/my-kb.ts"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

---

Características

📁 Ingestión Multi-Fuente

// Files (PDF, DOCX, TXT, Markdown)
await kb.addFile('./guide.pdf')
await kb.addFile('./manual.docx')

// Directories (recursive)
await kb.addDirectory('./docs', {
  recursive: true,
  extensions: ['.md', '.txt', '.pdf'],
})

// URLs
await kb.addURL('https://docs.example.com')
await kb.addURLs([
  'https://example.com/page1',
  'https://example.com/page2',
])

// Raw text
await kb.addText('Custom content here', 'My Notes')

🔍 Fragmentación Inteligente

El texto se divide automáticamente en fragmentos óptimos para la incrustación:

const kb = new KnowledgeBase({
  name: 'my-kb',
  chunking: {
    maxSize: 1000,    // Max characters per chunk
    overlap: 200,     // Overlap between chunks for context
  },
})

🧠 Incrustaciones Flexibles

Usa OpenAI por defecto, pero puedes traer el tuyo propio:

import { KnowledgeBase, type EmbeddingsProvider } from 'akyn-ai'

// Use OpenAI (default)
const kb = new KnowledgeBase({ name: 'my-kb' })

// Or customize OpenAI settings
import { OpenAIEmbeddings } from 'akyn-ai'

const kb = new KnowledgeBase({
  name: 'my-kb',
  embeddings: new OpenAIEmbeddings({
    model: 'text-embedding-3-large',  // Better quality
    apiKey: 'sk-...',
  }),
})

// Or bring your own provider
class MyEmbeddings implements EmbeddingsProvider {
  readonly dimensions = 384
  
  async embed(text: string) {
    // Your embedding logic here
    return { embedding: [...], tokenCount: 100 }
  }
  
  async embedBatch(texts: string[]) {
    return Promise.all(texts.map(t => this.embed(t)))
  }
}

const kb = new KnowledgeBase({
  name: 'my-kb',
  embeddings: new MyEmbeddings(),
})

💾 Almacenes Vectoriales

En Memoria (Por Defecto)

Perfecto para desarrollo y conjuntos de datos pequeños:

import { InMemoryVectorStore } from 'akyn-ai'

const kb = new KnowledgeBase({
  name: 'my-kb',
  vectorStore: new InMemoryVectorStore({
    persistPath: './kb-data.json',  // Optional: save to disk
  }),
})

Qdrant

Para cargas de trabajo de producción, usa Qdrant - una base de datos vectorial de alto rendimiento:

import { KnowledgeBase, QdrantVectorStore } from 'akyn-ai'

const kb = new KnowledgeBase({
  name: 'my-kb',
  vectorStore: new QdrantVectorStore(),  // That's it!
})

Configuración Local (Docker)

# Start Qdrant with one command
docker run -p 6333:6333 qdrant/qdrant

# With persistent storage
docker run -p 6333:6333 -v ./qdrant_data:/qdrant/storage qdrant/qdrant

Qdrant Cloud

Para alojamiento gestionado, usa Qdrant Cloud:

const kb = new KnowledgeBase({
  name: 'my-kb',
  vectorStore: new QdrantVectorStore({
    url: 'https://your-cluster.cloud.qdrant.io',
    apiKey: process.env.QDRANT_API_KEY,
    collection: 'my-docs',  // Optional: defaults to 'akyn_documents'
  }),
})

Opción	Tipo	Predeterminado	Descripción
url	string	http://localhost:6333	URL del servidor Qdrant
apiKey	string	-	Clave API (requerida para Qdrant Cloud)
collection	string	akyn_documents	Nombre de la colección
dimensions	number	auto-detectado	Dimensiones del vector

Almacén Vectorial Personalizado

Implementa la interfaz VectorStore para otras bases de datos (Pinecone, Weaviate, etc.):

import type { VectorStore } from 'akyn-ai'

class MyVectorStore implements VectorStore {
  async add(document) { /* ... */ }
  async addBatch(documents) { /* ... */ }
  async search(embedding, options) { /* ... */ }
  async delete(id) { /* ... */ }
  async clear() { /* ... */ }
  async count() { /* ... */ }
}

🌐 Múltiples Opciones de Transporte

// Stdio (for Cursor/Claude Desktop)
kb.serveStdio()

// HTTP (for web clients)
await kb.serveHttp({ port: 3000 })

---

Uso de CLI

También puedes usar la CLI sin escribir código:

# Index a directory
npx akyn-ai --dir ./docs --name "My Docs"

# Use a config file
npx akyn-ai --config ./kb-config.json

# Run as HTTP server
npx akyn-ai --dir ./docs --http 3000

Formato de Archivo de Configuración

{
  "name": "My Knowledge Base",
  "description": "Project documentation",
  "sources": [
    { "type": "directory", "path": "./docs" },
    { "type": "file", "path": "./README.md" },
    { "type": "url", "url": "https://docs.example.com" }
  ]
}

---

Referencia de API

KnowledgeBase

Clase principal para crear y gestionar bases de conocimiento.

const kb = new KnowledgeBase({
  name: string,           // Required: Name of the knowledge base
  description?: string,   // Optional: Description
  version?: string,       // Optional: Version (default: '1.0.0')
  embeddings?: EmbeddingsProvider,  // Optional: Custom embeddings
  vectorStore?: VectorStore,        // Optional: Custom vector store
  chunking?: ChunkOptions,          // Optional: Chunking settings
  retrieval?: RetrievalOptions,     // Optional: Retrieval settings
})

Opciones de Recuperación

Controla cuántos resultados se devuelven y su calidad mínima. Estas opciones se configuran en tu código (no expuestas a agentes de IA), dándote control total sobre el comportamiento de recuperación.

const kb = new KnowledgeBase({
  name: 'my-kb',
  retrieval: {
    topK: 10,         // Return up to 10 chunks per query
    threshold: 0.5,   // Only return chunks with similarity score >= 0.5
  },
})

Opción	Tipo	Predeterminado	Descripción
topK	number	5	Número máximo de fragmentos a recuperar por consulta
threshold	number	0	Puntuación mínima de similitud (0-1). Establécelo en 0 para devolver todos los resultados, o más alto (p. ej. 0.5, 0.7) para filtrar fragmentos menos relevantes

Métodos

Método	Descripción
addText(text, name?)	Añadir contenido de texto sin procesar
addFile(path, name?)	Añadir un archivo (PDF, DOCX, TXT, MD)
addDirectory(path, options?)	Añadir todos los archivos de un directorio
addURL(url, name?)	Añadir contenido desde una URL
addURLs(urls)	Añadir múltiples URLs
query(question, options?)	Consultar la base de conocimiento
listSources()	Listar todas las fuentes indexadas
serveStdio(options?)	Iniciar servidor MCP stdio
serveHttp(options?)	Iniciar servidor MCP HTTP

Opciones del Servidor HTTP

await kb.serveHttp({
  port: 3000,           // Port to listen on (default: 3000)
  host: '0.0.0.0',      // Host to bind to (default: '0.0.0.0')
  cors: true,           // Enable CORS (default: true)
  corsOrigin: '*',      // CORS origin (default: '*')
  debug: false,         // Enable debug logging (default: false)
})

Utilidades

El SDK también exporta utilidades que puedes usar de forma independiente:

import {
  // Text processing
  normalizeText,
  chunkText,
  extractTextFromHTML,
  stripMarkdown,
  
  // File loading
  loadFile,
  loadDirectory,
  loadURL,
  
  // Embeddings
  OpenAIEmbeddings,
  cosineSimilarity,
  
  // Vector stores
  InMemoryVectorStore,
  QdrantVectorStore,
} from 'akyn-ai'

---

Herramientas MCP

Cuando se conecta vía MCP, tu base de conocimiento expone estas herramientas:

query

Busca en la base de conocimiento con una pregunta en lenguaje natural.

{
  "name": "query",
  "arguments": {
    "question": "How do I authenticate?"
  }
}

Parámetro	Tipo	Descripción
question	string	La pregunta a buscar

Nota: El número de resultados y el umbral de similitud se configuran mediante la opción retrieval al crear la KnowledgeBase. Ver Opciones de Recuperación.

list_sources

Lista todas las fuentes indexadas en la base de conocimiento.

{
  "name": "list_sources",
  "arguments": {}
}

---

Ejemplos

Consulta el directorio examples para más:

• Uso básico
• Servidor HTTP
• Incrustaciones personalizadas
• Almacén vectorial Qdrant

---

Requisitos

• Node.js 18+
• Clave API de OpenAI (o proveedor de incrustaciones personalizado)

---

¿Quieres Alojamiento Gestionado?

¿Construyendo algo más grande? Echa un vistazo a Akyn para:

• ☁️ Bases de conocimiento alojadas
• 👥 Colaboración en equipo
• 📊 Análisis de uso
• 💰 Monetización (cobra por consultas)
• 🔐 Gestión de claves API

---

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee primero nuestras guías de contribución.

---

Licencia

MIT © Akyn AI