Configuration

Optional

A config file is not required. Lucerna works out of the box with no configuration — this is only needed if you want to enable semantic search with a specific embedding provider or improve result ranking with a reranker.

Lucerna picks up an optional config file from your project root to configure embedding and reranking providers for the CLI and MCP server without writing any integration code.

Place a lucerna.config.ts at the project root — the MCP server and all CLI commands pick it up automatically:

lucerna.config.ts

import { CloudflareEmbeddings, VoyageReranker } from '@upstart.gg/lucerna';

export default {
  embeddingFunction: new CloudflareEmbeddings(),
  rerankingFunction: new VoyageReranker(),
};

You can also pass providers as CLI flags instead of a config file:

npx @upstart.gg/lucerna mcp-server --embedder cloudflare --reranker voyage
npx @upstart.gg/lucerna mcp-server --config /path/to/lucerna.config.ts

Supported filenames (checked in order):

• lucerna.config.ts
• lucerna.config.js
• lucerna.config.mjs

The file must export a default object that satisfies LucernaConfig:

lucerna.config.ts

import type { LucernaConfig } from '@upstart.gg/lucerna';
import { VoyageReranker } from '@upstart.gg/lucerna';

export default {
  // Use Cloudflare for embeddings (reads CLOUDFLARE_* env vars automatically)
  embeddingFunction: 'cloudflare',   // ← shorthand; see Built-in Providers
  rerankingFunction: new VoyageReranker(),
} satisfies LucernaConfig;

How config is applied

The config file is loaded by both lucerna mcp-server and all other CLI commands. CLI flags always take priority over config file settings:

Priority	Source
1 (highest)	--no-semantic flag (disables embeddings entirely)
2	--embedder / --reranker CLI flags
3	lucerna.config.ts / .js
4 (lowest)	Auto-detection from environment variables

Pointing to a custom path

If your config isn’t at the project root, pass --config:

lucerna mcp-server /path/to/project --config /path/to/my.config.ts
lucerna index /path/to/project --config ./configs/lucerna.dev.ts

Type reference

interface LucernaConfig {
  /**
   * Custom embedding function, or `false` to disable semantic search.
   * Omit to use the default (auto-detected from env vars).
   */
  embeddingFunction?: EmbeddingFunction | false;

  /**
   * Custom reranking function, or `false` to disable reranking.
   * Omit to use no reranking (the default).
   */
  rerankingFunction?: RerankingFunction | false;
}