Skip to main content
Glama
README.md
# Filament MCP Server

A Model Context Protocol (MCP) server that provides tools, prompts, and resources for working with [Filament](https://filamentphp.com/) - the Laravel admin panel framework.

## Overview

This MCP server enables AI assistants to help developers build Filament admin panels by providing:

- **Component Reference**: Access to Filament form, table, and infolist component documentation
- **Code Generation**: Generate implementation plans for Filament resources
- **Documentation Lookup**: Fetch and search official Filament documentation
- **Namespace Lookup**: Get correct PHP namespaces for Filament classes
- **Command Reference**: List available Filament artisan commands
- **Relationship Helpers**: Laravel Eloquent relationship type references

Supports both Filament **v4.x** and **v5.x**.

## Requirements

- **Node.js**: v20.10.0 or higher
- **npm**: v9.0.0 or higher (or pnpm v8.0.0+)

## Installation

1. Clone the repository:

```bash
cd filament-mcp-server
```

2. Install dependencies:

```bash
npm install
```

## Building

Compile TypeScript to JavaScript:

```bash
npm run build
```

This compiles the source from `src/` to `dist/`. The main entry point is `dist/index.js`.

## Running

### Development Mode

Watch for changes and rebuild automatically:

```bash
npm run dev
```

### Production Mode

Run the compiled server:

```bash
npm start
```

### Stdio Mode

The server uses stdio transport by default. This allows it to communicate with MCP clients over standard input/output streams. The server starts and waits for JSON-RPC messages from the client.

## MCP Integration

To use this server with MCP-compatible AI assistants, you need to register it as an MCP server. Below are configuration examples for popular clients.

### Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "filament": {
      "command": "node",
      "args": ["/absolute/path/to/filament-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}
```

or

(I prefer npx)

```json
{
  "mcpServers": {
    "filament": {
      "command": "npx",
      "args": ["/absolute/path/to/filament-mcp-server"],
      "env": {}
    }
  }
}

Replace `/absolute/path/to/filament-mcp-server` with the actual path to this project.

### Cursor

1. Open Cursor settings
2. Navigate to **Features** → **MCP**
3. Add a new MCP server with the following configuration:

```json
{
  "mcpServers": {
    "filament": {
      "command": "node",
      "args": ["/absolute/path/to/filament-mcp-server/dist/index.js"]
    }
  }
}
```

### Other MCP Clients

For other MCP-compatible assistants, configure them to spawn a child process using:

```bash
node /path/to/filament-mcp-server/dist/index.js
```

The server communicates via stdio using JSON-RPC 2.0 protocol.

## Available Tools

The server provides the following MCP tools:

| Tool | Description |
|------|-------------|
| [`filament_get_component`](src/tools/index.ts:58) | Get detailed information about a specific Filament component (properties, methods, examples) |
| [`filament_list_components`](src/tools/index.ts:72) | List all components in a category (forms, tables, infolists, actions, schemas, support) |
| [`filament_get_namespace`](src/tools/index.ts:82) | Get the correct PHP namespace for a Filament class type |
| [`filament_generate_plan`](src/tools/index.ts:105) | Generate a complete Filament implementation plan for a resource |
| [`filament_get_commands`](src/tools/index.ts:147) | Get a list of Filament artisan commands with descriptions |
| [`filament_get_relationships`](src/tools/index.ts:154) | Get Laravel Eloquent relationship types with examples |
| [`filament_get_docs`](src/tools/index.ts:158) | Fetch documentation from filamentphp.com for a specific category/section |
| [`filament_list_docs`](src/tools/index.ts:185) | List all available documentation sections |
| [`filament_discover_docs`](src/tools/index.ts:192) | Discover live documentation routes from the official website |
| [`filament_search_docs`](src/tools/index.ts:223) | Search Filament documentation and return matching sections |

### Tool Parameters

- **`version`**: All tools support a `version` parameter (`"4.x"` or `"5.x"`) to target specific Filament versions. Defaults to `"5.x"`.
- **`component`**: Component name (e.g., `TextInput`, `Select`, `Table`)
- **`category`**: Component category (`forms`, `tables`, `infolists`, `actions`, `schemas`, `support`)
- **`classType`**: Filament class type (`model`, `resource`, `widget`, `relation_manager`, etc.)
- **`description`**: What you want to build (used for plan generation)

## Available Prompts

The server provides the following MCP prompts for common tasks:

| Prompt | Description |
|--------|-------------|
| `create_resource_plan` | Generate an implementation plan for a Filament resource |
| `debug_filament_issue` | Help debug a Filament issue with error messages |
| `create_relation_manager` | Generate a Filament RelationManager for relationships |
| `create_custom_action` | Generate a custom Filament action |
| `migrate_to_v5` | Migrate Filament v4 code to v5 |
| `create_form_with_validation` | Generate a form with validation rules |
| `create_table_with_features` | Generate a table with filters and actions |

## Available Resources

The server provides the following MCP resources:

| Resource URI | Description |
|--------------|-------------|
| `filament://reference/v4/components` | Complete Filament v4 component reference |
| `filament://reference/v5/components` | Complete Filament v5 component reference |
| `filament://reference/v4/commands` | Filament v4 artisan commands |
| `filament://reference/v5/commands` | Filament v5 artisan commands |
| `filament://docs/v4/index` | Filament v4 documentation index |
| `filament://docs/v5/index` | Filament v5 documentation index |
| `filament://reference/quick` | Quick reference for common patterns |

## Configuration

### Version Targeting

Most tools accept an optional `version` parameter to target Filament v4 or v5:

```typescript
// Example tool call with version
{
  tool: "filament_get_component",
  arguments: {
    component: "TextInput",
    version: "5.x"  // or "4.x"
  }
}
```

### Namespace Mapping

The server includes predefined namespace mappings for different Filament class types:

| Class Type | v4.x Namespace | v5.x Namespace |
|------------|----------------|----------------|
| `model` | `App\Models` | `App\Models` |
| `resource` | `App\Filament\Resources` | `App\Filament\Resources` |
| `widget` | `App\Filament\Widgets` | `App\Filament\Widgets` |
| `relation_manager` | `App\Filament\Resources\{Resource}\RelationManagers` | `App\Filament\Resources\{Resource}\RelationManagers` |
| `form_component` | `Filament\Forms\Components` | `Filament\Forms\Components` |
| `schema_component` | (not available) | `Filament\Schemas\Components` |
| `table_column` | `Filament\Tables\Columns` | `Filament\Tables\Columns` |
| `action` | `Filament\Actions` | `Filament\Actions` |

## Testing

Run tests with Vitest:

```bash
npm test
```

Run tests in watch mode:

```bash
npm run test:watch
```

## Project Structure

```
filament-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── data/
│   │   └── filament-reference.ts  # Component reference data
│   ├── lib/
│   │   ├── doc-fetcher.ts    # Documentation fetching utilities
│   │   └── plan-generator.ts # Implementation plan generator
│   ├── prompts/
│   │   └── index.ts          # MCP prompts
│   ├── resources/
│   │   └── index.ts          # MCP resources
│   └── tools/
│       └── index.ts          # MCP tools
├── dist/                     # Compiled JavaScript output
├── tests/
│   └── index.test.ts         # Test suite
├── package.json
├── tsconfig.json
└── README.md
```

## Dependencies

- **@modelcontextprotocol/sdk**: MCP protocol implementation
- **cheerio**: HTML parsing for documentation fetching
- **zod**: Schema validation for tool parameters

## License

MIT

TDQS

B3/5.0

Scored across 10 tools

Disambiguation4/5

Most tools have distinct purposes, such as discovering docs, generating plans, getting commands, and fetching components. However, there is some overlap between filament_discover_docs, filament_get_docs, filament_list_docs, and filament_search_docs, which all relate to documentation access and could cause confusion about which to use for specific queries.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with the prefix 'filament_' and a clear verb_noun structure, such as filament_get_component and filament_list_components. This predictability makes it easy for agents to understand and select tools based on their naming conventions.

Tool Count5/5

With 10 tools, the server is well-scoped for assisting with Filament PHP development, covering key areas like documentation, components, commands, and planning. Each tool appears to serve a specific function without redundancy, making the count appropriate for the domain.

Completeness4/5

The tool set provides comprehensive coverage for Filament development tasks, including documentation retrieval, component management, and implementation planning. A minor gap is the lack of tools for creating or modifying Filament resources, such as generating code or updating components, which might limit full lifecycle support.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues