knowledge-rag
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_knowledgeA | Hybrid search combining semantic search + BM25 keyword search with cross-encoder reranking. Read-only. No side effects. Args:
query: Search query text (1–3 keywords recommended; phrase queries also work)
max_results: Maximum number of results (default: 5, capped by search.max_results).
category: Optional category filter. Accepts the categories the server is configured with
(category_mappings values and keyword_routes keys) plus general; an empty string, like
omitting it, searches every category, and any other value returns an error that lists
the valid ones. Call list_categories() first to see which categories hold documents and
how many.
hybrid_alpha: Balance between semantic and keyword search. 0.0 = keyword-only (best for exact
technical terms like CVE IDs or tool names), 0.3 = balanced default, 1.0 = semantic-only
(best for conceptual or natural-language queries).
min_score: Minimum score (0.0–1.0) a result needs to be returned; default 0.0 returns all
results. Scores are min-max normalized per query over its candidates: the best scores 1.0
and the weakest 0.0, while a single candidate or candidates that all tie score 1.0. On the
hybrid path (results labeled hybrid, semantic or keyword) the candidates are the returned
results, so any min_score above 0 drops at least the weakest one unless all tie; fts5
results are BM25 scores normalized over up to max(3 * max_results, 20) hits, so even the
weakest returned one can score well above 0.0. It is not an absolute relevance bar.
snippet_mode: When true (default), truncates content to ~500 characters from the start of the
matching chunk, at a natural break point, and adds a content_length field with the full
size. Use get_document() to fetch full content when needed. Set to false to return the full
content, which can include adjacent chunks; match_offset, when present, is where the match starts.
search_method: Dispatch selector (v4.8.2+). One of Returns: JSON string with results including content chunks, source filepath, relevance score, and search method used. Returns chunks, not full document content. Usage: Primary search tool — use for any topic or keyword lookup. Prefer search_similar() when you already have a reference document and want more like it. Prefer get_document() when you already know the exact filepath and need the full content. |
| get_documentA | Get the full content of a specific document by filepath. Read-only. No side effects. Args: filepath: Relative path to the document within the documents directory (e.g., "security/technique.md"). Must be an indexed file — use search_knowledge() to find the filepath by topic first, or browse list_documents(), which returns one page at a time (see its offset). Returns: JSON string with full document content and metadata (filepath, category, size). Usage: Use when you need the complete text of a known file — search_knowledge() returns chunks, not full docs. Use search_knowledge() first to find the filepath if unknown. Use list_documents() to browse files by category, one page at a time. |
| reindex_documentsA | Index or reindex all documents in the knowledge base (runs in background). No flags — incremental pass: index new or changed files, skip unchanged
ones, prune deleted sources. Use after filesystem edits outside
add_document/update_document.
Returns a JSON envelope. Poll |
| get_reindex_statusA | Get the current status of a background reindex operation. Lightweight — does not compute full index statistics. Use this to poll progress after calling reindex_documents(). Returns: JSON string with reindex status. When active: operation name, progress (processed/total), percent complete, indexed/skipped/errors counts, and start time. When inactive: active=false, plus last_result or last_error from the most recent completed reindex. When the last run had errors, last_result includes failed_files (deduped [{"path", "reason"}, ...], capped at 100) and failed_files_truncated, so you can see exactly which files failed and why. A failed full_rebuild surfaces in last_error, whose message lists the first failing paths, and the partial last_result still carries the failed_files list. Usage: Call repeatedly after reindex_documents() to monitor progress. When reindex.active becomes false, the operation is complete. Use get_index_stats() for full index health metrics. |
| list_categoriesA | List all document categories with their document counts. Read-only. No side effects. Reflects the live index state. Returns: JSON string with category names, document counts per category, and total document count. Usage: Use before filtering search_knowledge() or list_documents() by category to see which categories exist and how many documents each contains; search_knowledge() still rejects a listed name that is not configured, such as one stored by add_document(). Use get_index_stats() instead for broader system health metrics (model name, cache hit rate, BM25 status). |
| list_documentsA | List indexed documents one page at a time, optionally filtered by category. Read-only. No side effects. Args: category: Optional category filter, matched exactly against each document's category; an empty string, like omitting it, lists every document, and a category without documents returns an empty page (total 0). Call list_categories() to see the categories that hold documents. limit: Maximum number of documents to return (default: 100, max: 200). offset: Number of matching documents to skip (default: 0). For the next page, call again with offset + count until offset reaches total. Returns: JSON string with total (documents matching the filter), offset, limit, count (documents in this page) and the filepaths, categories, and metadata of this page, ordered by filepath. Usage: Use to browse what's in the index, one page at a time; to see every document, call again with offset + count until offset reaches total. Use list_categories() first to see which categories hold documents. Use search_knowledge() when you want to find documents by topic rather than browsing the full list. Use get_document() to read a specific file once you have its filepath. |
| get_index_statsA | Get statistics and health metrics for the knowledge base index. Read-only. No side effects. Returns: JSON string with system metrics: total documents, total chunks, embedding model name, BM25 status, query cache hit rate, file watcher status, a self_recall probe (fraction of sampled chunks returned as top-1 by their own stored vector; a value below 1.0 means the HNSW index misses some chunks — see search.ef_search in config.example.yaml), and hnsw_ef_search (the value ChromaDB actually applies to the live collection; it can lag behind search.ef_search until a full rebuild). Usage: Use for system health checks — inspecting embedding runtime status, checking index population, or monitoring cache efficiency. This does not load the embedding model or initialize BM25. Use list_categories() for per-category document counts instead. Use evaluate_retrieval() to measure actual search quality with test queries. |
| add_documentA | Add a new document to the knowledge base from raw text content. Mutating — writes a file to disk and indexes it immediately. No auth required. Args: content: Full text content of the document (markdown supported) filepath: Relative path within documents directory (e.g., "security/new-technique.md"). The subdirectory should match the category. category: Category stored with the document (default: general). Any name is accepted, but search_knowledge() filters only by configured categories (category_mappings values, keyword_routes keys, general), and update_document() or re-indexing the file detects it again from the path through category_mappings. list_categories() shows the categories in use. Returns: JSON string with indexing results (filepath, chunks created, status). Usage: Use to add new documents from text content. Use add_from_url() instead when the source is a web page. Use update_document() to replace content of an existing file. The document is immediately searchable after this call — no manual reindex needed. |
| update_documentA | Update the content of an existing document in the knowledge base. Mutating — overwrites the file on disk and re-indexes immediately. Old chunks are removed and replaced with new ones. Full content replacement, not a patch. The category is detected again from the path through category_mappings (general when none matches), so a category stored by add_document() or add_from_url() is not kept. Args: filepath: Full or relative path to the document file. Must be an already-indexed file — list_documents() lists indexed paths, one page at a time. content: New full-text content to replace the existing content entirely Returns: JSON string with update results (old chunk count, new chunk count, status). Usage: Use to replace a document's content completely. Use add_document() to create a new file instead. Use remove_document() to delete without replacing. Changes are immediately searchable — no manual reindex needed. |
| remove_documentA | Remove a document from the knowledge base index. Mutating — removes index entries. If delete_file=True, also permanently deletes the file from disk (irreversible, cannot be undone). Args: filepath: Path to the document file. Must be an indexed document — list_documents() lists indexed paths, one page at a time. delete_file: If True, permanently deletes the file from disk in addition to removing from the index (default: False). Returns: JSON string with removal results (filepath, status). Usage: Use to unindex a document while keeping the file on disk (default). Set delete_file=True only for permanent removal. Use update_document() to replace content instead of removing. Use reindex_documents(force=True) if you deleted the file manually on disk outside of this tool. |
| add_from_urlA | Fetch content from a URL, convert to markdown, and add to the knowledge base. Mutating — makes an outbound HTTP request (requires internet access), strips HTML, converts to markdown, saves to disk, and indexes immediately. Args: url: Full URL to fetch (https:// required). The page must be publicly accessible. category: Category stored with the document and the folder it is saved in; default: general. Being part of the path, it must stay inside documents_dir: a value such as ../outside returns a "Filepath rejected" error. Any other name is accepted, but search_knowledge() filters only by configured categories (category_mappings values, keyword_routes keys, general), and update_document() or re-indexing the file detects it again from the path through category_mappings. list_categories() shows the categories in use. title: Optional document title. Auto-detected from the page's tag if omitted. Returns: JSON string with indexing results (filepath, category, chunks added, status). The page is saved as /.md, or as -<first 8 hex characters of the URL's SHA-256>.md (then 16, then the full digest) when a file not saved from this URL already has the shorter name. Use the returned filepath instead of building the path. Usage: Use to ingest web content (writeups, blog posts, documentation pages) directly by URL. Use add_document() instead when you already have the text content. The document is immediately searchable after this call — no manual reindex needed. |
| search_similarA | Find documents semantically similar to a given reference document. Read-only. No side effects. Uses the document's embedding for similarity comparison. Args: filepath: Path to the reference document (must already be indexed — list_documents() lists indexed paths, one page at a time). E.g., "security/technique.md" max_results: Number of similar documents to return (default: 5, max: 20) Returns: JSON string with list of similar document filepaths and similarity scores (0.0–1.0). Usage: Use when you have a specific document and want to discover thematically related ones. Use search_knowledge() instead when you have a text query rather than a reference document. The reference document must be indexed; list_documents() lists indexed paths one page at a time. |
| evaluate_retrievalA | Evaluate search quality by testing whether search_knowledge() retrieves expected documents. Read-only. Runs multiple search queries internally. No side effects on the index. Args: test_cases: JSON string array of test cases. Each item requires "query" (search string) and "expected_filepath" (path of the document that should appear in top-5 results). Example: [{"query": "suid exploit", "expected_filepath": "security/suid.md"}] Returns: JSON string with MRR@5 (Mean Reciprocal Rank), Recall@5, and per-query hit/miss breakdown. MRR@5 above 0.7 indicates good retrieval quality. Usage: Use to audit search quality after bulk document ingestion, a model change or a reindex. Each case runs as one top-5 search with the defaults of search_knowledge() (hybrid_alpha 0.3, search_method auto, no category or folder filter), so the figures describe what a client gets when it passes no options; this tool takes no search options. Use get_index_stats() for system health checks instead. Use search_knowledge() for actual document retrieval — this tool is for quality measurement only. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose, and the descriptions actively cross-reference siblings to prevent misselection (e.g., evaluate_retrieval vs search_knowledge vs get_index_stats, search_similar vs search_knowledge vs get_document). The read/ingest/maintenance split is unambiguous: search, retrieve, list, add, update, remove, reindex, status, stats, categories, evaluation.
Every tool follows a consistent snake_case verb_noun pattern: search_knowledge, get_document, add_document, update_document, remove_document, add_from_url, list_categories, list_documents, get_index_stats, get_reindex_status, evaluate_retrieval, search_similar. No mixed conventions or vague single-word names.
13 tools is well within the 3-15 sweet spot for a RAG knowledge-base server. Each tool covers a distinct operation (search, similar, fetch, list, add text, add URL, update, remove, reindex, status, stats, categories, evaluation) with no filler.
Full lifecycle coverage: ingest (add_document, add_from_url), read (get_document), browse (list_documents, list_categories), mutate (update_document, remove_document), discover (search_knowledge, search_similar), and operational tooling (reindex_documents with recovery modes, get_reindex_status, get_index_stats, evaluate_retrieval). No obvious dead ends for the stated domain.