MCPDB - Database Access MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview MCPDB is a Laravel 12 application that serves as an MCP (Model Context Protocol) Server, providing Claude Desktop with secure access to multiple database connections. The application features a complete web-based management interface for configuring database connections and exposes two main MCP tools for database interaction. The application uses PHP 8.2+ with TailwindCSS for styling and Vite for asset building. The project is configured to use MariaDB as the default database and includes full Docker support via Laravel Sail. ### Core Functionality - **MCP Server**: Complete implementation of the Model Context Protocol with JSON-RPC support - **Database Connection Management**: Web-based CRUD interface for managing database connections - **Multi-Database Support**: Supports MySQL, PostgreSQL, SQLite, and SQL Server databases - **Two MCP Tools**: - `list_connections`: Lists all active database connections - `execute_sql`: Executes SQL queries on specified database connections - **Session Management**: Proper MCP session handling with UUID-based session tracking - **Security**: Database credentials stored securely, only active connections exposed to MCP - **Error Handling**: Comprehensive error handling for both web interface and MCP protocol ## Development Commands ### Core Laravel Commands - `./vendor/bin/sail artisan serve` - Start the development server - `./vendor/bin/sail artisan migrate` - Run database migrations - `./vendor/bin/sail artisan migrate:fresh --seed` - Reset database with fresh migrations and seed data - `./vendor/bin/sail artisan tinker` - Interactive PHP REPL with Laravel context - `./vendor/bin/sail artisan config:clear` - Clear configuration cache - `./vendor/bin/sail artisan route:list` - List all registered routes ### Testing - `composer test` - Run all tests (clears config cache first) - `./vendor/bin/sail artisan test` - Run PHPUnit tests directly - `./vendor/bin/sail artisan test --filter TestName` - Run specific test - `./vendor/bin/phpunit tests/Unit/ExampleTest.php` - Run single test file ### Code Quality - `./vendor/bin/pint` - Format code using Laravel Pint (PSR-12 style) - `./vendor/bin/pint --test` - Check code formatting without making changes ### Asset Building - `npm run dev` - Start Vite development server with hot reload - `npm run build` - Build assets for production ### Docker Development - `./vendor/bin/sail up` - Start Docker containers (MySQL + MariaDB) - `./vendor/bin/sail down` - Stop Docker containers - `./vendor/bin/sail artisan` - Run artisan commands in container - `./vendor/bin/sail test` - Run tests in container ### Full Development Environment - `composer dev` - Start complete development stack (server, queue, logs, vite) using concurrently ## Architecture ### Directory Structure - `app/Models/SubjectConnection.php` - Database connection model with query execution - `app/Http/Controllers/ConnectionController.php` - Web CRUD interface for connections - `app/Http/Controllers/McpController.php` - MCP server implementation (JSON-RPC) - `resources/views/connections/` - Blade templates for connection management - `routes/web.php` - Web routes including MCP endpoints - `database/migrations/` - Including subject_connections table migration - `tests/` - PHPUnit tests (Feature/ and Unit/ directories) ### Key Files - `README.md` - Complete installation and usage instructions - `CLAUDE.md` - Development guidance (this file) - `composer.json` - PHP dependencies and custom scripts - `package.json` - Frontend dependencies including @modelcontextprotocol/sdk - `vite.config.js` - Asset bundling configuration with TailwindCSS - `docker-compose.yml` - Laravel Sail configuration with MariaDB - `.env.example` - Environment configuration template - `mcp-bridge.sh` - Bridge script for stdio-to-HTTP communication (optional) ### Database Schema - `subject_connections` table stores database connection configurations: - `connection_name` (unique identifier) - `driver` (mysql, pgsql, sqlite, sqlsrv) - `host`, `port`, `database`, `username`, `password` - `description`, `is_active` (boolean) - Standard Laravel timestamps ### MCP Integration - **Protocol**: Uses mcp-remote with HTTP transport - **Endpoints**: `POST /mcp` for JSON-RPC, `GET /mcp` for SSE (placeholder) - **Tools**: `list_connections` and `execute_sql` - **Configuration**: Claude Desktop connects via `npx mcp-remote http://localhost:8000/mcp` - **Session Management**: UUID-based sessions stored in Laravel Cache ### Frontend Stack - TailwindCSS for responsive styling - Vite for asset bundling and hot reload - Laravel Blade templating engine - No JavaScript frameworks - pure HTML forms for simplicity