README

🚀 Transform your Laravel database into AI-powered analytics dashboards
Expose your database as an MCP (Model Context Protocol) server and let AI assistants like Claude, ChatGPT, Cursor, and Windsurf generate live, interactive analytics dashboards from natural language — zero manual schema work required.

✨ Features

🤖 AI-Powered Generation - Generate dashboards using natural language prompts
🔒 OAuth 2.1 + PKCE - Secure authentication with RFC compliance (7591, 8414, 9728)
📊 Live Data Visualization - Interactive charts, KPIs, and tables with real-time data
🎨 Glassmorphism UI - Modern, responsive design with dark/light themes
🔐 Access Control - Public/private dashboards with user management
🛠️ Manager UI - Full CRUD, audit logs, and bulk operations
🧪 Comprehensive Testing - Extensive test coverage for reliability
🔌 Extensible Architecture - Customize via interfaces and configuration

📋 Requirements

Dependency	Version	Description
PHP	≥ 8.2	Core language
Laravel	≥ 11.x	Framework (11, 12, or 13)
laravel/passport	≥ 13.x	OAuth 2.1 server
laravel/mcp	≥ 0.1	MCP protocol implementation

📦 Installation

Step 1: Register Repository

Add to your host app composer.json:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/webbycrown/mcp-dashboard-studio"
    }
]

Step 2: Install Package

composer require webbycrown/mcp-dashboard-studio:dev-main

Step 3: Install Laravel Passport

php artisan install:api --passport
php artisan passport:client

Step 4: Update User Model

use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

Step 5: Add API Guard

// config/auth.php
'guards' => [
    'web' => ['driver' => 'session', 'provider' => 'users'],
    'api' => ['driver' => 'passport', 'provider' => 'users'],
],

Step 6: Trust Proxy Headers

Required for ngrok, Nginx, or Cloudflare:

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

Step 7: Publish Assets (Optional)

php artisan vendor:publish --tag=mcp-dashboard-studio-config
php artisan vendor:publish --tag=mcp-dashboard-studio-assets
php artisan vendor:publish --tag=mcp-dashboard-studio-migrations
php artisan vendor:publish --tag=mcp-dashboard-studio-views

Step 8: migrate tables

php artisan migrate

Step 9: Set Environment Variables

APP_URL=https://your-public-domain.com
MCP_DATA_MODE=database
MCP_DB_ENABLED=true
MCP_DB_CONNECTION=mysql
MCP_OAUTH_ENABLED=true
MCP_OAUTH_LOGIN_ROUTES=true
MCP_REQUIRE_ADMIN_CONSENT=false

Step 10: Connect Your AI Tool (e.g., ChatGPT)

You have two ways to connect your AI client to your live server:

Method A: Static API Key (Recommended & Easiest)

This method bypasses OAuth and works even if your server blocks hidden directories.

Set a secure MCP_SECRET_TOKEN in your .env (e.g., MCP_SECRET_TOKEN=my_secure_key_123).
Run php artisan config:clear.
In ChatGPT's "Add App" or "Connectors" setup, set Authentication to API Key.
Set Auth Type to Bearer.
Paste your MCP_SECRET_TOKEN into the API Key box.

Method B: Full OAuth (Requires Login Popup)

If you want to use standard OAuth, you must generate a real Client ID and Secret:

Run php artisan passport:client.
Name it "ChatGPT" and provide the Callback URL shown in the ChatGPT UI.
In ChatGPT, select OAuth for Authentication.
If your server supports auto-discovery, it will connect automatically. If auto-discovery fails (e.g., Nginx blocks .well-known), enter the endpoints manually:
- Authorization URL: https://your-domain.com/oauth/authorize
- Token URL: https://your-domain.com/oauth/token
Paste the Client ID and Client Secret generated by Passport into the ChatGPT UI. (Do NOT use your MCP_SECRET_TOKEN here).

Step 11: Set ai models to use this mcp API

Configure config/mcp-dashboard-studio.php

