Laravel MCP Companion (Go Implementation)

A Model Context Protocol (MCP) server providing comprehensive Laravel documentation and package recommendations for AI assistants. This is a complete Go implementation using the official github.com/mark3labs/mcp-go library.

🚀 Features

16 MCP Tools Available

Documentation Tools (6 tools)

list_laravel_docs - List available documentation files
read_laravel_doc_content - Read complete documentation content
search_laravel_docs - Search across documentation with match counts
search_laravel_docs_with_context - Advanced search with surrounding context
get_doc_structure - Extract table of contents from documentation
browse_docs_by_category - Discover docs by category (frontend, database, etc.)

Package Tools (4 tools)

get_laravel_package_recommendations - Get package recommendations by use case
get_laravel_package_info - Detailed information about specific packages
get_laravel_package_categories - List packages within a category
get_features_for_laravel_package - Get common features and patterns

Update & Info Tools (2 tools)

update_laravel_docs - Update documentation from GitHub
laravel_docs_info - Get metadata about documentation versions

External Service Tools (4 tools)

update_external_laravel_docs - Update external service documentation
list_laravel_services - List available Laravel services (Forge, Vapor, etc.)
search_external_laravel_docs - Search external service documentation
get_laravel_service_info - Get detailed service information

📦 Installation

Prerequisites

Go 1.24 or later
Git (for documentation updates)

Build from Source

# Clone the repository
git clone https://github.com/izzamoe/laravel-mcp-companion-go.git
cd laravel-mcp-companion-go

# Install dependencies
go mod download

# Build the server
go build -o bin/server ./cmd/server

# Run the server
./bin/server --docs-path ./docs --version 12.x

🔧 Configuration

Command Line Flags

--docs-path - Path to documentation directory (default: ./docs)
--packages-path - Path to packages catalog (default: ./configs/packages.json)
--version - Default Laravel version (default: 12.x)
--log-level - Logging level: debug, info, warn, error (default: info)

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "laravel-companion": {
      "command": "/path/to/laravel-mcp-companion-go/bin/server",
      "args": [
        "--docs-path", "/path/to/laravel-mcp-companion-go/docs",
        "--version", "12.x",
        "--log-level", "info"
      ]
    }
  }
}

📚 Usage Examples

1. List Available Documentation

Tool: list_laravel_docs
Parameters:
  version: "12.x"

2. Read Documentation Content

Tool: read_laravel_doc_content
Parameters:
  filename: "routing.md"
  version: "12.x"

3. Search Documentation

Tool: search_laravel_docs
Parameters:
  query: "middleware"
  version: "12.x"

4. Search with Context

Tool: search_laravel_docs_with_context
Parameters:
  query: "middleware"
  context_length: 200

5. Get Package Recommendations

Tool: get_laravel_package_recommendations
Parameters:
  use_case: "implementing payment system"

6. Get Package Information

Tool: get_laravel_package_info
Parameters:
  package_name: "laravel/cashier"

7. Browse by Category

Tool: browse_docs_by_category
Parameters:
  category: "frontend"
  version: "12.x"

🏗️ Architecture

laravel-mcp-companion-go/
├── cmd/server/           # Main entry point
│   └── main.go
├── internal/
│   ├── docs/            # Documentation management
│   │   ├── manager.go   # Core doc operations
│   │   └── cache.go     # Documentation caching
│   ├── packages/        # Package catalog
│   │   ├── catalog.go   # Package search & recommendations
│   │   └── format.go    # Output formatting
│   ├── server/          # MCP server & tools
│   │   ├── server.go    # Server initialization
│   │   ├── doc_tools.go # Documentation tools (6)
│   │   ├── package_tools.go # Package tools (4)
│   │   └── external_tools.go # External tools (6)
│   ├── updater/         # GitHub documentation updater
│   ├── external/        # External resource handling
│   ├── logging/         # Logging utilities
│   └── models/          # Data models
├── docs/                # Documentation files
│   └── 12.x/           # Laravel 12.x docs
├── configs/             # Configuration files
│   └── packages.json   # Package catalog
└── bin/                # Built binaries
    └── server

🔍 Implementation Details

MCP Library

This implementation uses the official MCP Go library:

Library: github.com/mark3labs/mcp-go v0.41.1
Transport: stdio (Standard Input/Output)
Protocol Version: 2024-11-05

