laravel-ascend

# Laravel Ascend Ascend is an MCP-compatible server and toolkit that upgrades Laravel applications with structured upgrade documentation, analyzers, and automation. It ships with a curated Laravel knowledge base, a rich MCP tool suite, and first-class Artisan commands that make it easy to surface the guidance directly in modern IDEs like VS Code. ## Features - **MCP-ready server** – launch over stdio via `php artisan ascend:mcp`, exposing tools, resources, and prompts that follow the Model Context Protocol. - **Curated knowledge base** – search upgrade guides, breaking changes, migration patterns, and upgrade paths sourced from `resources/knowledge-base`. - **Extensive tool catalog** – documentation queries, dependency scanners, code migration advisors, and package compatibility checks implemented under `src/Tools`. - **One-command IDE registration** – `ascend:register` writes entries to `.vscode/mcp.json`, `.cursor/mcp.json`, and `.junie/mcp/mcp.json`. - **Composer-friendly package** – auto-discovered Laravel service provider registers the Artisan commands needed for MCP integration. ## Requirements - PHP 7.4+ or 8.x (supports PHP 7.4, 8.0, 8.1, 8.2, 8.3) - Laravel 6.x - 11.x - Composer 2.x - Node.js is **not** required (server runs via PHP/Artisan) ## Installation ### Laravel application 1. Require the package (typically as a dev dependency): ```bash composer require --dev goldenpathdigital/laravel-ascend ``` 2. Laravel's package auto-discovery registers the `AscendServiceProvider`, exposing: - `php artisan ascend:mcp` – start the MCP server over stdio (add `--kb-path` or `--heartbeat` if needed) - `php artisan ascend:register` – register the server with supported MCP clients ## Quick Start 1. **Start the MCP server** ```bash php artisan ascend:mcp ``` - Runs over stdio (compatible with Claude Desktop, VSCode MCP). - Provide `--kb-path=/path/to/knowledge-base` to point at a custom data directory. - Provide `--heartbeat=30` to configure heartbeat interval (default: 30 seconds, min: 10). **Connection Keep-Alive:** The server automatically sends heartbeat notifications every 30 seconds (configurable) to prevent idle connection timeouts in MCP clients like VSCode. 2. **Register the server with IDE clients** ```bash # Laravel Artisan php artisan ascend:register ``` Registration automatically updates the following if present: **Project-level configurations:** - `.vscode/mcp.json` (VSCode) - `.cursor/mcp.json` (Cursor) - `.junie/mcp/mcp.json` (Junie) **User-level configurations:** - `~/.config/Code/User/mcp.json` (VSCode Global) - `~/.claude/mcp/mcp.json` (Claude Desktop Legacy) - `~/.config/Claude/mcp.json` (Claude Desktop) - `~/.config/Codex/mcp.json` (Codex JSON) - `~/.codex/config.toml` (Codex TOML) 3. **Connect from your IDE** - In VS Code, open the MCP Servers panel and confirm `laravel-ascend` is enabled. - For other MCP-aware clients, import the generated config or point them at the running stdio endpoint. ## Artisan Commands | Command | Description | | --- | --- | | `php artisan ascend:mcp [options]` | Start the Ascend MCP server over stdio. | | `php artisan ascend:register [--global]` | Add Ascend to detected MCP configuration targets (project + global). | ### MCP Server Options | Option | Description | Default | | --- | --- | --- | | `--kb-path=/path` | Path to a custom knowledge base directory | Auto-detected | | `--heartbeat=30` | Heartbeat interval in seconds (prevents timeout) | 30 seconds | | `--timeout=900` | Server process timeout in seconds (0 = unlimited) | 900 seconds | | `--websocket` | Use WebSocket instead of stdio | stdio | | `--host=127.0.0.1` | Host for WebSocket mode | 127.0.0.1 | | `--port=8765` | Port for WebSocket mode | 8765 | ## Examples ### Starting the MCP server (stdio mode) ```bash # Basic usage php artisan ascend:mcp # With custom heartbeat interval (recommended for VSCode) php artisan ascend:mcp --heartbeat=20 ``` ### Generated configuration entry (excerpt) ```json { "mcpServers": { "laravel-ascend": { "command": "php", "args": [ "/path/to/your/project/artisan", "ascend:mcp" ], "timeout": 60 } } } ``` ## MCP Tooling Overview - **Documentation tools** (`src/Tools/Documentation/*`) – search upgrade docs, fetch breaking change details, list deprecated features, and retrieve guided upgrade summaries. - **Analysis tools** (`src/Tools/Analysis/*`) – inspect current Laravel versions, dependency manifests, PHP compatibility, and breaking changes specific to your code base. - **Code migration tools** (`src/Tools/Code/*` & `src/Tools/Migration/*`) – analyze configs, facades, Blade templates, generate upgrade checklists, and validate migration steps. - **Package insights** (`src/Tools/Package/*`) – verify package compatibility and suggest updates that align with target Laravel versions. - **Tool registry** (`src/Tools/ToolRegistry.php`) – auto-discovers classes implementing `ToolInterface`, so new tools are picked up without manual wiring. ## Knowledge Base Content The bundled knowledge base lives under `resources/knowledge-base`: - `index.json` – metadata for the entire data set. - `breaking-changes/*.json` – per-version breaking change summaries. - `patterns/*.json` – migration patterns with remediation guidance. - `upgrade-paths/upgrade-paths.json` – curated upgrade roadmaps (e.g. `8-to-9`). - `mcp_knowledge_base_guide.md` – authoring guidelines for extending the KB. To point Ascend at a modified data set, start the Artisan MCP command with `--kb-path=/absolute/path`. ## Development Clone the repository and install dependencies with Composer, then use the provided scripts: ```bash composer test # Pest test suite composer typecheck # PHPStan level 8 static analysis composer format # php-cs-fixer (PSR-12) composer coverage # Pest with coverage (requires Xdebug) composer mutate # Infection mutation testing composer security:audit # Composer advisories ``` The test suite covers knowledge base parsing, MCP registration, and tool behaviors. Please ensure all checks pass before opening a pull request. ## Contributing See `CODE_OF_CONDUCT.md` for community standards. Security disclosures should follow the instructions in `SECURITY.md`. ## License Laravel Ascend is open-source software licensed under the [MIT license](LICENSE).