GitHub Stats

    Stars

    6

    Forks

    6

    Release Date

    4/3/2025

    about 3 months ago

    Detailed Description

    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:

    npm install
    

    build the server:

    npm run build
    

    for development with auto-rebuild:

    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:

    export gemini_api_key=your-api-key-here
    

    you can obtain a gemini api key from the google ai studio 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

    {
      "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, which is available as a package script:

    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.

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.