Tool Registration

All tools are registered with:

✅ Proper parameter schemas (required/optional)
✅ Type validation (string, number, boolean, array)
✅ Default values for optional parameters
✅ Comprehensive descriptions with "When to use" guidance
✅ Error handling and response formatting

Documentation Manager

Features:

File-based documentation storage
In-memory caching with TTL
Path safety validation (prevents directory traversal)
Version management (12.x, 11.x, etc.)
Search with context extraction
Structure parsing (TOC generation)
Category-based browsing

Package Catalog

Features:

JSON-based package index
Use case matching with relevance scoring
Category organization
Popularity scoring
Maintenance status tracking
Alternative package suggestions

🧪 Testing

Manual Testing

# Build the server
go build -o bin/server ./cmd/server

# Run test script
./test_tools.sh

# Or manually test with Claude Desktop

Verify Tool Count

The server should log on startup:

Registered documentation tools (6 tools)
Registered package tools (4 tools)
Registered update and info tools (2 tools)
Registered external service tools (4 tools)
Server ready with 16 total tools, starting event loop...

📝 Documentation

Project Documentation

All development documentation is organized in the _docs/ folder:

TOOLS_VERIFICATION.md - Complete tool specifications and compliance checklist
MCP_GO_IMPLEMENTATION_COMPLETE.md - Detailed implementation guide
FINAL_VERIFICATION_REPORT.md - Final verification report
IMPLEMENTATION_SUMMARY.md - Implementation summary
TODO_PROGRESS_DASHBOARD.md - Development progress tracking

Laravel Documentation

Laravel documentation files are stored in the docs/ folder, organized by version (e.g., docs/12.x/, docs/11.x/).

🚀 Development

Building

go build -o bin/server ./cmd/server

Running

./bin/server --docs-path ./docs --version 12.x --log-level debug

Logging

Logs are output to stderr (stdout is reserved for MCP protocol):

Debug: Detailed operation logs
Info: General operation logs (default)
Warn: Warning messages
Error: Error messages

🤝 Contributing

Contributions are welcome! Please ensure:

All 16 tools remain functional
Parameter schemas match the specification
Response formats are Markdown-compatible
Tests pass
Code follows Go conventions

📄 License

MIT License

🙏 Acknowledgments

Laravel Framework team for excellent documentation
Anthropic for the MCP protocol specification
mark3labs for the mcp-go library

📞 Support

For issues and questions:

Create an issue on GitHub
Check the Laravel documentation in docs/
Review the implementation guide in _docs/MCP_GO_IMPLEMENTATION_COMPLETE.md
See development documentation in _docs/

Status: ✅ All 16 tools implemented and tested
Version: 1.0.0
Go Version: 1.24.0
Binary Size: 9.7MB

🚀 MCP Server for Laravel documentation and package recommendations

✨ Features

📚 Complete Laravel Documentation - Versions 6.x through 12.x
🔍 Smart Package Recommendations - AI-powered suggestions based on your use case
🌐 External Services - Forge, Vapor, Nova, Envoyer documentation
⚡ High Performance - Built with Go for speed and efficiency
💾 Intelligent Caching - Fast responses with automatic cache management
🎯 16 MCP Tools - Comprehensive API for Laravel development
🔗 Resource URIs - Direct access via laravel:// and laravel-external://

📋 Prerequisites

Go 1.24 or higher
Claude Desktop app or VSCode with MCP support
macOS, Linux, or Windows

🚀 Installation

Download Pre-built Binaries

Download the latest release from GitHub Releases for your platform:

Linux (AMD64/ARM64): laravel-mcp-companion-go-linux-{arch}
macOS (AMD64/ARM64): laravel-mcp-companion-go-darwin-{arch}
Windows (AMD64): laravel-mcp-companion-go-windows-amd64.exe

Make the binary executable and move to your preferred location:

# For Linux/macOS
chmod +x laravel-mcp-companion-go-*
sudo mv laravel-mcp-companion-go-* /usr/local/bin/laravel-mcp-companion-go

# For Windows, just move the .exe file to your desired location

Build from Source

# Clone the repository
git clone https://github.com/izzamoe/laravel-mcp-companion-go.git
cd laravel-mcp-companion-go

# Build
go build -o laravel-mcp-companion-go cmd/server/main.go

