simple-dynamsoft-mcp 6.3.0 → 7.0.0

package/src/observability/logging.js

@@ -0,0 +1,51 @@
+function normalizeEnvValue(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim().toLowerCase();
+}
+
+function isVerboseLoggingEnabled(env = process.env) {
+  const explicit = normalizeEnvValue(env.MCP_LOG_LEVEL);
+  if (["debug", "verbose", "trace"].includes(explicit)) return true;
+  const toggle = normalizeEnvValue(env.MCP_VERBOSE_LOGS);
+  return ["1", "true", "yes", "on"].includes(toggle);
+}
+
+function quoteValue(value) {
+  const raw = String(value ?? "");
+  if (raw.length === 0) return "\"\"";
+  if (/\s|=/.test(raw)) return JSON.stringify(raw);
+  return raw;
+}
+
+function latencyBucket(latencyMs) {
+  const n = Number(latencyMs);
+  if (!Number.isFinite(n) || n < 0) return "unknown";
+  if (n < 100) return "lt100ms";
+  if (n < 300) return "100-299ms";
+  if (n < 1000) return "300-999ms";
+  if (n < 3000) return "1-2s";
+  return "ge3s";
+}
+
+function logEvent(component, event, fields = {}, options = {}) {
+  const level = normalizeEnvValue(options.level || "info") || "info";
+  const verbose = isVerboseLoggingEnabled(options.env);
+  if (level === "debug" && !verbose) return;
+
+  const parts = [`[${component}]`, `event=${quoteValue(event || "detail")}`];
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (value === undefined || value === null || value === "") continue;
+    parts.push(`${key}=${quoteValue(value)}`);
+  }
+
+  if (level !== "info") {
+    parts.push(`level=${level}`);
+  }
+  console.error(parts.join(" "));
+}
+
+export {
+  isVerboseLoggingEnabled,
+  latencyBucket,
+  logEvent
+};

