### Install Project Dependencies

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Install all necessary project dependencies using Composer.

```bash
composer install
```

--------------------------------

### Install MCP Tools Package

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

Install the MCP Tools package using Composer. The service provider is automatically registered.

```bash
composer require abr4xas/mcp-tools
```

--------------------------------

### Describe API Route - Batch Response Example

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Example batch response for describing multiple routes, showing results for each path/method combination.

```json
{
    "batch_results": [
        { "path": "/api/v1/users",        "method": "GET",  "data": { "auth": { "type": "bearer" }, "api_version": "v1" } },
        { "path": "/api/v1/users",        "method": "POST", "data": { "auth": { "type": "bearer" }, "api_version": "v1" } },
        { "path": "/api/v1/posts/{post}", "method": "GET",  "data": { "undocumented": true } },
        { "path": "/api/v1/posts/{post}", "method": "POST", "data": { "undocumented": true } }
    ],
    "total_operations": 4
}
```

--------------------------------

### List API Routes - Response Example

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Example response structure for listing API routes, showing total count and grouped results.

```json
{
    "total": 4,
    "limit": 20,
    "grouped_by": "version",
    "groups": {
        "v1": [
            { "path": "/api/v1/users",        "method": "GET", "auth": "bearer", "api_version": "v1" },
            { "path": "/api/v1/users/{user}",  "method": "GET", "auth": "bearer", "api_version": "v1" }
        ]
    }
}
```

--------------------------------

### Run Tests with PestPHP

Source: https://github.com/abr4xas/mcp-tools/blob/master/llms.txt

Instructions on how to execute tests using PestPHP and generate code coverage reports. Ensure PestPHP is installed and configured.

```bash
composer test
# or
vendor/bin/pest

composer test-coverage
# or
vendor/bin/pest --coverage
```

--------------------------------

### List API Routes - Batch Response Example

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Example batch response structure, detailing results for each filter combination and total operations.

```json
{
    "batch_results": [
        {
            "filters": { "method": "GET", "version": "v1", "search": "user" },
            "total": 2,
            "limit": 10,
            "routes": [
                { "path": "/api/v1/users",       "method": "GET", "auth": "bearer", "api_version": "v1" },
                { "path": "/api/v1/users/{user}", "method": "GET", "auth": "bearer", "api_version": "v1" }
            ]
        },
        {
            "filters": { "method": "POST", "version": "v1", "search": "user" },
            "total": 1,
            "limit": 10,
            "routes": [
                { "path": "/api/v1/users", "method": "POST", "auth": "bearer", "api_version": "v1" }
            ]
        }
    ],
    "total_operations": 2
}
```

--------------------------------

### Pest Test Example

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

An example of a basic test case using PestPHP syntax. This snippet demonstrates the structure for defining a test.

```php
it('command generates API contract successfully', function () {
    // test code using expect()
});
```

--------------------------------

### Describe API Route - Response Example

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Example response structure for describing a single API route, including path parameters, schemas, and status codes.

```json
{
    "description": "Retrieve a single user",
    "deprecated": null,
    "auth": { "type": "bearer", "scheme": "Bearer" },
    "path_parameters": {
        "user": { "type": "integer", "required": true }
    },
    "request_schema": { "location": "query", "properties": {} },
    "response_schema": {
        "id":    { "type": "integer" },
        "name":  { "type": "string" },
        "email": { "type": "string" }
    },
    "response_headers": [],
    "custom_headers": [],
    "rate_limit": null,
    "api_version": "v1",
    "status_codes": { "200": "OK", "404": "Not Found" },
    "content_negotiation": [],
    "matched_route": "/api/v1/users/{user}"
}
```

--------------------------------

### Conventional Commit Message Example

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Example of a commit message following the conventional commit format, including a type, scope, description, and issue number.

```git
fix(command): corregir inconsistencia en signature del comando (#004)
```

--------------------------------

### API Contract Structure Example

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

This JSON structure represents a generated API contract. It details endpoints, HTTP methods, descriptions, authentication, request/response schemas, and status codes.

```json
{
    "/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": []
        }
    }
}
```

--------------------------------

### List API Routes - Filter GET v1

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Use this to filter API routes by method, version, and search term. Supports pagination and grouping.

```json
{
    "method": "GET",
    "version": "v1",
    "search": "user",
    "limit": 20,
    "page": 1,
    "group_by": "version",
    "sort": "path"
}
```

