本地目录中文档的 RAG（检索增强生成）
这是一个基于 TypeScript 的 MCP 服务器，它为存储在本地目录中的文档实现了 RAG 系统。它允许用户使用 LLM 查询本地存储库和文本文件中的文档。
通过docs:// URI 列出并访问文档
文档可以是 Git 存储库或文本文件
用于内容访问的纯文本 MIME 类型
list_documents - 列出 DOCS_PATH 目录中所有可用的文档
返回所有文档的格式化列表
显示可用文档总数
rag_query - 使用 RAG 查询文档
以 document_id 和 query 作为参数
返回 AI 生成的包含文档上下文的响应
add_git_repository - 使用可选的稀疏检出将 Git 存储库克隆到 docs 目录
以 repository_url 作为参数
可选的 document_name 参数用于自定义文档的名称（使用不带“-docs”后缀的简单描述性名称）
用于稀疏检出特定目录的可选子目录参数
如果存储库已存在，则自动提取最新更改
add_text_file - 下载文本文件到文档目录
以 file_url 作为参数
使用 wget 下载文件
guide_documents_usage - 有关如何使用文档和 RAG 功能的指南
包括可用文件列表
提供 RAG 功能的使用提示
Related MCP server: MCP-Typescribe
安装依赖项：
npm install构建服务器：
npm run build对于使用自动重建的开发：
npm run watch此服务器需要一个本地目录来存储文档。默认情况下，它使用~/docs ，但您可以使用DOCS_PATH环境变量配置其他位置。
文档目录可以包含：
Git 存储库（克隆目录）
纯文本文件（扩展名为 .txt）
每个文档都使用带有 Google Gemini 嵌入的 llama-index.ts 单独进行索引。
此服务器使用 Google 的 Gemini API 进行文档索引和查询。您需要将 Gemini API 密钥设置为环境变量：
export GEMINI_API_KEY=your-api-key-here您可以从Google AI Studio网站获取 Gemini API 密钥。将此密钥添加到您的 Shell 配置文件中，或将其包含在 Claude Desktop 的环境配置中。
要与 Claude Desktop 一起使用，请添加服务器配置：
在 MacOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json在 Windows 上： %APPDATA%/Claude/claude_desktop_config.json在 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"
}
}
}
}确保将/Users/username/docs替换为文档目录的实际路径。
由于 MCP 服务器通过 stdio 进行通信，调试起来可能比较困难。我们推荐使用MCP Inspector ，它以包脚本的形式提供：
npm run inspector检查器将提供一个 URL 来访问浏览器中的调试工具。
配置完成后，您可以使用 Claude 服务器来执行以下操作：
添加文件：
Add a new document from GitHub: https://github.com/username/repository或使用自定义文档名称：
Add GitHub repository https://github.com/username/repository-name and name it 'framework'或者对特定目录进行稀疏检出：
Add only the 'src/components' directory from https://github.com/username/repository或者结合自定义名称和稀疏结帐：
Add the 'examples/demo' directory from https://github.com/username/large-repo and name it 'demo-app'或添加文本文件：
Add this text file: https://example.com/document.txt查询文件：
What does the documentation say about X in the Y repository?列出可用文件：
What documents do you have access to?服务器将自动处理文档索引以实现高效检索。
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