package/src/rag/config.js

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import "dotenv/config";
+import { getResolvedDataRoot } from "../data/root.js";
+import { resolveProfileConfig } from "./profile-config.js";
+
+const dataRoot = getResolvedDataRoot();
+
+const pkgUrl = new URL("../../package.json", import.meta.url);
+const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+
+const legacyPrebuiltIndexUrl =
+  `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v${pkg.version}/prebuilt-rag-index-${pkg.version}.tar.gz`;
+
+const defaultPrebuiltIndexUrls = {
+  local:
+    `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v${pkg.version}/prebuilt-rag-index-local-${pkg.version}.tar.gz`,
+  gemini:
+    `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v${pkg.version}/prebuilt-rag-index-gemini-${pkg.version}.tar.gz`
+};
+
+function readEnvValue(key, fallback) {
+  const value = process.env[key];
+  if (value === undefined || value === "") return fallback;
+  return value;
+}
+
+function readBoolEnv(key, fallback) {
+  const value = readEnvValue(key, "");
+  if (!value) return fallback;
+  return ["1", "true", "yes", "on"].includes(String(value).toLowerCase());
+}
+
+function readIntEnv(key, fallback) {
+  const raw = readEnvValue(key, "");
+  if (!raw) return fallback;
+  const value = Number.parseInt(raw, 10);
+  return Number.isNaN(value) ? fallback : value;
+}
+
+function readFloatEnv(key, fallback) {
+  const raw = readEnvValue(key, "");
+  if (!raw) return fallback;
+  const value = Number.parseFloat(raw);
+  return Number.isNaN(value) ? fallback : value;
+}
+
+function normalizeGeminiModel(model) {
+  if (!model) return "models/embedding-001";
+  if (model.startsWith("models/")) return model;
+  return `models/${model}`;
+}
+
+const profileConfig = resolveProfileConfig(process.env);
+
+const ragConfig = {
+  profile: profileConfig.profile,
+  profileDefaults: profileConfig.defaults,
+  providerSource: profileConfig.providerSource,
+  fallbackSource: profileConfig.fallbackSource,
+  provider: profileConfig.provider,
+  fallback: profileConfig.fallback,
+  cacheDir: readEnvValue("RAG_CACHE_DIR", join(dataRoot, ".rag-cache")),
+  modelCacheDir: readEnvValue("RAG_MODEL_CACHE_DIR", join(dataRoot, ".rag-cache", "models")),
+  localModel: readEnvValue("RAG_LOCAL_MODEL", "Xenova/all-MiniLM-L6-v2"),
+  localQuantized: readBoolEnv("RAG_LOCAL_QUANTIZED", true),
+  chunkSize: readIntEnv("RAG_CHUNK_SIZE", 1200),
+  chunkOverlap: readIntEnv("RAG_CHUNK_OVERLAP", 200),
+  maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 6),
+  maxTextChars: readIntEnv("RAG_MAX_TEXT_CHARS", 4000),
+  minScore: readFloatEnv("RAG_MIN_SCORE", 0.2),
+  includeScore: readBoolEnv("RAG_INCLUDE_SCORE", false),
+  rebuild: readBoolEnv("RAG_REBUILD", false),
+  prewarm: readBoolEnv("RAG_PREWARM", false),
+  prewarmBlock: readBoolEnv("RAG_PREWARM_BLOCK", false),
+  prebuiltIndexAutoDownload: readBoolEnv("RAG_PREBUILT_INDEX_AUTO_DOWNLOAD", true),
+  prebuiltIndexUrl: readEnvValue("RAG_PREBUILT_INDEX_URL", ""),
+  prebuiltIndexUrlLocal: readEnvValue("RAG_PREBUILT_INDEX_URL_LOCAL", defaultPrebuiltIndexUrls.local),
+  prebuiltIndexUrlGemini: readEnvValue("RAG_PREBUILT_INDEX_URL_GEMINI", defaultPrebuiltIndexUrls.gemini),
+  prebuiltIndexTimeoutMs: readIntEnv("RAG_PREBUILT_INDEX_TIMEOUT_MS", 180000),
+  geminiApiKey: readEnvValue("GEMINI_API_KEY", ""),
+  geminiModel: normalizeGeminiModel(readEnvValue("GEMINI_EMBED_MODEL", "models/gemini-embedding-001")),
+  geminiBaseUrl: readEnvValue("GEMINI_API_BASE_URL", "https://generativelanguage.googleapis.com"),
+  geminiBatchSize: readIntEnv("GEMINI_EMBED_BATCH_SIZE", 16),
+  geminiRetryMaxAttempts: readIntEnv("GEMINI_RETRY_MAX_ATTEMPTS", 5),
+  geminiRetryBaseDelayMs: readIntEnv("GEMINI_RETRY_BASE_DELAY_MS", 500),
+  geminiRetryMaxDelayMs: readIntEnv("GEMINI_RETRY_MAX_DELAY_MS", 10000),
+  geminiRequestThrottleMs: readIntEnv("GEMINI_REQUEST_THROTTLE_MS", 0)
+};
+
+export {
+  pkg,
+  ragConfig,
+  legacyPrebuiltIndexUrl,
+  defaultPrebuiltIndexUrls
+};

package/src/rag/index.js

