API-Referenz

Vollstaendige Uebersicht aller exportierten Funktionen, Interfaces und Types.

Core

createSearchStore(config)

Erstellt einen neuen Search Store.


function createSearchStore(config: QmdSearchConfig): Promise<SearchStore>

QmdSearchConfig:

Feld	Typ	Default	Beschreibung
`dbPath`	`string`	(Pflicht)	Pfad zur SQLite-Datenbank
`searchMode`	`'fts' \| 'hybrid'`	`'fts'`	Such-Modus
`embedProvider`	`EmbedProviderConfig`	—	Embedding-Provider
`collections`	`CollectionDef[]`	—	Collection-Definitionen
`resultFormatter`	`Partial<ResultFormatter>`	Defaults	Ergebnis-Formatierung

SearchStore:

Methode	Beschreibung
`search(query, options?)`	Suche ausfuehren → `SearchResponse`
`getDocument(id, options?)`	Einzelnes Dokument im Volltext → `DocumentResponse \| null`
`listCollections()`	Collections mit Dokumentanzahl
`isHybridSearch()`	Hybrid-Modus aktiv?
`formatter`	Zugriff auf den ResultFormatter
`close()`	Store schliessen

createLimiter(config?)

Erstellt einen Backpressure-Limiter.


function createLimiter(config?: LimiterConfig): { withBackpressure, limit }

Feld	Typ	Default	Beschreibung
`maxConcurrency`	`number`	`5`	Max. parallele Anfragen
`maxPending`	`number`	`20`	Max. wartende Anfragen (dann 429)

Indexer

createIndexer(config)

Erstellt einen Indexer.


function createIndexer(config: IndexerConfig): Indexer

IndexerConfig:

Feld	Typ	Beschreibung
`dbPath`	`string`	Pfad zur SQLite-Datenbank
`collections`	`CollectionDef[]`	Collection-Definitionen
`contentSources`	`ContentSourceEntry[]`	Plugin-basierte Quellen
`plugins`	`ContentSourcePlugin[]`	Registrierte Plugins
`embedProvider`	`EmbedProviderConfig`	Embedding-Provider
`skipEmbed`	`boolean`	Embeddings ueberspringen
`fetchOutputDir`	`string`	Verzeichnis fuer gefetchte Dateien

Indexer:

Methode	Beschreibung
`run(callbacks?)`	Index erstellen/aktualisieren → `IndexResult`

IndexResult:

Feld	Typ	Beschreibung
`indexed`	`number`	Neu indexierte Dokumente
`updated`	`number`	Aktualisierte Dokumente
`unchanged`	`number`	Unveraenderte Dokumente
`removed`	`number`	Entfernte Dokumente
`needsEmbedding`	`number`	Dokumente ohne Embedding
`duration_s`	`number`	Dauer in Sekunden

Adapter

createNextHandler(store, options?)


function createNextHandler(store: SearchStore, options?: NextHandlerOptions): (req: Request) => Promise<Response>

createNextDocumentHandler(store, options?)


function createNextDocumentHandler(store: SearchStore, options?: NextHandlerOptions): (req: Request) => Promise<Response>

Handler fuer GET /api/document?id=…. Gibt 501 zurueck, wenn der uebergebene Store kein getDocument anbietet.

createExpressMiddleware(store, options?)


function createExpressMiddleware(store: SearchStore, options?: ExpressMiddlewareOptions): ExpressMiddleware

createExpressDocumentMiddleware(store, options?)


function createExpressDocumentMiddleware(store: SearchStore, options?: ExpressMiddlewareOptions): ExpressMiddleware

Express-Middleware fuer GET /api/document?id=…&maxBytes=….

createHonoHandler(store, options?)


function createHonoHandler(store: SearchStore, options?: HonoHandlerOptions): HonoHandler

createHonoDocumentHandler(store, options?)


function createHonoDocumentHandler(store: SearchStore, options?: HonoHandlerOptions): HonoHandler

Hono-Handler fuer GET /api/document?id=…&maxBytes=….

startServer(store, options?)


function startServer(store: SearchStore, options?: StandaloneServerOptions): Promise<StandaloneServer>

StandaloneServerOptions:

Feld	Typ	Default	Beschreibung
`port`	`number`	`3001`	Server-Port
`host`	`string`	`'0.0.0.0'`	Server-Host
`auth`	`AuthPlugin`	—	Auth-Plugin
`corsOrigin`	`string`	`'*'`	CORS-Origin
`mcp`	`McpSearchServerConfig \| boolean`	—	MCP-Endpoint aktivieren

Der Standalone-Server stellt zusätzlich GET /api/document?id=…&maxBytes=… bereit. Die Dokument-ID muss aus einem SearchResponse stammen. Unterstützt der Store keinen Einzelabruf, antwortet der Endpunkt mit 501.

MCP

createMcpSearchServer(store, config?)