--------------------------------

### MCP Tool: Describe API Route

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

Get detailed information about a specific API endpoint, including path and optional method. This is an MCP tool that must be registered with your MCP server.

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

--------------------------------

### Custom MCP Tool: AuthCoverageReport

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

An example of a custom MCP tool that extends Laravel\Mcp\Server\Tool to report on API route coverage grouped by authentication type. It requires the API contract to be generated first.

```php
<?php

namespace App\Tools;

use Abr4xas\McpTools\Tools\ListApiRoutes;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Illuminate\Support\Facades\File;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

// Example: a tool that counts API routes grouped by authentication type
class AuthCoverageReport extends Tool
{
    protected string $name = 'auth-coverage-report';

    protected string $description = 'Returns a breakdown of API routes by authentication type.';

    public function handle(Request $request): Response
    {
        $contractPath = storage_path('api-contracts/api.json');

        if (! File::exists($contractPath)) {
            return Response::text('Error: run php artisan api:contract:generate first.');
        }

        $contract = json_decode(File::get($contractPath), true);
        if (! is_array($contract)) {
            return Response::text('Error: invalid contract format.');
        }

        $counts = [];
        foreach ($contract as $path => $methods) {
            if ($path === '_metadata') {
                continue;
            }
            foreach ($methods as $method => $data) {
                $authType = $data['auth']['type'] ?? 'none';
                $counts[$authType] = ($counts[$authType] ?? 0) + 1;
            }
        }

        arsort($counts);

        $json = json_encode([
            'total_routes'    => array_sum($counts),
            'by_auth_type'    => $counts,
            'protected_pct'   => round(100 * (1 - ($counts['none'] ?? 0) / max(1, array_sum($counts))), 1),
        ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

        return Response::text($json === false ? '{}' : $json);
    }

    public function schema(JsonSchema $schema): array
    {
        return []; // no input parameters needed
    }
}

// Expected response:
// {
//     "total_routes": 42,
//     "by_auth_type": { "bearer": 38, "none": 4 },
//     "protected_pct": 90.5
// }
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Clone the MCP Tools repository and navigate into the project directory.

```bash
git clone https://github.com/abr4xas/mcp-tools.git
cd mcp-tools
```

--------------------------------

### Run Project Tests

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Execute all project tests using Composer.

```bash
composer test
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Execute project tests and generate a code coverage report using Composer.

```bash
composer test-coverage
```

--------------------------------

### Show MCP Tools Metrics

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Display performance metrics for the MCP Tools package via the Artisan command. Useful for monitoring and optimization.

```bash
php artisan mcp-tools:metrics
```

--------------------------------

### Manually Format Code with Pint

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Manually run the Pint code formatter to ensure code style consistency.

```bash
vendor/bin/pint
```

--------------------------------

### Format Code with Laravel Pint

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Format your code according to project standards using Composer.

```bash
composer format
```

--------------------------------

### Describe API Route - Batch Mode

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Describe multiple routes in a single call by passing arrays of paths and methods. Useful for efficient multi-route inspection.

```json
{
    "path": ["/api/v1/users", "/api/v1/posts/{post}"],
    "method": ["GET", "POST"]
}
```

--------------------------------

### Perform Static Analysis with PHPStan

Source: https://github.com/abr4xas/mcp-tools/blob/master/CONTRIBUTING.md

Ensure code quality by running static analysis with PHPStan via Composer.

```bash
composer analyse
```

--------------------------------

### Project Structure Overview

Source: https://github.com/abr4xas/mcp-tools/blob/master/llms.txt

This outlines the directory structure of the MCP Tools Laravel package, detailing the purpose of each major directory and its key components.