@@ -0,0 +1,266 @@
+import {
+  resourceIndex,
+  normalizeProduct,
+  normalizePlatform,
+  normalizeEdition,
+  editionMatches,
+  platformMatches,
+  getRagSignatureData,
+  resourceIndexByUri
+} from "../server/resource-index.js";
+import { latencyBucket } from "../observability/logging.js";
+import { createLexicalProvider } from "./lexical-provider.js";
+import { pkg, ragConfig, legacyPrebuiltIndexUrl } from "./config.js";
+import {
+  ragLogState,
+  logRag,
+  logRagConfigOnce,
+  resetRagProviderLogState
+} from "./logger.js";
+import {
+  createFuseSearch,
+  attachScore,
+  normalizeSearchFilters,
+  entryMatchesScope,
+  normalizeText,
+  truncateText,
+  buildEmbeddingItems,
+  buildIndexSignature,
+  normalizeVector,
+  dotProduct,
+  isRateLimitError
+} from "./search-utils.js";
+import { createProviderOrchestrator } from "./providers.js";
+import { createVectorCacheHelpers } from "./vector-cache.js";
+
+const searchUtils = {
+  createFuseSearch: () => createFuseSearch(resourceIndex),
+  attachScore: (entry, score) => attachScore(entry, score, ragConfig.includeScore),
+  normalizeText,
+  truncateText,
+  buildEmbeddingItems,
+  buildIndexSignature,
+  normalizeVector,
+  dotProduct,
+  isRateLimitError,
+  entryMatchesScope: (entry, filters) => entryMatchesScope(entry, filters, {
+    editionMatches,
+    platformMatches
+  })
+};
+
+const vectorCache = createVectorCacheHelpers({
+  ragConfig,
+  pkgVersion: pkg.version,
+  legacyPrebuiltIndexUrl,
+  logRag
+});
+
+const providerOrchestrator = createProviderOrchestrator({
+  pkgVersion: pkg.version,
+  ragConfig,
+  ragLogState,
+  logRag,
+  resourceIndex,
+  resourceIndexByUri,
+  createLexicalProvider,
+  getRagSignatureData,
+  utils: searchUtils,
+  vectorCache
+});
+
+function refreshRagIndexes() {
+  providerOrchestrator.refreshProviders();
+  resetRagProviderLogState();
+  logRag(`indexes refreshed resources=${resourceIndex.length}`);
+}
+
+async function searchResources({ query, product, edition, platform, type, limit }) {
+  const startedAt = Date.now();
+  const filters = normalizeSearchFilters({ product, edition, platform, type }, {
+    normalizeProduct,
+    normalizePlatform,
+    normalizeEdition
+  });
+  const searchQuery = query ? String(query).trim() : "";
+  const maxResults = limit ? Math.min(limit, 50) : undefined;
+
+  if (!searchQuery) {
+    const results = resourceIndex.filter((entry) => searchUtils.entryMatchesScope(entry, filters));
+    return maxResults ? results.slice(0, maxResults) : results;
+  }
+
+  logRagConfigOnce(ragConfig);
+  const providers = providerOrchestrator.resolveProviderChain();
+  if (!ragLogState.providerChain) {
+    ragLogState.providerChain = true;
+    logRag("provider_chain", {
+      profile: ragConfig.profile,
+      provider: providers[0] || "unknown",
+      fallback: ragConfig.fallback,
+      chain: providers.join("->")
+    });
+  }
+
+  let lastError = null;
+  for (const name of providers) {
+    try {
+      const provider = await providerOrchestrator.loadSearchProvider(name);
+      const results = await provider.search(searchQuery, filters, maxResults);
+      if (!ragLogState.providerFirstUse.has(name)) {
+        ragLogState.providerFirstUse.add(name);
+        logRag("provider_selected", {
+          profile: ragConfig.profile,
+          provider: name,
+          fallback: ragConfig.fallback
+        });
+      }
+      if (name !== providers[0] && !ragLogState.fallbackUse.has(name)) {
+        ragLogState.fallbackUse.add(name);
+        logRag("fallback_engaged", {
+          selected_provider: name,
+          primary_provider: providers[0],
+          fallback: ragConfig.fallback
+        });
+      }
+      const elapsedMs = Date.now() - startedAt;
+      logRag("search_complete", {
+        profile: ragConfig.profile,
+        provider: name,
+        fallback: ragConfig.fallback,
+        product: filters.product || "any",
+        edition: filters.edition || "any",
+        platform: filters.platform || "any",
+        type: filters.type || "any",
+        result_count: results.length,
+        latency_ms: elapsedMs,
+        latency_bucket: latencyBucket(elapsedMs)
+      });
+      return results;
+    } catch (error) {
+      lastError = error;
+      logRag("provider_failed", {
+        provider: name,
+        fallback: ragConfig.fallback,
+        error: error.message
+      }, { level: "error" });
+    }
+  }
+
+  if (lastError) {
+    const elapsedMs = Date.now() - startedAt;
+    logRag("search_failed", {
+      profile: ragConfig.profile,
+      provider: providers[0] || "unknown",
+      fallback: ragConfig.fallback,
+      latency_ms: elapsedMs,
+      latency_bucket: latencyBucket(elapsedMs),
+      error: lastError.message
+    }, { level: "error" });
+  }
+  return [];
+}
+
+async function prewarmRagIndex() {
+  if (!ragConfig.prewarm) return;
+  logRagConfigOnce(ragConfig);
+  const providers = providerOrchestrator.resolveProviderChain();
+  const primary = providers[0];
+  if (!primary || primary === "fuse") return;
+  try {
+    logRag("prewarm_start", {
+      profile: ragConfig.profile,
+      provider: primary,
+      fallback: ragConfig.fallback
+    });
+    const provider = await providerOrchestrator.loadSearchProvider(primary);
+    if (provider.warm) {
+      await provider.warm();
+    }
+    logRag("prewarm_done", {
+      profile: ragConfig.profile,
+      provider: primary,
+      fallback: ragConfig.fallback
+    });
+  } catch (error) {
+    logRag("prewarm_failed", {
+      provider: primary,
+      error: error.message
+    }, { level: "error" });
+  }
+}
+
+async function getSampleSuggestions({ query, product, edition, platform, limit = 5 }) {
+  const normalizedProduct = normalizeProduct(product);
+  const normalizedPlatform = normalizePlatform(platform);
+  const normalizedEdition = normalizeEdition(edition, normalizedPlatform, normalizedProduct);
+  const searchQuery = query ? String(query).trim() : "";
+  const maxResults = Math.min(limit || 5, 10);
+
+  if (searchQuery) {
+    const results = await searchResources({
+      query: searchQuery,
+      product: normalizedProduct,
+      edition: normalizedEdition,
+      platform: normalizedPlatform,
+      type: "sample",
+      limit: maxResults
+    });
+    if (results.length) return results;
+  }
+
+  const matchesScope = (entry) => {
+    if (normalizedProduct && entry.product !== normalizedProduct) return false;
+    if (!editionMatches(normalizedEdition, entry.edition)) return false;
+    if (!platformMatches(normalizedPlatform, entry)) return false;
+    return entry.type === "sample";
+  };
+
+  let candidates = resourceIndex.filter(matchesScope);
+  if (candidates.length === 0 && normalizedProduct) {
+    candidates = resourceIndex.filter((entry) => entry.type === "sample" && entry.product === normalizedProduct);
+  }
+
+  if (searchQuery && candidates.length > 1) {
+    const terms = normalizeText(searchQuery.toLowerCase()).split(/\s+/).filter(Boolean);
+    const scoreEntry = (entry) => {
+      const tags = Array.isArray(entry.tags) ? entry.tags.map((tag) => String(tag).toLowerCase()) : [];
+      const haystack = [
+        String(entry.title || "").toLowerCase(),
+        String(entry.summary || "").toLowerCase(),
+        tags.join(" ")
+      ].join(" ");
+      let score = 0;
+      for (const term of terms) {
+        if (!term) continue;
+        if (tags.some((tag) => tag === term || tag.includes(term))) score += 3;
+        if (haystack.includes(term)) score += 1;
+      }
+      return score;
+    };
+    candidates = [...candidates].sort((a, b) => {
+      const delta = scoreEntry(b) - scoreEntry(a);
+      if (delta !== 0) return delta;
+      return String(a.title || "").localeCompare(String(b.title || ""));
+    });
+  }
+
+  const seen = new Set();
+  const results = [];
+  for (const entry of candidates) {
+    if (seen.has(entry.uri)) continue;
+    seen.add(entry.uri);
+    results.push(entry);
+    if (results.length >= maxResults) break;
+  }
+
+  return results;
+}
+
+export {
+  ragConfig,
+  searchResources,
+  getSampleSuggestions,
+  prewarmRagIndex,
+  refreshRagIndexes
+};