function createMcpSearchServer(store: SearchStore, config?: McpSearchServerConfig): Promise<McpServer>

McpSearchServerConfig:

Feld	Typ	Default	Beschreibung
`name`	`string`	`'knowledge-sdk'`	Server-Name
`version`	`string`	`'1.0.0'`	Version
`baseUrl`	`string`	`''`	Basis-URL fuer Links
`collectionDescriptions`	`Record<string, string>`	`{}`	Beschreibungen
`searchToolDescription`	`string`	(generisch)	Tool-Beschreibung
`listCollectionsToolDescription`	`string`	(generisch)	Tool-Beschreibung
`getDocumentToolDescription`	`string`	(generisch)	Tool-Beschreibung

Das Tool get_document wird nur registriert, wenn der Store getDocument anbietet — bei einem eigenen SearchStore ohne diese Methode bleibt die Tool-Liste unveraendert.

Seit v2.0.0 werden alle Tools ueber registerTool() registriert (die tool()-API des MCP-SDK ist deprecated) und deklarieren ein outputSchema. Siehe MCP-Server → Strukturierte Antworten.

Auth

createEnvAuth(config?)


function createEnvAuth(config?: EnvAuthConfig): AuthPlugin

Feld	Typ	Default	Beschreibung
`headerName`	`string`	`'X-API-Key'`	HTTP-Header
`envVar`	`string`	`'QMD_API_KEY'`	Env-Var-Name
`apiKey`	`string`	—	Key direkt uebergeben

createOdooAuth(config)


function createOdooAuth(config: OdooAuthConfig): AuthPlugin

Feld	Typ	Default	Beschreibung
`odooBaseUrl`	`string`	(Pflicht)	Odoo-Basis-URL
`validateEndpoint`	`string`	`'/api/validate-key'`	Endpoint
`headerName`	`string`	`'X-API-Key'`	HTTP-Header
`cacheTtlMs`	`number`	`300000`	Cache-TTL (5 Min.)
`maxCacheSize`	`number`	`1000`	Max. Cache-Eintraege

Types

EmbedProviderConfig

Feld	Typ	Beschreibung
`provider`	`'none' \| 'local' \| 'openai' \| 'voyage'`	Provider-Typ
`apiKey`	`string`	API-Key
`model`	`string`	Embedding-Modell
`dimensions`	`number`	Vektor-Dimensionen
`domainContext`	`string`	Kontext fuer Query Expansion
`maxRetries`	`number`	Max. Retries
`retryBaseMs`	`number`	Basis-Wartezeit

CollectionDef

Feld	Typ	Beschreibung
`name`	`string`	Eindeutiger Name
`path`	`string`	Quellverzeichnis
`pattern`	`string`	Glob-Pattern
`context`	`string`	LLM-Kontext
`group`	`string`	Gruppierung

SearchResponse

Feld	Typ	Beschreibung
`results`	`SearchResult[]`	Suchergebnisse
`query`	`string`	Suchbegriff
`collection`	`string \| null`	Filter
`total`	`number`	Anzahl Ergebnisse
`duration_ms`	`number`	Dauer in ms

SearchResult

Feld	Typ	Beschreibung
`id`	`string`	Stabile Dokument-ID (qmd-Virtual-Path) — Eingabe fuer `getDocument()`
`title`	`string`	Seitentitel
`path`	`string`	URL-Pfad
`collection`	`string`	Collection-Name
`snippet`	`string`	Textauszug
`score`	`number`	Relevanz-Score

path ist die Ziel-URL und muss nicht umkehrbar sein — ein pathToUrl darf mehrere Dokumente auf dieselbe URL abbilden (auf docs.processcube.io etwa alle Changelogs auf /release-notes#<produkt>). Fuer den Rueckweg zum Dokument ist deshalb id da, nicht path.

DocumentResponse

Feld	Typ	Beschreibung
`id`	`string`	Dokument-ID (identisch zu `SearchResult.id`)
`title`	`string`	Seitentitel
`path`	`string`	URL-Pfad
`collection`	`string`	Collection-Name
`body`	`string`	Volltext (Markdown/MDX-Quelle)
`body_length`	`number`	Laenge des ungekuerzten Bodys in Zeichen
`truncated`	`boolean`	`true`, wenn `body` wegen `maxBytes` gekuerzt wurde

ContentSourcePlugin

Feld	Typ	Beschreibung
`name`	`string`	Plugin-Name
`fetch(config)`	`Promise<FetchResult>`	Dateien laden
`validate?(config)`	`boolean`	Config validieren

AuthPlugin

Feld	Typ	Beschreibung
`name`	`string`	Plugin-Name
`resolve(req)`	`Promise<AuthResult>`	Request authentifizieren

AuthResult

Feld	Typ	Beschreibung
`valid`	`boolean`	Authentifiziert?
`customerId`	`string`	Kunden-ID
`scopes`	`string[]`	Berechtigungen
`error`	`string`	Fehlermeldung