```plaintext
src/
├── Analyzers/          # Code analysis components
│   ├── RouteAnalyzer.php           # Extracts route information (params, auth, rate limits)
│   ├── FormRequestAnalyzer.php    # Parses validation rules and generates request schemas
│   ├── ResourceAnalyzer.php       # Analyzes API Resources and generates response schemas
│   ├── PhpDocAnalyzer.php         # Extracts PHPDoc comments for descriptions
│   ├── MiddlewareAnalyzer.php     # Analyzes middleware applied to routes
│   ├── ResponseCodeAnalyzer.php   # Detects possible HTTP status codes
│   └── ExampleGenerator.php       # Generates example data from schemas
├── Commands/          # Artisan commands
│   ├── GenerateApiContractCommand.php  # Main command for generating API contracts
│   ├── ClearCacheCommand.php           # Clears analysis cache
│   ├── ExportOpenApiCommand.php        # Exports contracts to OpenAPI format
│   ├── ContractVersionCommand.php     # Manages contract versions
│   ├── HealthCheckCommand.php          # Performs health checks
│   ├── MetricsCommand.php              # Displays contract metrics
│   └── ViewLogsCommand.php             # Views recent logs
├── Tools/             # MCP Tools for external integration
│   ├── ListApiRoutes.php          # Lists and filters API routes
│   ├── DescribeApiRoute.php       # Describes a single API route
│   ├── ValidateApiContract.php    # Validates contract is up to date
│   └── CompareApiContracts.php   # Compares two contract versions
├── Services/          # Shared services
│   ├── AnalysisCacheService.php   # Caches analysis results
│   ├── AstCacheService.php        # Caches AST parsing results
│   ├── JsonSchemaValidator.php    # Validates schemas against JSON Schema
│   └── SchemaTransformerRegistry.php  # Manages custom schema transformers
├── Exceptions/        # Custom exceptions
│   ├── AnalysisException.php
│   ├── RouteAnalysisException.php
│   ├── FormRequestAnalysisException.php
│   └── ResourceAnalysisException.php
└── Interfaces/
    └── SchemaTransformerInterface.php
```

--------------------------------

### Create Custom Analyzer

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/EXTENDING.md

Create a custom analyzer class with an analyze method that accepts a Route object and returns an array of custom information.

```php
<?php

namespace App\Analyzers;

use Illuminate\Routing\Route;

class CustomAnalyzer
{
    public function analyze(Route $route): array
    {
        // Extract custom information
        return [
            'custom_field' => 'value',
        ];
    }
}
```

--------------------------------

### Call compare-api-contracts tool

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Use this JSON payload to invoke the `compare-api-contracts` tool, providing paths to the two contract files you wish to compare.

```json
{
    "contract1_path": "storage/api-contracts/versions/api-2025-01-14-093045.json",
    "contract2_path": "storage/api-contracts/api.json"
}
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

Run tests and generate code coverage reports using Pest.

```bash
vendor/bin/pest --coverage
```

--------------------------------

### Export OpenAPI Contract with Custom Paths

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Use this command to export an OpenAPI contract to a specified output path and format. Ensure the contract file and output directory are correctly specified.

```bash
php artisan api:export-openapi \
    --contract=storage/api-contracts/api.json \
    --output=/var/www/public/openapi.json \
    --format=json
```

--------------------------------

### Manage API Contract Versions

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Manage API contract version history. Use 'list' to view saved versions and 'restore' to revert to a previous version. The current contract is backed up before restoration.

```bash
# List all saved versions
php artisan api:contract:versions list
```

```bash
# Restore a previous version (current contract is backed up first)
php artisan api:contract:versions restore --file=api-2025-01-14-093045.json
```

--------------------------------

### Describe API Route

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Returns the full contract entry for a specific route and method. Supports exact path matching and pattern matching for routes with dynamic segments. Also supports batch mode.

```APIDOC
## `describe-api-route` (`Abr4xas\McpTools\Tools\DescribeApiRoute`)

### Description
Returns the full contract entry for a specific route and method. Supports exact path matching and pattern matching for routes with dynamic segments (e.g., `/api/v1/users/42` resolves to `/api/v1/users/{user}`). Also supports batch mode by passing an array of paths.

### Method
Not directly specified, but the tool call structure suggests an internal API interaction.

### Endpoint
Not directly specified.

### Parameters
#### Request Body
- **`path`** (string or array of strings) - Required - Route path, e.g. `/api/v1/users/{user}` or a concrete path like `/api/v1/users/42`
- **`method`** (string or array of strings) - Optional - HTTP method (default `GET`)

### Request Example (Single Call)
```json
{
    "path": "/api/v1/users/{user}",
    "method": "GET"
}
```

### Request Example (Batch Mode)
```json
{
    "path": ["/api/v1/users", "/api/v1/posts/{post}"],
    "method": ["GET", "POST"]
}
```

