mcp-lab

Laravel MCP의 모든 부분을 강제로 사용하게 만드는 Laravel 앱입니다. 가짜 헬프데스크. 가짜 회사. 다 끝나면 버리세요.

이것은 Laravel에서 MCP가 어떻게 작동하는지, 그리고 이 저장소가 어떻게 사용하는지에 대한 기본 참조입니다.

이것은 제품이 아니라 체육관입니다. 글꼴을 고르거나 청구 페이지를 만드는 자신을 발견하면 멈추세요.

Laravel MCP 작동 방식

Model Context Protocol은 JSON-RPC입니다. AI 호스트가 서버가 노출하는 것을 나열한 다음 호출합니다. Cursor와 Inspector가 이 저장소가 관심을 두는 호스트입니다. Laravel MCP, 여기서는 laravel/mcp 0.9.x가 래퍼입니다.

프로토콜을 직접 만들지 않습니다. PHP 클래스를 작성하고 등록합니다.

서버

서버는 Laravel\Mcp\Server를 확장하는 클래스입니다. 도구, 리소스, 프롬프트의 카탈로그입니다.

#[Name('Northwind Tickets')]
#[Version('0.0.1')]
#[Instructions('...')]
class TicketsServer extends Server
{
    protected array $tools = [/* ... */];
    protected array $resources = [/* ... */];
    protected array $prompts = [/* ... */];
}

#[Name], #[Version], #[Instructions], #[Icon]은 호스트가 모델에 보여주는 메타데이터입니다. Instructions는 해당 서버의 시스템 프롬프트입니다. 짧고 실용적으로 유지하세요.

php artisan make:mcp-server로 생성하세요. routes/ai.php에 등록하세요. Laravel은 해당 파일을 자체적으로 로드합니다. bootstrap/app.php에 추가하지 마세요.

로컬 vs 웹

동일한 서버 클래스. 두 가지 진입 방식.

Mcp::local('tickets', TicketsServer::class);
Mcp::web('/mcp/tickets', TicketsServer::class)->middleware(['auth:api', 'throttle:mcp']);

로컬은 stdio입니다. 호스트가 php artisan mcp:start tickets를 자식 프로세스로 실행합니다. 이것이 일상적인 Cursor 루프입니다. HTTP 세션, 쿠키, Passport가 없습니다.

웹은 해당 경로에서의 HTTP JSON-RPC입니다. Inspector와 원격 호스트가 사용합니다. 미들웨어가 적용되며, OAuth가 여기에 있습니다.

routes/ai.php를 web 미들웨어 그룹으로 감싸지 마세요. CSRF가 Inspector를 차단합니다.

도구, 리소스, 프롬프트

서버는 도구, 리소스, 프롬프트를 노출할 수 있습니다. make:mcp-tool, make:mcp-resource, make:mcp-prompt로 생성하세요. 그런 다음 클래스를 서버 배열에 추가하세요. 등록되지 않은 클래스는 아무것도 하지 않습니다.

도구는 작업입니다. 모델이 인수와 함께 호출합니다. schema()는 호스트가 광고하는 JSON Schema입니다. handle(Request $request)가 작업을 수행합니다. $request->validate()는 일반적인 Laravel 검증입니다. 모델이 행동할 수 있는 메시지를 작성하세요. 예: Give me the ticket id, like 12.가 아니라 The ticket_id field is required.가 아닌.

리소스는 URI에서 읽을 수 있는 문서입니다. 정적 URI는 #[Uri('desk://playbook')]을 사용합니다. 템플릿은 HasUriTemplate을 구현하고 $request->get('id')로 변수를 읽습니다. MIME 유형은 #[MimeType]을 사용합니다. 호스트는 도구를 호출하지 않고도 나열하고 읽을 수 있습니다.

프롬프트는 재사용 가능한 메시지 템플릿입니다. arguments()는 호스트가 수집해야 할 것을 선언합니다. handle()은 메시지를 반환하며, 일반적으로 어시스턴트 지시문과 실제 데이터를 포함하는 사용자 메시지입니다. 그런 다음 모델이 그 내용을 바탕으로 작성합니다.

생성자에서 리포지토리를 주입하세요. 도구 클래스에 쿼리를 넣지 마세요. handle()은 Laravel 서비스를 타입-힌트할 수도 있습니다.

응답

handle()은 Laravel\Mcp\Response, 응답 팩토리, 응답 배열 또는 Generator를 반환합니다.

Response::structured는 비어 있을 수 없으며 팩토리를 반환합니다. 구조화된 JSON과 리소스 링크를 혼합하려면 둘 다 빌드하고 withStructuredContent로 페이로드를 첨부하세요. list_tickets가 그렇게 합니다.

