Search by

josbeir / cakephp-synapse

josbeir

CakePHP MCP Server Plugin - Expose CakePHP functionality via Model Context Protocol

Package info

github.com/josbeir/cakephp-synapse

Type:cakephp-plugin

pkg:composer/josbeir/cakephp-synapse

Statistics

Installs: 2 981

Dependents: 0

Suggesters: 0

Stars: 9

Open Issues: 0

0.3.0 2026-08-08 09:26 UTC

This package is auto-updated.

Last update: 2026-11-16 17:17:09 UTC


README

PHPStan Level 8 Build Status codecov License: MIT PHP Version CakePHP Version Packagist Downloads

Synapse: a CakePHP MCP-Server plugin

Expose your CakePHP application functionality via the Model Context Protocol (MCP).

CakePHP Synapse Hero

Table of Contents

Overview

Synapse provides CakePHP development capabilities over the Model Context Protocol (MCP). It uses Crustum MCP for protocol handling, local stdio transport, explicit capability registration, and Inspector integration.

The Model Context Protocol is an open protocol that enables seamless integration between AI assistants (like Claude) and your application's data and functionality. With Synapse, you can expose:

  • Tools: Functions that AI assistants can call (e.g., database queries, route inspection)
  • Resources: Data sources that can be read
  • Prompts: Pre-configured templates for common tasks

Features

  • 🚀 Rapid Integration: Enable MCP support in your CakePHP app with minimal setup
  • 🔍 Explicit Capability Catalog: Built-in tools, resources, and prompts with stable names, schemas, and annotations
  • 🛠️ Built-in Tools: Includes tools for system info, database schema exploration, route inspection, code execution, log inspection, cache management, ORM introspection, and more
  • 📚 Advanced Documentation Search: Full-text search with fuzzy matching and relevance ranking, powered by SQLite FTS5 (indexes official CakePHP markdown docs)
  • 🧩 Customizable & Extensible: Easily define your own tools, resources, and prompts using attributes and configuration
  • ⚡ Prompt Workflows: Built-in prompt flows for common development tasks, code review, debugging, and feature building

Installation

Requirements

  • PHP 8.2 or higher
  • CakePHP 5.4 or higher (5.x)
  • SQLite3 with FTS5, intl, and the extensions required by Composer's dependency resolution
  • ext-sodium for the current OAuth dependency on PHP 8.5

Crustum currently registers Bake console commands unconditionally, so CakePHP Bake is included as a runtime dependency. Synapse does not load Bake or Tessera as application plugins and does not require OAuth tables.

Installing the Plugin

Install via Composer as a development dependency:

composer require --dev josbeir/cakephp-synapse

Note

This plugin is typically used as a development tool to allow AI assistants to interact with your application during development. It should not be installed in production environments.

Load the plugins in this order in your application's config/plugins.php:

return [
    'Crustum/Mcp' => [
        'onlyCli' => true,
        'optional' => true,
        'routes' => false,
        'middleware' => false,
    ],
    'Synapse' => ['onlyCli' => true, 'optional' => true],
];

For an application that loads plugins programmatically, use the same plugin names and options with $this->addPlugin(). Use the full Crustum/Mcp name so configuration loading resolves the already loaded plugin.

Synapse registers its local server as synapse. This setup enables no HTTP endpoints or HTTP middleware.

The existing documentation index remains compatible with 1.0. See the upgrade guide when migrating from 0.x.

Quick Start

  1. Install the plugin (see above)

  2. Configure your MCP-enabled client:

To connect Claude Code/Desktop or other MCP clients (VSCode/Zed/...):

  1. Configure the client to use stdio transport
  2. Point it to your CakePHP bin directory: bin/cake mcp start synapse
  3. The client will communicate with your app via the MCP protocol

Most clients require a command which will be your cake executable bin/cake followed by arguments: mcp start synapse

{
  "my-cakephp-app": {
    "command": "bin/cake",
    "args": ["mcp", "start", "synapse"]
  }
}

Or run when using DDEV instance

{
  "my-cakephp-app": {
    "command": "ddev",
    "args": ["cake", "mcp", "start", "synapse"]
  }
}

Configuration