package/src/rag/lexical-provider.js

@@ -0,0 +1,170 @@
+import Fuse from "fuse.js";
+
+const DEFAULT_FUSE_OPTIONS = {
+  keys: ["title", "summary", "tags", "uri"],
+  threshold: 0.35,
+  ignoreLocation: true,
+  includeScore: true
+};
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+
+function tokenize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function normalizeScore(value, max) {
+  if (!Number.isFinite(value) || value <= 0) return 0;
+  if (!Number.isFinite(max) || max <= 0) return 0;
+  return value / max;
+}
+
+function compareLexicalResults(a, b) {
+  const scoreDelta = b.score - a.score;
+  if (scoreDelta !== 0) return scoreDelta;
+  const titleA = String(a.entry.title || "");
+  const titleB = String(b.entry.title || "");
+  const titleDelta = titleA.localeCompare(titleB);
+  if (titleDelta !== 0) return titleDelta;
+  return String(a.entry.uri || "").localeCompare(String(b.entry.uri || ""));
+}
+
+function buildBm25Index(entries) {
+  const documents = [];
+  const documentFrequency = new Map();
+  let totalLength = 0;
+
+  entries.forEach((entry, index) => {
+    const haystack = [
+      entry.title,
+      entry.summary,
+      Array.isArray(entry.tags) ? entry.tags.join(" ") : "",
+      entry.uri
+    ].join(" \n ");
+
+    const tokens = tokenize(haystack);
+    const termFreq = new Map();
+    tokens.forEach((token) => {
+      termFreq.set(token, (termFreq.get(token) || 0) + 1);
+    });
+
+    const seen = new Set();
+    for (const token of tokens) {
+      if (seen.has(token)) continue;
+      seen.add(token);
+      documentFrequency.set(token, (documentFrequency.get(token) || 0) + 1);
+    }
+
+    totalLength += tokens.length;
+    documents.push({
+      index,
+      entry,
+      length: tokens.length,
+      termFreq
+    });
+  });
+
+  const avgLength = documents.length > 0 ? totalLength / documents.length : 0;
+  return {
+    documents,
+    documentFrequency,
+    totalDocuments: documents.length,
+    avgLength
+  };
+}
+
+function computeBm25Score(indexState, docState, terms) {
+  if (terms.length === 0) return 0;
+  if (!docState.length || !indexState.avgLength) return 0;
+
+  let score = 0;
+  for (const term of terms) {
+    const tf = docState.termFreq.get(term) || 0;
+    if (!tf) continue;
+    const df = indexState.documentFrequency.get(term) || 0;
+    const idf = Math.log(1 + (indexState.totalDocuments - df + 0.5) / (df + 0.5));
+    const denom = tf + BM25_K1 * (1 - BM25_B + BM25_B * (docState.length / indexState.avgLength));
+    score += idf * ((tf * (BM25_K1 + 1)) / denom);
+  }
+
+  return score;
+}
+
+function createLexicalProvider({
+  entries,
+  entryMatchesScope,
+  attachScore,
+  fuseOptions = DEFAULT_FUSE_OPTIONS,
+  bm25Weight = 0.7,
+  fuseWeight = 0.3
+}) {
+  const fuse = new Fuse(entries, fuseOptions);
+  const bm25Index = buildBm25Index(entries);
+  const entryByUri = new Map(entries.map((entry) => [entry.uri, entry]));
+
+  return {
+    name: "lexical",
+    search: async (query, filters, limit) => {
+      const terms = [...new Set(tokenize(query))];
+      const fuseHits = fuse.search(query);
+      const fuseScoreByUri = new Map();
+      let maxFuse = 0;
+
+      for (const hit of fuseHits) {
+        const candidateScore = Number.isFinite(hit.score) ? Math.max(0, 1 - hit.score) : 0;
+        const current = fuseScoreByUri.get(hit.item.uri) || 0;
+        if (candidateScore > current) {
+          fuseScoreByUri.set(hit.item.uri, candidateScore);
+          if (candidateScore > maxFuse) maxFuse = candidateScore;
+        }
+      }
+
+      const bm25ScoreByUri = new Map();
+      let maxBm25 = 0;
+
+      for (const doc of bm25Index.documents) {
+        if (!entryMatchesScope(doc.entry, filters)) continue;
+        const score = computeBm25Score(bm25Index, doc, terms);
+        if (score <= 0) continue;
+        bm25ScoreByUri.set(doc.entry.uri, score);
+        if (score > maxBm25) maxBm25 = score;
+      }
+
+      const scopedUris = new Set();
+      for (const doc of bm25Index.documents) {
+        if (!entryMatchesScope(doc.entry, filters)) continue;
+        if (bm25ScoreByUri.has(doc.entry.uri) || fuseScoreByUri.has(doc.entry.uri)) {
+          scopedUris.add(doc.entry.uri);
+        }
+      }
+
+      const merged = [];
+      for (const uri of scopedUris) {
+        const entry = entryByUri.get(uri);
+        if (!entry) continue;
+        const bm25Norm = normalizeScore(bm25ScoreByUri.get(uri) || 0, maxBm25);
+        const fuseNorm = normalizeScore(fuseScoreByUri.get(uri) || 0, maxFuse);
+        const score = (bm25Norm * bm25Weight) + (fuseNorm * fuseWeight);
+        merged.push({ entry, score });
+      }
+
+      merged.sort(compareLexicalResults);
+      const ranked = merged.map((item) => attachScore(item.entry, item.score));
+      if (limit) return ranked.slice(0, limit);
+      return ranked;
+    },
+    warm: async () => {}
+  };
+}
+
+export {
+  tokenize,
+  compareLexicalResults,
+  createLexicalProvider
+};