allowed_redirect_domains' => [
    'claude.ai',
    'chatgpt.com',
    'cursor.com'
]

Step 12: Configure instruction

Configure some instructions about the site and database like domain,relationships etc.so any AI tool easily understand your site and db structure.

🚀 Quick Start

After installation, here's how to access and manage your dashboards:

Access Dashboard Manager

Visit the manager panel to view and manage all dashboards:

https://your-domain.com/mcp-manager/dashboards

Default URL Structure:

Manager Panel: /{prefix}/dashboards (default: /mcp-manager/dashboards)
View Dashboard: /{prefix}/dashboard-studio/{slug} (default: /dashboard-studio/{slug})
MCP API: /{prefix}/mcp/generate-dashboard (default: /mcp/generate-dashboard)

Manager Features

The manager UI provides full CRUD operations:

Action	URL	Description
List All Dashboards	`/mcp-manager/dashboards`	View all dashboards with search & filter
View Dashboard	`/dashboard-studio/{slug}`	Interactive live dashboard
Edit Dashboard	`/mcp-manager/dashboards/{uuid}/edit`	Modify name, status, layout
Delete Dashboard	`/mcp-manager/dashboards/{uuid}` (DELETE)	Move to trash
Access Control	`/mcp-manager/dashboards/{uuid}/access`	Manage who can view/edit
Audit Log	`/mcp-manager/dashboards/{uuid}/audit`	View access history
Export	`/mcp-manager/dashboards/{uuid}/export`	Download as JSON
Trash	`/mcp-manager/dashboards/trash`	Restore or permanently delete

Quick Access Links

Once logged into the manager, you can:

View Dashboard - Click the dashboard name or "View" button to see the live interactive dashboard
Edit Settings - Change dashboard name, description, or visibility (public/private)
Manage Access - Grant/revoke access for system users or invite external users via email
Clone Dashboard - Duplicate an existing dashboard as a template
Bulk Actions - Select multiple dashboards to delete or change status
Import/Export - Backup dashboards or migrate between environments

Dashboard Status

Each dashboard has a status:

Private - Only accessible to creator and explicitly granted users
Public - Viewable by anyone with the link (no login required)

User Access Types

System Users (from your Laravel users table):

Grant access via the manager UI
Users must log in to view private dashboards
Can be granted view or edit permissions

Custom Users (external invites):

Receive a unique tokenized link via email
No Laravel account required
Link can be set to expire after X days
Password-protected access

Example Workflow

# 1. Generate a dashboard via AI (e.g., ChatGPT, Claude)
# The AI calls your MCP endpoint and returns a dashboard

# 2. View all your dashboards
https://your-domain.com/mcp-manager/dashboards

# 3. Click on a dashboard to view it live
https://your-domain.com/dashboard-studio/sales-overview-2024

# 4. Edit or share access
https://your-domain.com/mcp-manager/dashboards/{uuid}/edit
https://your-domain.com/mcp-manager/dashboards/{uuid}/access

Tips

Bookmark the manager URL for quick access
Use public status for dashboards you want to share widely
Use private status with custom user invites for client/shareable links
Enable audit logging to track who accessed what and when
Set token expiry for custom users to automatically revoke access after a period

⚙️ Configuration

Optional Environment Variables

# Core
MCP_ENABLED=true
MCP_MANAGER_ENABLED=true
MCP_MANAGER_REQUIRE_ADMIN=false
MCP_MANAGER_PREFIX=mcp-manager

# OAuth
MCP_REQUIRE_ADMIN_CONSENT=false
MCP_TOKEN_TTL_DAYS=30
MCP_REFRESH_TOKEN_TTL_DAYS=90

# Routes
MCP_ROUTE_PREFIX=
MCP_DASHBOARD_PREFIX=dashboard-studio
MCP_PATH=mcp/generate-dashboard

# Database
MCP_DATA_MODE=schema
MCP_DB_ENABLED=false
MCP_MAX_TABLES=100
MCP_MAX_COLUMNS=8
MCP_MAX_QUERY_LIMIT=100

