Content
# Livewire MCP Server
MCP server for Livewire documentation references
This is a TypeScript-based MCP server that provides reference information for Livewire documentation. It implements a Model Context Protocol (MCP) server that helps AI assistants access Livewire documentation and examples directly from the official Livewire documentation repository.
## Features
### Tools
- `list_livewire_topics` - Get a list of all available Livewire documentation topics
- `get_livewire_topic_details` - Get detailed information about a specific topic
- `get_livewire_topic_examples` - Get usage examples for a specific topic
- `search_livewire_docs` - Search for topics in Livewire documentation by keyword
- `list_livewire_categories` - Get a list of all Livewire documentation categories
### Functionality
This server fetches and caches information from:
- The official Livewire documentation GitHub repository (https://github.com/livewire/livewire/tree/main/docs)
- Uses the raw Markdown files for each documentation topic
- Organizes topics by categories as defined in the documentation
- Caches documentation files locally to avoid repeated downloads
It provides structured data including:
- Complete topic content from Markdown files
- Categorized documentation structure
- 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:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
npm run watch
```
## Usage with Augment
Once you've configured the Livewire MCP server with Augment, you can use it to access Livewire documentation directly in your VS Code environment. Here are some examples of how to use it:
### Listing Livewire Documentation Topics
You can ask Augment to list all available Livewire documentation topics:
```
What Livewire documentation topics are available?
```
Or list topics by category:
```
What Livewire documentation topics are available in the "Directives" category?
```
```
Show me all the topics in the "Advanced" category.
```
### Getting Topic Details
You can ask for details about a specific Livewire topic:
```
Show me the documentation for Livewire components.
```
```
Explain Livewire properties in detail.
```
```
I need help understanding Livewire's validation system.
```
### Finding Code Examples
You can ask for code examples for a specific topic:
```
Show me examples of Livewire wire:model directive.
```
```
Give me code examples for Livewire forms.
```
```
How do I implement events in Livewire? Show me some examples.
```
### Searching Documentation
You can search the Livewire documentation for specific concepts:
```
Search Livewire documentation for "validation".
```
```
Find information about Alpine.js integration in Livewire.
```
```
What does Livewire documentation say about testing?
```
### Combining with Coding Tasks
You can combine documentation queries with coding tasks:
```
I need to implement a contact form in my Livewire component. Show me the documentation and then help me implement it.
```
```
Help me create a Livewire component for user registration based on Livewire documentation.
```
```
I'm working on a Livewire app. Show me the documentation for wire:loading and help me implement loading states.
```
### Exploring Livewire Features
You can explore Livewire features by category:
```
What are the main directives available in Livewire?
```
```
Tell me about Livewire's security features.
```
```
What are the different ways to handle forms in Livewire?
```
## 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:
```bash
mkdir -p ~/.augment/mcp-servers
```
3. Clone this repository into that directory:
```bash
git clone https://github.com/your-username/laravel-mcp-server.git ~/.augment/mcp-servers/laravel-mcp-server
```
4. Install dependencies and build the server:
```bash
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:
```json
"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:
```json
"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 Laravel 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
```json
{
"mcpServers": {
"laravel-server": {
"command": "/path/to/laravel-mcp-server/build/index.js"
}
}
}
```
#### Option 2: Using npx command
```json
{
"mcpServers": {
"laravel-server": {
"command": "npx",
"args": ["-y", "laravel-mcp-server"]
}
}
}
```
### Windsurf Configuration
Add this to your `./codeium/windsurf/model_config.json`:
```json
{
"mcpServers": {
"laravel-server": {
"command": "npx",
"args": ["-y", "laravel-mcp-server"]
}
}
}
```
### Cursor Configuration
Add this to your `.cursor/mcp.json`:
```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](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
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 Laravel 12.x documentation. As Laravel evolves, the server may need updates to support new versions or changes in the documentation structure.
## License
MIT
