RAG Vault is a local-first MCP/REST server that lets your AI assistant ingest, search, and manage private documents using hybrid semantic + keyword retrieval.
Search documents: Use query_documents for hybrid vector/BM25 search, with exact phrase, metadata, AND/OR, and exclusion syntax; optional score explanations.
Ingest content: Add files via ingest_file (PDF, DOCX, TXT, MD, JSON, JSONL) or raw text/HTML/markdown via ingest_data, with custom metadata.
Manage the knowledge base: List indexed files (list_files), delete files/sources (delete_file), and check status/DB size (status).
Improve search results with feedback: Pin helpful results (feedback_pin) or dismiss unhelpful ones (feedback_dismiss) to tune future ranking, and review feedback stats (feedback_stats).
Run a web UI and REST API: Upload, search, preview, delete, switch databases, monitor status, import/export settings, and access Reader endpoints for chunks and cross-document related chunks.
Connect remotely: Run as an HTTP MCP server (Streamable HTTP/SSE) for Claude Desktop/Claude.ai, with auth, rate limiting, CORS, and security headers.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@RAG Vault search my project notes for deployment steps"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your documents. Your machine. Your control.
RAG Vault lets your AI coding assistant search your private documents, things like API specs, research papers, and internal docs. Everything runs locally and your data stays on your machine unless you choose to pull in content from a remote URL.
One command to run, minimal setup, privacy by default.
Pain Point | RAG Vault Solution |
"I don't want my docs on someone else's server" | Everything stays local by default. No background cloud calls for indexing or search. |
"Semantic search misses exact code terms" | Hybrid search with RRF fusion, optional cross-encoder reranking |
"Setup requires Docker, Python, databases..." | One |
"Cloud APIs charge per query" | Free forever. No subscriptions. |
Related MCP server: nodespace-mcp
RAG Vault comes with security built in:
API Authentication: Optional API key via RAG_API_KEY
Rate Limiting: You can throttle requests
CORS Control: Restrict allowed origins
Security Headers: Helmet.js protection
See SECURITY.md for complete documentation.
Before adding MCP config:
Install Node.js 20 or newer.
Pick a documents directory and set BASE_DIR to that path.
Make sure your AI tool process can read BASE_DIR.
Restart your AI tool after editing config.
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"local-rag": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:RobThePCGuy/rag-vault"],
"env": {
"BASE_DIR": "/path/to/your/documents"
}
}
}
}Replace /path/to/your/documents with your real absolute path.
Add to .mcp.json in your project directory:
{
"mcpServers": {
"local-rag": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:RobThePCGuy/rag-vault"],
"env": {
"BASE_DIR": "./documents",
"DB_PATH": "./documents/.rag-db",
"CACHE_DIR": "./.cache",
"RAG_EMBEDDING_DEVICE": "cpu",
"RAG_HYBRID_WEIGHT": "0.6",
"RAG_GROUPING": "related"
}
}
}
}Or add inline via CLI:
claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y github:RobThePCGuy/rag-vaultAdd to ~/.codex/config.toml:
[mcp_servers.local-rag]
command = "npx"
args = ["-y", "github:RobThePCGuy/rag-vault"]
[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"If you want your AI to write better queries and make more sense of results, install the RAG Vault skills:
# Claude Code (project-level - recommended for team projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code
# Claude Code (user-level - available in all projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code --global
# Codex (user-level)
npx github:RobThePCGuy/rag-vault skills install --codex
# Custom location
npx github:RobThePCGuy/rag-vault skills install --path /your/custom/pathSkills teach Claude best practices for:
Query formulation and expansion strategies
Score interpretation. In boost mode, under 0.3 is a good match and over 0.5 is worth skipping. RRF mode scores by rank instead.
When to use ingest_file vs ingest_data
HTML ingestion and URL handling
Restart your AI tool, and start talking:
You: "Ingest api-spec.pdf"
AI: Successfully ingested api-spec.pdf (47 chunks)
You: "How does authentication work?"
AI: Based on section 3.2, authentication uses OAuth 2.0 with JWT tokens...That's it. No Docker. No Python. No server infrastructure to manage.
RAG Vault has a web UI so you can manage your documents without touching the command line.
npx github:RobThePCGuy/rag-vault webOpen http://localhost:3000 in your browser.
By default the web server binds to
127.0.0.1(loopback), so it is reachable only from this machine. To use it from another device on your network, setRAG_BIND_HOST=0.0.0.0— and setRAG_API_KEYas well, since the API is otherwise unauthenticated.
Upload documents: Drag and drop PDF, DOCX, Markdown, TXT, JSON, JSONL, and NDJSON files
Search instantly: Type queries and see results with relevance scores
Preview content: Click any result to see the full chunk in context
Manage files: View all indexed documents and delete what you don't need
Switch databases: Create and switch between multiple knowledge bases
Monitor status: See document counts, memory usage, and search mode
Export/Import settings: Back up and restore your vault configuration
Theme preferences: Switch between light, dark, or system theme
Folder browser: Navigate directories to select documents
The web server has a REST API you can hit directly. Set RAG_API_KEY to require authentication:
# With authentication (when RAG_API_KEY is set)
curl -X POST "http://localhost:3000/api/v1/search" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"query": "authentication", "limit": 5}'
# Search documents (no auth needed if RAG_API_KEY isn't set)
curl -X POST "http://localhost:3000/api/v1/search" \
-H "Content-Type: application/json" \
-d '{"query": "authentication", "limit": 5}'
# List all files
curl "http://localhost:3000/api/v1/files"
# Upload a document
curl -X POST "http://localhost:3000/api/v1/files/upload" \
-F "file=@spec.pdf"
# Delete a file
curl -X DELETE "http://localhost:3000/api/v1/files" \
-H "Content-Type: application/json" \
-d '{"filePath": "/path/to/spec.pdf"}'
# Get system status
curl "http://localhost:3000/api/v1/status"
# Health check (for load balancers)
curl "http://localhost:3000/api/v1/health"These endpoints let you read documents and find connections across them:
# Get all chunks for a document (ordered by index)
curl "http://localhost:3000/api/v1/documents/chunks?filePath=/path/to/doc.pdf"
# Find related chunks for cross-document discovery
curl "http://localhost:3000/api/v1/chunks/related?filePath=/path/to/doc.pdf&chunkIndex=0&limit=5"
# Batch request for multiple chunks (efficient for UIs)
curl -X POST "http://localhost:3000/api/v1/chunks/batch-related" \
-H "Content-Type: application/json" \
-d '{"chunks": [{"filePath": "/path/to/doc.pdf", "chunkIndex": 0}], "limit": 3}'RAG Vault can also run as an HTTP server so remote MCP clients like Claude.ai, Claude Desktop, or anything that supports Streamable HTTP or SSE can connect to it.
# Start remote server (default port 3001)
npx github:RobThePCGuy/rag-vault --remote
# Custom port
npx github:RobThePCGuy/rag-vault --remote --port 8080Stdio mode is unchanged. Just leave off --remote and everything works as before with Cursor, Claude Code, and Codex.
Add to your Claude Desktop config:
{
"mcpServers": {
"rag-vault-remote": {
"type": "url",
"url": "http://localhost:3001/mcp"
}
}
}Or via Claude Code CLI:
claude mcp add --transport http rag-vault http://localhost:3001/mcpFor Claude.ai (Pro/Max/Team/Enterprise), add as a custom connector with URL https://your-host:3001/mcp. For local development, expose your server with a tunnel:
cloudflared tunnel --url http://localhost:3001The remote server also binds to 127.0.0.1 (loopback) by default. To accept connections from other machines directly, set RAG_BIND_HOST=0.0.0.0. Set RAG_API_KEY for authentication whenever you expose the server beyond loopback (including via a tunnel). The server supports both Streamable HTTP (/mcp) and legacy SSE (/sse) transports, plus a health check at /health.
You: "Ingest all the markdown files in /docs"
AI: Ingested 23 files (847 chunks total)
You: "What's the retry policy for failed API calls?"
AI: According to error-handling.md, failed requests retry 3 times
with exponential backoff: 1s, 2s, 4s...You: "Fetch https://docs.example.com/api and ingest the HTML"
AI: Ingested "docs.example.com/api" (156 chunks)
You: "What rate limits apply to the /users endpoint?"
AI: The API limits /users to 100 requests per minute per API key...You: "Ingest my research papers folder"
AI: Ingested 12 PDFs (2,341 chunks)
You: "What do recent studies say about transformer attention mechanisms?"
AI: Based on attention-mechanisms-2024.pdf, the key finding is...RAG Vault's hybrid search catches both meaning and exact matches:
You: "Search for ERR_CONNECTION_REFUSED"
AI: Found 3 results mentioning ERR_CONNECTION_REFUSED:
1. troubleshooting.md - "When you see ERR_CONNECTION_REFUSED..."
2. network-errors.pdf - "Common causes include..."Pure semantic search would miss this. RAG Vault finds it.
Document → Parse → Chunk by meaning → Embed locally → Store in LanceDB
↓
Query → Embed → Vector search + BM25 → Fusion → Optional reranking → ResultsSmart chunking: Splits by meaning, not character count. Keeps code blocks intact.
Hybrid search: Two fusion modes that combine vector similarity with BM25 keyword matching:
Boost mode (default): BM25 boosts vector search distances multiplicatively. Simple and predictable.
RRF mode (opt-in via RAG_SEARCH_MODE=rrf): Reciprocal Rank Fusion treats vector and BM25 as independent voters. This can surface documents that vector search alone would miss.
Cross-encoder reranking (opt-in): After the first pass, a cross-encoder model (Xenova/ms-marco-MiniLM-L-6-v2, ~23MB) scores each (query, passage) pair together for tighter relevance ranking. Turn it on with RAG_RERANKER_ENABLED=true.
Query expansion (opt-in): Generates reformulated queries to improve recall when searches are paraphrased or conceptual. Two backends: local template-based expansion (default, fully offline) or LLM-based HyDE through an external API. Turn it on with RAG_HYDE_ENABLED=true.
Quality filtering: Groups results by relevance gaps instead of arbitrary top-K cutoffs.
Local by default: Embeddings via Transformers.js. Storage via LanceDB. Network is only needed for initial model download or if you explicitly ingest remote URLs.
MCP tools included: query_documents, ingest_file, ingest_data, delete_file, list_files, status, feedback_pin, feedback_dismiss, and feedback_stats.
Format | Extension | Notes |
| Full text extraction, header/footer filtering | |
Word |
| Tables, lists, formatting preserved |
Markdown |
| Code blocks kept intact |
Text |
| Plain text |
JSON |
| Converted to searchable key-value text |
JSONL / NDJSON |
| Parsed line-by-line for logs and structured records |
HTML | via | Auto-cleaned with Readability |
Variable | Default | What it does |
| Current directory | Only files under this path can be accessed |
|
| Where vectors are stored |
|
| Model cache directory |
|
| HuggingFace embedding model |
|
| Biggest file you can ingest |
|
| Device for running embeddings: |
|
| Port for web interface |
|
| Temporary directory for web UI file uploads |
Windows users:
RAG_EMBEDDING_DEVICE=autotries GPU providers (DirectML), which can fail if ONNX Runtime GPU binaries aren't available. If you see embedding initialization errors, setRAG_EMBEDDING_DEVICE=cpuin your MCP config for reliable operation. See the GPU acceleration FAQ for details.
One-command override (no .env edit):
# MCP mode
npx github:RobThePCGuy/rag-vault --embedding-device cpu
# Web mode
npx github:RobThePCGuy/rag-vault web --embedding-device dml
# Explicitly force auto detection
npx github:RobThePCGuy/rag-vault --gpu-autoVariable | Default | What it does |
|
| Fusion mode: |
|
| Balance between vector and BM25. |
|
| RRF smoothing constant (only applies in |
| unset | Quality filter: |
| unset | Drops results below this relevance threshold (use with |
|
| How many standard deviations between groups counts as a relevance gap |
|
| How many extra vector candidates to grab before keyword reranking |
|
| Full-text search failures before FTS is temporarily disabled |
|
| How long to wait before retrying FTS after hitting the failure limit |
Variable | Default | What it does |
|
| Turn on cross-encoder reranking for better results |
|
| HuggingFace cross-encoder model (~23MB ONNX, downloads on first use) |
|
| Fetch this many extra candidates for the reranker to score |
|
| Device for the reranker (same options as |
|
| Timeout for model download and initialization |
Variable | Default | What it does |
|
| Turn on query expansion for better recall |
|
|
|
|
| Number of expanded queries to generate |
| unset | API key for LLM backend (required when |
|
| API endpoint for LLM backend |
|
| Model for LLM-based expansion |
Privacy note: The
apibackend sends query text to an external LLM endpoint, which breaks the "zero cloud" guarantee. The defaultrule-basedbackend is fully local.
Variable | Default | What it does |
| unset | API key for authentication |
|
| Interface the web/remote servers bind to. Loopback only by default; set to |
| localhost | Allowed origins (comma-separated, or |
|
| Rate limit time window (ms) |
|
| Max requests per window |
Variable | Default | What it does |
| Home directory | Directories allowed for database scanning |
|
| Max request body size |
|
| API request timeout |
|
| Turn on request audit logging |
Copy
.env.examplefor a complete configuration template.
For code-heavy content, try:
"env": {
"RAG_HYBRID_WEIGHT": "0.8",
"RAG_GROUPING": "similar"
}For local files, yes. Indexing and search run on your machine after the embedding model downloads (~90MB). RAG Vault only hits the network if you choose remote URL ingestion or need to download a model.
Yes, after the first run. The model caches locally.
RAG Vault picks a device automatically by default (RAG_EMBEDDING_DEVICE=auto). When GPU providers are set up correctly, this can speed up embedding generation.
Important: On Windows, auto tries DirectML (dml), which requires ONNX Runtime GPU binaries. If those binaries aren't installed or your GPU setup is incomplete, the server won't start at all. It doesn't fall back to CPU gracefully. The same goes for Linux without CUDA binaries.
Recommendation: If you hit embedding initialization errors, set RAG_EMBEDDING_DEVICE=cpu in your MCP config. CPU mode is reliable on all platforms and fast enough for most workloads (the default model is only ~90MB).
"env": {
"RAG_EMBEDDING_DEVICE": "cpu"
}Supported device values: auto, cpu, cuda, dml, gpu, wasm, webgpu, webnn, webnn-npu, webnn-gpu, webnn-cpu. The alias directml is also accepted and maps to dml.
Yes. Set MODEL_NAME to any compatible HuggingFace model. You'll need to delete DB_PATH and re-ingest because different models produce incompatible vectors.
Recommended upgrade: For better quality and multilingual support, use EmbeddingGemma:
"MODEL_NAME": "onnx-community/embeddinggemma-300m-ONNX"It's a solid pick if you need multilingual support or higher-quality retrieval.
Other specialized models:
Scientific: sentence-transformers/allenai-specter
Code: jinaai/jina-embeddings-v2-base-code
Copy the DB_PATH directory (default: ./lancedb/).
Problem | Solution |
No results found | Documents need to be ingested first. Run "List all ingested files" to check. |
Model download failed | Check your internet connection. The model is ~90MB from HuggingFace. |
Embedding initialization fails | Set |
| Corrupted model cache. Delete |
File too large | Default limit is 100MB. Set |
Path outside BASE_DIR | All file paths must be under |
MCP tools not showing | Check your config syntax and restart your AI tool completely (Cmd+Q on Mac). |
| Use token login instead: |
401 Unauthorized | API key required. Set |
429 Too Many Requests | Rate limited. Wait for the reset or increase |
CORS errors | Add your origin to |
git clone https://github.com/RobThePCGuy/rag-vault.git
cd rag-vault
pnpm install
pnpm --prefix web-ui install
# Install local git hooks (recommended, even for solo dev)
pnpm hooks:install
# Fast local quality gate (backend + web-ui type/lint/format, deps, unused, build, unit tests)
pnpm check:all
# Unit tests only (no model download required)
pnpm test:unit
# Integration/E2E tests (requires model download/network)
pnpm test:integration
# Build
pnpm build
# Run MCP server locally (stdio)
pnpm dev
# Run MCP server locally (remote HTTP + SSE)
pnpm dev:remote
# Run web server locally
pnpm web:dev
# Release to npm (local, guarded)
pnpm release # patch
pnpm release:minor
pnpm release:major
pnpm release:drypnpm test:unit: deterministic tests for local/CI quality checks. Doesn't include model-download integration paths.
pnpm test:integration: full integration and E2E workflows, including embedding model initialization.
Use RUN_EMBEDDING_INTEGRATION=1 to explicitly opt into network/model-dependent suites.
Releases are local and scripted via scripts/release-npm.sh.
Supported bumps: patch, minor, major.
The script runs dependency installs, pnpm check:all, and pnpm ui:build before touching version files.
package.json and server.json versions only get updated after checks pass, and they're auto-restored if any later step fails.
pnpm release:dry runs the full gate plus npm dry-run publish and always restores version files.
src/
├── bin/ # CLI subcommands (skills install)
├── chunker/ # Semantic text splitting
├── embedder/ # Transformers.js wrapper
├── errors/ # Error handling utilities
├── explainability/ # Keyword-based result explanations
├── flywheel/ # Feedback loop (pin/dismiss reranking)
├── hyde/ # Query expansion + HyDE (LLM-based)
├── parser/ # PDF, DOCX, HTML parsing
├── query/ # Advanced query syntax parser
├── reranker/ # Cross-encoder reranking (Transformers.js)
├── server/ # MCP tool handlers + remote transport
├── utils/ # Config, file helpers, process handlers
├── vectordb/ # LanceDB + hybrid search (boost + RRF)
└── web/ # Express server + REST API
web-ui/ # React frontend (Vite + Tailwind)SECURITY.md: Security configuration and best practices
.env.example: Complete environment variable template
MIT: free for personal and commercial use.
Built with Model Context Protocol, LanceDB, and Transformers.js.
Started as a fork of mcp-local-rag by Shinsuke Kagawa. Now it's its own thing. Huge credit to upstream contributors for the foundation, I've been iterating hard from there. Local-first dev tools, all the way.
Remove a document from your knowledge base. Use filePath for files you added with ingest_file, or source for content you added with ingest_data. You need to provide one or the other.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | ||
| filePath | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It indicates removal from the knowledge base, implying destructive action, but does not mention irreversibility, error handling (e.g., nonexistent file), or what happens if both parameters are provided. The note about providing one or the other adds some context, but more detail would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences, front-loading the core action. Every word is purposeful, and there is no redundant or extraneous information. It efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema, no annotations), the description covers the primary usage scenario well. It explains how to specify the document to delete. However, it omits details like success/error responses, permission requirements, or side effects, which would enhance completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the schema has zero parameter descriptions, the description compensates by explaining the origin of each parameter (filePath for ingest_file, source for ingest_data) and their mutual exclusivity. This adds meaningful context beyond the parameter names, though it could specify valid formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'document from your knowledge base'. It distinguishes itself from sibling tools like ingest_file and ingest_data (which add content) and list_files (which lists them), leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on which parameter to use based on how the content was added (filePath for ingest_file, source for ingest_data) and states that exactly one is needed. While it does not compare against alternatives, deletion is unique among siblings, so this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a search result as irrelevant for a query. Dismissed results get pushed down in future searches. Use this when a result wasn't helpful.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceQuery | Yes | The query that returned this result | |
| targetFilePath | Yes | File path of the result to dismiss | |
| targetChunkIndex | Yes | Chunk index of the result to dismiss | |
| targetFingerprint | No | Optional fingerprint for resilient matching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the effect (pushed down) but fails to mention important behavioral details such as whether the action is reversible, if it persists across sessions, or if it affects other users.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two sentences that front-load the action and effect, followed by a usage instruction. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the well-described schema, the description provides adequate functional context. However, it lacks mention of return value, error conditions, or undo capability, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all 4 parameters with descriptions (100% coverage). The tool description adds no additional parameter-specific information, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (dismiss) and the object (search result for a query), and explains the effect (pushed down). It distinguishes from sibling tools like feedback_pin by implying this is for irrelevant results, though not explicitly contrasting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a usage guideline: 'Use this when a result wasn't helpful.' However, it does not mention when not to use or compare with alternatives like feedback_pin, leaving room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a search result as relevant for a query. Pinned results get boosted in future searches. Use this when a result was helpful.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceQuery | Yes | The query that returned this result | |
| targetFilePath | Yes | File path of the result to pin | |
| targetChunkIndex | Yes | Chunk index of the result to pin | |
| targetFingerprint | No | Optional fingerprint for resilient matching |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description adds behavioral context by mentioning that pinned results get boosted. It does not disclose reversibility, limits, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action and purpose, with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no output schema, no annotations), the description is adequate but incomplete, missing error conditions or idempotency details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description does not add additional meaning beyond the schema, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it marks a search result as relevant and explains the boosting effect. However, it does not explicitly differentiate from sibling tools like feedback_dismiss.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear when-to-use ('Use this when a result was helpful'), but lacks guidance on when not to use it or alternatives like feedback_dismiss.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See your feedback stats: total events, how many results you've pinned, and how many you've dismissed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It states 'see your feedback stats,' implying a read-only operation, but does not explicitly confirm safety, disclose any side effects, authentication needs, or limitations. The lack of additional behavioral context leaves the agent with minimal guidance beyond the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every part contributes meaning, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description adequately covers what the tool does and the specific metrics it returns. However, it could be more complete by specifying scope (e.g., timeframe, user-specific) or return format, but it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%. Per rubric, '0 params = baseline 4.' The description adds no parameter information, which is acceptable since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides feedback stats including total events, pinned results, and dismissed results. The verb 'see' and the specific metrics make the purpose unambiguous, and it distinguishes itself from sibling action tools like feedback_pin and feedback_dismiss.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when feedback stats are needed, providing clear context. However, it does not explicitly state when not to use it or mention alternatives like query_documents, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add text content directly instead of from a file. Good for: fetched web pages (format: html), copied text (format: text), or markdown strings (format: markdown). The source identifier lets you update the content later by re-ingesting with the same source. You can add custom metadata too. For files on disk, use ingest_file instead.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that re-ingesting with same source updates content, and notes custom metadata. Lacks mention of whether it appends or overwrites, and no info on return value or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with core purpose. Every sentence adds value: purpose, use cases, update behavior, alternative tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completeness is high given no output schema or annotations. Covers input, update semantics, and sibling differentiation. Minor gap: no mention of return type or success indication.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description provides context for parameters: explains purpose of source (update later) and format options (text, html, markdown). Does not detail content parameter beyond 'text content directly' or custom metadata structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb-resource pair: 'Add text content directly.' Distinguishes from sibling tool ingest_file by explicitly saying 'instead of from a file' and listing use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (for fetched web pages, copied text, markdown strings) and when not to use (use ingest_file for files on disk). Also mentions re-ingesting capability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a document (PDF, DOCX, TXT, MD, JSON, JSONL) to your knowledge base so you can search it. Use the full file path. If you ingest the same file again, it replaces the old version. You can tag it with metadata like author, domain, or tags.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | ||
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses that re-ingesting the same file replaces the old version and mentions metadata tagging. It does not cover synchronous/asynchronous behavior, permission requirements, or side effects on existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loads the action, and provides key details without unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description covers operation, file types, duplicate behavior, and metadata. It lacks return value or error information, but is adequate for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning: filePath should be a full path, and metadata allows tagging with keys like author, domain. However, it could be more specific, e.g., accepted metadata key names or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool adds a document to a knowledge base for searching, and lists supported file types. It implicitly differentiates from siblings like query_documents by mentioning search capability, but does not explicitly contrast with other tools like ingest_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to add a document) and notes behavior on re-ingestion. However, it does not provide guidance on when not to use it or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show all documents in your knowledge base, with file paths and how many chunks each one has.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses output (file paths, chunk counts) but omits potential issues like pagination or large KB performance. Adequate for simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, directly communicates purpose and output. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and no output schema, the description fully covers what the tool does and returns. No missing context for a list-all operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% (vacuous). Description adds no param info as none needed. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Show all documents in your knowledge base' with specific details on returned info (file paths, chunk counts). Distinct from siblings like query_documents and ingest_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives. Purpose is self-explanatory but lacks guidance on when not to use or comparison to query_documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search your documents using both meaning and exact keyword matching. You can also use advanced syntax:
"exact phrase" → Match phrase exactly
field:value → Filter by custom metadata (e.g., domain:legal, author:john)
term1 AND term2 → Both terms required (default)
term1 OR term2 → Either term matches
-term → Exclude results containing term Results include a score (0 = best match, higher = less relevant). Set explain=true to see why each result matched.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| explain | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses query semantics, scoring (0=best match), and explain behavior. Since no annotations exist, the description carries full burden and does so adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Effective front-loading: first sentence states purpose, then syntax details. Slightly verbose but remains clear. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers query syntax, scoring, and explain. Missing output schema but explains result score. Adequate for a search tool with 3 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining the query parameter's syntax in detail and the explain parameter. limit is self-explanatory, but not detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search your documents using both meaning and exact keyword matching.' This distinguishes it from sibling tools like ingest_file, delete_file, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed usage guidelines including advanced query syntax and parameter effects. No explicit when-to-use vs alternatives, but the search purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check how many documents and chunks you have, the database size, and current settings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states what information the tool retrieves (counts, size, settings) but does not disclose behavioral traits like whether it is read-only or requires authentication. Since no annotations are provided, the description should cover these aspects more thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose without any unnecessary words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and low complexity, the description provides sufficient information for an agent to understand what the tool returns. It is complete for its intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the input schema covers 100% of the (empty) set. The description does not need to add parameter details, making a baseline score of 4 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies what the tool does: check counts of documents and chunks, database size, and current settings. This distinguishes it from sibling tools that perform data operations like querying documents or ingesting files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for checking system status rather than manipulating data, but it does not explicitly state when to use it or when to avoid it. The context from sibling tools helps, but explicit guidance would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.9.2delete_filefeedback_dismissfeedback_pinfeedback_statsingest_dataingest_filelist_filesquery_documentsstatusEach tool has a distinct purpose: querying, ingesting (file vs. data), deleting, listing, status, and feedback actions. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (e.g., query_documents, ingest_file, delete_file) using lowercase and underscores, making them predictable.
9 tools cover document ingestion, deletion, query, listing, status, and feedback—well-scoped for a RAG server without being too many or too few.
Core CRUD and search are present, with feedback for iterative improvement. Slightly missing direct document content retrieval, but re-ingestion allows updates. Minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A personal RAG database you build from chat, so AI creates work that sounds like you.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Versioned documentation registry and semantic search for AI tools and coding assistants.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RobThePCGuy/rag-vault'
If you have feedback or need assistance with the MCP directory API, please join our Discord server