How lyonzin/knowledge-rag works
knowledge-rag is a local MCP server that indexes documents and code, then returns ranked, source-attributed results to an MCP client. The main workflow is client request → server dispatch → document ingestion (parse, chunk, embed, index) and hybrid retrieval (lexical and vector candidates, fusion, reranking) → results. The README documents these stages and optional FTS5 routing; sampled source confirms key parsing, routing, scope, storage, and security responsibilities. Some retrieval details are documented but not visible in the excerpts, so those links are marked as documented rather than inferred from unsampled code.
Main entry points: server.py MCP server · ingestion.py Document parsing · skills_cli.py Skills CLI · filesystem.py Document filesystem
Components 23
MCP runtime
- MCP server
mcp_server/server.py - Configuration
mcp_server/config.py - Health checks
mcp_server/health.py - Metrics
mcp_server/metrics.py
Ingestion and indexing
- Document parsing
mcp_server/ingestion.py - PDF extraction
mcp_server/pdf_support.py - Document filesystem
mcp_server/filesystem.py - Vector indexing
mcp_server/server.py
Retrieval
- BM25 retrieval
mcp_server/server.py - FTS5 index
mcp_server/fts5_index.py - Query router
mcp_server/query_router.py - Search scope
mcp_server/search_scope.py - Candidate selection
mcp_server/search_candidates.py - Cross-encoder reranker
mcp_server/server.py
Operations and safety
- Path and content safety
mcp_server/security.py - File transactions
mcp_server/file_transaction.py - Startup preflight
mcp_server/preflight.py - Instance lock
mcp_server/instance_lock.py - Logging setup
mcp_server/logging_config.py
Assistant skills
- Assistant detection
mcp_server/assistants.py - Skills CLI
mcp_server/skills_cli.py - Skills bundle
mcp_server/skills_bundle.py
Other components
- MCP client
Connections 28
- MCP client → MCP server: sends requests
README.md - MCP server → MCP client: returns results
README.md - MCP server → Configuration: loads settings
mcp_server/server.py - MCP server → Document parsing: indexes documents
mcp_server/server.py - MCP server → Vector indexing: stores embeddings
README.md - MCP server → BM25 retrieval: runs keyword search
README.md - MCP server → Query router: classifies queries
mcp_server/query_router.py - MCP server → FTS5 index: dispatches lexical search
mcp_server/server.py - MCP server → Search scope: filters sources
mcp_server/server.py - MCP server → Candidate selection: selects candidates
mcp_server/server.py - MCP server → Cross-encoder reranker: reranks candidates
README.md - MCP server → Health checks: serves health
mcp_server/server.py - MCP server → Metrics: records metrics
mcp_server/server.py - MCP server → Document filesystem: watches documents
mcp_server/server.py - MCP server → Path and content safety: validates paths
mcp_server/server.py - MCP server → File transactions: stages file changes
mcp_server/server.py - MCP server → Startup preflight: runs preflight
mcp_server/server.py - MCP server → Instance lock: acquires lock
mcp_server/server.py - MCP server → Logging setup: configures logging
mcp_server/server.py - Document parsing → PDF extraction: extracts PDF text
mcp_server/ingestion.py - Document parsing → Document filesystem: walks document paths
mcp_server/ingestion.py - Document parsing → Path and content safety: checks input paths
mcp_server/ingestion.py - Search scope → Document filesystem: normalizes paths
mcp_server/search_scope.py - Query router → FTS5 index: selects lexical path
- MCP server → Assistant detection: invokes skills CLI
mcp_server/server.py - Skills CLI → Assistant detection: detects targets
mcp_server/skills_cli.py - Skills CLI → Skills bundle: loads bundled skills
mcp_server/skills_cli.py - Skills CLI → File transactions: updates skill files