# 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