CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Stack

anilcancakir/laravel-agent-mcp is a Laravel PACKAGE (not an application): a secure, read-only MCP server that exposes 25 read-only tools to LLM agents. PHP ^8.3 (CI runs 8.3, 8.4, 8.5), Laravel 12/13 via illuminate/contracts, built on laravel/mcp >=0.6 <0.10. Other runtime deps: phpmyadmin/sql-parser, spatie/laravel-package-tools. Tests run on Orchestra Testbench against in-memory SQLite; there is no app bootstrap or .env to run.

Commands

• composer test runs the Pest suite; composer test-coverage enforces the 80% coverage gate.
• composer analyse runs PHPStan/Larastan at level 6 over src and tests.
• vendor/bin/pint fixes code style (Laravel preset); vendor/bin/pint --test checks without writing.

Layout (non-obvious)

• src/Tools/ is the 25 MCP tools. Each extends AbstractAgentTool and its handle() runs the same pipeline in order: authorize() (the per-tool config gate) first, then audit() (records the argument shape, never values), then the read-only work, then redactor() on the output. A new tool follows this exact order and is gated by config('agent-mcp.tools.<name>').
• src/Server/AgentMcpServer.php holds the $tools registry array and the server #[Instructions].
• src/Support/ is final static helpers (InstallMode, AgentTarget, GuidelineInjector, SkillInstaller, OutputRedactor).
• src/Database/ and src/Sql/ hold the read-only connection resolver and the SELECT-only statement validator.
• config/agent-mcp.php is the consumer-facing config: every tool enable flag, the auth keys, and the query limits.
• resources/boost/ ships the laravel-boost skills and guideline; the resources/boost/** rule covers editing them.

Conventions (project-specific)

• Do not add declare(strict_types=1); pint is configured to strip it and the whole package omits it.
• Outside config/, read the environment with Illuminate\Support\Env::get, never the env() helper.
• Support and value classes are final with class and method docblocks that explain WHY.
• laravel/boost is not a dependency: reference its classes only by string FQCN (e.g. class_exists('Laravel\Boost\BoostServiceProvider')), never a use import.

Invariants (do not break)

• Read-only: there are no write tools and none may be added. Every database read goes through the hardened read-only connection, and db_raw_select is validated SELECT-only. Surface a change for the operator instead of writing.
• Auth is a single server-admin key (AGENT_MCP_KEY), fail-closed: not Sanctum, not a user model, not a database table. Do not add per-user auth.
• The package must stay green across the whole laravel/mcp >=0.6 <0.10 range. Code that touches the mcp surface (Response, Request, transport, trace handling) works across it; do not widen the constraint without testing the new minor.

Git workflow

• main is protected: no direct pushes. Land every change through a pull request that passes CI (the "CI Passed" check) and one approval, then squash-merge; the head branch is deleted on merge.
• Branch off main for work (feat/..., fix/..., chore/...) and open a PR into main.
• Release by pushing a vX.Y.Z tag on main: .github/workflows/release.yml validates, creates the GitHub Release with generated notes, and pings Packagist (which also auto-updates from the tag via its GitHub integration). Do not create releases by hand.
• Dependabot opens grouped weekly PRs for composer and github-actions; low-risk ones (GitHub Actions minor/patch, dev-dependency patches) auto-merge once CI passes.