# Cakephp Synapse

> A CakePHP-focussed MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-josbeir-cakephp-synapse`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [josbeir](https://agentstack.voostack.com/s/josbeir)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [josbeir](https://github.com/josbeir)
- **Source:** https://github.com/josbeir/cakephp-synapse

## Install

```sh
agentstack add mcp-josbeir-cakephp-synapse
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://github.com/josbeir/cakephp-synapse)
[](https://github.com/josbeir/cakephp-synapse/actions)
[](https://codecov.io/github/josbeir/cakephp-synapse)
[](https://opensource.org/licenses/MIT)
[](https://www.php.net/releases/8.2/en.php)
[](https://cakephp.org/)
[](https://packagist.org/packages/josbeir/cakephp-synapse)

# Synapse: a CakePHP MCP-Server plugin

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

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
  - [Requirements](#requirements)
  - [Installing the Plugin](#installing-the-plugin)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Built-in Tools](#built-in-tools)
- [Built-in Prompts](#built-in-prompts)
  - [Creating Custom Tools, Resources, and Prompts](#creating-custom-tools-resources-and-prompts)
- [CLI usage](#cli-usage)
- [Running the Server](#running-the-server)
  - [Command Options](#command-options)
  - [Testing with MCP Inspector](#testing-with-mcp-inspector)
  - [Transport Options](#transport-options)
- [Discovery Caching](#discovery-caching)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
- [Credits](#credits)

## Overview

Synapse is a CakePHP plugin that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), 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](https://github.com/modelcontextprotocol/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, 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.2 or higher

### Installing the Plugin

Install via Composer as a development dependency:

```bash
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.

```bash
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:
> ```bash
> 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`

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

Or run when using `DDEV` instance

```json
{
  "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:

| Category | Name | Description |
|----------|------|-------------|
| System | `system_info` | Get CakePHP version, PHP version, debug mode, etc. |
| System | `config_read` | Read configuration values |
| System | `debug_status` | Check if debug mode is enabled |
| System | `list_env_vars` | List all available environment variables |
| 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/{documentId}` | Retrieve full document content by document ID (format: `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](https://github.com/cakephp/docs-md). 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 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`:

```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
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](https://github.com/modelcontextprotocol/php-sdk).

## CLI usage

Use the CLI to manage and search the index:

```bash
# 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:

```bash
# 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

| Option | Short | Description |
|--------|-------|-------------|
| `--transport` | `-t` | Transport type (currently only `stdio` is supported) |
| `--no-cache` | `-n` | Disable discovery caching for this run |
| `--clear-cache` | `-c` | Clear discovery cache before starting |
| `--inspect` | `-i` | Launch MCP Inspector to test the server interactively (requires Node.js/npx) |
| `--verbose` | `-v` | Enable verbose output (pipes logging to stderr) |
| `--quiet` | `-q` | Suppress all output except errors |

### Testing with MCP Inspector

The `--inspect` flag launches the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), a development tool that provides a web-based UI for testing your MCP server:

```bash
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

```bash
# 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:

```bash
# Run all tests
composer test

# Run with coverage
composer test-coverage

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [josbeir](https://github.com/josbeir)
- **Source:** [josbeir/cakephp-synapse](https://github.com/josbeir/cakephp-synapse)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-josbeir-cakephp-synapse
- Seller: https://agentstack.voostack.com/s/josbeir
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.