https://github.com/kazuph/mcp-docs-rag
https://github.com/kazuph/mcp-docs-rag
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/kazuph/mcp-docs-rag
- Owner: kazuph
- Created: 2025-03-09T07:50:02.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-03-09T09:13:37.000Z (7 months ago)
- Last Synced: 2025-03-09T09:24:36.787Z (7 months ago)
- Language: JavaScript
- Size: 21.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- mcp-index - RAG Server for Documents - Manage and query documents in a local directory using retrieval-augmented generation techniques, integrating context from text files and Git repositories. Supports listing documents and generating responses based on queries with context from the stored content. (Data Analytics)
README
# mcp-docs-rag MCP Server
RAG (Retrieval-Augmented Generation) for documents in a local directory
This is a TypeScript-based MCP server that implements a RAG system for documents stored in a local directory. It allows users to query documents using LLMs with context from locally stored repositories and text files.
## Features
### Resources
- List and access documents via `docs://` URIs
- Documents can be Git repositories or text files
- Plain text mime type for content access
### Tools
- `list_documents` - List all available documents in the DOCS_PATH directory
- Returns a formatted list of all documents
- Shows total number of available documents
- `rag_query` - Query documents using RAG
- Takes document_id and query as parameters
- Returns AI-generated responses with context from documents
- `add_git_repository` - Clone a Git repository to the docs directory with optional sparse checkout
- Takes repository_url as parameter
- Optional document_name parameter to customize the name of the document (use simple descriptive names without '-docs' suffix)
- Optional subdirectory parameter for sparse checkout of specific directories
- Automatically pulls latest changes if repository already exists
- `add_text_file` - Download a text file to the docs directory
- Takes file_url as parameter
- Uses wget to download file
### Prompts
- `guide_documents_usage` - Guide on how to use documents and RAG functionality
- Includes list of available documents
- Provides usage hints for RAG functionality
## Development
Install dependencies:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
npm run watch
```
## Setup
This server requires a local directory for storing documents. By default, it uses `~/docs` but you can configure a different location with the `DOCS_PATH` environment variable.
### Document Structure
The documents directory can contain:
- Git repositories (cloned directories)
- Plain text files (with .txt extension)
Each document is indexed separately using llama-index.ts with Google's Gemini embeddings.
### API Keys
This server uses Google's Gemini API for document indexing and querying. You need to set your Gemini API key as an environment variable:
```bash
export GEMINI_API_KEY=your-api-key-here
```
You can obtain a Gemini API key from the [Google AI Studio](https://makersuite.google.com/app/apikey) website. Add this key to your shell profile or include it in the environment configuration for Claude Desktop.
## Installation
To use with Claude Desktop, add the server config:
On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
On Linux: `~/.config/Claude/claude_desktop_config.json`
```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"
}
}
}
}
```
Make sure to replace `/Users/username/docs` with the actual path to your documents directory.
### Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
## Usage
Once configured, you can use the server with Claude to:
1. **Add documents**:
```
Add a new document from GitHub: https://github.com/username/repository
```
or with a custom document name:
```
Add GitHub repository https://github.com/username/repository-name and name it 'framework'
```
or with sparse checkout of a specific directory:
```
Add only the 'src/components' directory from https://github.com/username/repository
```
or combine custom name and sparse checkout:
```
Add the 'examples/demo' directory from https://github.com/username/large-repo and name it 'demo-app'
```
or add a text file:
```
Add this text file: https://example.com/document.txt
```
2. **Query documents**:
```
What does the documentation say about X in the Y repository?
```
3. **List available documents**:
```
What documents do you have access to?
```
The server will automatically handle indexing of documents for efficient retrieval.