abb-opencode-local-rag 0.1.0

package/dist/server/index.js

@@ -0,0 +1,1104 @@
+// RAGServer implementation with MCP tools
+import { randomUUID } from 'node:crypto';
+import { readFile, stat, unlink } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { resolve, sep } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { DEFAULT_MIN_CHUNK_LENGTH, SemanticChunker } from '../chunker/index.js';
+import { Embedder } from '../embedder/index.js';
+import { listDocuments } from '../features/list.js';
+import { formatSyncError, runSync, } from '../features/sync.js';
+import { buildChunksAndEmbeddings, buildVectorChunks, computeContentHash, } from '../ingest/compute.js';
+import { buildPreparedFileVectorChunks, prepareFileForIngest, } from '../ingest/file.js';
+import { parseHtml } from '../parser/html-parser.js';
+import { DocumentParser, ValidationError } from '../parser/index.js';
+import { extractMarkdownTitle, extractTxtTitle } from '../parser/title-extractor.js';
+import { displayPath } from '../utils/base-dirs.js';
+import { MAX_SCAN_DEPTH } from '../utils/limits.js';
+import { checkRawDataArtifacts, extractSourceFromPath, generateMetaJsonPath, generateRawDataPath, isEnoent, isManagedRawDataPath, isPathInRawDataDir, isPathInRawDataDirLexical, loadMetaJson, saveMetaJson, saveRawData, } from '../utils/raw-data-utils.js';
+import { bfsCollectSupportedFiles, canonicalizeRequestedPath, classifyRequestedPath, } from '../utils/scan.js';
+import { nonAbsolutePrefixes } from '../utils/scope-match.js';
+import { VectorStore } from '../vectordb/index.js';
+import { DatabaseError } from '../vectordb/types.js';
+import { appendConfigWarnings, buildConfigErrorBlock, formatErrorForClient, logError, toMcpError, } from './error-utils.js';
+import { normalizeBaseDirs, scanBaseDir } from './list-scanner.js';
+import { toolDefinitions } from './tool-definitions.js';
+import { parseDeleteFileInput, parseIngestDataInput, parseIngestFileInput, parseListFilesInput, parseQueryDocumentsInput, parseReadChunkNeighborsInput, parseSyncStartInput, parseSyncStatusInput, } from './tool-input.js';
+/**
+ * Per-tool client-message policy consumed by the central dispatcher mapper
+ * (`toMcpError(error, context)`). The `prefix`, when present, is prepended to
+ * the controlled client message ONLY for native / non-`AppError` failures; a
+ * recognized `AppError` (e.g. `DatabaseError`, `EmbeddingError`) always keeps
+ * its own raw message regardless of the prefix (see `toMcpError`). This table
+ * is the single source of truth for the Contract-Delta per-handler policy:
+ * - `ingest_file` / `ingest_data` / `delete_file` / `read_chunk_neighbors`
+ *   prepend an operation prefix on native errors.
+ * - `query_documents` / `list_files` / `status` are prefix-less.
+ */
+const TOOL_ERROR_CONTEXT = {
+    ingest_file: { prefix: 'Failed to ingest file' },
+    ingest_data: { prefix: 'Failed to ingest data' },
+    delete_file: { prefix: 'Failed to delete file' },
+    read_chunk_neighbors: { prefix: 'Failed to read chunk neighbors' },
+    sync_start: { prefix: 'Failed to start sync' },
+    query_documents: {},
+    list_files: {},
+    status: {},
+    sync_status: {},
+};
+const ATTACHMENT_WARNING_ANNOTATIONS = {
+    audience: ['user', 'assistant'],
+    priority: 0.3,
+};
+function attachmentOmissionWarning(omittedCount) {
+    return {
+        type: 'text',
+        text: `Warning: Visual attachments omitted ${omittedCount} unavailable or invalid attachment${omittedCount === 1 ? '' : 's'}. Text search results are unchanged.`,
+        annotations: ATTACHMENT_WARNING_ANNOTATIONS,
+    };
+}
+function attachmentHydrationFailureWarning() {
+    return {
+        type: 'text',
+        text: 'Warning: Visual attachments could not be loaded. Text search results are unchanged.',
+        annotations: ATTACHMENT_WARNING_ANNOTATIONS,
+    };
+}
+/**
+ * Tools that mutate the index and therefore pass through the one server-instance
+ * mutation guard (SYNC-007). Read-only tools are deliberately absent: they stay
+ * callable while a sync holds the guard.
+ */
+const MUTATION_TOOLS = new Set([
+    'sync_start',
+    'ingest_file',
+    'ingest_data',
+    'delete_file',
+]);
+const packageVersion = createRequire(import.meta.url)('../../package.json')
+    .version;
+/**
+ * Zero-chunk outcome of {@link RAGServer.handleIngestFile}, raised before any
+ * destructive work so the existing index is preserved.
+ *
+ * An `McpError` subclass rather than a separate error type: the code and message
+ * a client sees are unchanged, while the internal sync collaborator can tell
+ * "this file produced nothing" apart from a genuine ingest failure and count it
+ * as `empty` instead of failing the whole job.
+ */
+class NoChunksError extends McpError {
+}
+/**
+ * Render the scanner's coverage facts as caller-facing warnings, one per
+ * unobserved region, because each one is a reason prune was withheld there. The
+ * wording is not a contract. Carried as JSON strings on the job record rather
+ * than as content blocks, because status is a single pollable record — the
+ * `list_files` warning blocks are unchanged.
+ *
+ * Paths go through `displayPath`, as `list_files` already does with the same
+ * walker facts: the MCP client is remote to the operator's account, so the home
+ * directory (and with it the OS username) is abbreviated to `~`. The CLI variant
+ * deliberately prints the full path — that terminal belongs to the operator.
+ */
+function coverageWarnings(coverage, maxFileSize) {
+    return [
+        ...coverage.unreadableDirs.map(({ dirPath, code }) => `Warning: cannot read directory (${code}), so its indexed files were kept: ${displayPath(dirPath)}`),
+        ...coverage.depthLimitedDirs.map((dirPath) => `Warning: not scanned because it exceeds the maximum depth (${MAX_SCAN_DEPTH}), so its indexed files were kept: ${displayPath(dirPath)}`),
+        ...coverage.skippedSymlinks.map((linkPath) => `Warning: symbolic link not followed, so its indexed files were kept: ${displayPath(linkPath)}`),
+        ...coverage.oversizedFiles.map((filePath) => `Warning: not read because it exceeds the maximum file size (${maxFileSize} bytes), so its indexed chunks were kept: ${displayPath(filePath)}`),
+    ];
+}
+/** RAG server compliant with MCP Protocol */
+export class RAGServer {
+    server;
+    vectorStore;
+    embedder;
+    chunker;
+    parser;
+    dbPath;
+    /**
+     * One or more allowed document base directories — REALPATH-normalized
+     * (the validation/security domain). Passed to `DocumentParser` as the
+     * security boundary. NOT used for `list_files` scanning/display; that uses
+     * the NORMAL-path `rawBaseDirs` below. Normalized from either the legacy
+     * `{ baseDir }` config shape or the new `{ baseDirs }` shape so downstream
+     * readers do not need to branch on shape.
+     */
+    baseDirs;
+    /**
+     * Normal-path (resolve()) roots, index-aligned with `baseDirs`, for
+     * user-facing `list_files` scan/display. Falls back to `baseDirs` for legacy
+     * `{ baseDir }` callers. See {@link BaseDirsConfig} for the path policy.
+     */
+    rawBaseDirs;
+    /** Legacy single-root accessor for `rawBaseDirs`. Derived from `rawBaseDirs[0]`. */
+    rawBaseDir;
+    cacheDir;
+    // Used by handleListFiles filter to exclude system-managed directories
+    excludePaths;
+    configWarnings;
+    /**
+     * Structured base-dirs resolution error. When non-null, the server is in
+     * degraded mode: `status` remains callable so the user can diagnose the
+     * problem via MCP, while root-dependent tools should surface this error
+     * before doing DB or filesystem work. See `resolveBaseDirs` for the error
+     * semantics.
+     */
+    configError;
+    minChunkLength;
+    /**
+     * Configured byte ceiling for one ingested file. The parser enforces it for
+     * parsing; sync also needs it before hashing, where nothing else bounds the
+     * read.
+     */
+    maxFileSize;
+    device;
+    storeImages;
+    /**
+     * The one current-or-latest sync job this process retains (SYNC-006). A new
+     * `sync_start` replaces a terminal record, so the older id becomes unknown,
+     * and process exit simply discards it: there is no history, persistence,
+     * eviction policy, or recovery.
+     */
+    syncJob = null;
+    /**
+     * True while one external mutation is in flight (SYNC-007). A request-scoped
+     * mutation clears it when the request completes; a sync keeps it until its
+     * job reaches a terminal state.
+     */
+    mutationInFlight = false;
+    constructor(config) {
+        this.dbPath = config.dbPath;
+        // Normalize both config shapes into a single `baseDirs: string[]` plus the
+        // legacy single-root accessor. See `normalizeBaseDirs` for the degraded-
+        // mode and misuse semantics.
+        const { baseDirs, baseDir } = normalizeBaseDirs(config);
+        this.baseDirs = baseDirs;
+        // Normal-path roots for user-facing scanning; fall back to the realpath'd
+        // roots for legacy `{ baseDir }` callers.
+        const rawBaseDirs = config.rawBaseDirs !== undefined ? [...config.rawBaseDirs] : [...baseDirs];
+        this.rawBaseDirs = rawBaseDirs;
+        this.rawBaseDir = rawBaseDirs[0] ?? baseDir;
+        this.cacheDir = config.cacheDir;
+        this.configWarnings = config.configWarnings ?? [];
+        this.configError = config.configError ?? null;
+        this.minChunkLength = config.chunkMinLength ?? DEFAULT_MIN_CHUNK_LENGTH;
+        this.maxFileSize = config.maxFileSize;
+        this.device = config.device;
+        this.storeImages = config.storeImages ?? false;
+        this.excludePaths = [`${resolve(this.dbPath)}${sep}`, `${resolve(this.cacheDir)}${sep}`];
+        this.server = new Server({ name: 'rag-mcp-server', version: packageVersion }, { capabilities: { tools: {} }, instructions: this.generateInstructions() });
+        // Component initialization
+        // Only pass quality filter settings if they are defined
+        const vectorStoreConfig = {
+            dbPath: config.dbPath,
+            tableName: 'chunks',
+        };
+        if (config.maxDistance !== undefined) {
+            vectorStoreConfig.maxDistance = config.maxDistance;
+        }
+        if (config.grouping !== undefined) {
+            vectorStoreConfig.grouping = config.grouping;
+        }
+        if (config.hybridWeight !== undefined) {
+            vectorStoreConfig.hybridWeight = config.hybridWeight;
+        }
+        if (config.maxFiles !== undefined) {
+            vectorStoreConfig.maxFiles = config.maxFiles;
+        }
+        this.vectorStore = new VectorStore(vectorStoreConfig);
+        const embedderConfig = {
+            modelPath: config.modelName,
+            batchSize: 16,
+            cacheDir: config.cacheDir,
+        };
+        if (config.device !== undefined) {
+            embedderConfig.device = config.device;
+        }
+        if (config.dtype !== undefined) {
+            embedderConfig.dtype = config.dtype;
+        }
+        this.embedder = new Embedder(embedderConfig);
+        this.chunker = new SemanticChunker(config.chunkMinLength !== undefined ? { minChunkLength: config.chunkMinLength } : {});
+        // Always construct the parser with the multi-root shape — the parser
+        // accepts a single-element `baseDirs` array as the byte-equivalent of
+        // the legacy `baseDir` shape, so passing `this.baseDirs` covers both
+        // config inputs without branching here.
+        this.parser = new DocumentParser({
+            baseDirs: this.baseDirs,
+            maxFileSize: config.maxFileSize,
+        });
+        this.setupHandlers();
+    }
+    /**
+     * Fail-fast guard for root-dependent tools. When a {@link BaseDirsConfigError}
+     * is stored on the instance the server is in degraded mode (invalid
+     * `BASE_DIRS` — see `resolveBaseDirs`) and every root-dependent tool MUST
+     * reject BEFORE any DB / embedder / parser access so the user sees the
+     * configuration problem unambiguously. Throws the stored
+     * {@link BaseDirsConfigError} (kind `config`) so the central dispatcher
+     * mapper renders it as `McpError(InvalidParams)` — error→code ownership
+     * stays in exactly one place instead of being hand-built here.
+     *
+     * `status` deliberately does NOT call this helper; it remains callable in
+     * degraded mode and exposes the error via a diagnostic content block so
+     * the user can recover via MCP without inspecting stderr.
+     */
+    assertConfigOk() {
+        if (this.configError !== null) {
+            throw this.configError;
+        }
+    }
+    /**
+     * Append the centralized config-warning blocks to a handler response.
+     * Every tool handler funnels through this method so the warning shape
+     * stays in exactly one place (design-doc-mandated countermeasure for the
+     * "warning shape changes touch many handlers" risk).
+     */
+    withWarnings(content) {
+        return appendConfigWarnings(content, this.configWarnings);
+    }
+    /**
+     * Take the single external-mutation slot, or describe the overlap.
+     *
+     * Returns `null` when the slot was free (the caller now holds it), otherwise
+     * the responsive overlap result: an ordinary tool result with `isError: true`
+     * rather than a thrown error, so it never passes through `toMcpError`. When a
+     * sync holds the guard the message names its job id and points at
+     * `sync_status`, which is the only way for the caller to learn when to retry.
+     */
+    acquireMutation() {
+        if (!this.mutationInFlight) {
+            this.mutationInFlight = true;
+            return null;
+        }
+        const runningJob = this.syncJob?.state === 'running' ? this.syncJob : null;
+        const text = runningJob === null
+            ? 'Another write operation is already running on this server. Retry when it finishes.'
+            : `A sync job is running (jobId: ${runningJob.jobId}). Poll sync_status with that jobId and retry once it is no longer running.`;
+        return { content: this.withWarnings([{ type: 'text', text }]), isError: true };
+    }
+    releaseMutation() {
+        this.mutationInFlight = false;
+    }
+    /**
+     * Set up MCP handlers
+     */
+    setupHandlers() {
+        // Tool list
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: toolDefinitions,
+        }));
+        // Tool invocation. The handlers are gutted of error mapping — every error
+        // they throw (with its ORIGINAL identity) is routed through the single
+        // central catch below, which logs the full cause chain to stderr and maps
+        // the error to an `McpError` for the client via `toMcpError(error,
+        // context)`. The per-tool `context` (see `TOOL_ERROR_CONTEXT`) encodes each
+        // handler's client-message prefix policy so the Contract-Delta per-handler
+        // table is preserved in exactly one place.
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const toolName = request.params.name;
+            // The mutation guard sits here, on the external dispatch path only, so
+            // an internal call such as `handleIngestData` -> `handleIngestFile`
+            // cannot reacquire it and self-deadlock.
+            if (MUTATION_TOOLS.has(toolName)) {
+                const overlap = this.acquireMutation();
+                if (overlap !== null)
+                    return overlap;
+            }
+            // `sync_start` hands the guard to the job it schedules, which releases
+            // it on the terminal transition; every other mutation is request-scoped
+            // and releases below whether it succeeds or throws.
+            let releaseWhenRequestEnds = MUTATION_TOOLS.has(toolName);
+            try {
+                switch (toolName) {
+                    case 'query_documents':
+                        return await this.handleQueryDocuments(parseQueryDocumentsInput(request.params.arguments));
+                    case 'ingest_file':
+                        return await this.handleIngestFile(request.params.arguments);
+                    case 'ingest_data':
+                        return await this.handleIngestData(parseIngestDataInput(request.params.arguments));
+                    case 'delete_file':
+                        return await this.handleDeleteFile(request.params.arguments);
+                    case 'read_chunk_neighbors':
+                        return await this.handleReadChunkNeighbors(request.params.arguments);
+                    case 'list_files':
+                        return await this.handleListFiles(parseListFilesInput(request.params.arguments));
+                    case 'status':
+                        return await this.handleStatus();
+                    case 'sync_start': {
+                        const started = await this.handleSyncStart(parseSyncStartInput(request.params.arguments));
+                        // Reached only once a job is registered and scheduled; a throw
+                        // above leaves the flag set so the `finally` frees the guard.
+                        releaseWhenRequestEnds = false;
+                        return started;
+                    }
+                    case 'sync_status':
+                        return await this.handleSyncStatus(parseSyncStatusInput(request.params.arguments));
+                    default:
+                        throw new Error(`Unknown tool: ${toolName}`);
+                }
+            }
+            catch (error) {
+                const context = TOOL_ERROR_CONTEXT[toolName] ?? {};
+                logError(toolName, error);
+                throw toMcpError(error, context);
+            }
+            finally {
+                if (releaseWhenRequestEnds)
+                    this.releaseMutation();
+            }
+        });
+    }
+    /**
+     * Initialization
+     */
+    async initialize() {
+        await this.vectorStore.initialize();
+        console.error('RAGServer initialized');
+    }
+    /**
+     * query_documents tool handler
+     */
+    async handleQueryDocuments(args) {
+        // query_documents operates over the LanceDB only (no baseDirs access), so
+        // it stays callable in degraded mode (configError present). The warning
+        // and error blocks attached via `withWarnings` / status remain the user-
+        // visible diagnostic surface for the config problem.
+        //
+        // No local catch: any failure propagates with original identity to the
+        // central dispatcher mapper (prefix-less context for this tool).
+        // Generate query embedding
+        const queryVector = await this.embedder.embed(args.query);
+        // `args.scope` is parser-validated; array-wrap without re-validating, and
+        // omit the key when absent (exactOptionalPropertyTypes) to keep the scope-absent path.
+        const searchResults = await this.vectorStore.search(queryVector, {
+            queryText: args.query,
+            limit: args.limit ?? 10,
+            ...(args.scope !== undefined
+                ? { scope: Array.isArray(args.scope) ? args.scope : [args.scope] }
+                : {}),
+        });
+        // Format results with source restoration for raw-data files
+        const results = searchResults.map((result) => {
+            const queryResult = {
+                filePath: result.filePath,
+                chunkIndex: result.chunkIndex,
+                text: result.text,
+                score: result.score,
+                fileTitle: result.fileTitle ?? null,
+            };
+            if (isManagedRawDataPath(result.filePath, this.dbPath)) {
+                const source = extractSourceFromPath(result.filePath);
+                if (source) {
+                    queryResult.source = source;
+                }
+            }
+            return queryResult;
+        });
+        let hydratedRows = [];
+        let attachmentWarning = null;
+        try {
+            const hydration = await this.vectorStore.hydrateVisualAttachments(searchResults);
+            hydratedRows = hydration.rows;
+            if (hydration.omittedCount > 0) {
+                attachmentWarning = attachmentOmissionWarning(hydration.omittedCount);
+            }
+        }
+        catch {
+            attachmentWarning = attachmentHydrationFailureWarning();
+        }
+        const content = [
+            {
+                type: 'text',
+                text: JSON.stringify(results, null, 2),
+            },
+        ];
+        const attachmentsByIdentity = new Map(hydratedRows.map((row) => [row.id, row.attachments]));
+        for (const [resultIndex, result] of results.entries()) {
+            const attachments = attachmentsByIdentity.get(searchResults[resultIndex]?.id ?? '') ?? [];
+            for (const attachment of attachments) {
+                content.push({
+                    type: 'text',
+                    text: JSON.stringify({
+                        type: 'visual_attachment',
+                        result: {
+                            filePath: result.filePath,
+                            chunkIndex: result.chunkIndex,
+                            ...(result.source === undefined ? {} : { source: result.source }),
+                        },
+                        imageIndex: attachment.imageIndex,
+                        mimeType: attachment.mimeType,
+                    }),
+                });
+                content.push({
+                    type: 'image',
+                    data: attachment.data,
+                    mimeType: attachment.mimeType,
+                });
+            }
+        }
+        if (attachmentWarning)
+            content.push(attachmentWarning);
+        // Append config warnings on every call because MCP clients may hide
+        // stderr and may not retain context across calls.
+        return { content: this.withWarnings(content) };
+    }
+    /**
+     * ingest_file tool handler (re-ingestion support, transaction processing, rollback capability)
+     *
+     * `options.skipOptimize` is internal: sync compacts once per run, so its reuse
+     * of this handler must not compact once per file (a 100-file sync would
+     * otherwise perform 101 compactions). The `ingest_file` and `ingest_data` tools
+     * omit it and keep compacting per call, which is the behavior they always had.
+     */
+    async handleIngestFile(raw, options = {}) {
+        const result = await this.ingestFile(parseIngestFileInput(raw), options);
+        return {
+            content: this.withWarnings([
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ]),
+        };
+    }
+    async ingestFile(args, options = {}) {
+        const isRawData = await isPathInRawDataDir(args.filePath, this.dbPath);
+        // Skip the configError gate only for paths structurally inside
+        // `<dbPath>/raw-data/` (internal invocation from handleIngestData).
+        if (!isRawData) {
+            this.assertConfigOk();
+        }
+        // `args.filePath` is the DB key (backup/delete/insert/result), stored
+        // verbatim so lookups match (realpath stays in validateFilePath; see
+        // BaseDirsConfig for the path policy).
+        const visualArg = args.visual;
+        const visualQuality = args.visualQuality ?? 'fast';
+        let backup = null;
+        // No outer error-mapping catch: failures propagate with original identity
+        // to the central dispatcher mapper. The inner insert/rollback try/catch
+        // below is retained — it is local-effect (data rollback) only.
+        // Parse file (with header/footer filtering for PDFs)
+        // For raw-data files (from ingest_data), read directly without validation
+        // since the path is internally generated and content is already processed
+        const isPdf = args.filePath.toLowerCase().endsWith('.pdf');
+        const isDocx = args.filePath.toLowerCase().endsWith('.docx');
+        const images = (isPdf || isDocx) && (options.images ?? this.storeImages);
+        let title;
+        let vectorChunks;
+        let preparedFile;
+        let omittedImageCount = 0;
+        if (isRawData) {
+            // Raw-data files: skip parser validation, read directly.
+            const sourceBytes = await readFile(args.filePath);
+            const text = sourceBytes.toString('utf-8');
+            const meta = await loadMetaJson(args.filePath);
+            title = meta?.title ?? null;
+            console.error(`Read raw-data file: ${args.filePath} (${text.length} characters)`);
+            const { chunks, embeddings } = await buildChunksAndEmbeddings(text, this.chunker, this.embedder);
+            vectorChunks = buildVectorChunks({
+                filePath: args.filePath,
+                chunks,
+                embeddings,
+                fileSize: text.length,
+                fileTitle: title,
+                contentHash: computeContentHash(sourceBytes),
+            });
+        }
+        else {
+            // The MCP boundary accepts an arbitrary client path, unlike CLI ingestion
+            // paths that have already passed a regular-file collector. Reject a FIFO
+            // before the shared whole-file hash read can block the mutation slot.
+            await this.parser.validateFilePath(args.filePath);
+            this.parser.validateFileSize(args.filePath);
+            if (!(await stat(args.filePath)).isFile()) {
+                throw new ValidationError(`Ingest source is not a regular file: ${args.filePath}`);
+            }
+            preparedFile = await prepareFileForIngest(args.filePath, this.parser, this.chunker, this.embedder, {
+                images,
+                ...(visualArg === true
+                    ? {
+                        captioner: {
+                            profile: visualQuality,
+                            cacheDir: this.cacheDir,
+                            device: this.device,
+                        },
+                    }
+                    : {}),
+            });
+            title = preparedFile.title;
+            omittedImageCount = preparedFile.omittedImageCount;
+        }
+        if (omittedImageCount > 0) {
+            console.warn(`Skipped ${omittedImageCount} undecodable or oversized image(s) in ${args.filePath}`);
+        }
+        // Fail-fast: Prevent data loss when chunking produces 0 chunks
+        // This check must happen BEFORE delete to preserve existing data on re-ingest
+        const chunkCount = vectorChunks?.length ?? preparedFile?.chunks.length ?? 0;
+        if (chunkCount === 0) {
+            throw new NoChunksError(ErrorCode.InvalidParams, `No chunks generated from file: ${args.filePath}. The file may be empty or all content was filtered (minimum ${this.minChunkLength} characters required). Existing data has been preserved.`);
+        }
+        // Back up existing chunks BEFORE the destructive delete, with their real
+        // stored vectors and the full chunk set, so a failed re-ingest can be
+        // rolled back without data loss or vector corruption (TD-7). Read this
+        // before deleting; if the read fails it propagates here — leaving the
+        // existing data untouched — rather than proceeding into the delete with
+        // an empty/partial backup.
+        backup = await this.vectorStore.getChunksByFilePath(args.filePath);
+        if (backup.length > 0) {
+            console.error(`Backup created: ${backup.length} chunks for ${args.filePath}`);
+        }
+        // Preserve the original server ordering: row construction follows the
+        // backup read but still completes before the destructive delete.
+        if (preparedFile !== undefined) {
+            vectorChunks = buildPreparedFileVectorChunks(preparedFile);
+        }
+        const chunksToInsert = vectorChunks;
+        // Delete existing data
+        await this.vectorStore.deleteChunks(args.filePath);
+        console.error(`Deleted existing chunks for: ${args.filePath}`);
+        // Insert vectors (transaction processing)
+        try {
+            await this.vectorStore.insertChunks(chunksToInsert);
+            console.error(`Inserted ${chunksToInsert.length} chunks for: ${args.filePath}`);
+            // Optimize once after both delete + insert (not per-operation), unless the
+            // caller compacts once for the whole batch.
+            if (options.skipOptimize !== true) {
+                await this.vectorStore.optimize();
+            }
+            // Delete backup on success
+            backup = null;
+        }
+        catch (insertError) {
+            // Rollback on error
+            if (backup && backup.length > 0) {
+                console.error('Ingestion failed, rolling back...', insertError);
+                try {
+                    await this.vectorStore.insertChunks(backup);
+                    await this.vectorStore.optimize();
+                    console.error(`Rollback completed: ${backup.length} chunks restored`);
+                }
+                catch (rollbackError) {
+                    // Rollback also failed: throw a distinct error (cause = insertError)
+                    // so the client learns the prior data may be lost, not just that the insert failed.
+                    console.error('Rollback failed:', rollbackError);
+                    throw new DatabaseError(`Ingest failed and rollback failed for ${args.filePath}; existing data may not have been restored. Original insert error: ${insertError.message}`, insertError);
+                }
+            }
+            throw insertError;
+        }
+        return {
+            filePath: args.filePath,
+            chunkCount,
+            timestamp: new Date().toISOString(),
+            fileTitle: title || null,
+        };
+    }
+    /**
+     * ingest_data tool handler
+     * Saves raw content to raw-data directory and calls handleIngestFile internally
+     *
+     * For HTML content:
+     * - Parses HTML and extracts main content using Readability
+     * - Converts to Markdown for better chunking
+     * - Saves as .md file
+     */
+    async handleIngestData(args) {
+        // ingest_data writes only to `dbPath`/raw-data — it never reads from a
+        // configured `baseDir`. Keeping it callable in degraded mode means a user
+        // with invalid BASE_DIRS can still capture raw-data via MCP while they
+        // diagnose the config error from `status`. The internal `handleIngestFile`
+        // call below operates on a generated raw-data path, which routes
+        // around `parser.validateFilePath`, so no baseDirs access happens.
+        //
+        // No outer error-mapping catch: failures propagate with original identity
+        // to the central dispatcher mapper. The inner raw-data rollback try/catch
+        // below is retained — it is local-effect (file cleanup) only.
+        let contentToSave = args.content;
+        let title = null;
+        // Per-format title extraction and content preparation
+        if (args.metadata.format === 'html') {
+            console.error(`Parsing HTML from: ${args.metadata.source}`);
+            const { content: markdown, title: htmlTitle } = await parseHtml(args.content, args.metadata.source);
+            if (!markdown.trim()) {
+                throw new Error('Failed to extract content from HTML. The page may have no readable content.');
+            }
+            title = htmlTitle || null;
+            contentToSave = markdown;
+            console.error(`Converted HTML to Markdown: ${markdown.length} characters`);
+        }
+        else if (args.metadata.format === 'markdown') {
+            const result = extractMarkdownTitle(args.content, args.metadata.source);
+            title = result.source !== 'filename' ? result.title : null;
+        }
+        else {
+            // text format
+            const result = extractTxtTitle(args.content, args.metadata.source);
+            title = result.source !== 'filename' ? result.title : null;
+        }
+        // Save content to raw-data directory
+        const rawDataPath = await saveRawData(this.dbPath, args.metadata.source, contentToSave);
+        // Save metadata sidecar (.meta.json) alongside the raw-data file
+        await saveMetaJson(rawDataPath, {
+            title,
+            source: args.metadata.source,
+            format: args.metadata.format,
+        });
+        console.error(`Saved raw data: ${args.metadata.source} -> ${rawDataPath}`);
+        // Call existing ingest_file internally with rollback on failure
+        try {
+            return await this.handleIngestFile({ filePath: rawDataPath });
+        }
+        catch (ingestError) {
+            // Rollback: delete the raw-data file and .meta.json if ingest fails
+            try {
+                await unlink(rawDataPath);
+                await unlink(generateMetaJsonPath(rawDataPath));
+                console.error(`Rolled back raw-data file: ${rawDataPath}`);
+            }
+            catch {
+                console.warn(`Failed to rollback raw-data file: ${rawDataPath}`);
+            }
+            throw ingestError;
+        }
+    }
+    /**
+     * list_files tool handler
+     *
+     * Scans the normal-path roots (`this.rawBaseDirs`) so scanned paths match the
+     * resolve()-stored DB keys (see {@link BaseDirsConfig} for the path policy).
+     *
+     * Scans every effective base directory (`this.rawBaseDirs`) for supported
+     * files and cross-references with ingested documents. Multi-root contract:
+     * - Returns top-level `baseDirs` (all effective roots in normal-path space,
+     *   nested-root-pruned by `resolveBaseDirs`).
+     * - Preserves legacy top-level `baseDir = rawBaseDirs[0]` for clients written
+     *   against the single-root shape.
+     * - Annotates each file entry with the producing `baseDir`.
+     * - De-duplicates exact duplicate file paths across roots (first occurrence
+     *   wins, preserving root iteration order).
+     * - Preserves raw-data / orphaned DB entries under `sources` with no
+     *   producing-root annotation.
+     * - Excludes `dbPath` and `cacheDir` uniformly across every root.
+     */
+    async handleListFiles(input = {}) {
+        // Root-dependent tool: fail fast on configError BEFORE any DB / FS access.
+        // `assertConfigOk` throws `BaseDirsConfigError` (mapped to InvalidParams by
+        // the central dispatcher); no local error-mapping catch here.
+        this.assertConfigOk();
+        // `input.scope` is parser-normalized to `string[]`, but the shared input
+        // type admits `string | string[]`; array-wrap once (mirrors query_documents)
+        // so scope threads uniformly into the walker and the sources classifier.
+        // Undefined scope leaves both the scan and the sources split unchanged.
+        const scope = input.scope === undefined
+            ? undefined
+            : Array.isArray(input.scope)
+                ? input.scope
+                : [input.scope];
+        const ingested = await this.vectorStore.listFiles();
+        const listed = await listDocuments({
+            roots: this.rawBaseDirs,
+            dbPath: this.dbPath,
+            ingested,
+            scope,
+            scan: (baseDir, scanScope) => scanBaseDir(baseDir, this.excludePaths, scanScope),
+        });
+        const files = listed.files;
+        const sources = listed.sources;
+        const result = {
+            baseDir: this.rawBaseDir,
+            baseDirs: [...this.rawBaseDirs],
+            files,
+            sources,
+        };
+        // Build the response with the primary JSON block first, then any
+        // per-root scan warnings as additional text blocks so
+        // clients see the warnings alongside the file list without needing
+        // to inspect stderr. Config-level warnings (`configWarnings`) are
+        // still appended via `withWarnings`.
+        const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
+        for (const warning of listed.warnings) {
+            content.push({
+                type: 'text',
+                text: `Warning: [${warning.baseDir}] ${warning.message}`,
+            });
+        }
+        // A non-absolute scope prefix matches nothing (the scan is absolute-path
+        // based) but yields no result-level signal, so surface it as a non-fatal
+        // warning block. Result semantics are unchanged — the prefix still matches
+        // nothing; this only makes the silent miss visible to the client.
+        if (scope !== undefined) {
+            for (const prefix of nonAbsolutePrefixes(scope)) {
+                content.push({
+                    type: 'text',
+                    text: `Warning: scope prefix "${prefix}" is not absolute; it matches nothing.`,
+                });
+            }
+        }
+        return { content: this.withWarnings(content) };
+    }
+    /**
+     * status tool handler
+     */
+    async handleStatus() {
+        // `status` remains callable in degraded mode (configError set) so the
+        // user can diagnose the root configuration via MCP without inspecting
+        // stderr. Do NOT call `assertConfigOk` here — status surfaces the config
+        // error as a diagnostic content block instead of throwing. No local
+        // error-mapping catch: genuine DB failures propagate (prefix-less) to the
+        // central dispatcher mapper.
+        const status = await this.vectorStore.getStatus();
+        const content = [
+            {
+                type: 'text',
+                text: JSON.stringify(status, null, 2),
+            },
+        ];
+        // Surface the configError as a diagnostic content block when present.
+        // Placed BEFORE warning blocks so it appears with the primary status
+        // payload at a higher priority annotation.
+        if (this.configError !== null) {
+            content.push(buildConfigErrorBlock(this.configError.message));
+        }
+        return { content: this.withWarnings(content) };
+    }
+    /**
+     * delete_file tool handler
+     * Deletes chunks from VectorDB and physical raw-data files
+     * Supports both filePath (for ingest_file) and source (for ingest_data)
+     */
+    async handleDeleteFile(raw) {
+        const args = parseDeleteFileInput(raw);
+        // No outer error-mapping catch: the inline `McpError(InvalidParams)` and
+        // `assertConfigOk` throw propagate with original identity to the central
+        // dispatcher mapper. The inner unlink try/catch blocks below are
+        // local-effect (best-effort file cleanup) and are retained.
+        const targetPath = await this.resolveDocumentTarget(args);
+        // Delete chunks from vector database
+        const removedChunks = await this.vectorStore.deleteChunks(targetPath);
+        // Optimize immediately after the DB delete: a later raw-data unlink failure
+        // must not skip compaction once the rows are already gone.
+        await this.vectorStore.optimize();
+        let rawDataExisted = false;
+        let metaExisted = false;
+        // Also delete physical raw-data file if applicable.
+        if (isPathInRawDataDirLexical(targetPath, this.dbPath)) {
+            // Pre-unlink existence (shared with the CLI delete path).
+            const artifacts = await checkRawDataArtifacts(targetPath);
+            rawDataExisted = artifacts.rawDataExisted;
+            metaExisted = artifacts.metaExisted;
+            try {
+                await unlink(targetPath);
+                console.error(`Deleted raw-data file: ${targetPath}`);
+            }
+            catch (error) {
+                if (!isEnoent(error)) {
+                    throw error;
+                }
+                console.warn(`Could not delete raw-data file (may not exist): ${targetPath}`);
+            }
+            try {
+                await unlink(generateMetaJsonPath(targetPath));
+                console.error(`Deleted meta.json: ${generateMetaJsonPath(targetPath)}`);
+            }
+            catch (error) {
+                if (!isEnoent(error)) {
+                    throw error;
+                }
+            }
+        }
+        const result = {
+            filePath: targetPath,
+            deleted: true,
+            removedChunks,
+            existed: removedChunks > 0 || rawDataExisted || metaExisted,
+            timestamp: new Date().toISOString(),
+        };
+        return {
+            content: this.withWarnings([
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ]),
+        };
+    }
+    /**
+     * read_chunk_neighbors tool handler
+     * Returns chunks around a target chunkIndex within a single ingested document.
+     * Context-expansion utility — not a search tool. Mirrors handleDeleteFile's
+     * dual-input (filePath XOR source) resolution pattern.
+     */
+    async handleReadChunkNeighbors(raw) {
+        const args = parseReadChunkNeighborsInput(raw);
+        // No local error-mapping catch: `assertConfigOk` errors propagate with original identity to the
+        // central dispatcher mapper. A `DatabaseError` reaches the mapper as a
+        // recognized `AppError` and so stays prefix-less (no "Failed to read chunk
+        // neighbors" prefix); only a native error picks up that prefix.
+        const before = args.before ?? 2;
+        const after = args.after ?? 2;
+        const targetPath = await this.resolveDocumentTarget(args);
+        // Range composition (handler-side clamp; primitive stays feature-agnostic).
+        const minIdx = Math.max(0, args.chunkIndex - before);
+        const maxIdx = args.chunkIndex + after;
+        // Primitive call.
+        const rows = await this.vectorStore.getChunksByRange(targetPath, minIdx, maxIdx);
+        // Post-fetch marking: isTarget per item; source attached for raw-data rows.
+        const isRaw = isManagedRawDataPath(targetPath, this.dbPath);
+        const sourceForAll = isRaw ? extractSourceFromPath(targetPath) : null;
+        const items = rows.map((row) => {
+            const item = {
+                filePath: row.filePath,
+                chunkIndex: row.chunkIndex,
+                text: row.text,
+                isTarget: row.chunkIndex === args.chunkIndex,
+                fileTitle: row.fileTitle ?? null,
+            };
+            if (sourceForAll)
+                item.source = sourceForAll;
+            return item;
+        });
+        return {
+            content: this.withWarnings([
+                {
+                    type: 'text',
+                    text: JSON.stringify(items, null, 2),
+                },
+            ]),
+        };
+    }
+    /** Resolve the shared filePath/source reference without changing its DB-key spelling. */
+    async resolveDocumentTarget(reference) {
+        if ('source' in reference) {
+            // Generated raw-data paths do not depend on configured document roots, so
+            // source-mode operations remain callable while root configuration is invalid.
+            return generateRawDataPath(this.dbPath, reference.source);
+        }
+        this.assertConfigOk();
+        await this.parser.validateFilePath(reference.filePath);
+        return reference.filePath;
+    }
+    /**
+     * sync_start tool handler
+     *
+     * Registers the one current job, schedules the run, and answers with its id
+     * without waiting for any of it: the caller polls `sync_status` (SYNC-006).
+     * The scheduled promise is deliberately floating — an unexpected rejection is
+     * captured into the job record instead of escaping, and the run holds the
+     * external-mutation guard until it is terminal.
+     */
+    async handleSyncStart(input) {
+        // Root-dependent tool: fail fast on configError before registering a job.
+        this.assertConfigOk();
+        const jobId = randomUUID();
+        this.syncJob = {
+            jobId,
+            state: 'running',
+            total: null,
+            completed: 0,
+            summary: { upserted: 0, skipped: 0, empty: 0, pruned: 0 },
+            warnings: [],
+            error: null,
+        };
+        void this.runSyncJob(jobId, input.path)
+            .catch((error) => {
+            // Only an unexpected orchestration failure lands here: `runSync` already
+            // returns its own controlled error. One error, no rollback, no retry.
+            this.updateSyncJob(jobId, { state: 'failed', error: formatErrorForClient(error) });
+        })
+            .finally(() => {
+            this.releaseMutation();
+        });
+        return {
+            content: this.withWarnings([{ type: 'text', text: JSON.stringify({ jobId }, null, 2) }]),
+        };
+    }
+    /**
+     * sync_status tool handler
+     *
+     * Read-only, so it stays callable while a sync holds the mutation guard. Any
+     * id other than the current one is unknown: the record was replaced by a newer
+     * `sync_start` or lost with a previous server process.
+     */
+    async handleSyncStatus(input) {
+        const job = this.syncJob;
+        if (job === null || job.jobId !== input.jobId) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown sync job: ${input.jobId}. Only the current or latest job is kept: it is replaced by a newer sync_start and discarded when the server process exits.`);
+        }
+        return {
+            content: this.withWarnings([{ type: 'text', text: JSON.stringify(job, null, 2) }]),
+        };
+    }
+    /** Patch the current job, ignoring a write aimed at a record already replaced. */
+    updateSyncJob(jobId, patch) {
+        if (this.syncJob === null || this.syncJob.jobId !== jobId)
+            return;
+        this.syncJob = { ...this.syncJob, ...patch };
+    }
+    /**
+     * The scheduled body of one sync job: supply the real collaborators to the
+     * shared core (`src/features/sync.ts`) and fold its result into the pollable
+     * record. Planning, prune eligibility, and the stop-on-first-error policy stay
+     * in the core; path classification and depth therefore match the CLI exactly.
+     */
+    async runSyncJob(jobId, requestedPath) {
+        let hashedFiles = 0;
+        let ingestedFiles = 0;
+        const collaborators = {
+            // The containment boundary for a client-supplied path: the core compares
+            // this canonical form against the realpath'd roots, which is the only way
+            // to see that an intermediate component is a symbolic link out of the root.
+            // `ingest_file` validates the same way, so both tools refuse the same paths.
+            canonicalizeRequestedPath,
+            // The walker's own predicates, so an explicitly requested path is subject
+            // to the same rules as a discovered one and is refused before it is read.
+            // A path whose read would never return (a FIFO) is refused here too, which
+            // matters more on this surface than on the CLI: the mutation guard is
+            // released by this job's promise settling, and nothing else would.
+            classifyPath: async (path) => await classifyRequestedPath(path, this.excludePaths),
+            // No `scope` argument, on purpose: a scope-pruned directory appears in
+            // none of the coverage arrays, which would hide an unobserved region and
+            // make prune unsafe.
+            scanDir: async (rootPath) => await bfsCollectSupportedFiles(rootPath, this.excludePaths, MAX_SCAN_DEPTH),
+            // Size first, bytes second: `maxFileSize` is otherwise enforced inside the
+            // parser, which runs long after the whole file would already be in memory
+            // here. Declining (`null`) keeps the rest of the run usable instead of
+            // failing every future sync of the whole root on one oversized file.
+            //
+            // The bound holds only against a non-racing filesystem: a writer that grows
+            // the file, or replaces it with a FIFO, between the `stat` and the
+            // `readFile` restores the unbounded read or an indefinite block. That actor
+            // needs local write access as this same user and can already reach the
+            // database directly, so this is a recorded limitation rather than a defended
+            // boundary — as with the watchdog limitation noted on the mutation guard.
+            hashFile: async (filePath) => {
+                if ((await stat(filePath)).size > this.maxFileSize)
+                    return null;
+                const contentHash = computeContentHash(await readFile(filePath));
+                hashedFiles += 1;
+                return contentHash;
+            },
+            loadDbManifest: async () => {
+                // The core hashes every scanned file before it loads the manifest, so
+                // this is the first moment the supported-file count is final.
+                this.updateSyncJob(jobId, { total: hashedFiles });
+                return await this.vectorStore.listChunkHashes();
+            },
+            ingestFile: async (filePath, images) => {
+                const chunkCount = await this.ingestFileForSync(filePath, images);
+                ingestedFiles += 1;
+                this.updateSyncJob(jobId, { completed: ingestedFiles });
+                return chunkCount;
+            },
+            deleteExactPath: async (filePath) => await this.vectorStore.deleteChunks(filePath),
+            optimize: async () => {
+                await this.vectorStore.optimize();
+            },
+        };
+        const result = await runSync({
+            roots: this.rawBaseDirs,
+            // The realpath'd counterpart of the same roots, which is what the core
+            // decides requested-path containment in (the parser's boundary domain).
+            canonicalRoots: this.baseDirs,
+            dbPath: this.dbPath,
+            excludePaths: this.excludePaths,
+            platform: process.platform,
+            // resolve() (never realpath) so the requested path is spelled like the
+            // stored DB keys; the core validates it against the configured roots.
+            ...(requestedPath === undefined ? {} : { requestedPath: resolve(requestedPath) }),
+            ...(this.storeImages ? { images: true } : {}),
+            collaborators,
+        });
+        this.updateSyncJob(jobId, {
+            state: result.error === null ? 'succeeded' : 'failed',
+            // Skips are only known once the plan has run, so the final value can only
+            // grow: a poll never sees `completed` go backwards.
+            completed: result.upserted + result.skipped + result.empty,
+            summary: {
+                upserted: result.upserted,
+                skipped: result.skipped,
+                empty: result.empty,
+                pruned: result.pruned,
+            },
+            warnings: coverageWarnings(result.coverage, this.maxFileSize),
+            error: result.error === null ? null : formatSyncError(result.error),
+        });
+    }
+    /**
+     * Sync's `ingestFile` collaborator uses the same typed ingestion operation as
+     * `ingest_file`, preserving its backup and rollback semantics while returning
+     * only the chunk count the sync core needs. A zero-chunk file is reported as
+     * `empty`; the typed operation rejects it before delete, leaving prior rows
+     * unchanged.
+     *
+     * Compaction is the second difference: the sync core runs one `optimize()` for
+     * the whole run, so the per-file one is skipped here. A rollback still compacts
+     * — that path restores rows and then aborts the run, so no later `optimize()`
+     * follows it.
+     */
+    async ingestFileForSync(filePath, images) {
+        try {
+            const result = await this.ingestFile({ filePath }, { skipOptimize: true, images });
+            return result.chunkCount;
+        }
+        catch (error) {
+            if (error instanceof NoChunksError)
+                return 0;
+            throw error;
+        }
+    }
+    /**
+     * Serve this instance's tool registration over `transport`.
+     *
+     * Exposed because the registration itself — not a re-registered copy of it —
+     * is what an MCP client talks to, and `this.server` is private. `run()` passes
+     * the stdio transport; a test passes an in-memory pair.
+     *
+     * One instance serves at most one client: the sync job record and the mutation
+     * slot are per-process, so a transport that multiplexed clients would share one
+     * caller's job state and one caller's write lock with every other caller.
+     */
+    async connect(transport) {
+        await this.server.connect(transport);
+    }
+    /**
+     * Start the server
+     */
+    async run() {
+        await this.connect(new StdioServerTransport());
+        console.error('RAGServer running on stdio transport');
+    }
+    /**
+     * Stop the server and release resources
+     */
+    async close() {
+        await this.server.close();
+        await this.vectorStore.close();
+        await this.embedder.dispose();
+        console.error('RAGServer stopped');
+    }
+    /**
+     * Generate MCP server instructions automatically based on the configured
+     * base directories. A single root equal to the current working directory
+     * means the server indexes the current project; any other roots mean it
+     * indexes shared/common directories.
+     */
+    generateInstructions() {
+        const isProject = this.rawBaseDirs.length === 1 && resolve(this.rawBaseDirs[0]) === resolve(process.cwd());
+        if (isProject) {
+            return ('Ce serveur MCP indexe le projet courant. Pour toute question portant sur le code, ' +
+                "l'architecture, les fonctions PHP/Python ou le fonctionnement du projet courant, " +
+                "utilise l'outil query_documents pour chercher dans les fichiers indexés avant de répondre. " +
+                "Effectue cette recherche de manière transparente et invisible pour l'utilisateur.");
+        }
+        const dirs = this.rawBaseDirs.join(', ');
+        return (`Ce serveur MCP indexe les dossiers communs partagés entre projets : ${dirs}. ` +
+            "Pour toute question portant sur ce contenu commun, utilise l'outil query_documents " +
+            "pour chercher dans les fichiers indexés avant de répondre. " +
+            "Effectue cette recherche de manière transparente et invisible pour l'utilisateur.");
+    }
+}
+//# sourceMappingURL=index.js.map