josbeir / cakephp-synapse
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
Requires
- php: >=8.2
- ext-sqlite3: *
- cakephp/cakephp: ^5.2
- mcp/sdk: ^0.7
- symfony/filesystem: ^7.0 || ^8.0
- symfony/finder: ^7.0 || ^8.0
Requires (Dev)
- cakephp/cakephp-codesniffer: ^5.2
- cakephp/plugin-installer: ^2.0.1
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.1.3 || ^12.0
- rector/rector: ^2.1
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Synapse: a CakePHP MCP-Server plugin
Expose your CakePHP application functionality via the Model Context Protocol (MCP).
Table of Contents
- Overview
- Features
- Installation
- Quick Start
- Configuration
- Built-in Tools
- Built-in Prompts
- CLI usage
- Running the Server
- Upgrading from 0.x
- Testing
- Contributing
- License
- Credits
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-sodiumfor 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
-
Install the plugin (see above)
-
Configure your MCP-enabled client:
To connect Claude Code/Desktop or other MCP clients (VSCode/Zed/...):
- Configure the client to use stdio transport
- Point it to your CakePHP bin directory:
bin/cake mcp start synapse - 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:
- Code Standards: Follow CakePHP coding standards
- Tests: Add tests for new features
- PHPStan: Ensure level 8 compliance
- 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
- Built with CakePHP
- Implements Model Context Protocol
- Built on Crustum MCP