### Response
#### Success Response
- **`description`** (string) - Description of the route.
- **`deprecated`** (any) - Indicates if the route is deprecated.
- **`auth`** (object) - Authentication details.
  - **`type`** (string) - Type of authentication.
  - **`scheme`** (string) - Authentication scheme.
- **`path_parameters`** (object) - Details of path parameters.
  - **`param_name`** (object) - Details for a specific parameter.
    - **`type`** (string) - Type of the parameter.
    - **`required`** (boolean) - Whether the parameter is required.
- **`request_schema`** (object) - Schema for the request.
  - **`location`** (string) - Location of the schema (e.g., query).
  - **`properties`** (object) - Properties of the schema.
- **`response_schema`** (object) - Schema for the response.
  - **`field_name`** (object) - Details for a specific response field.
    - **`type`** (string) - Type of the field.
- **`response_headers`** (array) - List of response headers.
- **`custom_headers`** (array) - List of custom headers.
- **`rate_limit`** (any) - Rate limit information.
- **`api_version`** (string) - The API version.
- **`status_codes`** (object) - Supported status codes and their descriptions.
- **`content_negotiation`** (array) - Content negotiation types.
- **`matched_route`** (string) - The route that was matched.
- **`batch_results`** (array) - An array of results when in batch mode.
  - **`path`** (string) - The API route path.
  - **`method`** (string) - The HTTP method.
  - **`data`** (object) - The contract details for the route.
    - **`auth`** (object) - Authentication details.
    - **`api_version`** (string) - The API version.
    - **`undocumented`** (boolean) - Indicates if the route is undocumented.
- **`total_operations`** (integer) - Total number of operations across all batch results.

### Response Example (Single Call)
```json
{
    "description": "Retrieve a single user",
    "deprecated": null,
    "auth": { "type": "bearer", "scheme": "Bearer" },
    "path_parameters": {
        "user": { "type": "integer", "required": true }
    },
    "request_schema": { "location": "query", "properties": {} },
    "response_schema": {
        "id":    { "type": "integer" },
        "name":  { "type": "string" },
        "email": { "type": "string" }
    },
    "response_headers": [],
    "custom_headers": [],
    "rate_limit": null,
    "api_version": "v1",
    "status_codes": { "200": "OK", "404": "Not Found" },
    "content_negotiation": [],
    "matched_route": "/api/v1/users/{user}"
}
```

### Response Example (Batch Mode)
```json
{
    "batch_results": [
        { "path": "/api/v1/users",        "method": "GET",  "data": { "auth": { "type": "bearer" }, "api_version": "v1" } },
        { "path": "/api/v1/users",        "method": "POST", "data": { "auth": { "type": "bearer" }, "api_version": "v1" } },
        { "path": "/api/v1/posts/{post}", "method": "GET",  "data": { "undocumented": true } },
        { "path": "/api/v1/posts/{post}", "method": "POST", "data": { "undocumented": true } }
    ],
    "total_operations": 4
}
```
```

--------------------------------

### View MCP Tools Logs

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Access the logs generated by MCP Tools using the Artisan command. Essential for debugging and tracking package activity.

```bash
php artisan mcp-tools:logs
```

--------------------------------

### Inject Custom Analyzer into Command

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/EXTENDING.md

Extend the GenerateApiContractCommand and inject your custom analyzer into the constructor to use it.

```php
protected CustomAnalyzer $customAnalyzer;

public function __construct(
    // ... existing dependencies
    CustomAnalyzer $customAnalyzer
)
{
    // ...
    $this->customAnalyzer = $customAnalyzer;
}
```

--------------------------------

### Generate API Contract

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Use the Artisan command to generate the API contract. This command scans routes and creates a JSON contract file.

```bash
php artisan api:contract:generate
```

--------------------------------

### MCP Tool: List API Routes

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

Lists all API routes, with optional filtering by method, version, search term, limit, and page. This is an MCP tool that must be registered with your MCP server.

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

--------------------------------

### List API Routes

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Returns a paginated, filterable, sortable, and optionally grouped list of API routes from the contract. Supports fuzzy search with AND/OR logic and single-call batch mode when arrays are passed.

```APIDOC
## `list-api-routes` (`Abr4xas\McpTools\Tools\ListApiRoutes`)

### Description
Returns a paginated, filterable, sortable, and optionally grouped list of API routes from the contract. Supports fuzzy search with AND/OR logic and single-call batch mode when arrays are passed.

