使用说明

Laravel MCP服务器（项目感知）🚀

A. 项目感知模型上下文协议（MCP）服务器 基于Laravel构建，提供具有动态上下文切换的只读数据库访问。非常适合Claude、Cursor和GitHub Copilot等人工智能助手。

✨ 特性

🔄 动态数据库切换 -在多个数据库之间切换而无需重新启动
🔒 按设计只读 -只允许SELECT操作，不允许写访问
🎯 项目意识 -单个服务器实例为多个项目/数据库提供服务
🛡️ 安全第一 -仅结构化查询，无原始SQL，运算符白名单
🤖 人工智能原生 -专为AI助手集成而构建
⚡ 零停机 -无需重新启动服务器即可添加/切换项目

🏗️ 建筑

┌─────────────────┐
│   AI Assistant  │ (Claude, Cursor, Copilot)
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────────────────────────┐
│   Laravel MCP Server (v2.0.0)       │
│   ┌─────────────────────────────┐   │
│   │  DbConnectionResolver       │   │
│   │  (Runtime Connection)       │   │
│   └─────────────────────────────┘   │
│            │                         │
│   ┌────────┴────────┐               │
│   │  Project Config │               │
│   │  mcp_projects   │               │
│   └────────┬────────┘               │
└────────────┼─────────────────────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌─────────┐      ┌─────────┐
│  DB #1  │      │  DB #2  │
│ (MySQL) │      │ (SQLite)│
└─────────┘      └─────────┘

🚀 快速开始

安装

# Clone the repository
git clone <your-repo-url>
cd ohh-mcp

# Install dependencies
composer install

# Configure your first project
cp .env.example .env
php artisan key:generate

配置

添加项目数据库配置 在 config/mcp_projects.php:

return [
    'demo_project' => [
        'driver' => 'sqlite',
        'database' => database_path('database.sqlite'),
        'prefix' => '',
        'foreign_key_constraints' => true,
    ],
    
    'production_project' => [
        'driver' => 'mysql',
        'host' => '127.0.0.1',
        'port' => 3306,
        'database' => 'production_db',
        'username' => 'mcp_reader',
        'password' => 'readonly_password',
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
    ],
];

设置活动项目 在 .ai/project.json:

{
  "mcp_project": "demo_project"
}

启动MCP服务器:

php artisan mcp:serve

📚 可用工具

1. `db_schema_tables`

列出所有数据库表及其注释。

{
  "project": "demo_project"
}

2. `db_schema_table_detail`

获取特定表的详细架构信息。

{
  "project": "demo_project",
  "table": "users"
}

3. `db_select_query`

执行结构化SELECT查询。

{
  "project": "demo_project",
  "table": "users",
  "select": ["id", "name", "email"],
  "where": [["status", "=", "active"]],
  "limit": 10
}

🔒 安全特性

✅ 只读操作 -只允许SELECT查询
✅ 无原始SQL -仅限结构化查询
✅ 操作员白名单 -仅限安全操作员(=, >, <, LIKE等等）
✅ 表/列验证 -根据架构自动验证
✅ 查询限制 -每个查询最多100行
✅ 连接隔离 -每个项目都使用单独的连接

🎯 用例

多项目开发

# Switch between projects without restart
# Just update .ai/project.json

多租户SaaS

// Each tenant gets their own project config
'tenant_123' => [...],
'tenant_456' => [...],

环境隔离

'dev_project' => [...],
'staging_project' => [...],
'production_project' => [...],

🤖 AI助手集成

适用于克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "laravel-db": {
      "command": "php",
      "args": ["artisan", "mcp:serve"],
      "cwd": "/path/to/ohh-mcp"
    }
  }
}

对于光标

添加到MCP设置中：

{
  "mcp": {
    "servers": {
      "laravel-db": {
        "command": "php artisan mcp:serve",
        "cwd": "/path/to/ohh-mcp"
      }
    }
  }
}

📖 文档

升级指南 -从v1.0.0迁移到v2.0.0
AI上下文配置 -AI助手应该如何使用此服务器
Laravel MCP文档 -Laravel MCP官方文档

🛠️ 发展

运行测试

php artisan test

添加新工具

在中创建工具类 app/Mcp/Tools/
扩展 Laravel\Mcp\Server\Tool
实施 schema() 和 handle() 方法
注册于 app/Mcp/DatabaseServer.php

🔄 版本历史

v2.0.0（当前）

✨ 项目感知架构
✨ 动态数据库切换
✨ 运行时连接解析
✨ AI上下文配置

v1.0.0

🎉 初始版本
✅ 基本只读数据库访问
✅ 三个核心工具（模式+选择）

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📄 许可证

该项目是根据 MIT许可证.

🙏 致谢

建于拉瑞维尔
由...驱动 Laravel MCP
灵感源于模型上下文协议

Made with ❤️ for AI-native development