package/src/rag/logger.js

@@ -0,0 +1,46 @@
+import { logEvent } from "../observability/logging.js";
+
+const ragLogState = {
+  config: false,
+  providerChain: false,
+  localEmbedderInit: false,
+  providerReady: new Set(),
+  providerFirstUse: new Set(),
+  fallbackUse: new Set()
+};
+
+function logRag(eventOrMessage, fields = {}, options = {}) {
+  if (fields && typeof fields === "object" && Object.keys(fields).length > 0) {
+    logEvent("rag", eventOrMessage, fields, options);
+    return;
+  }
+  logEvent("rag", "detail", { message: String(eventOrMessage || "") }, { ...options, level: options.level || "debug" });
+}
+
+function logRagConfigOnce(ragConfig) {
+  if (ragLogState.config) return;
+  ragLogState.config = true;
+  logRag(
+    `config provider=${ragConfig.provider} fallback=${ragConfig.fallback} prewarm=${ragConfig.prewarm} rebuild=${ragConfig.rebuild} ` +
+    `cache_dir=${ragConfig.cacheDir} prebuilt_auto_download=${ragConfig.prebuiltIndexAutoDownload} ` +
+    `prebuilt_url_override=${ragConfig.prebuiltIndexUrl ? "set" : "empty"} prebuilt_url_local=${ragConfig.prebuiltIndexUrlLocal ? "set" : "empty"} ` +
+    `prebuilt_url_gemini=${ragConfig.prebuiltIndexUrlGemini ? "set" : "empty"} ` +
+    `prebuilt_timeout_ms=${ragConfig.prebuiltIndexTimeoutMs} gemini_retry_max_attempts=${ragConfig.geminiRetryMaxAttempts} ` +
+    `gemini_retry_base_delay_ms=${ragConfig.geminiRetryBaseDelayMs} gemini_retry_max_delay_ms=${ragConfig.geminiRetryMaxDelayMs} ` +
+    `gemini_request_throttle_ms=${ragConfig.geminiRequestThrottleMs}`
+  );
+}
+
+function resetRagProviderLogState() {
+  ragLogState.providerReady.clear();
+  ragLogState.providerFirstUse.clear();
+  ragLogState.fallbackUse.clear();
+  ragLogState.providerChain = false;
+}
+
+export {
+  ragLogState,
+  logRag,
+  logRagConfigOnce,
+  resetRagProviderLogState
+};