### Method
GET (implied by tool usage)

### Endpoint
Not directly specified, but the tool call structure suggests an internal API interaction.

### Parameters
#### Request Body
- **`method`** (string or array of strings) - Optional - Filter by HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`
- **`version`** (string or array of strings) - Optional - Filter by API version, e.g. `v1`, `v2`
- **`search`** (string or array of strings) - Optional - Fuzzy search across path, description, parameters, schema fields
- **`limit`** (integer) - Optional - Max results per page (default 50, max 200)
- **`page`** (integer) - Optional - Page number (default 1)
- **`group_by`** (string) - Optional - Group by `controller`, `prefix`, or `version`
- **`controller`** (string) - Optional - Partial-match filter on inferred controller name
- **`resource`** (string) - Optional - Partial-match filter on response resource class
- **`sort`** (string) - Optional - Comma-separated sort fields, e.g. `"path,method"`, `"version:desc,path"`

### Request Example (Single Call)
```json
{
    "method": "GET",
    "version": "v1",
    "search": "user",
    "limit": 20,
    "page": 1,
    "group_by": "version",
    "sort": "path"
}
```

### Request Example (Batch Mode)
```json
{
    "method": ["GET", "POST"],
    "version": ["v1"],
    "search": ["user"],
    "limit": 10
}
```

### Response
#### Success Response
- **`total`** (integer) - Total number of results found.
- **`limit`** (integer) - The limit applied to the results.
- **`grouped_by`** (string) - The field by which results were grouped.
- **`groups`** (object) - An object containing groups of routes.
- **`batch_results`** (array) - An array of results when in batch mode.
  - **`filters`** (object) - The filters applied for this batch result.
  - **`total`** (integer) - Total number of results for this batch.
  - **`limit`** (integer) - The limit applied to this batch result.
  - **`routes`** (array) - An array of route objects.
    - **`path`** (string) - The API route path.
    - **`method`** (string) - The HTTP method.
    - **`auth`** (string) - Authentication method.
    - **`api_version`** (string) - The API version.
- **`total_operations`** (integer) - Total number of operations across all batch results.

### Response Example (Single Call)
```json
{
    "total": 4,
    "limit": 20,
    "grouped_by": "version",
    "groups": {
        "v1": [
            { "path": "/api/v1/users",        "method": "GET", "auth": "bearer", "api_version": "v1" },
            { "path": "/api/v1/users/{user}",  "method": "GET", "auth": "bearer", "api_version": "v1" }
        ]
    }
}
```

### Response Example (Batch Mode)
```json
{
    "batch_results": [
        {
            "filters": { "method": "GET", "version": "v1", "search": "user" },
            "total": 2,
            "limit": 10,
            "routes": [
                { "path": "/api/v1/users",       "method": "GET", "auth": "bearer", "api_version": "v1" },
                { "path": "/api/v1/users/{user}", "method": "GET", "auth": "bearer", "api_version": "v1" }
            ]
        },
        {
            "filters": { "method": "POST", "version": "v1", "search": "user" },
            "total": 1,
            "limit": 10,
            "routes": [
                { "path": "/api/v1/users", "method": "POST", "auth": "bearer", "api_version": "v1" }
            ]
        }
    ],
    "total_operations": 2
}
```
```

--------------------------------

### Manage API Contract Versions

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Utilize the Artisan command to manage different versions of the API contract. This command helps in version control of your API definitions.

```bash
php artisan api:contract:versions
```

--------------------------------

### Response: API contract comparison results

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

This JSON response details the differences between two API contract files, including added/removed routes, method changes, and schema modifications.

```json
{
    "summary": {
        "added_routes":    1,
        "removed_routes":  0,
        "added_methods":   1,
        "removed_methods": 0,
        "modified_routes": 2,
        "schema_changes":  1,
        "auth_changes":    1
    },
    "changes": [
        {
            "type": "added_route",
            "path": "/api/v2/users",
            "methods": ["GET", "POST"],
            "details": {}
        },
        {
            "type": "added_method",
            "path": "/api/v1/users",
            "method": "PATCH",
            "details": {}
        },
        {
            "type": "modified_route",
            "path": "/api/v1/posts/{post}",
            "method": "GET",
            "changes": {
                "auth": {
                    "old": { "type": "none" },
                    "new": { "type": "bearer", "scheme": "Bearer" }
                }
            }
        },
        {
            "type": "modified_route",
            "path": "/api/v1/comments",
            "method": "POST",
            "changes": {
                "request_schema": {
                    "old": { "location": "body", "properties": { "body": { "type": "string" } } },
                    "new": { "location": "body", "properties": { "body": { "type": "string" }, "post_id": { "type": "integer", "required": true } } }
                }
            }
        }
    ]
}
```

