Luxp MCP Server

Model Context Protocol (MCP) server for Luxury Presence luxp CLI tools. This MCP server enables AI assistants like Claude to interact with luxp's local development environment management tools.

Features

This MCP server provides minimal-context, efficient access to luxp CLI commands through a single flexible tool:

• Local Development: Service orchestration, environment health checks, SSL generation
• Database Management: PostgreSQL and Redis operations
• Stack Management: Git-spice integration for branch stacking workflows
• Worktree Management: Create, list, and manage git worktrees
• AI-Powered Tools: Claude Code proxy and code review with CodeRabbit

Installation

Using npx (Recommended)

Add the MCP server to your Claude desktop configuration:

claude mcp add --transport stdio luxp-server -- npx -y @luxury-presence/luxp-mcp

Manual Installation

1. Install globally:

npm install -g @luxury-presence/luxp-mcp

2. Add to your Claude desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "luxp-server": {
      "command": "luxp-mcp",
      "transport": {
        "type": "stdio"
      }
    }
  }
}

Prerequisites

• Node.js >= 18.0.0
• luxp CLI installed and configured
• Configured luxp local environment (luxp local init)

Available Tool

luxp

Single, flexible tool that executes any luxp command. The tool accepts an array of command arguments.

Parameters:

• args (array of strings, required): Command arguments (e.g., ['local', 'start', 'database.postgres'])

MCP Server Instructions

This MCP server provides prompts that instruct Claude about when to automatically use luxp tools. This means Claude will:

1. Automatically detect when users ask about local development tasks
2. Translate natural language requests into appropriate luxp commands
3. Use the tool proactively without requiring users to mention "luxp" or "MCP"

Common phrases that trigger automatic luxp usage:

• "What's running?" → luxp local list services
• "Start postgres" → luxp local start database.postgres --detached
• "Check environment" → luxp local doctor
• "Show logs" → luxp local logs

This makes the MCP integration seamless and user-friendly.

Command Reference

Local Development Commands

Environment Setup

• luxp local init - Initial setup for local environments
• luxp local install - Install local environment dependencies
• luxp local doctor - Check environment health (Node, Docker, process-compose, services)
• luxp local clean - Clean up all services and reset environment

Service Management

• luxp local start <resource> [name] [--detached] - Start a service
  • Resources: database.postgres, database.redis, template, k8s.service
  • Example: ['local', 'start', 'database.postgres']
• luxp local stop [resource] [name] [--clean] - Stop service(s)
  • Omit resource to stop all services
• luxp local list <resource> - List templates or services
  • Resources: template, templates, service, services
• luxp local logs [services...] - Stream service logs
• luxp local refresh database [database] - Refresh database image

SSL Management

• luxp local ssl [hostname] - Generate SSL certificate

Database Commands

PostgreSQL

• luxp local db up [database] - Start postgres (default: main)
• luxp local db down [database] - Stop postgres
• luxp local db pull [database] - Pull database image

Redis

• luxp local redis up [database] - Start redis
• luxp local redis down [database] - Stop redis

Stack Management (Git-Spice Integration)

Stack Operations

• luxp local stack init [trunk] - Initialize repository (default trunk: main)
• luxp local stack restack [--branch branch] - Restack a stack
• luxp local stack submit - Submit a stack (supports --dry-run, --draft, --force, etc.)
• luxp local stack sync [--no-restack] - Sync a stack
• luxp local stack log - Log a stack (supports --short, --all, --status)
• luxp local stack auth - Store GitHub auth token for git-spice

Branch Management

• luxp local branch track <name> [--base base] - Track a branch
• luxp local branch untrack <name> - Untrack a branch
• luxp local branch create <name> - Create a branch
  • Options: --all, --message, --target, --worktree, --no-verify, --no-commit, --no-install, --insert, --below
