Laravel MCP Companion

formerly Laravel Docs MCP Server

> ⚠️ BETA SOFTWARE - This project is in active development. Features may change and breaking changes may occur.

Laravel MCP Companion is a documentation aggregator and navigator for the Laravel ecosystem. It centralizes and organizes high-quality documentation from across the Laravel ecosystem, making it easily discoverable through your AI assistant.

How It Compares

| Feature | Laravel Boost | Context7 | Laravel MCP Companion |
|---------|:--------:|:--------:|:--------------------:|
| Focus | Code generation | General docs | Laravel documentation |
| Best for | Active development | Any library | Learning & reference |
| Project-aware context | ✅ | ❌ | ❌ |
| Laravel multi-version support (6.x - latest) | ❌ | ❌ | ✅ |
| Laravel service docs (Forge, Vapor, Nova, Envoyer) | ❌ | ❌ | ✅ |
| Learning paths & difficulty levels | ❌ | ❌ | ✅ |
| "I need X" documentation finder | ❌ | ❌ | ✅ |
| Curated Laravel package recommendations | ❌ | ❌ | ✅ |
| Offline documentation access | ❌ | ❌ | ✅ |
| TOON format output (30-60% fewer tokens) | ❌ | ❌ | ✅ |
| General documentation (non-Laravel) | ❌ | ✅ | ❌ |

Use Boost when writing code and you need project-aware context. Use Context7 for non-Laravel libraries. Use Companion when learning, researching, or need Laravel documentation reference.

What you get:

- Multi-version Laravel documentation (6.x through latest) with enhanced search - Learning paths - Structured learning sequences by topic and skill level - "I need X" finder - Describe what you need, get relevant documentation - Difficulty filtering - Content organized by beginner/intermediate/advanced - 15 semantic categories - Browse documentation by topic area - Auto-discovery Laravel services - Forge, Vapor, Envoyer, Nova (117+ sections) - Community package documentation - 42,000+ lines from Spatie, Livewire, Inertia, Filament - Package integration guides - Installation and setup for 50+ curated packages - Cross-package compatibility - Learn which packages work well together - Unified search across core Laravel docs, services, and packages - Daily updates - Automatically syncs with latest documentation

Installation

Claude Desktop

1. Open Claude Desktop Settings
- Click Claude menu → Settings → Developer → Edit Config

2. Add to your configuration file:

   {

     "mcpServers": {

       "laravel-mcp-companion": {

         "command": "docker",

         "args": ["run", "--rm", "-i", "ghcr.io/brianirish/laravel-mcp-companion:latest"]

       }

     }

   }

   

3. Restart Claude Desktop for changes to take effect

Config file locations:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code

Use the claude mcp add command:

# Add with Docker
claude mcp add laravel-mcp-companion -- docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest
Or add to project-specific config (for team sharing)
claude mcp add laravel-mcp-companion --scope project -- docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest

The --scope project option creates a .mcp.json file in your project root that can be committed to version control.

Configuration Options

These options can be used with the Docker command. For example:

# Pin to a specific older Laravel version
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --version 11.x
Force update all documentation
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --force-update

| Option | Description | Default |
|--------|-------------|---------|
| --version VERSION | Laravel version (e.g., "11.x", "12.x") | Latest |
| --docs-path PATH | Documentation directory | ./docs |
| --log-level LEVEL | DEBUG, INFO, WARNING, ERROR, CRITICAL | INFO |
| --update-docs | Update documentation on startup | false |
| --force-update | Force documentation update | false |

Features (v0.9.0)

Documentation Aggregation

- Multi-version Laravel docs - All versions from 6.x to latest - Auto-discovery engine - Finds new docs across Forge, Vapor, Nova, Envoyer - Community package docs - 42,000+ lines from Spatie, Livewire, Inertia, Filament - Daily updates - Automatic sync with latest documentation

Learning & Discovery (New in v0.9.0)

- Learning paths - Structured sequences for any Laravel topic - Difficulty levels - Filter by beginner, intermediate, or advanced - 15 categories - Browse by authentication, database, testing, etc. - "I need X" finder - Natural language documentation discovery - Related resources - Find connected documentation automatically

Search & Navigation

- Use case mapping - Describe what you need, get relevant packages - Package integration guides - Installation and setup for 50+ packages - Cross-package compatibility - Documentation for package combinations - Unified search - One search across all documentation sources

Upcoming

- v0.10.0: MCP 2025-11-25 spec support, Registry publishing - v0.11.0: Production hardening, monitoring, security audit - v1.0.0: First stable release with LTS commitment

For detailed roadmap information, see ROADMAP.md.

TOON Format Output

Laravel MCP Companion uses TOON (Token-Oriented Object Notation) for structured output, saving 30-60% on tokens compared to JSON/markdown.

Example Output

When you search for packages or list documentation, you get efficient structured data:

context: "authentication for SPA"
count: 2
packages[2]{id,name,description,categories,install}:
  laravel/sanctum,Laravel Sanctum,"Featherweight authentication for SPAs",[authentication,spa],"composer require laravel/sanctum"
  laravel/passport,Laravel Passport,"Full OAuth2 implementation",[authentication,api],"composer require laravel/passport"

Compare to the equivalent JSON (nearly 2x the tokens):

{"context":"authentication for SPA","count":2,"packages":[{"id":"laravel/sanctum","name":"Laravel Sanctum",...}]}

Why TOON?

- Token efficient: LLMs understand TOON natively - no parsing overhead
- Structured data: Arrays, objects, and metadata without JSON verbosity
- AI-friendly: Designed specifically for LLM context windows

Auto-Discovery & Update Frequency

This application features an intelligent auto-discovery system that automatically finds and indexes Laravel documentation. Every day, it:

- Auto-discovers new documentation sections across Laravel services (Forge, Vapor, Nova, Envoyer)
- Retrieves the latest Laravel core documentation for all versions since 6.x
- Fetches community package documentation (Spatie, Livewire, Inertia, Filament)
- Adapts automatically to structural changes in documentation websites
- Generates new patch releases automatically when updates are found

Development

Prerequisites

- Python 3.12+ - Node.js 18+ (for MCP Inspector)

Setup

git clone https://github.com/brianirish/laravel-mcp-companion
cd laravel-mcp-companion
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt

Running Tests

# All tests with coverage
pytest --cov --cov-report=html
Unit tests only
pytest tests/unit/
Integration tests only
pytest tests/integration/
Protocol compliance tests
pytest tests/protocol/ -m protocol

Manual Testing with MCP Inspector

The MCP Inspector provides a visual UI for testing MCP servers.

# Launch Inspector (opens browser at http://localhost:6274)
npx @modelcontextprotocol/inspector python laravel_mcp_companion.py
With specific version
npx @modelcontextprotocol/inspector python laravel_mcp_companion.py --version 11.x

Use the Inspector to:
- Tools tab: Test all tools with auto-generated input forms
- Resources tab: Browse laravel:// and laravel-external:// resources
- Prompts tab: Test prompt templates

Code Quality

ruff check --fix .     # Linting
mypy --ignore-missing-imports .  # Type checking
black .                # Formatting

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Acknowledgements

- Laravel for their excellent documentation
- Laravel package authors for their contributions to the ecosystem