# Logging
MCP_LOGGING_ENABLED=false

🏗️ Architecture

Dashboard Generation Pipeline

User Prompt
    ↓
Enhanced Prompt Analyzer
    ↓
Dashboard Planner (Explicit Plan)
    ↓
Dashboard Spec Builder
    ↓
Data Source Resolver (Live DB Hydration)
    ↓
Dashboard Validator
    ↓
Layout Engine
    ↓
HTML Renderer
    ↓
Interactive Dashboard

Key Components

DashboardPlanner - Creates explicit plans before construction
DashboardGenerator - Orchestrates the entire pipeline
DatabaseProvider - Handles SQL generation with driver support
ComponentGenerators - KPI, Chart, Table, Filter generators
MCP Tools - 6 tools for different generation scenarios

🎨 CSS Customization

Publishing Assets

To customize the package CSS, publish the assets:

php artisan vendor:publish --tag=mcp-dashboard-studio-assets

This copies files to:

public/mcp-dashboard-studio/assets/
├── css/
│   ├── style.css          # Main dashboard styles
│   ├── alerts.css         # Alert component styles
│   ├── bulk-actions.css   # Bulk action styles
│   └── manager.css        # Manager UI styles
└── js/
    └── app.js             # JavaScript functionality

View Customization

Publish views to override templates:

php artisan vendor:publish --tag=mcp-dashboard-studio-views

Views are published to:

resources/views/vendor/mcp-dashboard-studio/

🛡️ Security

OAuth 2.1 + PKCE Flow

The package implements full OAuth 2.1 with PKCE:

RFC 7591 - Dynamic client registration
RFC 8414 - OAuth server metadata
RFC 9728 - Protected resource metadata

Security Features

Feature	Description
🔐 Token Validation	OAuth Bearer + Static token support
🛡️ SQL Injection Protection	Parameterized queries with limits
🚫 Domain Allowlist	Restrict OAuth client registration
⏱️ Rate Limiting	10 registrations/minute on `/oauth/register`
🔒 HTTPS Enforcement	Rejects HTTP in production
👤 Access Control	Public/private dashboard permissions
📝 Audit Logging	Track all dashboard operations

Best Practices

Always use HTTPS in production
Set strong MCP_SECRET_TOKEN for non-OAuth clients
Configure domain allowlist for OAuth registration
Enable admin consent for sensitive environments
Regularly review audit logs in manager UI
Keep dependencies updated for security patches

💾 Database Requirements

Supported Databases

✅ MySQL / MariaDB
✅ PostgreSQL
✅ SQLite

Performance Considerations

Query Limits: Configurable via MCP_MAX_QUERY_LIMIT (default: 100 rows)
Table Discovery: Limited to MCP_MAX_TABLES (default: 100)
Column Limits: Maximum MCP_MAX_COLUMNS per table (default: 8)
Caching: Schema caching with TTL (default: 3600 seconds)

Large Dataset Handling

For databases with millions of rows:

Enable schema mode: MCP_DATA_MODE=schema
Increase query limits cautiously
Use database indexes on frequently queried columns
Consider read replicas for dashboard queries

⚠️ Limitations

Limitation	Default	Configurable
Tables discovered	100	`MCP_MAX_TABLES`
Columns per table	8	`MCP_MAX_COLUMNS`
Query result rows	100	`MCP_MAX_QUERY_LIMIT`
Token TTL	30 days	`MCP_TOKEN_TTL_DAYS`
Refresh token TTL	90 days	`MCP_REFRESH_TOKEN_TTL_DAYS`

Known Constraints

Complex JOIN queries require manual configuration
Custom SQL queries not supported (use views instead)
Real-time streaming not available (AJAX polling only)
Multi-tenant databases need connection configuration

📊 Examples & Use Cases

Sales Dashboard

Prompt:

"Show me sales overview with revenue by month, top 10 products, and regional breakdown"

Result:

