Laravel Mcp Api Docs Laravel Package

Technical Evaluation

Architecture fit: dhur-gham/laravel-mcp-api-docs v2.0.0 is a Laravel package that exposes OpenAPI documentation to AI agents through MCP tools such as get_endpoint and the new get_changelog(since?). It fits Laravel 12 applications that already maintain an openapi.json spec, either manually or via Scramble. The new changelog feature adds a CI-driven metadata layer: each PR produces a per-endpoint changelog entry generated by comparing OpenAPI specs with oasdiff and classifying changes as breaking, deprecation, or non-breaking.

Integration feasibility: For Laravel 12 teams on GitHub Actions, integration is straightforward. The new installer command php artisan mcp-api-docs:install-changelog asks whether the spec is manual or Scramble-generated and writes the workflow. The changelog is opt-in and remains off until MCP_API_DOCS_CHANGELOG_FILE is configured. Teams outside GitHub Actions, or those using another VCS/CI provider, will need custom workflow work because the release is oriented around PR-based GitHub automation.

Technical risk: The release contains breaking changes: Laravel 12 only, laravel/mcp ^0.7 or newer, and changed precedence when both openapi.file and openapi.url are configured — the local file now wins. These are manageable but require upgrade validation. The changelog bot writes to PR branches and comments on PRs, so repository token permissions and branch protection rules must be reviewed. oasdiff classification may produce noisy or debatable entries, especially for large or inconsistently maintained specs. The release does include sensible safety defaults: pinned action SHAs, SHA-256 verification for oasdiff downloads, skipped fork PRs, collaborator-only command execution, and a first-spec baseline to avoid a massive initial changelog entry.

Key questions:

• Which CI/VCS providers are supported beyond GitHub Actions, and is the changelog workflow adaptable to GitLab CI or Bitbucket Pipelines?
• What GitHub token permissions are required for the bot to commit to PR branches and comment on PRs, and how does that interact with protected branches?
• How large can the committed changelog file grow, and is there a pruning or retention strategy?
• Does get_changelog return the full history by default, and how does that affect MCP context size and agent performance?
• Are private repository specs or changelog entries exposed to the MCP server in ways that require additional authentication or access control?
• How reliable is oasdiff classification for this team’s API style, and who reviews false positives or missed breaking changes?

Integration Approach

Stack fit: Best fit is a Laravel 12 application using laravel/mcp ^0.7 through ^1.0, with an OpenAPI spec maintained manually or through Scramble, hosted on GitHub with Actions enabled. The package’s core MCP documentation serving can be adopted without the changelog feature; the changelog is an additional opt-in capability.

Migration path: From 1.4.x, the upgrade path is:

1. Confirm the application is on Laravel 12. If still on Laravel 11, either stay on 1.4.x or schedule a Laravel 12 upgrade first.
2. Confirm laravel/mcp is at ^0.7 or newer.
3. Run composer require dhur-gham/laravel-mcp-api-docs:^2.0.
4. Review configuration where both openapi.file and openapi.url are set, because file precedence has changed.
5. Run the test suite and verify existing MCP tools still return expected endpoint documentation.
6. Only then run php artisan mcp-api-docs:install-changelog and set MCP_API_DOCS_CHANGELOG_FILE in a pilot repository.

Compatibility: The main compatibility gate is Laravel 12. Laravel 11 environments are explicitly unsupported in 2.0.0. The laravel/mcp version requirement is also stricter. The changelog workflow assumes GitHub-style PRs, bot comments, and branch commits; non-GitHub environments should treat that feature as requiring custom implementation. The new spec lookup order — local file, then URL, then fallback paths — may change behavior in setups that previously relied on URL precedence.

Sequencing: Treat this as a dependency and workflow upgrade, not just a Composer bump. Sequence:

1. Inventory Laravel and laravel/mcp versions across affected services.
2. Upgrade the framework/runtime dependency path in a branch.
3. Upgrade the package and validate core MCP documentation tools.
4. Verify cache behavior with MCP_API_DOCS_OPENAPI_CACHE_TTL.
5. Pilot the changelog installer in one low-risk repository.
6. Exercise the PR workflow, including a breaking-change PR, a non-breaking PR, and a /update-mcp-changelog conflict scenario.
7. Roll out to additional repositories once the workflow and review expectations are clear.

Operational Impact

Maintenance: The core package remains relatively low-maintenance, but the changelog feature adds a CI workflow and a committed changelog artifact that the team owns. Changelog entries are generated by CI and reviewed with code, which is good for accuracy, but it means developers will see bot commits and PR comments in their normal review flow. The workflow’s pinned actions and checksum verification reduce supply-chain risk, but the workflow itself should be reviewed and periodically updated.

Support: Teams already comfortable with Laravel and GitHub Actions should have low support burden. The one-command installer lowers setup friction. Teams on other CI systems will need platform engineering support to reproduce the workflow. Documentation should clarify token permissions, fork PR behavior, and what to do when the changelog command conflicts with a merged PR.

Scaling: Scaling is mostly per-repository rather than centralized. Each repository gets its own workflow and changelog file. CI runtime overhead should be modest because oasdiff operates on spec files, but large OpenAPI specs or very active repositories may create more changelog churn. The runtime cache for openapi.json — default 60 seconds, with failed loads not cached — helps reduce repeated spec-loading cost during MCP tool calls. Over time, the committed changelog file may grow and need a retention or summarization policy.

Failure modes:

• GitHub Actions permissions prevent the bot from committing to the PR branch or commenting.
• The spec is not exported, causing missing or stale diffs; Scramble mode mitigates this by regenerating on push.
• oasdiff misclassifies a change, producing a misleading breaking/non-breaking label.
• Concurrent PRs create changelog conflicts; the /update-mcp-changelog command is the recovery path.
• Fork PRs are skipped by design, so external contributions will not receive automated changelog entries.
• Misconfigured openapi.file and openapi.url precedence causes the wrong spec to be served.
• Cached specs may be up to 60 seconds stale; failed loads are not cached, which is safer but can increase retries during outages.
• Upgrading without addressing the Laravel 12 or laravel/mcp requirements will break installation or runtime behavior.

Ramp-up: Ramp-up is low for Laravel 12 teams on GitHub: install the package, run the installer, review one pilot PR, and document the changelog review convention. Ramp-up is medium for teams on Laravel 11, non-GitHub CI, or multiple repositories, because those teams need a framework upgrade or a custom automation path before the changelog feature delivers its main value.