# Move to your preferred location
mv laravel-mcp-companion-go /usr/local/bin/

⚙️ Configuration

Claude Desktop Setup

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "laravel-companion": {
      "command": "/usr/local/bin/laravel-mcp-companion-go",
      "args": []
    }
  }
}

VSCode Setup

Download or build the binary (see Installation section above).
Create MCP configuration:
- Create a .vscode folder in your workspace root (if it doesn't exist)
- Create a file named mcp.json inside .vscode/
- Add the following content to mcp.json:
```
{
  "servers": {
    "laravel_docs": {
      "type": "stdio",
      "command": "/absolute/path/to/laravel-mcp-companion-go",
      "args": []
    }
  },
  "inputs": []
}
```
Note: Replace /absolute/path/to/laravel-mcp-companion-go with the actual absolute path to your binary (e.g., /usr/local/bin/laravel-mcp-companion-go).
Restart VSCode or reload the window to apply the MCP configuration.
Verify setup: The MCP server should now be available in VSCode's MCP-enabled extensions.

📖 Usage

In Claude Desktop

Simply ask Claude about Laravel! Examples:

Documentation: "Show me Laravel 11.x routing documentation"
Packages: "Recommend packages for implementing payment processing"
Features: "What features does Laravel Sanctum provide?"
Search: "Search for middleware in Laravel 11.x"

📋 Implementation Status

Current Status: 16/16 tools fully implemented (100% complete) ✅

All features are now production-ready:

✅ Tool 13: update_external_laravel_docs - Fully implemented with web scraping
✅ Tool 15: search_external_laravel_docs - Fully implemented with search functionality
✅ Tool 3 & 4: include_external parameters - Fully functional

Recent Updates (October 2025):

✅ Implemented external service documentation manager
✅ Added web scraping for Forge, Vapor, Envoyer, and Nova
✅ Implemented caching mechanism for external docs (24h validity)
✅ Integrated external search with main documentation search
✅ All TODO comments removed from codebase

For historical context about previously unimplemented features:

📊 Implementation History: See _docs/TODO_PROGRESS_DASHBOARD.md
📋 Completed Tasks: See _docs/TODO_IMPLEMENTATION_CHECKLIST.md

Status: All core and external service features are production-ready and fully functional! 🎉

🏗️ Development

Run Tests

# All tests
go test ./...

# With coverage
go test -cover ./...

# Verbose output
go test -v ./...

Run with Debug Logging

LOG_LEVEL=debug ./laravel-mcp-companion-go

📝 License

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

🙏 Acknowledgments

Laravel Framework - The PHP framework
MCP Protocol - Model Context Protocol
mark3labs/mcp-go - Go MCP library

Made with ❤️ for the Laravel community

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
_docs		_docs
cache/external		cache/external
cmd/server		cmd/server
configs		configs
internal		internal
tests		tests
.gitignore		.gitignore
README.md		README.md
go.mod		go.mod
go.sum		go.sum
test_tools.sh		test_tools.sh

izzamoe/laravel-mcp-companion-go

Folders and files

Latest commit

History

Repository files navigation

Laravel MCP Companion (Go Implementation)

🚀 Features

16 MCP Tools Available

Documentation Tools (6 tools)

Package Tools (4 tools)

Update & Info Tools (2 tools)

External Service Tools (4 tools)

📦 Installation

Prerequisites

Build from Source

🔧 Configuration

Command Line Flags

Claude Desktop Configuration

📚 Usage Examples

1. List Available Documentation

2. Read Documentation Content

3. Search Documentation

4. Search with Context

5. Get Package Recommendations

6. Get Package Information

7. Browse by Category

🏗️ Architecture

🔍 Implementation Details

MCP Library

Tool Registration

Documentation Manager

Package Catalog

🧪 Testing

Manual Testing

Verify Tool Count

📝 Documentation

Project Documentation

Laravel Documentation

🚀 Development

Building

Running

Logging

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

✨ Features

📋 Prerequisites

🚀 Installation

Download Pre-built Binaries

Build from Source

⚙️ Configuration

Claude Desktop Setup

VSCode Setup

📖 Usage

In Claude Desktop

📋 Implementation Status

Recent Updates (October 2025):

🏗️ Development

Run Tests

Run with Debug Logging

📝 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Languages

Packages