--------------------------------

### Custom Schema Transformer Implementation

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

Implement the SchemaTransformerInterface to create custom schema transformations. Register your transformer in your service provider.

```php
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;
    }
}
```

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

--------------------------------

### Export API Contract to OpenAPI

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Export the generated API contract into OpenAPI format using the Artisan command. Useful for integrating with other tools.

```bash
php artisan api:export-openapi
```

--------------------------------

### List API Routes - Batch Mode

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Utilize batch mode by passing arrays for multiple filter combinations to query simultaneously. Limits results per query.

```json
{
    "method": ["GET", "POST"],
    "version": ["v1"],
    "search": ["user"],
    "limit": 10
}
```

--------------------------------

### Response: Contract is up to date

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

This JSON response signifies that the API contract is current and matches the live application routes, with no issues reported.

```json
{
    "valid": true,
    "issues": [],
    "summary": {
        "new_routes": 0,
        "removed_routes": 0,
        "method_changes": 0,
        "total_current": 17,
        "total_contract": 17
    }
}
```

--------------------------------

### Generate API Contract

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Generates the API contract JSON file. Use --incremental to re-process only changed files, --dry-run to validate without writing, --validate-schemas to run JSON Schema validation, and --log to enable structured logging.

```bash
php artisan api:contract:generate
```

```bash
php artisan api:contract:generate --incremental
```

```bash
php artisan api:contract:generate --dry-run
```

```bash
php artisan api:contract:generate --validate-schemas
```

```bash
php artisan api:contract:generate --log
```

--------------------------------

### Custom Analyzer for API Contract Generation

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/ARCHITECTURE.md

Extend contract generation by implementing a custom analyzer. This class should contain your custom analysis logic and return an array of custom fields.

```php
class CustomAnalyzer
{
    public function analyze($route, $routeData): array
    {
        // Your custom analysis logic
        return ['custom_field' => 'value'];
    }
}
```

--------------------------------

### Extract Path Parameters with Type Inference

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Extracts path parameters from a given URI, inferring their types from route-model binding. Ensure the controller method and route are correctly configured for type inference.

```php
use Abr4xas\McpTools\Analyzers\RouteAnalyzer;

$analyzer = app(RouteAnalyzer::class);

// Extract path parameters with type inference from route-model binding
$params = $analyzer->extractPathParams('/api/v1/posts/{post}/comments/{comment}', 'App\Http\Controllers\CommentController@index');
// => ["post" => ["type" => "integer", "required" => true], "comment" => ["type" => "integer", "required" => true]]
```

--------------------------------

### Create Custom MCP Tool

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/EXTENDING.md

Extend the Laravel MCP's Tool class to create a custom tool. Implement the handle and schema methods for tool logic and schema definition.

```php
<?php

namespace App\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CustomTool extends Tool
{
    protected string $name = 'custom-tool';

    protected string $description = 'Custom tool description';

    public function handle(Request $request): Response
    {
        // Get arguments from request
        $argument = $request->get('argument');

        // Implement tool logic
        $result = ['result' => 'data'];

        // Return response (handle json_encode false case)
        $json = json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
        return Response::text($json === false ? '{}' : $json);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'argument' => $schema->string()
                ->description('Example argument'),
        ];
    }
}
```

--------------------------------

### Implement custom schema transformer in PHP

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Implement the `SchemaTransformerInterface` to define custom logic for post-processing generated schemas. Transformers are applied in descending priority order.