Defaults live in config/synapse.php. Override them under the Synapse key in your application configuration, or create config/app_synapse.php. Documentation indexing, prompt settings, Tinker paths, server metadata, and instructions remain configurable.

Additional capabilities belong under Synapse.capabilities.tools, .prompts, and .resources. Crustum registration belongs under Mcp.local. Hosts can override Mcp.local.synapse with their own server class.

Capabilities are registered explicitly on each process startup. Synapse no longer scans application directories or caches discovered classes. Crustum handles protocol negotiation and response cache hints.

Built-in Tools

Synapse includes several built-in tools and resources for common operations:

Category Name Description
System system_info Get CakePHP version, PHP version, debug mode, etc.
System config_read Read configuration values with sensitive keys redacted
System debug_status Check if debug mode is enabled
System list_env_vars List available environment variable names with values redacted
Code Execution tinker Execute arbitrary PHP code with full application context
Database database_connections List all configured database connections
Database database_schema Get detailed schema information for tables (view all tables, inspect columns, constraints, indexes, understand foreign key relationships)
Routes list_routes List all routes with filtering and sorting
Routes get_route Get detailed information about a specific route
Routes match_url Find which route matches a given URL
Routes detect_route_collisions Find potential route conflicts
Documentation search_docs Search documentation with relevance ranking, fuzzy matching, and filtering
Documentation get_doc Retrieve full document content by document ID (format: source::path)
Documentation docs_stats View index statistics and available sources
Documentation docs://search/{query} Search CakePHP documentation and return formatted results
Documentation docs://content/{docId} Retrieve full document content by document ID (URI-encoded source::path)
Commands list_commands List all available CakePHP console commands with optional filtering and sorting
Commands get_command_info Get detailed information about a specific console command (options, arguments, help)
Commands run_command Run a registered CakePHP console command in a subprocess with configurable timeout
Logs log_list List all log files in the application logs directory with size and modification time
Logs log_read Read the last N lines from a log file, optionally filtered by log level (error, warning, info, debug, …)
Cache cache_configs List all configured CakePHP cache configurations with engine information
Cache cache_read Read a value from a cache configuration by key
Cache cache_write Write a string value to a cache configuration
Cache cache_delete Delete a key from a cache configuration
Cache cache_clear Clear all entries from a cache configuration
ORM orm_describe Describe a CakePHP ORM Table: associations, behaviors, display field, primary key, entity class
ORM orm_find Run a find query (all, first, or count) on an ORM Table with a configurable row limit

Warning

The tinker tool executes arbitrary code in your application. Use responsibly and avoid modifying data without explicit approval.

Tip

The tinker tool can be used to query the database using CakePHP's ORM. The tinker context provides access to $this->fetchTable() for easy database operations.

Note

Documentation is indexed from the official CakePHP markdown documentation. The index is built locally using SQLite FTS5 for fast, dependency-free full-text search.

Built-in Prompts

Synapse includes pre-defined prompt workflows that guide LLMs through common CakePHP development tasks. Prompts combine multiple tools (search docs, read documentation, tinker) into structured, best-practice workflows.

Available Prompts

Prompt Description Arguments
documentation-expert Get comprehensive guidance on CakePHP features with examples topic (required), depth (optional: basic/intermediate/advanced)
debug-helper Systematic debugging workflow for errors and issues error (required), context (optional: controller/model/database/view)
feature-builder Guide for implementing complete features following conventions feature (required), component (optional: controller/model/behavior/helper/middleware/command/full-stack)
database-explorer Explore database schema, relationships, and data table (required), show (optional: schema/data/relationships/all)
code-reviewer Review code against CakePHP conventions and best practices code (required), focus (optional: conventions/security/performance/testing/all)
migration-guide Help migrate code between CakePHP versions fromVersion, toVersion (required), area (optional: specific feature or general)
testing-assistant Generate test cases and testing guidance subject (required), testType (optional: unit/integration/fixture/all)
performance-analyzer Analyze and optimize performance issues concern (required), context (optional: code snippet or description)
orm-query-helper Build complex ORM queries with guidance queryGoal (required), tables (optional: comma-separated list)
tinker-workshop Interactive PHP exploration and testing guide goal (required: explore/test/debug), subject (optional)
quality-assurance Coding guidelines and QA best practices for CakePHP context (optional: guidelines/integration/troubleshooting/all), tools (optional: all or comma-separated list)