클래스 $meta는 도구 자체의 메타데이터입니다. ->withMeta([...])는 단일 응답의 메타데이터입니다. create_ticket에는 전자가 있고 get_ticket에는 후자가 있습니다.

어노테이션

호스트를 위한 힌트입니다. PHP에서 아무것도 강제하지 않습니다. 정책은 여전히 그렇게 합니다.

shouldRegister(Request $request): bool은 도구, 리소스 또는 프롬프트를 목록에서 숨깁니다. 호스트가 숨겨진 것을 여전히 호출하려고 하면 서버는 not-found를 반환합니다. 역할 게이트에 사용하세요. delete_ticket은 관리자 전용입니다. handle() 내부에서 여전히 $request->user()->can(...)을 확인하세요. 나열과 실행은 다른 문입니다.

권한 부여

$request->user()는 컨트롤러와 동일한 로그인 사용자입니다. $user->can('update', $ticket)을 호출하고 Response::error('Permission denied.')를 반환하세요. 두 번째 인증 시스템을 만들지 마세요.

로컬 서버에는 HTTP 세션이 없습니다. 이 앱의 티켓 서버는 Auth가 비어 있을 때 boot()에서 Sam으로 로그인합니다. 웹 서버는 Passport에서 사용자를 얻습니다.

MCP 클라이언트

Laravel도 MCP 서버를 호출할 수 있습니다. 명명된 클라이언트는 서비스 프로바이더에 있습니다.

Mcp::registerClient('directory', fn () => Client::local('php', [
    'artisan', 'mcp:start', 'directory',
]));

그런 다음 티켓 코드는 Mcp::client('directory')->callTool('get_person', ['id' => $id]) 또는 ->readResource('directory://people/'.$id)를 수행합니다.

Client::local은 프로세스를 생성합니다. Client::web($url)은 HTTP입니다. php artisan serve에 대한 동일 앱 HTTP는 해당 프로세스가 단일 스레드이므로 교착 상태가 됩니다. 동일 앱 호출에는 local을 사용하세요.

MCP 앱

AppResource는 ui:// URI에서 자체 포함된 HTML 문서를 반환합니다. #[RendersApp(resource: QueueApp::class)]로 표시된 도구는 가능한 호스트에게 해당 HTML을 가져와 샌드박스 iframe에 넣도록 지시합니다.

Blade 뷰는 <x-mcp::app>을 사용합니다. 이 컴포넌트는 클라이언트 SDK를 제공합니다. iframe 내부에서 createMcpApp은 app.callServerTool(...)을 제공합니다. Vite와 React는 적용되지 않습니다. Tailwind와 Alpine은 #[AppMeta(libraries: [Library::Tailwind, Library::Alpine])]에서 제공됩니다.

Visibility::App은 모델에서 도구를 숨겨 iframe만 호출할 수 있게 합니다. get_queue_data가 그 도구입니다.

Cursor는 이러한 도구를 나열합니다. iframe을 렌더링하지 않습니다. 클래스가 작동하는지 확인하는 방법은 Pest입니다.

웹에서의 인증

Laravel 문서는 Sanctum과 Passport를 제공합니다. Sanctum은 베어러 토큰입니다. Passport는 OAuth 2.1이며, 프로토콜이 지정하는 것입니다.

이 앱은 Passport를 사용합니다. Mcp::oauthRoutes()는 검색 및 동적 클라이언트 등록을 등록합니다. 웹 라우트는 auth:api를 사용합니다. Laravel MCP는 단일 mcp:use 범위를 광고합니다. mcp-views를 게시하고 Passport::authorizationView를 resources/views/mcp/authorize.blade.php로 지정하세요. 그 Blade는 건드리지 마세요.

테스트

Inspector는 찔러보기용입니다. Pest는 정책이 유지되는지 확인하는 방법입니다.

TicketsServer::actingAs($sam)
    ->tool(ListTicketsTool::class, ['status' => 'open'])
    ->assertOk()
    ->assertSee('...');

TicketsServer::resource(TicketResource::class, ['id' => $ticket->id]);
TicketsServer::prompt(DraftReplyPrompt::class, ['ticket_id' => $ticket->id, 'tone' => 'curt']);

템플릿 리소스는 URI 변수를 두 번째 인수로 사용합니다. 헬퍼는 desk://tickets/{id}를 확장합니다.

