io.github.sfrangulov/minirag-mcp

Delete an indexed file, data item, or url item from the index. Provide exactly one of filePath (absolute path inside a document root) or source (the id of a data/url item). This only removes the index entry — a file left in place under a document root is re-ingested by a later sync_start.

Ingest text/markdown/html content the client holds, under a source id you choose. format is one of "text", "markdown", or "html" (default "text"). source is a stable identifier you pick, not a filesystem path — re-using it replaces the previously ingested content for that id, so reuse the same source to update an item.

Ingest or re-ingest one file, replacing any content already indexed for it. filePath must be an absolute path inside a configured document root. Re-ingesting an already-indexed file discards its old chunks and replaces them with freshly parsed ones.

Fetch an http(s) URL, convert it to Markdown, and index it. Only http and https schemes are accepted, and the host must not be a private or local address (loopback, link-local, private, reserved) — set ALLOW_PRIVATE_URLS=1 to lift that. This is the one tool that reaches the network — every other tool works purely against local files and the local index. source defaults to the URL itself; pass one to control the index key or to update a previously ingested URL.

List files found on disk under the document roots, plus indexed data/url sources. Each disk file is reported with a state: "ingested" (index matches disk), "stale" (changed on disk since it was indexed), "stale_scheme" (unchanged on disk, but indexed under an older chunking scheme, so its vectors are not comparable with current ones), "not_ingested" (never indexed), or "unreadable" (indexed and still on disk, but of a type this installation cannot read because an optional extra is absent — images need [ocr]). Everything but "ingested" and "unreadable" needs a sync_start; an "unreadable" source is kept as indexed and no sync can refresh it here. "stale_scheme" is the per-source view of what status reports as staleChunkCount. Data and url sources have no disk state to compare against, so they are "ingested" or "stale_scheme".

Hybrid search: semantic similarity plus a keyword boost for exact terms. Returns `results` — ranked chunks with text, source, title, chunkIndex, score and parentId — `sources`, the distinct sources in rank order each with a hits count and a `displayPath` to show the user (`source` stays absolute and is what the other tools take), and `parents`, a map from parentId to section text. Use `sources` to answer "which documents cover this topic" without inspecting individual chunks. `text` is the passage that matched and that `score` describes. `parentId` names the section it sits in — a transcript time window, a heading section, a slide, a table. Look it up in `parents` to read the whole section when the match alone is too small to act on. A chunk indexed before parent sections existed has parentId null and no entry; re-sync to fill it in. topK must be at least 1 and is capped at 100; a larger value is silently clamped to the cap rather than rejected. Cite what you take, so the user can verify it, in whatever language you answer: end with a Sources list, one line per document you actually used, each line just that document's `displayPath` copied verbatim — no [n] markers, nothing else on the line. Plain text, never a markdown link or file://.

Read the chunks immediately before and after a search result, for context. Provide exactly one of filePath (absolute path inside a document root) or source (the id of a data/url item). before/after control how many chunks to include on each side of chunkIndex (both default to 1).

Read a source's entire indexed content as Markdown. The document is reconstructed from its chunks, not concatenated from them: the context each chunk repeats so its own vector carries it — a heading breadcrumb, a time-window label, a table's header row — is emitted once, where the document had it. Provide exactly one of filePath (absolute path inside a document root) or source (the id of a data/url item). The response holds the full document text, so large documents produce large responses — prefer read_chunk_neighbors when only the context around one chunk is needed.

Report configuration and index status. Works even when configuration is invalid. Always includes version. When configuration is valid, also includes roots, dbPath, model, hybridWeight, and chunkCount/sourceCount (both present on every call, 0 before anything is indexed) — or, if opening the index itself fails, indexError instead of the counts. When configuration is invalid, includes configError instead, and every other tool raises an error referencing it until the configuration is fixed. chunkScheme is the chunking scheme the index is being written with. staleChunkCount counts chunks still stored under an older scheme — when it is above zero, schemeWarning explains that those chunks need a re-sync to be rebuilt. ocr names the OCR engine this install can use, or is "unavailable" when the optional extra is missing — scanned PDFs and images cannot be indexed then, and ocrHint says what to install.

Reconcile the index with the document roots (or one path inside them). Returns a jobId immediately; poll sync_status until state is 'succeeded' or 'failed'. New and changed files are ingested, byte-identical files skipped, vanished files removed from the index. Only the latest sync job is retained — starting a new one, or a server restart, discards the previous job's record. Only one sync runs against an index at a time. If one is already in progress — in this server or in another process, such as a `minirag-mcp sync` in a terminal — this call fails immediately with a message identifying it, and no job is started. Single-file ingests and queries are never blocked by a running sync.

Poll a sync job started by sync_start. Returns state ('pending' | 'running' | 'succeeded' | 'failed'), counts (scanned/ingested/skipped/deleted/unreadable/failed), and any per-file errors. Only the latest job is retained — an old jobId, or any jobId from before a server restart, raises an error. unreadable counts indexed sources this installation cannot read because an optional extra is absent (images need [ocr]); each one appears in errors saying it was kept rather than deleted, but it is not a failure and does not make the job fail.