# Directory Structure

```
├── .gitignore
├── package.json
├── pnpm-lock.yaml
├── README.md
├── src
│   └── index.ts
├── test-rag.ts
└── tsconfig.json
```

# Files

--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------

```
node_modules/
build/
*.log
.env*
```

--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------

```markdown
# 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.

```

--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

```

--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------

```json
{
  "name": "@kazuph/mcp-docs-rag",
  "version": "0.5.0",
  "description": "RAG (Retrieval-Augmented Generation) MCP server for documents using Gemini",
  "author": "kazuph",
  "license": "MIT",
  "type": "module",
  "bin": {
    "@kazuph/mcp-docs-rag": "./build/index.js"
  },
  "files": [
    "build"
  ],
  "keywords": [
    "mcp",
    "model-context-protocol",
    "rag",
    "documents",
    "gemini",
    "llamaindex"
  ],
  "publishConfig": {
    "access": "public"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/kazuph/mcp-docs-rag.git"
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "mcp": {
    "serverType": "docs-rag",
    "apiKeyRequirements": [
      "GEMINI_API_KEY"
    ],
    "environmentVariables": {
      "DOCS_PATH": "Path to documents directory"
    },
    "capabilities": [
      "rag",
      "documentManagement"
    ]
  },
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
    "prepare": "pnpm run build || npm run build",
    "watch": "tsc --watch",
    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
  },
  "dependencies": {
    "@llamaindex/google": "^0.1.0",
    "@modelcontextprotocol/sdk": "0.6.0",
    "llamaindex": "^0.9.9"
  },
  "devDependencies": {
    "@types/node": "^20.11.24",
    "typescript": "^5.3.3",
    "dotenv": "^16.4.7"
  }
}

```