josbeir/cakephp-synapse

Synapse: a CakePHP MCP-Server plugin

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

Table of Contents

• Overview
• Features
• Installation
  • Requirements
  • Installing the Plugin
• Quick Start
• Configuration
• Built-in Tools
• Built-in Prompts
  • Creating Custom Tools, Resources, and Prompts
• CLI usage
• Running the Server
  • Command Options
  • Testing with MCP Inspector
  • Transport Options
• Discovery Caching
• Testing
• Contributing
• License
• Credits

Overview

Synapse is a CakePHP plugin that implements the Model Context Protocol (MCP), allowing AI assistants and other MCP clients to interact with your CakePHP application through a standardized interface.

[!WARNING] This plugin uses the MCP PHP SDK which is currently in active development. Features and APIs may change as the SDK evolves.

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
• 🔍 Attribute-Based Discovery: Finds MCP tools, resources, and prompts using PHP 8+ attributes and class scanning
• 🛠️ Built-in Tools: Includes tools for system info, database schema exploration, route inspection, code execution, 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.2 or higher

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.

bin/cake plugin load --only-cli --optional Synapse

The plugin will automatically register itself and discover MCP elements in your application.

[!TIP] After updating the plugin, it's recommended to re-index the documentation to ensure all features work correctly:

bin/cake synapse index -d  # Destroy old index
bin/cake synapse index     # Re-index documentation

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 synapse server
3. The client will communicate with your app via the MCP protocol

Most clients require a command wich will be your cake executable bin/cake followed by arguments: synapse server

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

Or run when using DDEV instance

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

Configuration

Various configuration options are available for Synapse. Refer to config/synapse.php in this plugin for details on available settings and customization.

Built-in Tools

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

[!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

Prompts automatically:

• Search relevant documentation
• Read detailed guides
• Execute test code via tinker
• Provide structured, comprehensive answers following best practices

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

You can extend Synapse with your own tools, resources, and prompts using PHP attributes. Synapse automatically discovers classes in your src/ directory using MCP attributes.

Tools expose functions that AI assistants can call. Create them with #[McpTool]:

<?php
namespace App\Mcp;

use Mcp\Capability\Attribute\McpTool;

class MyTools
{
    #[McpTool(name: 'get_user', description: 'Fetch a user by ID')]
    public function getUser(int $id): array
    {
        $usersTable = $this->fetchTable('Users');
        $user = $usersTable->get($id);

        return [
            'id' => $user->id,
            'email' => $user->email,
            'name' => $user->name,
        ];
    }
}

Resources expose data sources. Create them with #[McpResourceTemplate].

Prompts guide LLMs through workflows. Create them with #[McpPrompt].

For detailed documentation on all MCP capabilities, attributes, and implementation patterns, see the MCP PHP SDK 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

[!NOTE] In most cases, you do not need to run the MCP server manually. The server is typically started automatically by your IDE or MCP-enabled client (such as Claude Desktop, VSCode, Zed, etc.) when you configure it to use your CakePHP app. The client will launch the server using the appropriate command (e.g., bin/cake synapse server) and handle the connection for you.

If you want to run the MCP server manually for testing or debugging purposes, you can use the following CLI commands:

# Start with default settings (stdio transport)
bin/cake synapse server

# Start with verbose output
bin/cake synapse server --verbose

# Disable caching
bin/cake synapse server --no-cache

# Launch MCP Inspector for testing (requires Node.js/npx)
bin/cake synapse server --inspect

# View help
bin/cake synapse server --help

Command Options

Testing with MCP Inspector

The --inspect flag launches the MCP Inspector, a development tool that provides a web-based UI for testing your MCP server:

bin/cake synapse server --inspect

This will:

1. Start the MCP Inspector (downloads automatically via npx if not installed)
2. Launch the server in inspector mode
3. Open a web browser with an interactive UI
4. Allow you to test tools, resources, and prompts interactively

Requirements:

• Node.js and npx must be installed
• A web browser

The inspector is invaluable during development for:

• Testing tool functionality
• Inspecting resource data
• Debugging server behavior
• Verifying tool schemas and documentation

Transport Options

Currently, Synapse supports:

• stdio - Standard input/output (default, recommended for most MCP clients)

Future versions may include HTTP/SSE transport.

Discovery Caching

Discovery caching improves server startup performance by caching the discovered MCP elements (tools, resources, prompts).

Configuration

Synapse uses CakePHP's built-in PSR-16 cache system. Configure caching in config/synapse.php

Command Options

# Disable caching for this run
bin/cake synapse server --no-cache
bin/cake synapse server -n

# Clear cache before starting
bin/cake synapse server --clear-cache
bin/cake synapse server -c

# Combine options
bin/cake synapse server --clear-cache --verbose

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 .

Credits

• Built with CakePHP
• Implements Model Context Protocol
• Uses the MCP PHP SDK

[!NOTE] The MCP PHP SDK is in active development and APIs may change.