package/src/rag/profile-config.js

@@ -0,0 +1,48 @@
+const PROFILE_DEFAULTS = {
+  lite: {
+    provider: "lexical",
+    fallback: "none"
+  },
+  "semantic-local": {
+    provider: "local",
+    fallback: "none"
+  },
+  "semantic-gemini": {
+    provider: "gemini",
+    fallback: "none"
+  }
+};
+
+function normalizeEnvValue(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim().toLowerCase();
+}
+
+function resolveProfileConfig(env = process.env) {
+  const rawProfile = normalizeEnvValue(env.MCP_PROFILE);
+  const explicitProvider = normalizeEnvValue(env.RAG_PROVIDER);
+  const explicitFallback = normalizeEnvValue(env.RAG_FALLBACK);
+
+  if (rawProfile && !PROFILE_DEFAULTS[rawProfile]) {
+    throw new Error(
+      `Invalid MCP_PROFILE "${rawProfile}". Expected one of: ${Object.keys(PROFILE_DEFAULTS).join(", ")}.`
+    );
+  }
+
+  const profile = rawProfile || "lite";
+  const defaults = PROFILE_DEFAULTS[profile];
+
+  return {
+    profile,
+    defaults,
+    provider: explicitProvider || defaults.provider,
+    fallback: explicitFallback || defaults.fallback,
+    providerSource: explicitProvider ? "env" : "profile-default",
+    fallbackSource: explicitFallback ? "env" : "profile-default"
+  };
+}
+
+export {
+  PROFILE_DEFAULTS,
+  resolveProfileConfig
+};