README

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)

# Basic usage
php artisan ascend:mcp

# With custom heartbeat interval (recommended for VSCode)
php artisan ascend:mcp --heartbeat=20

Generated configuration entry (excerpt)

{
  "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:

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.