Statamic Mcp Laravel Package

Technical Evaluation

The package is an MCP-oriented integration layer that exposes Statamic content-model introspection to agent runtimes inside a Laravel application. v0.9.1 extends blueprints_get to read navigation blueprints (type: navigation), returning branch data field definitions, Replicator/Bard set schemas, and example notes for title/url branch keys. This is an additive, read-only capability.

Architecture fit: Strong. It extends the existing blueprint-introspection surface rather than introducing a new subsystem. The change is scoped to tool dispatch and response shaping, which matches a Laravel package’s service-provider/tool-registration model and Statamic’s blueprint/navigation repositories. It supports the correct agent workflow: inspect schema before mutating navigation content.

Integration feasibility: Low effort. No migrations, no content changes, and likely no new configuration. Permissions reuse the existing view {handle} nav gate, so roles that can already call navigations_get should work. The main integration step is a Composer update and restart of the MCP server/worker so clients pick up the updated tool schema.

Technical risk: Low-to-moderate. The code path is read-only and additive, so regression risk to existing tools is limited. Risks are mainly contract and permission related: (1) 0.x versioning means tool input/output shapes can still change; (2) navigation blueprint shapes vary—Replicator/Bard nesting and branch-level title/url keys require agent prompts to follow example_notes; (3) partial permissions will produce partial schemas, which can confuse agents; (4) example rows may derive from real content, raising data-exposure questions.

Key questions:

• Does blueprints_get read live blueprints or cached definitions, and is caching configurable?
• How does the server resolve view {handle} nav permissions per request, especially for long-lived MCP sessions?
• What happens for missing navigation handles, blueprints without sets, or nested Replicator/Bard structures?
• Are example_notes and example rows synthetic, or sampled from production content?
• Is multisite supported—does the tool resolve the correct site’s navigation blueprint?
• What is the supported matrix for Statamic major versions, PHP versions, and MCP client schema-refresh behavior?

Integration Approach

Stack fit: Laravel application + Statamic CMS + an MCP-capable agent host. The package sits alongside existing Statamic tooling and does not alter the content repository. It is appropriate for teams already using navigations_get and navigations_update in agent workflows.

Migration path: Update the Composer dependency, run the application test suite, restart the MCP server/process, and confirm the tool schema includes the new navigation behavior. No database or content migration is required. If the package is pinned, update the lockfile deliberately and review the release diff.

Compatibility: Verify against the target Statamic major and PHP runtime before rollout. Confirm that the application’s permission model maps the same view {handle} nav permission used by navigations_get. Confirm that MCP clients refresh tool definitions after server restart; otherwise agents may continue using the old schema.

Sequencing:

1. Update in a development environment and call blueprints_get against a known navigation handle.
2. Validate the response for a Replicator or Bard field, including set fields and example rows.
3. Confirm example_notes correctly instructs agents to pass title/url as branch keys, not inside data.
4. Test with the least-privileged MCP role intended for production.
5. Roll out to staging, then production, behind a tool-level feature flag if the server supports it.
6. Update agent system prompts and runbooks to require blueprints_get before navigations_update on navigation content.

Operational Impact

Maintenance: Low. The change is additive and isolated to one read path. The main maintenance burden is tracking 0.x releases and reviewing tool-schema changes. Keep the dependency pinned and review each minor release.

Support: Expect some support load from agent misconfiguration—particularly agents placing title or url inside data. The new example_notes reduces this, but prompt templates and internal documentation should be updated. Document the required navigation permissions for MCP service accounts.

Scaling: Read-only blueprint introspection is inexpensive and does not affect content write throughput. Watch for repeated tool calls within a single agent turn; if the server supports response caching, cache blueprint responses per handle and site. Large blueprints with deep Replicator/Bard nesting may produce verbose tool output, so monitor token usage.

Failure modes: Permission-denied errors for roles lacking view {handle} nav; missing navigation handles; blueprints with type: navigation but no sets; deeply nested set structures; stale tool schemas in long-running MCP clients; and potential exposure of internal field naming or example content. Negative-path behavior should be tested explicitly.

Ramp-up: Low for Laravel developers familiar with Statamic blueprints. Moderate for agent prompt authors who need to understand branch data shape, Replicator/Bard sets, and the distinction between branch keys and data fields. Provide a short runbook with a working navigation example and the updated prompt guidance.