diff --git a/.agents/skills/mcp-development/SKILL.md b/.agents/skills/mcp-development/SKILL.md
new file mode 100644
index 0000000..5d950f0
--- /dev/null
+++ b/.agents/skills/mcp-development/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: mcp-development
+description: "Use this skill for Laravel MCP development only. Trigger when creating or editing MCP tools, resources, prompts, or servers in Laravel projects. Covers: artisan make:mcp-* generators, mcp:inspector, routes/ai.php, Tool/Resource/Prompt classes, schema validation, shouldRegister(), OAuth setup, URI templates, read-only attributes, and MCP debugging. Do not use for non-Laravel MCP projects or generic AI features without MCP."
+license: MIT
+metadata:
+ author: laravel
+---
+
+# MCP Development
+
+## Documentation
+
+Use `search-docs` for detailed Laravel MCP patterns and documentation.
+
+## Basic Usage
+
+Register MCP servers in `routes/ai.php`:
+
+
+```php
+use Laravel\Mcp\Facades\Mcp;
+
+Mcp::web();
+```
+
+### Creating MCP Primitives
+
+Create MCP tools, resources, prompts, and servers using artisan commands:
+
+```bash
+php artisan make:mcp-tool ToolName # Create a tool
+
+php artisan make:mcp-resource ResourceName # Create a resource
+
+php artisan make:mcp-prompt PromptName # Create a prompt
+
+php artisan make:mcp-server ServerName # Create a server
+
+```
+
+After creating primitives, register them in your server's `$tools`, `$resources`, or `$prompts` properties.
+
+### Tools
+
+
+```php
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Request;
+use Laravel\Mcp\Server\Response;
+
+class MyTool extends Tool
+{
+ public function handle(Request $request): Response
+ {
+ return new Response(['result' => 'success']);
+ }
+}
+```
+
+### Registering Primitives in a Server
+
+Each MCP server must explicitly declare the tools, resources, and prompts it exposes.
+
+
+```php
+use Laravel\Mcp\Server;
+
+class AppServer extends Server
+{
+ protected array $tools = [
+ \App\Mcp\Tools\MyTool::class,
+ ];
+
+ protected array $resources = [
+ \App\Mcp\Resources\MyResource::class,
+ ];
+
+ protected array $prompts = [
+ \App\Mcp\Prompts\MyPrompt::class,
+ ];
+}
+```
+
+## Verification
+
+1. Check `routes/ai.php` for proper registration
+2. Test tool via MCP client
+
+## Common Pitfalls
+
+- Running `mcp:start` command (it hangs waiting for input)
+- Using HTTPS locally with Node-based MCP clients
+- Not using `search-docs` for the latest MCP documentation
+- Not registering MCP server routes in `routes/ai.php`
+- Do not register `ai.php` in `bootstrap.php`; it is registered automatically.
+- OAuth registration supports custom URI schemes (e.g., `cursor://`, `vscode://`) for native desktop clients via `mcp.custom_schemes` config
\ No newline at end of file
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index ddab86b..378c3e7 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -4,7 +4,6 @@ on:
push:
branches:
- main
- - staging
pull_request:
jobs:
@@ -31,7 +30,7 @@ jobs:
node-version: '22'
- name: Install Node Dependencies
- run: npm i
+ run: npm i --from-lock-file
- name: Install Dependencies
run: composer install --no-interaction --prefer-dist --optimize-autoloader
@@ -46,4 +45,4 @@ jobs:
run: npm run build
- name: Tests
- run: ./vendor/bin/phpunit
+ run: composer ci:check
diff --git a/AGENTS.md b/AGENTS.md
index b4031f6..3bebeb7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,10 +13,10 @@ This application is a Laravel application and its main Laravel ecosystems packag
- inertiajs/inertia-laravel (INERTIA_LARAVEL) - v2
- laravel/fortify (FORTIFY) - v1
- laravel/framework (LARAVEL) - v13
+- laravel/mcp (MCP) - v0
- laravel/prompts (PROMPTS) - v0
- laravel/wayfinder (WAYFINDER) - v0
- laravel/boost (BOOST) - v2
-- laravel/mcp (MCP) - v0
- laravel/pail (PAIL) - v1
- laravel/pint (PINT) - v1
- laravel/sail (SAIL) - v1
@@ -34,7 +34,7 @@ This project has domain-specific skills available. You MUST activate the relevan
- `fortify-development` — ACTIVATE when the user works on authentication in Laravel. This includes login, registration, password reset, email verification, two-factor authentication (2FA/TOTP/QR codes/recovery codes), profile updates, password confirmation, or any auth-related routes and controllers. Activate when the user mentions Fortify, auth, authentication, login, register, signup, forgot password, verify email, 2FA, or references app/Actions/Fortify/, CreateNewUser, UpdateUserProfileInformation, FortifyServiceProvider, config/fortify.php, or auth guards. Fortify is the frontend-agnostic authentication backend for Laravel that registers all auth routes and controllers. Also activate when building SPA or headless authentication, customizing login redirects, overriding response contracts like LoginResponse, or configuring login throttling. Do NOT activate for Laravel Passport (OAuth2 API tokens), Socialite (OAuth social login), or non-auth Laravel features.
- `laravel-best-practices` — Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.
-- `project-route-structure` — Always apply in this project when creating, moving, or refactoring Laravel route definitions in routes/**/*.php; changing route prefixes, names, middleware, scoped bindings, or route files; or adding frontend-facing endpoints that Wayfinder generates. Documents the KanbanGit route-file layout and grouping conventions.
+- `mcp-development` — Use this skill for Laravel MCP development only. Trigger when creating or editing MCP tools, resources, prompts, or servers in Laravel projects. Covers: artisan make:mcp-* generators, mcp:inspector, routes/ai.php, Tool/Resource/Prompt classes, schema validation, shouldRegister(), OAuth setup, URI templates, read-only attributes, and MCP debugging. Do not use for non-Laravel MCP projects or generic AI features without MCP.
- `wayfinder-development` — Use this skill for Laravel Wayfinder which auto-generates typed functions for Laravel controllers and routes. ALWAYS use this skill when frontend code needs to call backend routes or controller actions. Trigger when: connecting any React/Vue/Svelte/Inertia frontend to Laravel controllers, routes, building end-to-end features with both frontend and backend, wiring up forms or links to backend endpoints, fixing route-related TypeScript errors, importing from @/actions or @/routes, or running wayfinder:generate. Use Wayfinder route functions instead of hardcoded URLs. Covers: wayfinder() vite plugin, .url()/.get()/.post()/.form(), query params, route model binding, tree-shaking. Do not use for backend-only task
- `inertia-vue-development` — Develops Inertia.js v2 Vue client-side applications. Activates when creating Vue pages, forms, or navigation; using ,