Laravel Docs

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

Laravel MCP Companionis 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.

Use Boostwhen writing code and you need project-aware context.Use Context7for non-Laravel libraries.Use Companionwhen learning, researching, or need Laravel documentation reference.

- 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 22 curated packages
- Cross-package compatibility- Learn which packages work well together
- Unified searchacross core Laravel docs, services, packages, and learning resources
- Daily updates- Automatically syncs with latest documentation

Listed in theofficial MCP Registryasio.github.brianirish/laravel-mcp-companion— clients with registry support can install it from there directly. Manual setup:

{ "mcpServers": { "laravel-mcp-companion": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/brianirish/laravel-mcp-companion:latest"] } } }

Restart Claude Desktopfor changes to take effect

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

# 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 projectoption creates a.mcp.jsonfile in your project root that can be committed to version control.

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

Documentation ships inside the image, and a new image is published whenever the documentation is refreshed, so:latestcarries the most recently published snapshot. The catch is thatdocker runreuses the copy you already have— once you've pulled the image, you keep running it until you pull again. Refresh whenever you like:

docker pull ghcr.io/brianirish/laravel-mcp-companion:latest

Or add--pull=alwaysto your MCP config so every start checks for a newer image. It costs a moment of startup time and needs a working connection, so it's opt-in rather than the default:

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

You don't have to track this yourself. The server tells your assistant how old the documentation is for the Laravel version it's serving, so if you ask about something newer than that snapshot it will say so and offer to refresh instead of answering from stale pages. You can also just ask —"how current are your Laravel docs?"

To update in place without pulling a new image,--update-docsfetches fresh documentation for the selected Laravel version during startup. Documentation for Forge, Vapor, Nova, Envoyer and community packages refreshes separately, through theupdate_external_laravel_docstool your assistant can call.

With--rmthe download is discarded when the container exits, so it repeats on every start. A named volume keeps it — but note the trade-off:

docker run --rm -i -v laravel-mcp-docs:/app/docs \ ghcr.io/brianirish/laravel-mcp-companion:latest --update-docs

A volume overrides the image's documentation.Once populated it masks/app/docs, so pulling a newer image no longer updates what the server reads — the volume becomes your source of truth and--update-docsbecomes the way you refresh it. Use a volume when you want to control updates explicitly; stick to plaindocker pullif you'd rather the image stay in charge.

By default the server no longer lists all of its tools. Instead it exposes a compact, search-first interface that keeps your AI client's context window lean:

- search(default) — Exposessearch_tools(BM25 relevance search over the tool catalog) andcall_tool(proxy to invoke any underlying tool).search_laravel_docsstays pinned and directly callable.
- code(experimental) — Exposes Code Mode meta-tools (tags,search,get_schema,execute) that let the client discover tools and orchestrate them with sandboxed Python. Requires thefastmcp[code-mode]extra (included inrequirements.txt). Avoid exposing this publicly over HTTP —executeis a code execution endpoint.
- none— Pre-0.9 behavior: every tool listed directly. Use this if your MCP client doesn't handle the synthetic search tools well.

# Restore the old flat tool listing docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --transform-mode none

Authentication is off by default.Anyone who can reach the HTTP port can call every tool, so treat network exposure as granting full access to the documentation tree — or turn on bearer-token auth:

# Validate tokens issued by a real OAuth 2.1 authorization server python laravel_mcp_companion.py --transport http \ --auth-jwks-uri https://auth.example/.well-known/jwks.json \ --auth-issuer https://auth.example \ --auth-audience laravel-mcp-companion # Development only: fixed tokens from the environment (never a CLI flag, # so secrets stay out of process listings) AUTH_STATIC_TOKENS="my-token:my-client" python laravel_mcp_companion.py --transport http

The server is aresource server: it validates tokens, it never issues them. Issuer and audience are mandatory with--auth-jwks-uri— accepting any issuer's tokens, or tokens minted for another service, would be authentication theater. Unauthenticated requests get401with aWWW-Authenticateheader (RFC 9728), and misconfiguration fails at startup rather than at request time. Auth applies to the HTTP transport only; stdio's access control is the process boundary.

- Binds127.0.0.1outside Docker. Inside the container it binds0.0.0.0, where the container boundary and explicit-ppublishing are the access control.
- Host and Origin validation is on, which blocks DNS-rebinding and drive-by-localhost attacks from a victim's browser.
- CORS is disabledunless you pass--cors-origin. Wildcard origins are rejected; credentials are never allowed cross-origin.

Onlylocalhost,127.0.0.1, and::1are accepted asHostvalues out of the box.If you bind a non-loopback interface you must add the hostname clients actually use, or every request is rejected with421:

python laravel_mcp_companion.py --transport http \ --host 0.0.0.0 \ --allowed-host mcp.internal.example \ --cors-origin https://app.example

Requests with an unrecognizedHostget421; requests from an unlistedOriginget403. Passing--allowed-hostor--cors-originon the command line replaces the corresponding environment variable rather than adding to it. If you expose this beyond localhost, put an authenticating reverse proxy in front of it. Avoid--transform-mode codeover HTTP entirely —executeis a code execution endpoint.

Off by default.--rate-limit 20capsMCP requests— tool calls, searches, the protocol surface — at 20/second with a single global token bucket: a total throughput cap, not per-client fairness (without auth there is no reliable client identity to key on). The operational endpoints (/healthz,/metrics,/.well-known/...) are deliberately outside the limit: throttling a load balancer's health checks marks healthy instances down, and those handlers are trivial reads. The limit counts every MCP request including the initialize handshake, which is why the burst default stays atmax(10, 2×RPS); keep the burst comfortably above your clients' handshake size if you lower it. Throttled requests receive a clean MCP error and succeed again once the bucket refills.

- GET /healthz— liveness/readiness JSON, always public (load balancers can't do OAuth).okanddegradedboth return 200 — degraded means the documentation copy is stale and a newer image should be pulled; 503 means no documentation is readable and traffic should not be routed here.
- GET /metrics— Prometheus text format: per-tool call counters, a latency histogram, request counts, uptime, and documentation age. Public on unauthenticated deployments; requires a valid bearer token whenever auth is configured.

- 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 paths- Structured sequences for any Laravel topic, offered interactively: ask without naming one and the server asks which of the ten curated paths you want
- 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

- Ranked section search- Ask in plain language ("how do I retry a failed queue job") and get the relevantsectionsranked by relevance, each with a snippet, an anchor, and a source label
- Section-level reads- Fetch just the section you need. A whole documentation file can exceed 30,000 tokens; a section is typically a few hundred, so answers leave room for your actual code
- Use case mapping- Describe what you need, get relevant packages
- Package integration guides- Installation and setup for 22 curated packages
- Cross-package compatibility- Documentation for package combinations
- Unified search- One search across every corpus: core versions, services, fetched package docs, and learning resources, with asourcesfilter to narrow it

- Task-capable updates- Documentation updates run as MCP tasks: submit, poll, fetch the result, instead of holding the connection for minutes
- Structured output- Tabular tools returnstructuredContentwith real schemas alongside their TOON text
- Elicitation- Interactive choices where they help, with plain listings as the fallback for clients without the capability
- Registry listed- Installable from theofficial MCP Registry, withserver.jsonmetadata,.well-knowndiscovery in HTTP mode, and automated publishing on release tags

For detailed roadmap information, seeROADMAP.md.

Laravel MCP Companion usesTOON (Token-Oriented Object Notation)for structured output, saving30-60% on tokenscompared to JSON/markdown.

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",...}]}

- 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

This application features anintelligent auto-discovery systemthat automatically finds and indexes Laravel documentation. Every day, it:

- Auto-discoversnew documentation sections across Laravel services (Forge, Vapor, Nova, Envoyer)
- Retrievesthe latest Laravel core documentation for all versions since 6.x
- Fetchescommunity package documentation (Spatie, Livewire, Inertia, Filament)
- Adaptsautomatically to structural changes in documentation websites
- Generatesnew patch releases automatically when updates are found

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

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

# 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

TheMCP Inspectorprovides 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

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

Create and read feature flags, review experiments, generate flag types, search docs, and interact with GrowthBook's feature flagging and experimentation platform.