assertSee는 텍스트와 구조화된 데이터만 읽습니다. 리소스 링크와 _meta는 원시 JSON-RPC 페이로드에 있습니다. 이 저장소의 tests/Helpers.php에 있는 mcpRpc() 및 mcpToolContent()가 그것을 읽습니다. 생성기 도구는 assertSentNotification 및 assertNotificationCount를 사용합니다. 최종 결과는 여전히 텍스트 페이로드를 보유합니다.

웹 인증은 HTTP 테스트입니다. mcpTicketsCall()로 POST /mcp/tickets를 호출합니다. 인증되지 않은 요청은 로그인 리디렉션이 아닌 401이어야 합니다.

이 저장소가 무엇인지

Northwind Support. 하나의 Laravel 13 앱, PHP 8.4, SQLite. Inertia와 React는 덤프 페이지 전용입니다. 에이전트가 쓰기 경로입니다.

두 개의 MCP 서버, 각각 로컬과 웹으로 두 번 등록됩니다.

routes/ai.php

Mcp::local('directory', DirectoryServer::class);
Mcp::local('tickets', TicketsServer::class);

Mcp::oauthRoutes();

Mcp::web('/mcp/directory', DirectoryServer::class)
    ->middleware(['auth:api', 'throttle:mcp']);

Mcp::web('/mcp/tickets', TicketsServer::class)
    ->middleware(['auth:api', 'throttle:mcp']);

DirectoryServer는 읽기 전용 사람과 팀입니다. TicketsServer는 헬프데스크입니다. 티켓 도구는 Eloquent를 통해 User 또는 Team을 쿼리해서는 안 됩니다. 명명된 directory 클라이언트, get_person 및 directory://people/{id}를 통해 사람을 찾습니다. 그래서 두 개의 서버가 있는 것입니다. 티켓 도구에서 User::find()를 사용한다면 요점을 건너뛴 것입니다.

쿼리는 DirectoryRepository 및 TicketRepository에 있습니다. 도구는 이를 주입합니다.

도메인

users.role에 세 가지 역할이 있습니다.

정책은 일반적인 Laravel 정책입니다. TicketPolicy는 보기, 업데이트, 댓글, 삭제를 다룹니다. ArticlePolicy는 내부 문서를 requester에게 숨깁니다. 직원은 Role::isStaff(), 에이전트 또는 관리자입니다.

로그인 사용자는 LabSeeder에서 제공됩니다. 모든 사용자의 비밀번호는 password입니다.

email_verified_at이 설정되어 있습니다. Fortify는 검증을 활성화했습니다. User는 MustVerifyEmail을 구현하지 않으므로 차단되지 않습니다.

Jonah Hale, jonah@northwind.test,은 온콜 에이전트입니다.

테이블

작게 유지하세요. 도구에 필요하지 않은 열은 없습니다.

users. 스타터 키트 열에 더해 role (requester\|agent\|admin), team_id nullable, title, on_call.

teams. name, slug. Support, Billing, Warehouse.

tickets. subject, body, status (open\|pending\|closed), priority (low\|normal\|high\|urgent), requester_id, assignee_id nullable, team_id nullable.

comments. ticket_id, user_id, body.

articles. slug, title, body, visibility (public\|internal). 네 개의 행. 공개 항목은 환불 및 배송입니다. 내부 항목은 에스컬레이션 및 환불 남용입니다.

LabSeeder는 DatabaseSeeder에서 실행됩니다. migrate:fresh 후 다시 실행할 수 있을 만큼 멱등적입니다. 티켓 20개, 댓글 30개, 사람 8명, storage/app/badge.png에 PNG 하나.

DirectoryServer

읽기 전용. 지시문이 그렇게 말합니다. 이름 Northwind Directory, 버전 0.0.1, 청록색 아이콘.

도구

리소스

여기에는 프롬프트가 없습니다. 프롬프트는 할 말이 있는 티켓 서버에 속합니다.

TicketsServer

이름 Northwind Tickets, 버전 0.0.1, 다크 아이콘.

boot()는 인증된 사용자가 없을 때 sam@northwind.test로 로그인합니다. 로컬 Cursor에는 HTTP 세션이 없습니다. 이것이 없으면 모든 도구가 You must be signed in.이라고 말할 것입니다. 웹 요청에는 이미 Passport 사용자가 있으므로 boot()는 조기에 반환됩니다.

도구

list_tickets는 링크에 TicketResource::uri()를 사용할 수 없습니다. 해당 메서드는 템플릿 desk://tickets/{id}를 반환합니다. 링크는 확장된 문자열이어야 합니다.

