Quartet MCP Server

A custom Model Context Protocol (MCP) server designed specifically for the Quartet Laravel/Vue.js admin project. This server provides powerful tools for rapid development, reducing errors, and improving productivity.

Features

🚀 Laravel Tools

• Migration Management: Create, modify, and manage database migrations
• Model Generation: Generate Eloquent models with relationships, scopes, and traits
• Controller Creation: Create controllers with CRUD operations and Inertia.js support

🎨 Vue.js/Inertia.js Tools

• Component Generation: Create Vue components with ShadCN UI integration
• Template Types: Support for CRUD, forms, lists, and custom templates
• TypeScript Support: Full TypeScript integration for type safety

🗄️ Database Tools

• Migration Operations: Run, rollback, and manage migrations
• Seeder Management: Create and run database seeders
• Status Monitoring: Check migration and database status

🧪 Testing Tools

• Test Generation: Create feature and unit tests
• Test Execution: Run individual tests or test suites
• Test Templates: Pre-configured test templates for common scenarios

🔧 Project Helper Tools

• Status Checking: Monitor project health and configuration
• Build Management: Frontend building and type checking
• Cache Management: Clear and optimize project caches
• Route & Config Checking: Verify routes and configuration

🌐 Port Verification Tools

• Port Management: Check and manage required ports (web, vite, database)
• Process Control: Force kill processes occupying required ports
• Service Verification: Verify that all required services are running
• Environment Integration: Automatically read port numbers from .env file

Installation

1. Clone/Setup: The MCP server is already set up in /Volumes/Data/Projects/_PROD/quartetmcp/

2. Install Dependencies:

   cd /Volumes/Data/Projects/_PROD/quartetmcp
   npm install

3. Build the Server:

   npm run build

4. Configure Cursor: The server is already configured in your Cursor MCP settings at /Users/ahmed/.cursor/mcp.json

Developer Instructions

Starting the MCP Server

Option 1: Development Mode (Recommended for Development)

cd /Volumes/Data/Projects/_PROD/quartetmcp
npm run dev

This runs the server in development mode with TypeScript directly using tsx, which provides faster startup and better error reporting.

Option 2: Production Mode

cd /Volumes/Data/Projects/_PROD/quartetmcp
npm run build
npm start

This compiles TypeScript to JavaScript first, then runs the compiled version.

Option 3: Watch Mode (Auto-restart on Changes)

cd /Volumes/Data/Projects/_PROD/quartetmcp
npm run watch

This runs the server in watch mode, automatically restarting when you make changes to the source code.

Running the MCP Server

1. Start the Server: Choose one of the options above
2. Verify it's Running: You should see the message "Quartet MCP server running on stdio"
3. Test in Cursor: The server will be available to Cursor through the MCP protocol

Development Workflow

1. Make Changes: Edit files in the src/ directory
2. Auto-restart: If using npm run watch, the server will restart automatically
3. Manual Restart: If using npm run dev, stop the server (Ctrl+C) and restart
4. Test Changes: Use Cursor to test your MCP tools

Troubleshooting Development Issues

Server Won't Start:

# Check if dependencies are installed
npm install

# Check for TypeScript errors (noEmit is now default)
npx tsc

# Run with verbose output
npm run dev -- --verbose

Changes Not Reflecting:

• If using npm run dev, restart the server
• If using npm run watch, wait for auto-restart
• If using npm start, rebuild first: npm run build

Cursor Not Connecting:

• Restart Cursor after making changes to the MCP server
• Check the MCP configuration in /Users/ahmed/.cursor/mcp.json
• Verify the server is running and shows "Quartet MCP server running on stdio"

Usage

Once configured, you can use the MCP server tools directly in Cursor. Here are some examples:

Create a Laravel Migration

Create a migration for a new table called 'mo_products' with columns: id (bigint, primary), name (string), description (text), price (decimal), created_at, updated_at

Generate a Laravel Model

Create a MoProduct model with fillable fields: name, description, price. Add a scope for 'active' products and a relationship to categories.

Create a Vue Component

Create a Vue component called 'ProductManagement' as a CRUD page with fields: name, description, price, category_id. Use ShadCN components and TypeScript.

Database Operations

Run all pending migrations and then seed the database with sample data.

Project Status

Check the current project status including Laravel version, PHP version, migration status, and cache status.

