README

MCP Tools

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

Important

This package provides MCP tools that must be registered in your project's MCP server. It does not create or run an MCP server itself - you need to have Laravel MCP configured in your project.

Features

• 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

Requirements

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

Installation

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.

Usage

Generate API Contract

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

Export to OpenAPI

php artisan api:export-openapi

Clear Cache

php artisan mcp-tools:clear-cache

Health Check

php artisan mcp-tools:health-check

View Metrics

php artisan mcp-tools:metrics

Manage Contract Versions

php artisan api:contract:versions

View Logs

php artisan mcp-tools:logs

MCP Tools

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

Important

Verify registration by checking your MCP server's available tools list.

1. list-api-routes

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
}

2. describe-api-route

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

Registering MCP Tools

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

Troubleshooting

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)

Configuration

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

API Contract Structure

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": []
        }
    }
}

Extending

Custom Schema Transformers

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());

Testing

Run the test suite:

composer test

Run tests with coverage:

vendor/bin/pest --coverage

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Angel
• All Contributors

License

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