Laravel Mcp Api Docs Laravel Package

Product Decisions This Supports

• Whether to invest in an "AI-agent-readable API" surface at all. This package turns an existing OpenAPI spec (plus feature docs) into an MCP server, so agents (Copilot, Claude, Cursor, internal assistants) can query endpoints instead of hallucinating them. The buy-vs-build call is: a few hours of integration vs. owning an MCP server, spec caching, and doc-lookup precedence logic yourself.
• How to communicate API change to machine consumers, not just humans. v2.0.0's changelog is the strategically interesting part: every PR that touches openapi.json produces a reviewed, CI-generated entry labelled 🔴 breaking / 🟡 deprecation / 🟢 non-breaking, and a new get_changelog(since?) MCP tool plus a changes list on get_endpoint expose it to agents. This is a deprecation-communication feature, not a docs feature — it lets you make "agents must not use deprecated fields" an enforceable, versioned statement rather than a Slack announcement.
• Roadmap sequencing for API versioning / breaking-change policy. If you have been deferring a formal breaking-change process, the oasdiff-based diff makes it cheap: the gate exists as soon as the workflow is installed. Conversely, if your team cannot commit to keeping openapi.json current (manual export discipline, or Scramble generation), the changelog feature is dead weight and should be scoped out of the pilot.
• Evaluating the "docs as a product surface" use case. Concrete near-term use cases worth piloting: onboarding agents to your public API for partner integrations, an internal support copilot that answers "what changed in the payments endpoint last sprint," and pre-release checks that surface breaking diffs in code review.
• Platform baseline decision. v2.0.0 is Laravel 12 only and requires laravel/mcp ^0.7–^1.0. That makes this a forcing function on your Laravel 12 migration timeline; it should be sequenced after, not in parallel with, the framework upgrade.

When to Consider This Package

Consider adoption when:

• You are on Laravel 12 and can take laravel/mcp ^0.7+.
• You already have, or can generate, an openapi.json (Scramble mode removes the manual export step and makes the changelog self-maintaining).
• You want agents consuming your API and you care about them not silently using deprecated endpoints — the changelog is the differentiator, and it is opt-in and off by default.
• You can accept CI-side changes: the install command writes a GitHub Actions workflow, and the diff script is committed to your repo (a plus for auditability, but it is a repo artifact your team now owns).
• Your PR flow is GitHub-centric and you want changelog entries reviewed with the code rather than authored separately.

Look elsewhere or defer when:

• You are still on Laravel 11 — v2.0.0 drops support, so stay on 1.4 until the upgrade lands.
• You rely on openapi.url while a stale openapi.file is also configured: v2.0.0 flips precedence so the file wins, which can silently change what agents see after upgrade. Audit config before rolling out.
• You use a non-GitHub CI system (GitLab, Bitbucket, Jenkins) — the changelog automation is GitHub Actions-shaped, and you would be reimplementing the workflow.
• Your API surface is small/stable enough that per-PR changelog entries are noise, or your team won't maintain the spec baseline.
• You need vendor support/SLAs; this is a single-maintainer OSS package.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost capability that makes our API legible to AI coding agents — both ours and our customers'. The 2.0 release adds an automatically generated, per-pull-request API changelog with breaking changes flagged in code review, which converts "we told people about the deprecation" into "it is recorded, versioned, and queryable by the tools agents actually use." Cost is one artisan command and a CI workflow; the main constraint is that it requires Laravel 12.

For engineering: Upgrade path is composer require dhur-gham/laravel-mcp-api-docs:^2.0, but treat it as a real major: Laravel 12 only, laravel/mcp ^0.7+, and openapi.file now takes precedence over openapi.url — check config before deploying. Changelog is opt-in via php artisan mcp-api-docs:install-changelog plus MCP_API_DOCS_CHANGELOG_FILE; it pins actions to SHAs, verifies the oasdiff download by SHA-256, skips fork PRs, and baselines the first spec so we don't get a fake "everything added" entry. Also new: openapi.json is cached between tool calls (60s default, failures not cached), which removes a per-call fetch cost.

Ask: approve a one-sprint pilot on an internal API after the Laravel 12 upgrade, with success measured by (a) agents answering endpoint questions without hallucinated routes, and (b) at least one breaking change caught in review by the changelog bot before merge.