Laravel Loop

Um servidor MCP para aplicações Laravel se conectarem com assistentes de IA usando o protocolo MCP.

GitHub
132
Experimente este MCPPatrocinado

Documentação

Laravel Loop

Laravel Supported Versions MIT Licensed Latest Version on Packagist

O Laravel Loop é um poderoso servidor Model Context Protocol (MCP) projetado especificamente para aplicações Laravel. Ele conecta sua aplicação Laravel a assistentes de IA usando o protocolo MCP.

O Laravel Loop usa Prism nos bastidores para construir as ferramentas.

[!IMPORTANT] O Laravel Loop e suas ferramentas pré-construídas ainda estão em desenvolvimento e esta é uma versão beta.

O Que Ele Faz

O Laravel Loop permite que você:

  • Crie e exponha suas próprias ferramentas diretamente integradas à sua aplicação Laravel
  • Conecte-se a clientes MCP como Claude Code, Cursor, Windsurf e outros

Ferramentas pré-construídas:

  • Filament MCP Server.
  • Laravel Model Tools (Interaja com os dados dos seus modelos): Kirschbaum\Loop\Toolkits\LaravelModelToolkit (Operações de escrita em breve)
  • Laravel Factories Tools (Crie dados de teste a partir do seu cliente MCP): Kirschbaum\Loop\Toolkits\LaravelFactoriesToolkit
  • Stripe Tool (Interaja com a API do Stripe): Kirschbaum\Loop\Tools\StripeTool

Instalação

Você pode instalar o pacote via composer:

composer require kirschbaum-development/laravel-loop

Publique o arquivo de configuração:

php artisan vendor:publish --tag="loop-config"

Uso

Primeiro, você deve registrar suas ferramentas (Se você não souber onde colocar, coloque em app/Providers/AppServiceProvider).

use Illuminate\Support\ServiceProvider;
use Kirschbaum\Loop\Facades\Loop;
use Kirschbaum\Loop\Toolkits;
use Kirschbaum\Loop\Tools;

Loop::toolkit(Kirschbaum\Loop\Filament\FilamentToolkit::make());

Ferramentas Personalizadas

Para construir suas próprias ferramentas, você pode usar o método Loop::tool.

use Kirschbaum\Loop\Facades\Loop;
use Kirschbaum\Loop\Tools\CustomTool;

Loop::tool(
    CustomTool::make(
        name: 'custom_tool',
        description: 'This is a custom tool',
    )
        ->withStringParameter(name: 'name', description: 'The name of the user', required: true)
        ->withNumberParameter(name: 'age', description: 'The age of the user')
        ->using(function (string $name, ?int $age = null) {
            return sprintf('Hello, %s! You are %d years old.', $name, $age ?? 'unknown');
        }),
    );
);

Os tipos de parâmetros disponíveis podem ser encontrados na Documentação de Ferramentas do Prism.

Objetos de Ferramentas Personalizadas

Você também pode construir suas próprias classes de ferramentas. Cada ferramenta deve implementar o contrato Tool e retornar uma instância de Prism\Prism\Tool no método build.

use Kirschbaum\Loop\Contracts\Tool;

class HelloTool implements Tool
{
    use \Kirschbaum\Loop\Concerns\Makeable;

    public function build(): \Prism\Prism\Tool
    {
        return app(\Prism\Prism\Tool::class)
            ->as($this->getName())
            ->for('Says hello to the user')
            ->withStringParameter('name', 'The name of the user to say hello to.', required: true)
            ->using(fn (string $name) => "Hello, $name!");
    }

    public function getName(): string
    {
        return 'hello';
    }
}

Se você quiser fornecer várias ferramentas semelhantes, pode construir um toolkit que retorna uma coleção de ferramentas.

use Kirschbaum\Loop\Collections\ToolCollection;
use Kirschbaum\Loop\Contracts\Toolkit;

class LaravelFactoriesToolkit implements Toolkit
{
    use \Kirschbaum\Loop\Concerns\Makeable;

    public function getTools(): ToolCollection
    {
        return new ToolCollection([
            HelloTool::make(),
            GoodbyeTool::make(),
        ]);
    }
}

Conectando ao servidor MCP

Para que isso seja realmente útil, você precisa conectar seu cliente MCP (Claude Code, Claude Desktop, Cursor, Windsurf, etc.) ao servidor Laravel LoopMCP.

O protocolo MCP tem dois transportes principais para conectar: STDIO e Streamable HTTP, e o transporte HTTP+SSE (obsoleto). O Laravel Loop suporta todos eles.

A maneira mais fácil de configurar seu cliente MCP é usar o comando php artisan loop:mcp:config. Isso o guiará pelo processo de configuração do seu cliente MCP.

php artisan loop:mcp:generate-config

STDIO

Para executar o servidor MCP usando STDIO, fornecemos o seguinte comando artisan:

php artisan loop:mcp:start [--user-id=1 [--user-model=] [--auth-guard=] [--debug]

Para conectar o servidor MCP do Laravel Loop ao Claude Code, por exemplo, você pode usar o seguinte comando:

claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start

# with an authenticated user
claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start --user-id=1 --user-model=App\Models\User

# with debug mode
claude mcp add laravel-loop-mcp php /your/full/path/to/laravel/artisan loop:mcp:start --debug

Para configurar o Laravel Loop no Cursor, Claude ou qualquer cliente MCP com um arquivo de configuração JSON:

{
  "mcpServers": {
    "laravel-loop-mcp": {
      "command": "php",
      "args": [
        "/your/full/path/to/laravel/artisan",
        "loop:mcp:start",
        "--user-id=1"
      ]
    }
  }
}

Streamable HTTP & SSE

Ter que executar PHP ou Node para rodar o servidor MCP pode ser irritante. Para evitar isso, você pode usar o transporte Streamable HTTP ou SSE, que conecta o cliente MCP diretamente à sua aplicação via HTTP.

O Laravel Loop também suporta o transporte streamable HTTP e o transporte HTTP+SSE (obsoleto).

[!IMPORTANT] NOTA: O transporte Streamable HTTP é novo e ainda não é suportado por todos os clientes MCP, enquanto o SSE (suportado pela maioria dos clientes MCP) está obsoleto.

A documentação a seguir é para ambos os transportes. Observe que você só precisa habilitar um deles.

1. Habilitar e configurar o transporte

Para habilitar o transporte Streamable HTTP, atualize seu arquivo .env:

# streamable http
LOOP_STREAMABLE_HTTP_ENABLED=true

# sse
LOOP_SSE_ENABLED=true

Nota: Ao usar SSE, o driver padrão é file, que é o mais simples e conveniente para desenvolvimento local. No entanto, para produção, recomendamos usar redis para evitar problemas com bloqueio de arquivos. Você pode alterar o driver e opções adicionais no arquivo config/loop.php.

Isso exporá dois endpoints MCP:

  • /mcp que suporta o novo transporte Streamable HTTP.
  • /mcp/sse que suporta o transporte HTTP+SSE (obsoleto).

Nota: Se você estiver executando sua aplicação localmente com https, a maioria dos clientes falhará devido aos certificados autoassinados. Para evitar isso, use o transporte STDIO ou use o protocolo http localmente.

2. Configurar autenticação (opcional)

Esteja ciente de que, se você estiver expondo seu endpoint publicamente, estará expondo seus dados ao mundo. Para garantir que seus endpoints MCP estejam seguros, certifique-se de configurar as opções de configuração streamable_http.middleware ou sse.middleware. Recomendamos usar algo como Sanctum (configurado por padrão) para proteger o endpoint.

[
    'streamable_http' => [
        'middleware' => ['auth:sanctum'],
    ],
    
    'sse' => [
        'middleware' => ['auth:sanctum'],
    ],
]

3. Adicionar o servidor MCP ao seu cliente

Então, você só precisa configurar o endpoint do servidor MCP no seu cliente:

Claude Code

claude mcp add laravel-loop-mcp http://your-url.test/mcp/sse -t sse

A partir do arquivo de configuração JSON

{
  "mcpServers": {
    "laravel-loop-mcp": {
      "url": "http://your-url.test/mcp/sse",
    }
  }
}

Observe que nem todos os clientes suportam conexões SSE diretas. Para essas situações, você pode fazer proxy através do pacote mcp-remote. Isso requer que você tenha Node.js (> 20) instalado. Abaixo está um exemplo usando o pacote mcp-remote.

{
  "mcpServers": {
    "laravel-loop-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-remote-url.com/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ]
    }
  }
}

Solução de Problemas

Falha na conexão: MCP error -32000: Connection closed

Se você receber este erro, provavelmente significa que há algum erro acontecendo na sua aplicação. Verifique os logs da sua aplicação para mais detalhes.

Erro: spawn php ENOENT

Isso pode acontecer quando seu binário "php" não está no PATH. Isso pode ser resolvido de algumas maneiras:

  • Adicione o caminho ao seu arquivo .bashrc ou .zshrc. Às vezes, pode estar apenas no arquivo .zshrc, mas aplicativos como Claude usam .bashrc.
  • Use o caminho completo do binário PHP. Você pode obtê-lo executando which php no seu terminal.
    • Esta pode ser uma boa opção para garantir que você sempre use a versão adequada do PHP para um determinado projeto. Se você usar Herd, por exemplo, seu php mudará dependendo da versão selecionada.

Chamar ferramentas manualmente e verificar a saída

Às vezes, ao construir ferramentas, você pode obter resultados inesperados e depurar pelo cliente MCP pode ser difícil. Você pode chamar ferramentas manualmente e verificar a saída executando o seguinte comando:

php artisan loop:mcp:call

Certifique-se de verificar os logs da sua aplicação

Se você estiver recebendo um erro desconhecido, verifique os logs da sua aplicação para mais detalhes.

Roadmap

  • Adicionar um componente de chat ao pacote, para que você possa usar as ferramentas dentro da aplicação sem um cliente MCP.
  • Refinar as ferramentas existentes
  • Adicionar capacidades de escrita às ferramentas existentes

Segurança

Se você descobrir algum problema relacionado à segurança, envie um e-mail para security@kirschbaumdevelopment.com em vez de usar o rastreador de problemas.

Patrocínio

O desenvolvimento deste pacote é patrocinado pela Kirschbaum Development Group, uma empresa voltada para desenvolvedores focada em resolução de problemas, formação de equipes e comunidade. Saiba mais sobre nós ou junte-se a nós!

Licença

A Licença MIT (MIT). Consulte o Arquivo de Licença para mais informações.