assign_ticket과 get_ticket은 User를 건드리지 않습니다. 디렉토리 클라이언트가 연결 해제되면 assign이 실패합니다. Pest가 이를 증명합니다.

프롬프트

리소스

desk://queue는 마크다운입니다. QueueApp은 iframe입니다. 혼동하지 마십시오.

QueueApp

QueueApp은 AppResource를 확장합니다. Blade는 resources/views/mcp/queue-app.blade.php에 있습니다. Alpine은 <x-mcp::app> 내부에 있습니다. 새로고침은 app.callServerTool을 통해 get_queue_data를 호출합니다.

이것은 Inertia 페이지가 아닙니다. React로 다시 작성하지 마십시오.

호스트가 MCP Apps를 렌더링할 수 없어도 클래스와 Pest 테스트가 여전히 증거입니다.

인증 및 웹 서버

/mcp/tickets와 /mcp/directory 모두 auth:api와 throttle:mcp를 사용합니다. mcp 리미터는 AppServiceProvider에서 분당 60회이며, 사용자 id 또는 IP를 키로 사용합니다.

User는 OAuthenticatable을 구현하고 Passport HasApiTokens를 사용합니다. 인터페이스가 없으면 일반적인 Passport 설정 버그입니다.

인증되지 않은 POST는 해당 경로의 보호된 리소스 메타데이터를 가리키는 WWW-Authenticate와 함께 401을 반환합니다. Discovery는 /mcp/tickets와 /mcp/directory를 모두 포함합니다. 동적 등록은 POST /oauth/register입니다. 하나의 액세스 토큰이 두 서버 모두에서 작동합니다.

승인 및 거부 화면은 resources/views/mcp/authorize.blade.php입니다. 그대로 두십시오.

대시보드

Fortify와 Inertia는 스타터 키트에서 제공됩니다. 교체하지 마십시오.

/dashboard는 두 개의 테이블입니다. 티켓은 id, 제목, 상태, 우선순위, 요청자, 담당자를 표시합니다. 사람은 id, 이름, 역할, 팀, 당직 여부를 표시합니다. Wayfinder가 라우트 이름을 지정합니다. DashboardController는 Inertia props를 전달합니다. 티켓을 생성하는 폼은 없습니다.

쓰기 도구가 작동했는지 증명하려면 /dashboard를 새로고침하십시오. React 페이지에 신경 쓸 때 composer run dev를 실행하십시오.

Passport authorize와 QueueApp iframe은 Blade로 유지됩니다. 패키지가 해당 부분을 소유합니다.

사용 방법

Cursor, 로컬. .cursor/mcp.json이 프로젝트 루트에서 두 서버를 모두 시작합니다.

{
    "mcpServers": {
        "northwind-tickets": {
            "command": "php",
            "args": ["artisan", "mcp:start", "tickets"]
        },
        "northwind-directory": {
            "command": "php",
            "args": ["artisan", "mcp:start", "directory"]
        }
    }
}

Tickets가 일상적인 루프입니다. 클라이언트 작업을 위해 Cursor에서 directory가 필요하지 않습니다. 티켓 서버 프로세스가 이를 생성합니다.

로컬 티켓은 Sam으로 실행됩니다. Ada 또는 Root를 보려면 Pest actingAs 또는 해당 토큰이 있는 웹 서버를 사용하십시오.

