A Laravel package for generating and managing API contracts with MCP (Model Context Protocol) integration.

• Automatic API Contract Generation: Generate comprehensive API contracts from your Laravel routes
• MCP Tools Integration: List and describe API routes through MCP tools
• Advanced Analysis: Deep analysis of routes, FormRequests, Resources, and middleware
• OpenAPI Export: Export contracts to OpenAPI 3.0 format
• Caching: Intelligent caching for improved performance
• Validation: JSON Schema validation for generated contracts

• PHP 8.4+
• Laravel 11.x or 12.x
• Laravel MCP ^0.5.1

Install the package via composer:

composer require abr4xas/mcp-tools

The package will automatically register its service provider. However, the MCP tools must be manually registered in your project's MCP server configuration.

Generate a comprehensive API contract from your Laravel routes:

php artisan api:contract:generate

This command will:

• Scan all your application routes
• Extract route information (methods, paths, parameters)
• Analyze controller methods and FormRequest classes
• Generate authentication requirements
• Create a JSON file at storage/api-contracts/api.json

Options:

• --incremental: Only update routes that have been modified
• --log: Enable detailed logging
• --dry-run: Validate without writing file
• --validate-schemas: Validate generated schemas against JSON Schema

php artisan api:export-openapi

php artisan mcp-tools:clear-cache

php artisan mcp-tools:health-check

php artisan mcp-tools:metrics

php artisan api:contract:versions

php artisan mcp-tools:logs

The package provides MCP tools that must be manually registered in your Laravel MCP server configuration.

Lists all API routes with optional filtering.

Arguments:

• method (optional): Filter by HTTP method (GET, POST, PUT, DELETE, PATCH)
• version (optional): Filter by API version (v1, v2, etc.)
• search (optional): Search term to filter routes by path
• limit (optional): Maximum number of results (default: 50, max: 200)
• page (optional): Page number for pagination (default: 1)

Example:

{
    "method": "GET",
    "version": "v1",
    "search": "users",
    "limit": 10,
    "page": 1
}

Get detailed information about a specific endpoint.

Arguments:

• path (required): The API route path (e.g., /api/v1/users/{user})
• method (optional): HTTP method (defaults to GET)

Example:

{
    "path": "/api/v1/users/{user}",
    "method": "GET"
}

Response includes:

• Route description
• API version
• Authentication requirements
• Path parameters with types
• Request/response schemas (if available)
• Rate limiting information
• HTTP status codes
• Content negotiation

The MCP tools provided by this package must be manually registered in your Laravel MCP server configuration.

If you encounter issues registering the tools:

• Tools not appearing: Ensure the MCP server configuration file is being loaded correctly
• Class not found errors: Run composer dump-autoload to refresh the autoloader
• Service provider not registered: Check that Abr4xas\McpTools\McpToolsServiceProvider is in your config/app.php providers array (should be auto-discovered)

The package automatically detects and includes in contracts:

• Route parameters and types
• Authentication requirements (derived from middleware analysis)
• Rate limiting information
• Request validation rules (from FormRequests)
• Response schemas (from Resources)
• HTTP status codes
• Custom headers
• Content negotiation
• API versioning

The generated contract at storage/api-contracts/api.json follows this structure:

{
    "/api/v1/users": {
        "GET": {
            "description": "List all users",
            "deprecated": null,
            "auth": { "type": "bearer" },
            "path_parameters": {},
            "request_schema": {
                "location": "query",
                "properties": {}
            },
            "response_schema": {
                "type": "array",
                "items": {}
            },
            "response_headers": [],
            "custom_headers": [],
            "rate_limit": null,
            "api_version": "v1",
            "status_codes": {
                "200": "OK",
                "401": "Unauthorized"
            },
            "content_negotiation": []
        },
        "POST": {
            "description": "Create a new user",
            "deprecated": null,
            "auth": { "type": "bearer" },
            "path_parameters": {},
            "request_schema": {
                "location": "body",
                "properties": {
                    "name": { "type": "string", "required": true },
                    "email": { "type": "string", "format": "email", "required": true }
                }
            },
            "response_schema": { "type": "object", "properties": {} },
            "response_headers": [],
            "custom_headers": [],
            "rate_limit": null,
            "api_version": "v1",
            "status_codes": {
                "201": "Created",
                "422": "Unprocessable Entity"
            },
            "content_negotiation": []
        }
    },
    "/api/v1/users/{user}": {
        "GET": {
            "description": "Get user details",
            "deprecated": null,
            "auth": { "type": "bearer" },
            "path_parameters": {
                "user": { "type": "integer", "required": true }
            },
            "request_schema": { "location": "query", "properties": {} },
            "response_schema": { "type": "object", "properties": {} },
            "response_headers": [],
            "custom_headers": [],
            "rate_limit": null,
            "api_version": "v1",
            "status_codes": {
                "200": "OK",
                "404": "Not Found"
            },
            "content_negotiation": []
        }
    }
}

Create a transformer implementing SchemaTransformerInterface:

use Abr4xas\McpTools\Interfaces\SchemaTransformerInterface;

class CustomTransformer implements SchemaTransformerInterface
{
    public function transform(array $schema): array
    {
        // Transform schema
        return $schema;
    }

    public function getPriority(): int
    {
        return 100;
    }
}

Register it in your service provider:

$this->app->make(SchemaTransformerRegistry::class)
    ->register(new CustomTransformer());

Run the test suite:

composer test

Run tests with coverage:

vendor/bin/pest --coverage

Please see CHANGELOG for more information on what has changed recently.

Please see CONTRIBUTING for details.

Please review our security policy on how to report security vulnerabilities.

• Angel
• All Contributors

The MIT License (MIT). Please see License File for more information.