```php
<?php

namespace App\Transformers;

use Abr4xas\McpTools\Interfaces\SchemaTransformerInterface;
use Abr4xas\McpTools\Services\SchemaTransformerRegistry;

// Transformer: add a "format" hint to every field whose name ends with "_at"
class DateFieldTransformer implements SchemaTransformerInterface
{
    public function transform(array $schema): array
    {
        foreach ($schema as $key => $value) {
            if (is_array($value) && str_ends_with((string) $key, '_at')) {
                $schema[$key]['format'] = 'date-time';
            }
        }
        return $schema;
    }

    public function getPriority(): int
    {
        return 100; // Higher = applied first
    }
}

// Registration in AppServiceProvider::boot()
public function boot(): void
{
    $registry = $this->app->make(SchemaTransformerRegistry::class);
    $registry->register(new DateFieldTransformer());
}

// SchemaTransformerRegistry::apply() is called automatically during contract generation.
// Multiple transformers at the same priority level are applied in registration order.
// Example: a schema { "created_at": { "type": "string" }, "name": { "type": "string" } }
// becomes: { "created_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" } }

```

--------------------------------

### Implement Custom Schema Transformer

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/EXTENDING.md

Implement the SchemaTransformerInterface to modify schemas before they are included in the final contract. Define the transform and getPriority methods.

```php
<?php

namespace App\Transformers;

use Abr4xas\McpTools\Interfaces\SchemaTransformerInterface;

class CustomTransformer implements SchemaTransformerInterface
{
    public function transform(array $schema): array
    {
        // Add custom logic to transform schema
        foreach ($schema as $key => $value) {
            if (isset($value['type']) && $value['type'] === 'string') {
                $schema[$key]['format'] = 'custom-format';
            }
        }

        return $schema;
    }

    public function getPriority(): int
    {
        return 100; // Higher priority = applied first
    }
}
```

--------------------------------

### Execute Specific Feature Test

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Run a specific feature test file using Pest. This is useful for focused testing during development.

```bash
vendor/bin/pest tests/Feature/GenerateApiContractCommandTest.php
```

--------------------------------

### Register Custom Schema Transformer

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/EXTENDING.md

Register your custom schema transformer in your service provider by making the SchemaTransformerRegistry and calling its register method.

```php
use Abr4xas\McpTools\Services\SchemaTransformerRegistry;

public function boot(): void
{
    $registry = $this->app->make(SchemaTransformerRegistry::class);
    $registry->register(new CustomTransformer());
}
```

--------------------------------

### Extract Route Rate Limit Configuration

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Extracts the rate limit configuration for a route, resolving named limiters defined in the RouteServiceProvider. This helps in understanding API usage constraints.

```php
// Extract throttle config (resolves named limiters from RouteServiceProvider)
$rateLimit = $analyzer->extractRateLimit($route);
// => ["max_attempts" => 60, "decay_minutes" => 1, "description" => "60 requests per 1 minute(s)"]
// => ["name" => "api", "description" => "60 requests per minute"]
```

--------------------------------

### API Contract Structure

Source: https://github.com/abr4xas/mcp-tools/blob/master/README.md

The generated API contract at storage/api-contracts/api.json follows a structured JSON format detailing available endpoints, HTTP methods, and their associated properties.

```APIDOC
## API Contract Structure

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

```json
{
    "/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": []
        }
    }
}
```
```

--------------------------------

### Call validate-api-contract tool

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Use this JSON payload to call the `validate-api-contract` tool, specifying the path to your API contract file.

```json
{
    "contract_path": "storage/api-contracts/api.json"
}
```

--------------------------------

### API Contract JSON Structure

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

The generated contract file at storage/api-contracts/api.json details API routes, including descriptions, authentication, request/response schemas, rate limits, and metadata.

```json
{
    "/api/v1/users": {
        "POST": {
            "description": "Create a new user account",
            "deprecated": null,
            "auth": { "type": "bearer", "scheme": "Bearer" },
            "path_parameters": {},
            "request_schema": {
                "location": "body",
                "properties": {
                    "name":  { "type": "string", "required": true },
                    "email": { "type": "string", "format": "email", "required": true },
                    "password": { "type": "string", "required": true, "constraints": ["min:8"] }
                }
            },
            "response_schema": {
                "id":    { "type": "integer" },
                "name":  { "type": "string" },
                "email": { "type": "string" }
            },
            "response_headers": [],
            "custom_headers": [],
            "rate_limit": { "max_attempts": 60, "decay_minutes": 1, "description": "60 requests per 1 minute(s)" },
            "api_version": "v1",
            "status_codes": { "201": "Created", "422": "Unprocessable Entity" },
            "content_negotiation": []
        }
    },
    "/api/v1/users/{user}": {
        "GET": {
            "description": "Retrieve a single user",
            "deprecated": null,
            "auth": { "type": "bearer", "scheme": "Bearer" },
            "path_parameters": {
                "user": { "type": "integer", "required": true }
            },
            "request_schema": { "location": "query", "properties": {} },
            "response_schema": {
                "id":    { "type": "integer" },
                "name":  { "type": "string" },
                "email": { "type": "string" }
            },
            "response_headers": [],
            "custom_headers": [],
            "rate_limit": null,
            "api_version": "v1",
            "status_codes": { "200": "OK", "404": "Not Found" },
            "content_negotiation": []
        }
    },
    "_metadata": {
        "generated_at": "2025-01-15T10:00:00+00:00",
        "git_commit": "a1b2c3d4...",
        "version": "1.0.0"
    }
}
```