Inspector. php artisan mcp:inspector tickets 및 php artisan mcp:inspector mcp/tickets. 도구가 아무것도 하지 않고 원시 결과가 필요할 때 사용하십시오. Web Inspector에는 Passport bearer 토큰이 필요합니다. Inspector UI는 :6274에 있고, 이 앱은 :8000에 있습니다. mcp/*, oauth/*, .well-known/*에 대한 CORS는 config/cors.php에 있습니다. 해당 경로가 없으면 discovery GET이 200을 반환해도 브라우저는 여전히 이를 버립니다.

대시보드. 쓰기 도구가 Eloquent에 도달했는지 증명합니다.

Pest. php artisan test --compact tests/Feature/Mcp.

artisan serve가 유일한 PHP 프로세스일 때 티켓 도구에서 Client::web('http://127.0.0.1:8000/mcp/directory')를 호출하지 마십시오. 그러면 멈춥니다. composer run dev도 이를 바꾸지 않습니다. :8001의 두 번째 PHP 서버와 Client::web은 선택적 후속 실험이지 기본값이 아닙니다.

이 저장소 테스트

기능 테스트는 tests/Feature/Mcp에 있습니다. TestCase는 항상 directory 클라이언트를 InProcessDirectoryTransport로 다시 바인딩하여 SQLite :memory:가 보이도록 합니다. DirectoryClientTest의 한 테스트는 실제 stdio 클라이언트를 사용하여 도구를 나열합니다. 연결 해제 클라이언트 테스트는 명명된 클라이언트를 php -r 'exit(1);'로 지정합니다.

tests/Helpers.php의 헬퍼:

• mcpRpc($response) — 원시 JSON-RPC 배열용

• mcpToolContent($response) — 결과 콘텐츠 목록용

• mcpTicketsCall($name, $arguments) — tools/call HTTP 본문용

도구가 숨겨져 있는지 확인하려면 TicketsServer::actingAs($user) 다음에 (new TicketsServer(new FakeTransporter))->createContext()->tools()를 호출하십시오. 숨겨진 도구에서 handle()을 호출하고 정책 오류를 기대하지 마십시오. 호출하면 not-found JSON-RPC 오류입니다.

$tool->annotations()에서 어노테이션을 읽으십시오. toArray()['annotations']가 아닙니다. Tool::toArray()는 해당 필드를 array|object로 타입 지정합니다. 리소스 toArray()는 어노테이션을 생략합니다.

Carbon::setTestNow로 시간을 고정하십시오. pest-plugin-phpstan이 없으면 $this는 TestCall이고 $this->travelTo는 타입 검사를 통과하지 못합니다.

Pest\Laravel\postJson과 Pest\Laravel\withToken을 가져오십시오. $this에서 호출하지 마십시오.

스위트가 다루는 내용:

• 요청자는 assign 또는 delete를 할 수 없음

• 에이전트는 assign 가능, delete 불가

• 관리자는 delete 가능

• Sam으로 acting할 때 delete_ticket이 없고 Root에게는 있음

• 내부 에스컬레이션 리소스가 Ada에게 숨겨짐

• search_kb가 요청자에게 내부 문서를 숨김

• weekly_review 직원 전용

• 디렉토리 클라이언트가 사람을 찾을 수 없으면 assign_ticket 실패

• 검증 오류는 문장 형태

• close_stale_tickets가 진행 알림 생성

• OAuth discovery, 등록, authorize Blade, PKCE, 그 다음 두 웹 서버에서 도구 호출

스타터 키트 Fortify 테스트는 유지됩니다. MCP를 증명하기 위해 다시 작성하지 마십시오.

파일 구조

app/
  Enums/Role.php Status.php Priority.php Visibility.php
  Models/User.php Team.php Ticket.php Comment.php Article.php
  Policies/TicketPolicy.php ArticlePolicy.php
  Repositories/DirectoryRepository.php TicketRepository.php ArticleRepository.php
  Http/Controllers/DashboardController.php
  Mcp/
    Servers/DirectoryServer.php TicketsServer.php
    Tools/          (15 tools)
    Resources/      (11 resources, including QueueApp)
    Prompts/        (3 prompts)
routes/ai.php
resources/js/pages/dashboard.tsx
resources/views/mcp/authorize.blade.php
resources/views/mcp/queue-app.blade.php
database/seeders/LabSeeder.php
tests/Feature/Mcp/
tests/Helpers.php
tests/Support/InProcessDirectoryTransport.php
.ai/rules/          (settled decisions for the next agent)

상습적인 함정

이것들은 이미 .ai/rules에 있습니다. 다시 깨지기 쉽기 때문에 여기에도 속합니다.

• 티켓 도구는 Client::local을 통해 DirectoryServer와 통신합니다. 테스트는 이를 인프로세스 전송으로 재정의합니다.

• assign_ticket 또는 get_ticket에서 User 또는 Team을 쿼리하지 마십시오. 해당 조회를 TicketRepository로 옮기지 마십시오.

• PHPDoc 디렉토리 $resources를 class-string<Server\Resource>로 지정하십시오. Pint는 class-string<Resource>를 PHP의 resource 타입으로 소문자화합니다.

• ai.php는 웹 미들웨어 그룹 밖에 유지됩니다.

• QueueApp은 ui://입니다. desk://queue는 마크다운입니다.

• KB 문서는 ArticleRepository를 통해 처리됩니다. 누락된 desk://kb/{slug} 읽기와 금지된 desk://kb/{slug} 읽기는 동일한 오류를 사용합니다.

문서

• Laravel MCP. https://laravel.com/docs/13.x/mcp

• 패키지. https://github.com/laravel/mcp

• 프로토콜. https://modelcontextprotocol.io/docs/getting-started/intro

• MCP Apps. https://modelcontextprotocol.io/extensions/apps/overview

• Inspector. https://modelcontextprotocol.io/docs/tools/inspector