laravel-simple-rag — Laravel Knowledge Provider

A self-hosted, single-user knowledge manager and MCP server built on Laravel MCP. Organise your snippets, questions, documents, and context in a web UI, then expose everything to AI assistants (Claude, etc.) via the Model Context Protocol. LLMs can read your knowledge base and write answers, scraped content, and summaries back into it.

Table of Contents

• Features

• Requirements

• Installation

• Configuration

• First-Time Setup

• Using the Web UI

• MCP Server

  • Authentication (OAuth2)

  • Registering with Claude Desktop

  • Available Tools

  • Available Prompts

  • Available Resources

• Key Use Cases

• Development

Related MCP server: memory-mcp

Features

• Web Knowledge Manager — CRUD UI for entries (markdown), entry types, topics, and responses

• MCP Server — exposes all content to LLMs via the Model Context Protocol over OAuth2

• Live Markdown editor — write and preview markdown side-by-side in the browser

• Response management — add and edit responses on separate pages or inline on the entry view

• Meta key-value pairs — attach arbitrary metadata (e.g. source_url, model_name) to entries and responses via an interactive key-value editor; LLMs can write metadata too

• Icons for entry types and topics — assign one of 25 curated SVG icons to categorise your knowledge visually; icons appear in tables, entry badges, and the dashboard

• Personal access tokens — create and manage long-lived API tokens in Settings → API Tokens for scripted or direct API access

• Full-text search — entry search uses native full-text indexes on MySQL/MariaDB/PostgreSQL, with automatic LIKE fallback on SQLite

• Invitation-based registration — controlled access via invite codes (optional, see Configuration)

• Fully self-hosted — no external dependencies beyond your own server

Screenshots

Requirements

• PHP 8.4+

• Composer

• Node.js & npm

• SQLite, MySQL, or PostgreSQL

• (Optional) Redis for queue/cache

Installation

# 1. Clone and install dependencies
git clone https://github.com/your-username/laravel-simple-rag.git
cd laravel-simple-rag
composer install
npm install

# 2. Environment setup
cp .env.example .env
php artisan key:generate

# 3. Configure your database in .env, then run migrations
php artisan migrate

# 4. Generate Passport OAuth2 keys (required for MCP auth)
php artisan passport:keys

# 5. Build frontend assets
npm run build

# 6. Start the development server
composer run dev

For production, deploy with Laravel Forge or any standard Laravel hosting. Run npm run build instead of npm run dev.

Configuration

The following custom environment variables control application behaviour. Set them in your .env file.

First-Time Setup

1. Register your account

If APP_REQUIRE_INVITATION is false (default), open your app URL and register directly.

If invitations are required, first generate an invitation code on the server:

php artisan invitation:manage create --description="my account"

Then open your app URL and register using the code.

2. List or deactivate invitation codes

php artisan invitation:manage list
php artisan invitation:manage deactivate --code=YOUR_CODE

3. (Optional) Enable personal access tokens

If you want to use Settings → API Tokens to create long-lived tokens for scripted API access, create the Passport personal access client once:

php artisan passport:client --personal --no-interaction

4. Set up your entry types

After logging in, go to Entry Types and create the types you want to use (e.g. question, snippet, document, context). Entry types are how you and the LLM categorize knowledge.

5. (Optional) Create topics

Go to Topics and create topic tags (e.g. Programming, Personal, Work) to organise entries across types.

Using the Web UI

Entries are the core unit — a title, Markdown content, a type, and optional topics. Responses are attached to entries and represent answers or generated content (written by you or by an LLM via MCP).

Both entries and responses support optional meta key-value pairs — arbitrary data attached to the record (e.g. source_url, model_name, confidence). The UI provides an interactive key-value editor; LLMs can supply meta via the MCP tools.

MCP Server

The RAG MCP server is available at /mcp/rag and is protected by Laravel Passport OAuth2.

Authentication (OAuth2)

The MCP server uses the standard OAuth2 flow. MCP clients (like Claude Desktop) handle authentication automatically once registered.

To verify your server is working, use the built-in inspector:

# Test the RAG server interactively
php artisan mcp:inspector rag

This launches the MCP Inspector and prints the client configuration to copy into your MCP client.

Registering with Claude Desktop

Add the following to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "knowledge-base": {
            "command": "npx",
            "args": ["mcp-remote", "https://your-app-url.com/mcp/rag"]
        }
    }
}

Replace https://your-app-url.com with your actual app URL. On first connection, Claude Desktop will open a browser window to complete the OAuth2 authorization — approve it to grant access.

Local development: Run php artisan mcp:inspector rag for the exact configuration to use. The local rag server is also registered for stdio-based testing.

HTTPS note: Many AI agents run on Node.js, which uses its own certificate store. Self-signed or local certificates may cause connection failures. For local testing, prefer plain http://; use https:// on production with a valid certificate.

Available Tools

All tools are scoped to your authenticated account.

Available Prompts

Prompts are reusable instruction templates that guide the LLM through multi-step workflows using the tools above.

answer_question

Finds an unanswered question entry matching a query and stores an answer as a response.

Argument: query (required) — topic or keywords to search for

Workflow the LLM follows:

1. Calls search_entries with the query keyword

2. Identifies entries that look like unanswered questions

3. Calls get_entry with with_responses: true to check for existing answers

4. Composes a thorough Markdown answer

5. Calls create_response to store it

scrape_and_store

Fetches a URL, extracts the meaningful content, and stores it as a new entry.

Arguments:

• url (required) — the page to fetch

• type_id (optional) — entry type to use; if omitted, the LLM calls list_types first

Workflow the LLM follows:

1. Fetches the URL content

2. Extracts title and body (skips navigation, ads, footers)

3. Formats as clean Markdown

4. Calls create_entry to store it

Available Resources

Key Use Cases

Q&A Flow

1. Create an entry with type question and your question as the title/content.

2. Ask your AI assistant to use the answer_question prompt with a matching keyword.

3. The LLM searches for the question, writes an answer, and stores it as a response.

4. Review and edit the response in the web UI.

Web Scraping Flow

1. Tell your AI assistant to use the scrape_and_store prompt with a URL.

2. The LLM fetches the page, converts it to Markdown, and creates an entry.

3. The entry appears in your knowledge base immediately.

Knowledge Retrieval

• Use search_entries with keywords or type/topic filters to find relevant context.

• Use get_entry with with_responses: true to pull a complete entry with all its stored answers.

• Access any entry directly via the entry://entries/{id} resource URI.

Development

# Run the development server (Vite + PHP server + queue worker)
composer run dev

# Run tests
php artisan test --compact

# Test the RAG MCP server interactively
php artisan mcp:inspector rag

# Format PHP code
vendor/bin/pint

# Run static analysis
vendor/bin/phpstan analyse

User management

php artisan user:manage list
php artisan user:manage promote --email=user@example.com
php artisan user:manage demote  --email=user@example.com

Run php artisan user:manage --help for full usage.

Invitation management

php artisan invitation:manage create [--description=] [--count=]
php artisan invitation:manage list
php artisan invitation:manage deactivate --code=CODE