• luxp local branch restack [--branch branch] - Restack a branch
• luxp local branch submit - Submit a branch (many options available)
• luxp local branch delete <branches...> [--force] - Delete branches

Worktree Management

• luxp local worktree create <name> [--no-install] - Create a worktree
• luxp local worktree list - List worktrees
• luxp local worktree remove <name> - Remove a worktree
• luxp local worktree open <name> - Open a worktree
  • Options: --claude, --vscode, --cursor, --windsurf

Auggie (AI) Commands

• luxp auggie - Proxy to Claude Code CLI (default action)
• luxp auggie init - Initial setup for Auggie
• luxp auggie version - Show Claude version
• luxp auggie review [--base branch] [--type type] [--prompt-only] - Code review with CodeRabbit
• luxp auggie review auth - Authenticate with CodeRabbit

Usage Examples

Starting a Service

Ask Claude: "Start the postgres database service"

MCP call:

{
  "tool": "luxp",
  "args": {
    "args": ["local", "start", "database.postgres", "--detached"]
  }
}

Checking Environment Health

Ask Claude: "Run luxp doctor to check my environment"

MCP call:

{
  "tool": "luxp",
  "args": {
    "args": ["local", "doctor"]
  }
}

Managing Databases

Ask Claude: "Start the main postgres database"

MCP call:

{
  "tool": "luxp",
  "args": {
    "args": ["local", "db", "up"]
  }
}

Stack Management

Ask Claude: "Submit my current stack as a draft"

MCP call:

{
  "tool": "luxp",
  "args": {
    "args": ["local", "stack", "submit", "--draft"]
  }
}

Worktree Operations

Ask Claude: "Create a worktree named 'feature-x' and open it in Claude"

MCP calls:

{
  "tool": "luxp",
  "args": {
    "args": ["local", "worktree", "create", "feature-x"]
  }
}

{
  "tool": "luxp",
  "args": {
    "args": ["local", "worktree", "open", "feature-x", "--claude"]
  }
}

Design Philosophy

This MCP server is designed for maximum context efficiency and automatic discoverability:

1. Single Tool: One flexible luxp tool instead of many specialized tools
2. Minimal Context: Tool description includes command reference but doesn't bloat context
3. Pass-Through Design: Directly executes luxp commands without translation overhead
4. Comprehensive Coverage: Supports all luxp-local and luxp-auggie commands
5. Smart Discovery: Provides instructions to Claude about when to automatically use the tools

Automatic Tool Usage

The MCP server includes prompts that tell Claude when to automatically use luxp tools. When users ask questions like:

• "What services are running?"
• "Start postgres"
• "Check my environment"
• "Show me the logs"

Claude will automatically recognize these patterns and use the luxp MCP without requiring explicit mentions of "luxp" or "MCP".

This approach minimizes the context window usage while providing full access to luxp's capabilities with smart, automatic tool selection.

Development

Building from Source

# Install dependencies
pnpm install

# Build the server
pnpm --filter @luxury-presence/luxp-mcp build

# Lint
pnpm --filter @luxury-presence/luxp-mcp lint

# Test locally
node apps/luxp-mcp/dist/index.js

Project Structure

apps/luxp-mcp/
├── src/
│   └── index.ts          # MCP server implementation
├── dist/                 # Built output
├── package.json
├── tsconfig.json
├── .eslintrc.js
└── README.md

Troubleshooting

"luxp command not found"

Ensure luxp CLI is installed and available in your PATH:

npm install -g @luxury-presence/luxp-cli

MCP Server Not Connecting

1. Check Claude desktop configuration is valid JSON
2. Verify Node.js version >= 18.0.0
3. Check MCP server logs in Claude desktop app

Command Timeouts

Commands have a 2-minute timeout with a 10MB output buffer. Long-running operations (like database pulls) should complete within this window. If you experience timeouts, the command may need to be run manually.

Contributing

This is part of the luxp-3 monorepo. Please submit issues and PRs to the main repository.

License

ISC