# ابنِ MCP Server في Laravel بالـPHP SDK الرسمي

> دليل مجرّب للـMCP PHP SDK الرسمي جوه Laravel: أدوات بالـAttributes، وstdio وStreamable HTTP، وتوصيل Claude Code.

*2026-10-15T14:50:47Z*

# ابنِ MCP Server في Laravel بالـPHP SDK الرسمي

الـModel Context Protocol (MCP) بيخلّي وكلاء الذكاء الاصطناعي زي Claude Code وCursor وChatGPT يكتشفوا الأدوات اللي في تطبيقك ويستدعوها. لو تطبيقك Laravel، تقدر تكشف استعلامات Eloquent حقيقية كأدوات MCP في حوالي 30 سطر.

**الإجابة المختصرة:** نزّل `mcp/sdk`، وحط PHP Attributes (`#[McpTool]` و`#[McpResource]`) على ميثودز عادية، وابنِ السيرفر بـ`Server::builder()` باستخدام Container بتاع Laravel، وشغّله من أمر Artisan (stdio) أو من Route (Streamable HTTP). كل اللي تحت اتجرّب على Laravel 13.36 وPHP 8.4 مع `mcp/sdk` إصدار v0.8.1.

## أنهي باكدج: `mcp/sdk` ولا `laravel/mcp`؟

فيه اختيارين كويسين، ومهم تختار بوعي:

- **`mcp/sdk`** هو الـSDK الرسمي لـPHP، بتصونه PHP Foundation وSymfony تحت منظمة `modelcontextprotocol` على GitHub. مش مربوط بـFramework، ولسه متعلّم إنه **تجريبي**، فثبّت الإصدار.
- **`laravel/mcp`** هو باكدج Laravel الرسمي. فيه Generators لـArtisan (`make:mcp-server` و`make:mcp-tool`)، وملف `routes/ai.php` مع `Mcp::web()` و`Mcp::local()`، وأمر `mcp:inspector`. لو مش هتشتغل غير على Laravel، هو الاختيار الأقرب لأسلوب Laravel.

الدليل ده بيستخدم الـSDK الرسمي: لأنه التنفيذ المرجعي للـSpec، ونفس الكود بيشتغل في Symfony أو PHP عادي، وبتشوف بالظبط إيه اللي بيحصل.

## الخطوة 1: التثبيت

```bash
composer require mcp/sdk symfony/finder
# محتاجينهم بس للـHTTP transport
composer require symfony/psr-http-message-bridge nyholm/psr7
```

`symfony/finder` بيستخدمه اكتشاف الـAttributes، والـPSR-7 bridge بيخلّي Route في Laravel يستقبل `ServerRequestInterface`.

## الخطوة 2: اكتب الأدوات كميثودز عادية

اعمل `app/Mcp/UserTools.php`:

```php
<?php

namespace App\Mcp;

use App\Models\User;
use Mcp\Capability\Attribute\McpResource;
use Mcp\Capability\Attribute\McpTool;

class UserTools
{
    /** Count the registered users. */
    #[McpTool(name: 'count_users')]
    public function countUsers(): int
    {
        return User::count();
    }

    /**
     * Find a user by email and return their public profile.
     *
     * @param string $email The user's email address
     */
    #[McpTool(name: 'find_user')]
    public function findUser(string $email): array
    {
        $user = User::where('email', $email)->first();

        return $user
            ? $user->only(['id', 'name', 'email', 'created_at'])
            : ['error' => "No user with email {$email}"];
    }

    #[McpResource(uri: 'app://config/name', name: 'app_name', mimeType: 'text/plain')]
    public function appName(): string
    {
        return config('app.name');
    }
}
```

الـDocblock هنا ليه شغل حقيقي: الـSDK بيبني منه وصف الأداة والـJSON Schema بتاع المدخلات، فـ`find_user` بتظهر للـAgent بـ`email` نصي إجباري ومعاه وصفه. اكتب الـDocblocks للموديل، مش للبشر بس.

## الخطوة 3: ابنِ السيرفر مرة واحدة

الـTransports الاتنين محتاجين نفس السيرفر، فحطّه في Factory. `app/Mcp/ServerFactory.php`:

```php
<?php

namespace App\Mcp;

use Mcp\Server;
use Mcp\Server\Session\FileSessionStore;

class ServerFactory
{
    public static function make(): Server
    {
        return Server::builder()
            ->setServerInfo(config('app.name').' MCP', '1.0.0')
            ->setContainer(app())
            ->setDiscovery(base_path(), ['app/Mcp'])
            ->setSession(new FileSessionStore(storage_path('framework/mcp-sessions')))
            ->build();
    }
}
```

