benjibee/laravel-mcp-server

Laravel MCP Server

MCP server for Laravel PHP framework documentation references

This is a TypeScript-based MCP server that provides reference information for Laravel PHP framework documentation. It implements a Model Context Protocol (MCP) server that helps AI assistants access Laravel documentation and examples directly from the official Laravel documentation repository.

Features

Tools

• list_laravel_topics - Get a list of all available Laravel documentation topics
• get_laravel_topic_details - Get detailed information about a specific Laravel topic
• get_laravel_topic_examples - Get usage examples for a specific Laravel topic
• search_laravel_docs - Search for topics in Laravel documentation by keyword
• list_laravel_categories - Get a list of all Laravel documentation categories

Functionality

This server fetches and caches information from:

• The official Laravel documentation GitHub repository (https://github.com/laravel/docs)
• Uses the raw Markdown files for each documentation topic
• Organizes topics by categories (Getting Started, Basics, Security, Database, etc.)
• Caches documentation files locally to avoid repeated downloads

It provides structured data including:

• Complete topic content from Markdown files
• Categorized documentation structure (Getting Started, Basics, Frontend, Security, Database, Eloquent ORM, Testing, Digging Deeper, Packages, Advanced, Miscellaneous)
• Extracted code examples with language detection
• Section content with headings and anchors
• Intelligent description extraction
• Background preloading of common topics
• Persistent file caching for offline usage

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Usage with Augment

Once you've configured the Laravel MCP server with Augment, you can use it to access Laravel documentation directly in your VS Code environment. Here are some examples of how to use it:

Listing Laravel Documentation Topics

You can ask Augment to list all available Laravel documentation topics:

What Laravel documentation topics are available?

Or list topics by category:

What Laravel documentation topics are available in the "Database" category?

Show me all the topics in the "Eloquent ORM" category.

Getting Topic Details

You can ask for details about a specific Laravel topic:

Show me the documentation for Laravel installation.

Explain Laravel routing in detail.

I need help understanding Laravel's Eloquent relationships.

Finding Code Examples

You can ask for code examples for a specific topic:

Show me examples of Laravel routing.

Give me code examples for Eloquent models.

How do I implement middleware in Laravel? Show me some examples.

Searching Documentation

You can search the Laravel documentation for specific concepts:

Search Laravel documentation for "authentication".

Find information about queues in Laravel.

What does Laravel documentation say about caching?

Combining with Coding Tasks

You can combine documentation queries with coding tasks:

I need to build a web application using Laravel. Show me the documentation and then help me implement it.

Help me create a Laravel API with authentication based on Laravel documentation.

I'm working on a Laravel project. Show me the Laravel documentation for database migrations and help me set up my database.

Exploring Laravel Features

You can explore Laravel features by category:

What are the main features available in Laravel?

Tell me about Laravel's Eloquent ORM capabilities.

What are the different ways to handle authentication in Laravel?

Installation

Augment Configuration

To use with Augment in Visual Studio Code:

1. Install the Augment extension from the VS Code marketplace if you haven't already.

2. Create a new directory for MCP servers if you don't have one already:

   mkdir -p ~/.augment/mcp-servers
   

3. Clone this repository into that directory:

   git clone https://github.com/your-username/laravel-mcp-server.git ~/.augment/mcp-servers/laravel-mcp-server
   

4. Install dependencies and build the server:

   cd ~/.augment/mcp-servers/laravel-mcp-server
   npm install
   npm run build
   

5. Configure Augment to use this MCP server by adding it to your Augment configuration:

   Open VS Code settings (Cmd+, on Mac or Ctrl+, on Windows/Linux), search for "Augment", and find the "Augment: MCP Servers" setting. Click "Edit in settings.json" and add the following:

   "augment.mcpServers": {
     "laravel-server": {
       "command": "node",
       "args": ["~/.augment/mcp-servers/laravel-mcp-server/build/index.js"]
     }
   }
   

   Alternatively, you can use the absolute path to the server:

   "augment.mcpServers": {
     "laravel-server": {
       "command": "node",
       "args": ["/absolute/path/to/laravel-mcp-server/build/index.js"]
     }
   }
   

6. Restart VS Code to apply the changes.

7. You can now use the Laravel documentation tools with Augment in your PHP projects!

Claude Desktop Configuration

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

Option 1: Using local build

{
  "mcpServers": {
    "laravel-server": {
      "command": "/path/to/laravel-mcp-server/build/index.js"
    }
  }
}

Option 2: Using npx command

{
  "mcpServers": {
    "laravel-server": {
      "command": "npx",
      "args": ["-y", "laravel-mcp-server"]
    }
  }
}

Windsurf Configuration

Add this to your ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "laravel-server": {
      "command": "npx",
      "args": ["-y", "laravel-mcp-server"]
    }
  }
}

Cursor Configuration

Add this to your .cursor/mcp.json:

{
  "mcpServers": {
    "laravel-server": {
      "command": "npx",
      "args": ["-y", "laravel-mcp-server"]
    }
  }
}

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.

Troubleshooting

If you encounter issues with the Laravel MCP server, try these solutions:

1. No Response from Server:

   • Make sure the server is properly installed and built
   • Check that the path in your configuration is correct
   • Try restarting VS Code
   • Check the VS Code output panel for any error messages (View > Output, then select "Augment" from the dropdown)

2. Server Crashes or Timeouts:

   • The server includes fallback data for common Laravel topics, so it should still work even if it can't connect to GitHub
   • If you're behind a corporate firewall or proxy, it might block GitHub API requests
   • Try running the server manually to see any error output: node /path/to/laravel-mcp-server/build/index.js
   • The server caches documentation files locally, so it should work offline after the first successful run

3. Incorrect or Missing Data:

   • The server caches data in memory for better performance. If you need fresh data, restart VS Code
   • If specific topics are missing, you can manually add them to the fallback data in the source code
   • To force a refresh of the cached documentation files, delete the cache directory and restart the server

4. Augment Can't Find the Server:

   • Make sure the server name in your configuration matches exactly: laravel-server
   • Check that the path to the server is correct and accessible
   • Try using an absolute path instead of ~ in your configuration

5. Cache Issues:

   • The server stores documentation files in a cache directory next to the build directory
   • If you're experiencing issues with cached files, you can delete the cache directory to force a fresh download
   • Make sure the process running the server has write permissions to the cache directory

Contributing

Contributions to improve the Laravel MCP server are welcome! Here are some ways you can contribute:

1. Bug Reports: If you find a bug, please create an issue with detailed steps to reproduce it.

2. Feature Requests: If you have ideas for new features or improvements, please create an issue to discuss them.

3. Documentation: Help improve the documentation by fixing errors or adding examples.

4. Code Contributions: Submit pull requests for bug fixes or new features.

Development Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Keeping Up with Laravel Documentation

This MCP server is designed to work with the latest Laravel documentation. As Laravel evolves, the server may need updates to support new versions or changes in the documentation structure.

License

MIT