📈 Line chart: Monthly revenue trend
🏆 Bar chart: Top 10 products by sales
🗺️ Pie chart: Regional distribution
📋 Data table: Recent transactions

HR Analytics

Prompt:

"Create HR dashboard showing employee count by department, hiring trends, and turnover rate"

Result:

👥 KPI cards: Total employees, new hires, turnover
📊 Bar chart: Employees by department
📈 Line chart: Hiring trends over time
📉 Gauge: Turnover rate

Inventory Management

Prompt:

"Build inventory dashboard with stock levels, low stock alerts, and category breakdown"

Result:

📦 KPI cards: Total items, low stock count, total value
🚨 Alert cards: Low stock warnings
📊 Pie chart: Inventory by category
📋 Table: Stock levels with filters

🌐 Deployment

Production Checklist

Set APP_URL to public domain
Configure HTTPS with valid SSL certificate
Set strong MCP_SECRET_TOKEN
Configure OAuth domain allowlist
Enable rate limiting
Set appropriate token TTL values
Configure database connection for production
Enable audit logging
Test OAuth flow with AI tools
Review and restrict table access

Scaling Considerations

Database: Use read replicas for dashboard queries
Caching: Enable Redis for session and schema cache
Load Balancing: Ensure sticky sessions for OAuth flow
CDN: Serve published assets via CDN
Monitoring: Track dashboard generation performance

🧪 Testing

Run Tests

cd vendor/webbycrown/mcp-dashboard-studio
vendor/bin/phpunit

Test Coverage

The package includes comprehensive tests:

✅ OAuth Flow - Dynamic registration, discovery, login
✅ Dashboard Generation - Pipeline, planner, generator
✅ Database Provider - SQL generation, aggregates, charts
✅ MCP Tools - Tool validation and execution
✅ Security - SQL injection, unauthorized access

Test Files

DynamicClientRegistrationTest.php - RFC 7591 compliance
OAuthDiscoveryTest.php - RFC 8414/9728 compliance
OAuthLoginTest.php - Login flow validation
VerifyMcpTokenTest.php - Token validation
DashboardPlannerTest.php - Planning phase
DashboardGeneratorTest.php - Generation pipeline
DatabaseProviderTest.php - SQL generation
McpDashboardToolTest.php - MCP tool execution
SecurityTest.php - Security vulnerabilities

🛠️ Troubleshooting

Common Issues

OAuth Warning in Logs

Problem: [MCP] OAuth 2.1 is DISABLED: Laravel Passport is not installed

Solution:

composer require laravel/passport
php artisan migrate
php artisan passport:install --uuids
php artisan passport:keys

Invalid Client Error

Problem: {"error":"invalid_client","error_description":"Client authentication failed"} when returning from the login screen.

Solution: You likely put your MCP_SECRET_TOKEN into the "OAuth Client Secret" box in the AI tool. The MCP_SECRET_TOKEN is only for API Key authentication. For OAuth, you must generate a real client secret using php artisan passport:client --confidential and use that instead.

Nginx 404 on OAuth Discovery

Problem: ChatGPT reports does not implement OAuth or returns a 404 for /.well-known/oauth-authorization-server.

Solution: Your Nginx server is blocking access to hidden directories (directories starting with a dot). Update your Nginx configuration to allow the .well-known directory:

location ~ /\.(?!well-known).* {
    deny all;
}

Alternatively, bypass OAuth discovery by entering the Auth/Token URLs manually in the AI client, or use the API Key method instead.

Session Store Not Set

Problem: Session store not set on request

Solution: Ensure package is updated (fixed in latest version)

Dashboard Shows No Data

Problem: Dashboard renders but shows empty data

Solution: Set MCP_DB_ENABLED=true and MCP_DATA_MODE=database

Manager Returns 503

Problem: Manager UI unavailable

Solution: Set MCP_MANAGER_ENABLED=true in .env

Assets Missing

Problem: CSS/JS not loading

Solution: Publish assets:

php artisan vendor:publish --tag=mcp-dashboard-studio-assets

Debug Mode

Enable verbose logging:

MCP_LOGGING_ENABLED=true

Check logs at:

tail -f storage/logs/laravel.log

❓ FAQ

Q: Can I use this without OAuth?

A: Yes! Set MCP_OAUTH_ENABLED=false and use MCP_SECRET_TOKEN for authentication.

Q: Does this work with any database?

A: It supports MySQL, PostgreSQL, and SQLite. Other databases may work but aren't officially tested.

Q: Can I customize the dashboard design?

A: Yes! Publish the assets and views, then modify CSS and Blade templates to match your brand.

Q: Is my data secure?

A: The package uses parameterized queries, access controls, and OAuth 2.1. However, always review your security settings and follow best practices.

Q: Can I limit which tables AI can access?

A: Yes! Configure excluded or whitelisted tables in config/mcp-dashboard-studio.php.

Q: How do I add custom authentication?

A: Implement the NlpClientInterface and bind it in a service provider.

Q: Can I use this in multi-tenant applications?

A: Yes, but you'll need to configure database connections per tenant.

📚 Documentation

DOCUMENTATION.md - Full technical reference (architecture, pipeline, security, config)
CHANGELOG.md - Release history and version notes

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Ensure all tests pass (vendor/bin/phpunit)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

git clone https://github.com/webbycrown/mcp-dashboard-studio.git
cd mcp-dashboard-studio
composer install
cp .env.example .env
php artisan key:generate
vendor/bin/phpunit

Code Style

Follow PSR-12 coding standards
Add tests for new features
Update documentation as needed
Keep commits clear and focused

📄 License

🙏 Acknowledgments

Built with Laravel
OAuth implementation via Laravel Passport
MCP protocol by Anthropic
Charts powered by Chart.js

📞 Support

⭐ If you find this package helpful, please consider giving it a star on GitHub!

Made with ❤️ by Webbycrown

webbycrown / mcp-dashboard-studio

Maintainers

Package info

Statistics

Security

README

✨ Features

📋 Requirements

📦 Installation

Step 1: Register Repository

Step 2: Install Package

Step 3: Install Laravel Passport

Step 4: Update User Model

Step 5: Add API Guard

Step 6: Trust Proxy Headers

Step 7: Publish Assets (Optional)

Step 8: migrate tables

Step 9: Set Environment Variables

Step 10: Connect Your AI Tool (e.g., ChatGPT)

Method A: Static API Key (Recommended & Easiest)

Method B: Full OAuth (Requires Login Popup)

Step 11: Set ai models to use this mcp API

Step 12: Configure instruction

🚀 Quick Start

Access Dashboard Manager

Manager Features

Quick Access Links

Dashboard Status

User Access Types

Example Workflow

Tips

⚙️ Configuration

Optional Environment Variables

🏗️ Architecture

Dashboard Generation Pipeline

Key Components

🎨 CSS Customization

Publishing Assets

View Customization

🛡️ Security

OAuth 2.1 + PKCE Flow

Security Features

Best Practices

💾 Database Requirements

Supported Databases

Performance Considerations

Large Dataset Handling

⚠️ Limitations

Known Constraints

📊 Examples & Use Cases

Sales Dashboard

HR Analytics

Inventory Management

🌐 Deployment

Production Checklist

Scaling Considerations

🧪 Testing

Run Tests

Test Coverage

Test Files

🛠️ Troubleshooting

Common Issues

OAuth Warning in Logs

Invalid Client Error

Nginx 404 on OAuth Discovery

Session Store Not Set

Dashboard Shows No Data

Manager Returns 503

Assets Missing

Debug Mode

❓ FAQ

Q: Can I use this without OAuth?

Q: Does this work with any database?

Q: Can I customize the dashboard design?

Q: Is my data secure?

Q: Can I limit which tables AI can access?

Q: How do I add custom authentication?

Q: Can I use this in multi-tenant applications?

📚 Documentation

🤝 Contributing