- `setContainer(app())`: الـContainer بتاع Laravel متوافق مع PSR-11، فكلاسات الأدوات بتتحلّ منه، والـConstructor Injection شغال.
- `setDiscovery()`: بيفحص `app/Mcp` بحثًا عن الـAttributes. وتقدر كمان تسجّل أدوات يدويًا بـ`addTool()`.
- `setSession()`: الـHTTP ملوش حالة بين الطلبات، فجلسات MCP محتاجة مكان تتخزّن فيه. مخزن ملفات جوه `storage/` كفاية كبداية.

## الخطوة 4أ: التشغيل عبر stdio (للوكلاء المحليين)

`app/Console/Commands/McpServe.php`:

```php
<?php

namespace App\Console\Commands;

use App\Mcp\ServerFactory;
use Illuminate\Console\Command;
use Mcp\Server\Transport\StdioTransport;

class McpServe extends Command
{
    protected $signature = 'mcp:serve';

    protected $description = 'Run the MCP server over stdio';

    public function handle(): int
    {
        return ServerFactory::make()->run(new StdioTransport());
    }
}
```

وصّله بـClaude Code من جذر المشروع:

```bash
claude mcp add --transport stdio laravel-app -- php artisan mcp:serve
```

كل اللي بعد `--` هو الأمر اللي Claude Code بيشغّله. ضيف `--scope project` عشان تشاركه مع الفريق عن طريق `.mcp.json`، والـScope الافتراضي هو `local`.

## الخطوة 4ب: التشغيل عبر HTTP (للوكلاء البعيدين)

ضيف ده في آخر `routes/web.php`:

```php
Route::match(['GET', 'POST', 'DELETE'], '/mcp', function (Psr\Http\Message\ServerRequestInterface $request) {
    return App\Mcp\ServerFactory::make()->run(
        new Mcp\Server\Transport\StreamableHttpTransport($request)
    );
})->withoutMiddleware(Illuminate\Foundation\Http\Middleware\PreventRequestForgery::class);
```

مشكلتين قابلتهم وأنا بجرّب:

1. **CSRF:** الـAgents مش بتبعت CSRF Token، فأول POST بيرجع `419`. في Laravel 13 الـMiddleware اسمه `PreventRequestForgery`، وفي Laravel 12 اسمه `ValidateCsrfToken`. والأفضل إنك تحط الـRoute في `routes/api.php` اللي مفيهاش CSRF أصلًا.
2. **PSR-7:** من غير `symfony/psr-http-message-bridge` و`nyholm/psr7`، Laravel مش هيعرف يعمل Inject لـ`ServerRequestInterface`.

وبعدين وصّل:

```bash
claude mcp add --transport http laravel-app https://your-app.test/mcp
```

## الخطوة 5: اختبره من غير Agent

تقدر تعمل Smoke Test للـHTTP بـcurl. رد `initialize` بيرجّع Header اسمه `Mcp-Session-Id` لازم تبعته في الطلبات اللي بعده:

```bash
curl -i -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

في تجربتي: `initialize` رجّع `200` مع الـSession Header، و`notifications/initialized` رجّع `202`، و`tools/list` عرض `count_users` و`find_user` بالـSchema المتولّدة، و`tools/call` على `find_user` رجّع بيانات المستخدم كنص ومعاها `structuredContent`.

## الحدود بصراحة

- **الـSDK تجريبي:** الـAPI ممكن يتغير قبل 1.0. ثبّت إصدار `mcp/sdk` واقرا الـChangelog مع كل تحديث.
- **مفيش Auth في المثال ده:** Route عام اسمه `/mcp` بيستعلم عن المستخدمين معناه تسريب بيانات. حطّه ورا Sanctum Tokens أو دعم OAuth اللي في الـSDK، وحدّد الأدوات بالـTenant بتاع المستخدم.
- **الأدوات لازم تكون صغيرة ومملّة:** فعل واضح واحد لكل أداة، ومدخلات متحقق منها، ومفيش أداة «نفّذ أي استعلام».

## أسئلة شائعة

**بيشتغل مع Filament؟** أيوه. الأدوات ميثودز PHP عادية، فتقدر تستخدم نفس الـModels والـPolicies والـActions اللي في Filament Resources بتاعتك.

**stdio ولا HTTP؟** stdio لأدوات المطور المحلية، وHTTP لأي حاجة محتاج جهاز تاني أو Agent مستضاف يوصلها.

## الخطوة الجاية

- إزاي تحدّد وتؤمّن وتطلق MCP Server لمنتج حقيقي: [اطلق MCP Server رسمي لمنتجك في أسبوعين](https://fadymondy.com/ar/blog/ship-official-mcp-server-for-saas-in-2-weeks).
- محتاج فريق يبنيه جوه منتج Laravel أو Filament بتاعك؟ [تطوير Laravel وFilament بالـWhite-label](https://fadymondy.com/ar/services/white-label-laravel-filament?utm_source=tomatophp&utm_medium=referral&utm_campaign=seo-content-oct26).

---

Source: https://tomatophp.com/ar/blog/laravel-mcp-server-official-php-sdk
