RAG (Recuperación-Generación Aumentada) para documentos en un directorio local
Este es un servidor MCP basado en TypeScript que implementa un sistema RAG para documentos almacenados en un directorio local. Permite a los usuarios consultar documentos mediante LLM con contexto de repositorios y archivos de texto almacenados localmente.
Listar y acceder a documentos mediante URI docs://
Los documentos pueden ser repositorios de Git o archivos de texto.
Tipo MIME de texto simple para acceso al contenido
list_documents - Lista todos los documentos disponibles en el directorio DOCS_PATH
Devuelve una lista formateada de todos los documentos
Muestra el número total de documentos disponibles
rag_query - Consultar documentos usando RAG
Toma document_id y consulta como parámetros
Devuelve respuestas generadas por IA con contexto de los documentos.
add_git_repository - Clona un repositorio Git en el directorio de documentos con extracción dispersa opcional
Toma repository_url como parámetro
Parámetro opcional document_name para personalizar el nombre del documento (use nombres descriptivos simples sin el sufijo '-docs')
Parámetro de subdirectorio opcional para la extracción dispersa de directorios específicos
Extrae automáticamente los últimos cambios si el repositorio ya existe
add_text_file - Descargar un archivo de texto al directorio de documentos
Toma file_url como parámetro
Utiliza wget para descargar archivos
guide_documents_usage - Guía sobre cómo usar documentos y la funcionalidad de RAG
Incluye lista de documentos disponibles
Proporciona sugerencias de uso para la funcionalidad RAG
Related MCP server: MCP-Typescribe
Instalar dependencias:
npm installConstruir el servidor:
npm run buildPara desarrollo con reconstrucción automática:
npm run watchEste servidor requiere un directorio local para almacenar documentos. Por defecto, usa ~/docs , pero puede configurar una ubicación diferente con la variable de entorno DOCS_PATH .
El directorio de documentos puede contener:
Repositorios Git (directorios clonados)
Archivos de texto sin formato (con extensión .txt)
Cada documento se indexa por separado utilizando llama-index.ts con incrustaciones Gemini de Google.
Este servidor utiliza la API de Gemini de Google para la indexación y consulta de documentos. Debe configurar su clave de API de Gemini como variable de entorno:
export GEMINI_API_KEY=your-api-key-herePuedes obtener una clave API de Gemini en el sitio web de Google AI Studio . Agrega esta clave a tu perfil de shell o inclúyela en la configuración del entorno de Claude Desktop.
Para utilizar con Claude Desktop, agregue la configuración del servidor:
En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json En Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"docs-rag": {
"command": "npx",
"args": ["-y", "@kazuph/mcp-docs-rag"],
"env": {
"DOCS_PATH": "/Users/username/docs",
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}Asegúrese de reemplazar /Users/username/docs con la ruta real a su directorio de documentos.
Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser complicada. Recomendamos usar el Inspector MCP , disponible como script de paquete:
npm run inspectorEl Inspector proporcionará una URL para acceder a las herramientas de depuración en su navegador.
Una vez configurado, puedes usar el servidor con Claude para:
Añadir documentos :
Add a new document from GitHub: https://github.com/username/repositoryo con un nombre de documento personalizado:
Add GitHub repository https://github.com/username/repository-name and name it 'framework'o con extracción dispersa de un directorio específico:
Add only the 'src/components' directory from https://github.com/username/repositoryo combinar nombre personalizado y pago disperso:
Add the 'examples/demo' directory from https://github.com/username/large-repo and name it 'demo-app'o agregar un archivo de texto:
Add this text file: https://example.com/document.txtConsulta de documentos :
What does the documentation say about X in the Y repository?Lista de documentos disponibles :
What documents do you have access to?El servidor gestionará automáticamente la indexación de los documentos para una recuperación eficiente.
Add a git repository to the docs directory with optional sparse checkout. Please do not use 'docs' in the document name.
| Name | Required | Description | Default |
|---|---|---|---|
| document_name | No | Optional: Custom name for the document (defaults to repository name). Use a simple, descriptive name without '-docs' suffix. For example, use 'react' instead of 'react-docs'. | |
| repository_url | Yes | URL of the git repository to clone | |
| subdirectory | No | Optional: Specific subdirectory to sparse checkout (e.g. 'path/to/specific/dir'). This uses Git's sparse-checkout feature to only download the specified directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool adds a repository and supports sparse checkout, but does not describe key behaviors such as what happens if the repository already exists, whether it requires authentication, if there are rate limits, or what the output looks like. For a mutation tool with zero annotation coverage, this is a significant gap in 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 concise and front-loaded, consisting of two sentences that directly state the tool's purpose and a key instruction. There is no wasted language, and every sentence serves a clear purpose in guiding usage.
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 complexity (adding a git repository with sparse checkout), lack of annotations, and no output schema, the description is incomplete. It fails to address important contextual aspects such as error handling, success criteria, or what the agent should expect after invocation, leaving gaps for effective tool 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 description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema by implying the tool's purpose relates to these parameters, but does not provide additional syntax, format details, or usage examples that aren't already covered in the schema descriptions.
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: 'Add a git repository to the docs directory with optional sparse checkout.' It specifies the verb ('add'), resource ('git repository'), and destination ('docs directory'), but does not explicitly differentiate it from sibling tools like 'add_text_file' or 'list_documents' beyond the type of resource being added.
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 some implied usage guidance by mentioning 'optional sparse checkout' and a specific instruction: 'Please do not use 'docs' in the document name.' However, it does not explicitly state when to use this tool versus alternatives like 'add_text_file' for non-git content or 'rag_query' for querying documents, nor does it outline prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a text file to the docs directory with a specified name. Please do not use 'docs' in the document name.
| Name | Required | Description | Default |
|---|---|---|---|
| document_name | Yes | Name of the document (will be used as directory name). Choose a descriptive name rather than using the URL filename (e.g. 'hono' instead of 'llms-full.txt') | |
| file_url | Yes | URL of the text file to download |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool adds a file and downloads from a URL, but doesn't disclose behavioral traits like error handling (e.g., invalid URLs, duplicate names), permissions needed, or side effects (e.g., overwriting existing files). The constraint about 'docs' is helpful but insufficient for a mutation 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?
The description is brief and front-loaded with the core action, followed by a specific constraint. Both sentences are relevant, with no wasted words, though it could be slightly more structured (e.g., separating action from constraints).
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 no annotations, no output schema, and a mutation tool with two parameters, the description is incomplete. It lacks details on return values, error conditions, or operational context (e.g., how files are stored, success indicators), leaving gaps for an agent to invoke it correctly.
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 description coverage is 100%, so the schema already documents both parameters fully. The description adds no additional meaning beyond the schema's details for 'document_name' and 'file_url', such as format examples or usage tips, meeting the baseline for high coverage.
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 ('Add a text file') and target location ('to the docs directory'), with a specific naming constraint. It distinguishes from sibling tools like 'add_git_repository' (different resource) and 'list_documents'/'rag_query' (different actions), though it doesn't explicitly contrast them.
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 a constraint ('do not use 'docs' in the document name') but offers no guidance on when to use this tool versus alternatives like 'add_git_repository' for repositories or 'list_documents' for viewing. It lacks context on prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available documents in the DOCS_PATH directory. Always use this tool first to check if desired documents already exist before adding new ones.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a read operation ('List') and suggests it's a preliminary check tool, but doesn't specify behavioral traits like whether it requires authentication, has rate limits, or what format the output takes. It adds some context but lacks comprehensive behavioral details.
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 perfectly concise with two sentences that each serve a distinct purpose: the first states what the tool does, the second provides usage guidance. There's zero wasted language and it's front-loaded with the core functionality.
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 simple list tool with no parameters and no output schema, the description provides good context about the tool's purpose and when to use it. However, without annotations or output schema, it could benefit from more information about what the output looks like (e.g., format, structure) to be fully complete for agent 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 0 parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't add parameter information beyond what's in the schema, maintaining a clean baseline. No compensation is needed for missing parameter documentation.
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 specific action ('List all available documents') and resource ('in the DOCS_PATH directory'), distinguishing it from sibling tools like add_git_repository or add_text_file which perform different operations. It explicitly identifies what the tool does without being vague or tautological.
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 when to use this tool ('Always use this tool first to check if desired documents already exist before adding new ones'), including a clear alternative scenario (using add_git_repository or add_text_file for adding documents). This gives strong context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query a document using RAG. Note: If the index does not exist, it will be created when you query, which may take some time.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ID of the document to query | |
| query | Yes | Query to run against the document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It helpfully reveals that 'If the index does not exist, it will be created when you query, which may take some time' - this is valuable behavioral context about performance implications and automatic index creation that isn't obvious from the tool name or schema alone.
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 appropriately concise with two sentences. The first states the core purpose, the second provides important behavioral context. Both sentences earn their place, though the structure could be slightly improved by front-loading the behavioral note more clearly.
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 query tool with 2 parameters and no output schema, the description provides adequate context about the core operation and an important behavioral note. However, it doesn't describe what the query returns (format, content), error conditions, or authentication requirements, leaving some gaps in completeness.
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 description coverage is 100%, so the schema already fully documents both parameters (document_id and query). The description doesn't add any additional parameter semantics beyond what the schema provides, such as query format examples or document_id constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
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 as 'Query a document using RAG' (verb+resource). It distinguishes from siblings like 'add_git_repository' and 'add_text_file' by focusing on querying rather than adding content. However, it doesn't explicitly differentiate from 'list_documents' in terms of querying vs listing.
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 some usage context with the note about index creation, implying this tool should be used for querying documents with RAG. However, it doesn't explicitly state when to use this vs alternatives like 'list_documents' or provide clear when-not-to-use guidance beyond the performance implication mentioned.
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.
v1.0.0add_git_repositoryadd_text_filelist_documentsrag_queryScored across 4 tools
Each tool has a clearly distinct purpose: add_git_repository and add_text_file handle different source types for adding documents, list_documents provides discovery, and rag_query enables retrieval. There is no overlap in functionality, making tool selection unambiguous.
All tools follow a consistent verb_noun pattern with snake_case: add_git_repository, add_text_file, list_documents, rag_query. The naming is predictable and readable throughout the set.
Four tools is reasonable for a RAG server focused on document management and querying, though it feels slightly minimal. The count supports core workflows without being overwhelming, but could potentially benefit from additional utilities like document deletion or index management.
The toolset covers adding documents (via git or text), listing, and querying, but lacks update or delete operations for document management. This creates a gap where agents cannot modify or remove documents, which may lead to dead ends in workflows requiring document lifecycle management.
An MCP server that gives your AI access to the source code and docs of all public github repos
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
MCP server for querying Forkast documentation
