Labsco
MCP SERVER

MCP Lucene Server

by mirkosertic ↗

Index your own PDFs and Office documents into Lucene, then search them by keyword, query syntax, or meaning.

NoSQL, Graph & Key-Value Stores
Summary
A big tool surface with a switch to make it small.

LUCENE_TOOLS_INCLUDE and LUCENE_TOOLS_EXCLUDE take group names — search, semantic, debug, info, observability, crawler, admin — so a small model can be given just the two search tools, and exclude always wins over include. If you want everything except the destructive maintenance, set LUCENE_TOOLS_EXCLUDE to purgeIndex,unlockIndex.

What it is

A Lucene full-text server with a document crawler attached. It walks the directories you nominate, extracts text and metadata from PDFs, Microsoft Office and OpenOffice files, and keeps the index current — incrementally, skipping unchanged files and removing orphans.

What you get
  • `simpleSearch` takes plain text with no Lucene syntax and treats special characters as literals; `extendedSearch` accepts the full query language with booleans, wildcards and proximity
  • `semanticSearch` finds related documents with no shared keywords, and `profileSemanticSearch` shows the cosine scores and matched chunks so you can tune the threshold
  • `profileQuery` explains a result set: which terms carried the score, how each filter cut the candidate pool, and where the query can be improved
  • Crawler control from the chat: `startCrawl`, `pauseCrawler`, `resumeCrawler`, `getCrawlerStats`, `getCrawlerStatus`, and `listCrawlableDirectories`, `addCrawlableDirectory`, `removeCrawlableDirectory` to change what is indexed at runtime
  • `getIndexStats`, `listIndexedFields` and `getDocumentDetails` — the last reads a document straight out of the index even if the original file has moved
  • `suggestTerms` and `getTopTerms` expose the actual vocabulary of your corpus, which is how you find the author or file-type value to filter on
  • Maintenance tools `optimizeIndex`, `purgeIndex`, `unlockIndex`, `getIndexAdminStatus`, and `indexAdmin`, which renders a small UI inline in the client
Requirements

Java 25 or later. Run the built JAR over stdio with `-Dspring.profiles.active=deployed`, which is what keeps console logging out of the protocol stream. The Docker image mirkosertic42/mcpluceneserver:main is HTTP-only and listens on port 9000. Semantic search needs VECTOR_MODEL set to e5-base or e5-large, and JAVA_OPTS raised from its default of -Xmx2g. Crawl configuration persists to ~/.mcplucene/config.yaml.

Setup effort

One command — docker run -v ./lucene-data-dir:/userdata -p 9000:9000 -it mirkosertic42/mcpluceneserver:main