Akyn AI

akyn-ai

Transforme qualquer fonte de dados em um servidor MCP em 5 minutos.

Crie bases de conhecimento que assistentes de IA como Claude e Cursor podem consultar diretamente. Sem necessidade de infraestrutura.

---

O que é isso?

Este SDK permite criar servidores MCP (Model Context Protocol) a partir de qualquer fonte de dados. Seus documentos, PDFs, sites ou qualquer texto podem se tornar uma base de conhecimento consultável que assistentes de IA podem acessar diretamente.

Casos de uso:

• 📚 Torne sua documentação pesquisável pelo Cursor/Claude
• 🔍 Construa pipelines de RAG (Geração Aumentada por Recuperação)
• 🤖 Crie assistentes de IA personalizados com conhecimento de domínio
• 📖 Indexe artigos de pesquisa, guias ou qualquer conteúdo de texto

---

Início Rápido

Instalação

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 ao Cursor

Adicione ao seu .cursor/mcp.json:

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

Conectar ao Claude Desktop

Adicione ao ~/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-..."
      }
    }
  }
}

---

Recursos

📁 Ingestão Multi-Fonte

// 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')

🔍 Fragmentação Inteligente

O texto é automaticamente dividido em fragmentos ideais para incorporação:

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

🧠 Incorporações Flexíveis

Usa OpenAI por padrão, mas você pode trazer o seu próprio:

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(),
})

💾 Armazenamentos Vetoriais

Em Memória (Padrão)

Perfeito para desenvolvimento e conjuntos de dados pequenos:

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 trabalho de produção, use Qdrant - um banco de dados vetorial de alto desempenho:

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

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

Configuração 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 hospedagem gerenciada, use 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'
  }),
})

Opção	Tipo	Padrão	Descrição
url	string	http://localhost:6333	URL do servidor Qdrant
apiKey	string	-	Chave de API (obrigatória para Qdrant Cloud)
collection	string	akyn_documents	Nome da coleção
dimensions	number	detectado automaticamente	Dimensões do vetor

Armazenamento Vetorial Personalizado

Implemente a interface VectorStore para outros bancos de dados (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últiplas Opções de Transporte

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

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

---

Uso via CLI

Você também pode usar a CLI sem escrever 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 do Arquivo de Configuração

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

---

Referência da API

KnowledgeBase

Classe principal para criar e gerenciar bases de conhecimento.

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
})

Opções de Recuperação

Controle quantos resultados são retornados e sua qualidade mínima. Essas opções são configuradas no seu código (não expostas a agentes de IA), dando a você controle total sobre o comportamento de recuperação.

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
  },
})

Opção	Tipo	Padrão	Descrição
topK	number	5	Número máximo de fragmentos a recuperar por consulta
threshold	number	0	Pontuação mínima de similaridade (0-1). Defina como 0 para retornar todos os resultados, ou mais alto (ex.: 0.5, 0.7) para filtrar fragmentos menos relevantes

Métodos

Método	Descrição
addText(text, name?)	Adicionar conteúdo de texto bruto
addFile(path, name?)	Adicionar um arquivo (PDF, DOCX, TXT, MD)
addDirectory(path, options?)	Adicionar todos os arquivos de um diretório
addURL(url, name?)	Adicionar conteúdo de uma URL
addURLs(urls)	Adicionar múltiplas URLs
query(question, options?)	Consultar a base de conhecimento
listSources()	Listar todas as fontes indexadas
serveStdio(options?)	Iniciar servidor MCP stdio
serveHttp(options?)	Iniciar servidor MCP HTTP

Opções do 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)
})

Utilitários

O SDK também exporta utilitários que você pode usar de forma independente:

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

---

Ferramentas MCP

Quando conectado via MCP, sua base de conhecimento expõe estas ferramentas:

query

Pesquise na base de conhecimento com uma pergunta em linguagem natural.

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

Parâmetro	Tipo	Descrição
question	string	A pergunta a ser pesquisada

Nota: O número de resultados e o limite de similaridade são configurados via a opção retrieval ao criar a KnowledgeBase. Veja Opções de Recuperação.

list_sources

Liste todas as fontes indexadas na base de conhecimento.

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

---

Exemplos

Veja o diretório examples para mais:

• Uso básico
• Servidor HTTP
• Incorporações personalizadas
• Armazenamento vetorial Qdrant

---

Requisitos

• Node.js 18+
• Chave de API OpenAI (ou provedor de incorporações personalizado)

---

Quer Hospedagem Gerenciada?

Construindo algo maior? Confira Akyn para:

• ☁️ Bases de conhecimento hospedadas
• 👥 Colaboração em equipe
• 📊 Análises de uso
• 💰 Monetização (cobre por consultas)
• 🔐 Gerenciamento de chaves de API

---

Contribuindo

Contribuições são bem-vindas! Por favor, leia nossas diretrizes de contribuição primeiro.

---

Licença

MIT © Akyn AI