Port Management

Check if the required ports (8000, 5173, 3306) are available and kill any processes using them

Verify that all services (Laravel web server, Vite dev server, database) are running on their designated ports

Available Tools

Laravel Tools

• laravel_migration: Create and manage database migrations
• laravel_model: Generate Eloquent models with relationships and scopes
• laravel_controller: Create controllers with CRUD operations

Vue.js Tools

• vue_component: Generate Vue components with various templates

Database Tools

• database_operation: Perform database operations (migrate, seed, etc.)

Testing Tools

• test_operation: Create and run tests

Project Helper Tools

• project_helper: Project maintenance and status checking

Port Verification Tools

• quartet_verify_ports: Check and manage ports for Quartet services

Development

Project Structure

quartetmcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── tools/                # Tool implementations
│   │   ├── laravel-migration.ts
│   │   ├── laravel-model.ts
│   │   ├── laravel-controller.ts
│   │   ├── vue-component.ts
│   │   ├── database.ts
│   │   ├── test.ts
│   │   ├── project-helper.ts
│   │   └── port-verification.ts
│   ├── types/                # TypeScript type definitions
│   └── utils/                # Utility functions
├── docs/                     # Documentation files
│   ├── DEVELOPER_GUIDE.md    # Comprehensive developer guide
│   ├── TOOLS_REFERENCE.md    # Quick reference for all tools
│   ├── PORT_CONFIGURATION.md # Port configuration guide
│   └── PUBLISHING_GUIDE.md   # Publishing and distribution guide
├── scripts/                  # Build scripts
│   └── build-executable.js   # Script to prepare executable
├── dist/                     # Compiled JavaScript
├── executables/              # Standalone executables (generated)
├── package.json
├── tsconfig.json            # TypeScript config (noEmit default)
├── tsconfig.build.json      # Build config (emits files)
└── README.md

Adding New Tools

1. Create a new tool file in src/tools/
2. Implement the tool class with getToolDefinition() and execute() methods
3. Add the tool to the imports and tool list in src/index.ts
4. Rebuild the server with npm run build

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run start: Run the compiled server
• npm run dev: Run the server in development mode with tsx
• npm run watch: Watch for changes and restart automatically

Configuration

The MCP server is configured to work with the Quartet project located at /Volumes/Data/Projects/_PROD/admin/. All tools are pre-configured with the correct paths and settings for this project.

Installation & Usage

Quick Start (npx - No Installation Required)

# Use directly without installation
npx quartetmcp

Global Installation

# Install globally
npm install -g quartetmcp

# Run the server
quartetmcp

Local Installation

# Install in your project
npm install quartetmcp

# Run with npx
npx quartetmcp

Development Build

# Build for development
npm run build:all

# Test the build
node test-build.js

Distribution

For End Users

Quick Install (Recommended):

# One-line installation
curl -sSL https://raw.githubusercontent.com/your-org/quartetmcp/main/install.sh | bash

# Or run directly
npx quartetmcp

Manual Installation:

# Global installation
npm install -g quartetmcp
quartetmcp

# Or local installation
npm install quartetmcp
npx quartetmcp

For Developers

Publishing to NPM:

# Build and test
npm run build:all
node test-build.js

# Publish
npm publish

Creating GitHub Release:

# Tag and push
git tag v1.0.0
git push origin v1.0.0

Documentation

• Developer Guide: Comprehensive guide for developers working on the MCP server
• Tools Reference: Quick reference for all available tools and their parameters
• Port Configuration: Guide for configuring and managing development ports
• Distribution Guide: Complete guide for distributing the MCP server to users

Troubleshooting

Server Not Starting

1. Check that Node.js is installed and accessible
2. Verify the build completed successfully (npm run build)
3. Check the Cursor MCP configuration in /Users/ahmed/.cursor/mcp.json

Tools Not Working

1. Ensure you're in the correct project directory
2. Check that Laravel and npm dependencies are installed
3. Verify file permissions for the project directory

Build Errors

1. Run npm install to ensure all dependencies are installed
2. Check TypeScript configuration in tsconfig.json
3. Verify all imports and exports are correct

Contributing

To add new features or fix issues:

1. Make changes to the TypeScript source files
2. Run npm run build to compile
3. Test the changes in Cursor
4. Update this README if needed

License

MIT License - See LICENSE file for details.