Prompts return guidance for the agent to follow using the available tools. They do not invoke tools or execute code themselves.

Benefits:

  • Faster workflows - Common tasks become one-step operations
  • Best practices - Prompts encode CakePHP expertise and conventions
  • Consistency - Standardized approaches to common problems
  • Discovery - See available workflows without remembering tool combinations

Configuring Prompts

Prompts can reference a specific CakePHP version and use various quality tools. Configure both in config/synapse.php:

return [
    'Synapse' => [
        'prompts' => [
            // Target CakePHP version for prompt responses (e.g. '5.x', '5.2', '4.5', '4.x')
            'cakephp_version' => env('MCP_CAKEPHP_VERSION', '5.x'),

            // Target PHP version for prompt responses (e.g. '8.2', '8.3', '8.x')
            'php_version' => env('MCP_PHP_VERSION', PHP_VERSION),

            // Quality tools configuration
            'quality_tools' => [
                'phpcs' => ['enabled' => true, 'standard' => 'cakephp'],
                'phpstan' => ['enabled' => true, 'level' => 8],
                'phpunit' => ['enabled' => true, 'coverage' => true],
                'rector' => ['enabled' => false, 'set' => 'cakephp'],
                'psalm' => ['enabled' => false, 'level' => 3],
            ],
        ],
    ],
];

Creating Custom Tools, Resources, and Prompts

Create classes extending Crustum's Tool, Prompt, or Resource, using its supported names, descriptions, schemas, and response API. Register additional classes explicitly:

return [
    'Synapse' => [
        'capabilities' => [
            'tools' => [\App\Mcp\Tools\ApplicationInfoTool::class],
            'prompts' => [],
            'resources' => [],
        ],
    ],
];

These lists append to Synapse's built-in catalog. Duplicate names and invalid classes fail at startup. Register dependencies in the CakePHP container; capability handlers can receive services through method injection. Crustum's shouldRegister() conditions apply to both listing and invocation.

See the complete custom-tool migration example and Crustum integration documentation.

CLI usage

Use the CLI to manage and search the index:

# Index all sources
bin/cake synapse index

# Index specific source
bin/cake synapse index --source cakephp-5x

# Force re-index and optimize
bin/cake synapse index --force --optimize

# Search documentation from CLI (interactive mode by default)
bin/cake synapse search "authentication"

# Search with options
bin/cake synapse search "database queries" --limit 5 --fuzzy --detailed

# Non-interactive mode for scripts/CI
bin/cake synapse search "authentication" --non-interactive

# Interactive features:
# - View result details and snippets
# - Navigate between results
# - View full document content
# - All from within the CLI

Running the Server

Configure your MCP client to launch the local server from the application directory:

bin/cake mcp start synapse

The command reads MCP requests from stdin and writes only protocol responses to stdout. Configure application logging to use files or stderr.

Testing with MCP Inspector

Crustum provides the native Inspector command:

bin/cake mcp inspector synapse

Inspector requires Node.js/npx and a browser. It can inspect capability metadata and invoke tools, prompts, and resources.

Synapse officially supports local stdio. Remote HTTP servers, OAuth configuration, and MCP Apps are outside this release's integration.

Upgrading from 0.x

Version 1.0 replaces the SDK implementation with Crustum MCP and requires CakePHP 5.4+. Update client launch arguments and migrate SDK attribute capabilities to explicit Crustum classes. The old server command, discovery cache flags, and scanning configuration have been removed.

See UPGRADING.md for the migration checklist, configuration mapping, and custom-tool example.

Testing

Run the test suite:

# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run PHPStan analysis
composer phpstan

# Check code style
composer cs-check

# Fix code style
composer cs-fix

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Code Standards: Follow CakePHP coding standards
  2. Tests: Add tests for new features
  3. PHPStan: Ensure level 8 compliance
  4. Documentation: Update README for new features

Development Setup

# Clone the repository
git clone https://github.com/josbeir/cakephp-synapse.git
cd synapse

# Install dependencies
composer install

# Run tests
composer test

# Run static analysis
composer phpstan

License

This plugin is open-sourced software licensed under the MIT license.

Credits