# MCP Laravel API - Kaipa

MCP (Model Context Protocol) service for Laravel API integration with Cursor.

## Features

- 🚀 Retrieve all Laravel routes
- 🗂️ List Eloquent models
- ⚙️ Execute Artisan commands
- 📋 Access Laravel configuration
- 🔗 Direct Docker container integration
- 💾 Redis cache management & operations
- 🔄 Full Redis CRUD operations

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Build TypeScript

```bash
npm run build
```

### 3. Configure Cursor

Add to your Cursor settings (`.cursor/rules.mcp.json` or settings):

```json
{
  "mcpServers": {
    "laravel-api": {
      "command": "node",
      "args": ["/var/www/ai-tools/mcp-laravel-api-kaitori/dist/server.js"],
      "env": {
        "APP_NAME": "kaipa",
        "DB_HOST": "db",
        "DB_PORT": "3306",
        "APP_PORT": "8181",
        "REDIS_HOST": "redis",
        "REDIS_PORT": "6379"
      }
    }
  }
}
```

### 4. Start the service

Development mode:
```bash
npm run mcp-dev
```

Production mode:
```bash
npm start
```

## Available Tools

### Laravel Tools

#### get_routes
Get all Laravel API routes with optional filtering.
```
get_routes({ method: "GET", path: "api" })
```

#### artisan_command
Execute any Artisan command in the Laravel container.
```
artisan_command({ command: "migrate", args: ["--fresh"] })
```

#### get_models
List all Eloquent models in the application.

#### get_config
Access Laravel configuration settings.

### Redis Tools

#### redis_get
Retrieve a value from Redis cache.
```
redis_get({ key: "user:123" })
```

#### redis_set
Store a value in Redis cache with optional TTL.
```
redis_set({ key: "user:123", value: "John Doe", ttl: 3600 })
```

#### redis_delete
Delete one or more keys from Redis.
```
redis_delete({ key: "user:123" })
```

#### redis_keys
Find keys matching a pattern.
```
redis_keys({ pattern: "cache:*" })
```

#### redis_exists
Check if a key exists in Redis.
```
redis_exists({ key: "user:123" })
```

#### redis_flush_db
Clear all data in the current Redis database (use with caution).
```
redis_flush_db({})
```

## Environment Variables

### Required
- `APP_NAME` - Application name (default: kaipa)
- `DB_HOST` - Database host (default: db)
- `DB_PORT` - Database port (default: 3306)
- `APP_PORT` - Application port (default: 8181)

### Optional (Redis)
- `REDIS_HOST` - Redis server host (default: redis)
- `REDIS_PORT` - Redis server port (default: 6379)
- `REDIS_PASSWORD` - Redis authentication password (optional)
- `REDIS_DB` - Redis database number (default: 0)

## Docker Integration

This MCP service communicates with your Laravel API and Redis running in Docker:

- **Laravel Container Pattern**: `{APP_NAME}_{APP_ENV}_php`
  - Default: `kaipa_local_php`
- **Redis Container**: `redis` service
  - Default connection: `redis:6379`

Make sure your Docker containers are running:

```bash
docker-compose up -d
```

## Usage in Cursor

Once configured, you can:

1. **View API routes**: `@laravel://routes`
2. **List models**: `@laravel://models`
3. **Run migrations**: Execute `artisan_command` with migrate
4. **Access configuration**: `@laravel://config`
5. **Manage Redis cache**: Use Redis tools for cache operations
6. **Monitor cache keys**: Use `redis_keys` with patterns

### Example Redis Operations

**Cache user data:**
```
redis_set({ key: "user:123:data", value: "{\"id\":123,\"name\":\"John\"}", ttl: 86400 })
```

**Retrieve cached data:**
```
redis_get({ key: "user:123:data" })
```

**Find all session keys:**
```
redis_keys({ pattern: "session:*" })
```

**Clear cache on deploy:**
```
redis_flush_db({})
```

## Troubleshooting

- **Docker connection error**: Ensure Docker daemon is running and containers are active
- **Redis not available**: Check if Redis container is running. MCP continues to work without Redis
- **Command timeout**: Verify Laravel container is responding
- **Route list empty**: Verify Laravel application is properly initialized

## Project Structure

```
/var/www/ai-tools/mcp-laravel-api-kaitori/
├── src/
│   ├── server.ts              # MCP server with Laravel & Redis
│   ├── services/
│   │   └── redis.service.ts   # Redis client wrapper
│   └── index.ts               # Exports
├── dist/                      # Compiled JavaScript
├── .cursor/
│   └── rules.mcp.json         # Cursor MCP config
├── docs/
│   └── laravel_setup/         # Laravel Docker config
├── package.json               # Dependencies
├── tsconfig.json              # TypeScript config
└── README.md                  # This file
```

## Development

### Build changes
```bash
npm run build
```

### Test server startup
```bash
timeout 3 npm start || echo "Server working"
```

### Install new packages
```bash
npm install <package-name>
npm run build
```

## Contributing

When adding new features:

1. Add tool definitions to `ListToolsRequestSchema`
2. Implement tool logic in `CallToolRequestSchema`
3. Run `npm run build` to verify TypeScript
4. Test with `npm start`