로컬 디렉토리의 문서에 대한 RAG(검색 증강 생성)
로컬 디렉터리에 저장된 문서에 대한 RAG 시스템을 구현하는 TypeScript 기반 MCP 서버입니다. 사용자가 로컬 저장소 및 텍스트 파일의 컨텍스트를 포함하는 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 - docs 디렉토리에 텍스트 파일을 다운로드합니다.
file_url을 매개변수로 사용합니다.
wget을 사용하여 파일을 다운로드합니다.
guide_documents_usage - 문서 및 RAG 기능 사용 방법에 대한 가이드
사용 가능한 문서 목록이 포함되어 있습니다
RAG 기능에 대한 사용 힌트를 제공합니다.
Related MCP server: MCP-Typescribe
종속성 설치:
지엑스피1
서버를 빌드하세요:
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-hereGoogle AI Studio 웹사이트에서 Gemini API 키를 받을 수 있습니다. 이 키를 셸 프로필에 추가하거나 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
