Model Context Protocol (MCP)

FW is AI-First. To support this, it implements a specialized Model Context Protocol (MCP) endpoint that allows AI agents to "handshake" with the application to understand its current state without expensive filesystem crawling.

The Endpoint: /mcp

The /mcp endpoint returns a structured JSON map of the application's metadata.

Security Note

The /mcp endpoint is restricted to Development environments. By default, it will return a 403 Forbidden if APP_DEBUG is false or if the environment is production.

Capabilities

The MCP endpoint currently exposes:

1. Framework Version: Returns the current FW version and core philosophy.
2. Route Map: A full list of all registered routes, including:
   • HTTP Method
   • URI Pattern
   • Handler Class (FQCN)
   • Associated Middleware
3. Container Metadata (Future): Will expose top-level service IDs and their dependencies.
4. Schema Metadata (Future): Will expose database entity maps and DTO structures.

Usage for AI Agents

When an agent first encounters an FW project, it should attempt to GET /mcp. This allows the agent to:

• Instantly know which endpoints are available.
• Identify the correct Handlers to modify for specific features.
• Understand the security layers (JWT/CSRF) applied to each route.

Example Response

{
  "version": "fw/v1.0",
  "philosophy": "AI-First, Lean Core, Progressive Enhancement",
  "routes": [
    {
      "method": "GET",
      "uri": "/",
      "handler": "App\\View\\Compiled\\WelcomeView",
      "middleware": []
    },
    {
      "method": "POST",
      "uri": "/auth/login",
      "handler": "Modules\\User\\LoginUserHandler",
      "middleware": []
    }
  ]
}