--------------------------------

### Execute Specific Test by Filter

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Run a specific feature test file and filter for a particular test case using Pest. Useful for isolating and debugging specific test failures.

```bash
vendor/bin/pest tests/Feature/GenerateApiContractCommandTest.php --filter="generates API contract"
```

--------------------------------

### Custom Contract Loader Trait

Source: https://github.com/abr4xas/mcp-tools/blob/master/docs/ARCHITECTURE.md

Share contract loading logic across MCP Tools using a trait. Implement your custom loading and validation logic within the loadContract method.

```php
trait LoadsContract
{
    protected function loadContract(): ?array
    {
        // Your custom loading logic
        $path = storage_path('api-contracts/api.json');
        // ... load and validate
    }
}
```

--------------------------------

### Extract API Version from URI

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Extracts the API version segment from a given URI. This is useful for versioning API endpoints.

```php
// Extract API version from URI
$version = $analyzer->extractApiVersion('/api/v2/users');
// => "v2"
```

--------------------------------

### Extract Custom Request Headers

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Extracts custom request headers required by a specific route, including their name, requirement, and description. This is useful for documenting necessary headers for API requests.

```php
// Extract custom request headers required by the route
$headers = $analyzer->extractCustomHeaders($route);
// => [["name" => "X-Signature", "required" => true, "description" => "Webhook signature for request validation"]]
```

--------------------------------

### Response: Contract is stale

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

This JSON response indicates that the API contract is stale, listing discrepancies such as new routes, removed routes, and method changes.

```json
{
    "valid": false,
    "issues": [
        {
            "type": "new_route",
            "path": "/api/v1/notifications",
            "methods": ["GET"],
            "message": "New route found: /api/v1/notifications with methods: GET"
        },
        {
            "type": "removed_route",
            "path": "/api/v1/legacy-endpoint",
            "methods": ["POST"],
            "message": "Route removed from code: /api/v1/legacy-endpoint with methods: POST"
        },
        {
            "type": "new_method",
            "path": "/api/v1/users",
            "method": "PATCH",
            "message": "New HTTP method found: PATCH for route /api/v1/users"
        }
    ],
    "summary": {
        "new_routes": 1,
        "removed_routes": 1,
        "method_changes": 1,
        "total_current": 18,
        "total_contract": 17
    }
}
```

--------------------------------

### MCP Tools Health Check

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Perform a health check on the MCP Tools package using the Artisan command. This helps verify the package's operational status.

```bash
php artisan mcp-tools:health-check
```

--------------------------------

### Clear MCP Tools Analysis Cache

Source: https://github.com/abr4xas/mcp-tools/blob/master/CLAUDE.md

Clear the analysis cache used by MCP Tools through the Artisan command. This can resolve issues related to stale cached data.

```bash
php artisan mcp-tools:clear-cache
```

--------------------------------

### Determine Route Authentication Type

Source: https://context7.com/abr4xas/mcp-tools/llms.txt

Determines the authentication type for a given route by inspecting its middleware. Supported types include Sanctum, Passport, JWT, API key, and Basic authentication.

```php
// Determine authentication type from middleware (Sanctum, Passport, JWT, API key, Basic)
$route = Route::getRoutes()->getByName('api.users.show');
$auth = $analyzer->determineAuth($route);
// => ["type" => "bearer", "scheme" => "Bearer"]   (for auth:sanctum middleware)
// => ["type" => "oauth2", "scheme" => "Bearer", "provider" => "passport"]
// => ["type" => "apiKey", "in" => "header", "name" => "X-API-Key"]
// => ["type" => "none"]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.