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
• Creating MCP Tools
• Built-in Tools
  • System Tools
  • Database Tools
  • Route Tools
  • Documentation Search
• Running the Server
• Discovery Caching
• Testing
• Contributing
• License

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 (coming soon)
• Prompts: Pre-configured templates for common tasks (coming soon)

Features

• 🚀 Easy Integration: Add MCP capabilities to your CakePHP app in minutes
• 🔍 Auto-Discovery: Automatically discovers MCP elements using PHP 8 attributes
• 🛠️ Built-in Tools: Pre-built tools for system info, database inspection, and route management
• 📚 Documentation Search: Full-text search powered by SQLite FTS5 with BM25 ranking (indexes CakePHP's official markdown documentation)
• 📦 Extensible: Create custom tools using simple PHP attributes

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.

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

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

Quick Start

1. Install the plugin (see above)

2. Start the MCP server:

bin/cake synapse server

3. Connect an MCP client (like Claude Desktop or another MCP-compatible tool) to stdio transport

4. Try it out - The AI assistant can now:

   • Query your database schema
   • Inspect routes
   • Read configuration
   • And more!

Configuration

Create a configuration file at config/synapse.php:

<?php
return [
    'Synapse' => [
        // Server information sent to MCP clients
        'serverInfo' => [
            'name' => 'My App MCP Server',
            'version' => '1.0.0',
        ],

        // MCP protocol version
        'protocolVersion' => '2024-11-05',

        // Discovery settings
        'discovery' => [
            'scanDirs' => ['src', 'plugins'],
            'excludeDirs' => ['tests', 'vendor', 'tmp'],
        ],
    ],
];

Environment Variables

You can also configure using environment variables:

MCP_SERVER_NAME="My App MCP Server"
MCP_SERVER_VERSION="1.0.0"
MCP_PROTOCOL_VERSION="2024-11-05"

Creating MCP Tools

Create custom tools by adding the #[McpTool] attribute to public methods:

<?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,
        ];
    }
    
    #[McpTool(name: 'list_users')]
    public function listUsers(int $limit = 10): array
    {
        $usersTable = $this->fetchTable('Users');
        $users = $usersTable->find()
            ->limit($limit)
            ->toArray();
            
        return [
            'total' => count($users),
            'users' => $users,
        ];
    }
}

The plugin will automatically discover these tools and make them available to MCP clients.

Tool Parameters

Tools support typed parameters with automatic validation:

#[McpTool(name: 'search_articles')]
public function searchArticles(
    string $query,
    int $limit = 20,
    bool $publishedOnly = true
): array {
    // Implementation
}

Built-in Tools

Synapse includes several built-in tools for common operations:

System Tools

Access system information and configuration:

• system_info - Get CakePHP version, PHP version, debug mode, etc.
• config_read - Read configuration values
• debug_status - Check if debug mode is enabled

Database Tools

Inspect and query your database:

• list_connections - List all configured database connections
• describe_schema - Get detailed schema information for tables
  • View all tables in a connection
  • Inspect columns, constraints, indexes
  • Understand foreign key relationships

Route Tools

Inspect and analyze your application routes:

• list_routes - List all routes with filtering and sorting
• get_route - Get detailed information about a specific route
• match_url - Find which route matches a given URL
• reverse_route - Generate URLs from route names or parameters
• detect_route_collisions - Find potential route conflicts

Documentation Search

Search CakePHP documentation with full-text search powered by SQLite FTS5:

• search_docs - Search documentation with relevance ranking, fuzzy matching, and filtering
• docs_stats - View index statistics and available sources
• docs://search/{query} - Resource for accessing formatted search results

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.

Use the CLI to manage and search the index:

# Index all sources
bin/cake index_docs

# Index specific source
bin/cake index_docs --source cakephp-5x

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

# Search documentation from CLI
bin/cake search_docs "authentication"

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

Running the Server

Start the MCP server using the CLI command:

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

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

# Enable logging to debug log engine
bin/cake synapse server --log debug

# Disable caching and enable logging
bin/cake synapse server --no-cache --log debug

# View help
bin/cake synapse server --help

Command Options

• --transport, -t - Transport type (currently only stdio is supported)
• --log, -l - Enable MCP server logging to specified log engine (e.g., debug, error)
• --no-cache, -n - Disable discovery caching for this run
• --clear-cache, -c - Clear discovery cache before starting
• --verbose, -v - Enable verbose output
• --quiet, -q - Suppress all output except errors

Transport Options

Currently, Synapse supports:

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

Future versions may include HTTP/SSE transport.

Connecting MCP Clients

To connect Claude Desktop or other MCP clients:

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

Example IDE/Tool configuration (VSCode/Claude/Zed/...)

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

Or run inside your DDEV instance

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

Logging

The MCP server supports PSR-3 logging via CakePHP's logging system. This logs server activity including discovery, protocol messages, and handler execution.

Enable Logging

Use the --log option to enable logging to any configured log engine:

# Log to 'debug' log engine
bin/cake synapse server --log debug

# Log to 'error' log engine
bin/cake synapse server --log error

# Log to custom engine
bin/cake synapse server --log mcp

Configure Log Engine

Configure your log engines in config/app.php:

'Log' => [
    'debug' => [
        'className' => 'File',
        'path' => LOGS,
        'file' => 'debug',
        'levels' => ['notice', 'info', 'debug'],
        'scopes' => false,
    ],
    'mcp' => [
        'className' => 'File',
        'path' => LOGS,
        'file' => 'mcp',
        'levels' => ['notice', 'info', 'debug', 'error', 'warning'],
    ],
],

What Gets Logged

When logging is enabled, the MCP server logs:

• Server startup and initialization
• Discovery process and found elements
• Protocol messages (requests/responses)
• Tool/resource handler execution
• Errors and warnings

This is useful for debugging and understanding how your MCP server interacts with clients.

Discovery Caching

Discovery caching dramatically improves server startup performance by caching the discovered MCP elements (tools, resources, prompts). This can reduce startup time by up to 99%!

Note

While caching improves performance, remember that this plugin is intended for development use. The caching feature is most useful when running the MCP server frequently during development sessions.

Configuration

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

return [
    'Synapse' => [
        'discovery' => [
            'scanDirs' => ['src', 'plugins/Synapse/src'],
            'excludeDirs' => ['tests', 'vendor', 'tmp', 'logs', 'webroot'],

            // Cache configuration (defaults to 'default')
            'cache' => 'default',  // or 'mcp', or any cache config name
        ],
    ],
];

Or use an environment variable:

# Use default cache engine
MCP_DISCOVERY_CACHE=default

# Use a custom cache engine
MCP_DISCOVERY_CACHE=mcp

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

Performance

• Without cache: ~100-500ms startup time (depending on codebase size)
• With cache: ~1-5ms startup time (99% improvement!)
• Recommendation: Enable caching for faster startup times during development

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

• 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.