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):

   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

   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

   # 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

MCP Server Options

Examples

Starting the MCP server (stdio mode)

Generated configuration entry (excerpt)

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:

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.