Skip to content

Commit 3f18ff0

Browse files
josbeirjosbeir
committed
Improve readme
1 parent 1a86e40 commit 3f18ff0

1 file changed

Lines changed: 38 additions & 118 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,8 @@ Expose your CakePHP application functionality via the Model Context Protocol (MC
2121
- [Configuration](#configuration)
2222
- [Creating MCP Tools](#creating-mcp-tools)
2323
- [Built-in Tools](#built-in-tools)
24-
- [System Tools](#system-tools)
25-
- [Tinker Tool](#tinker-tool)
26-
- [Database Tools](#database-tools)
27-
- [Route Tools](#route-tools)
28-
- [Documentation Search](#documentation-search)
2924
- [Built-in Prompts](#built-in-prompts)
30-
- [Available Prompts](#available-prompts)
31-
- [Using Prompts](#using-prompts)
32-
- [Configuring CakePHP Version](#configuring-cakephp-version)
33-
- [Quality Assurance Prompt](#quality-assurance-prompt)
25+
- [CLI usage](#cli-usage)
3426
- [Running the Server](#running-the-server)
3527
- [Command Options](#command-options)
3628
- [Testing with MCP Inspector](#testing-with-mcp-inspector)
@@ -194,75 +186,36 @@ public function searchArticles(
194186

195187
## Built-in Tools
196188

197-
Synapse includes several built-in tools for common operations:
198-
199-
### System Tools
200-
201-
Access system information and configuration:
202-
203-
| Tool | Description |
204-
|------|-------------|
205-
| `system_info` | Get CakePHP version, PHP version, debug mode, etc. |
206-
| `config_read` | Read configuration values |
207-
| `debug_status` | Check if debug mode is enabled |
208-
| `list_env_vars` | List all available environment variables |
209-
210-
### Tinker Tool
211-
212-
Execute PHP code in the CakePHP application context:
213-
214-
| Tool | Description |
215-
|------|-------------|
216-
| `tinker` | Execute arbitrary PHP code with full application context |
189+
Synapse includes several built-in tools and resources for common operations:
190+
191+
| Category | Name | Description |
192+
|----------|------|-------------|
193+
| System | `system_info` | Get CakePHP version, PHP version, debug mode, etc. |
194+
| System | `config_read` | Read configuration values |
195+
| System | `debug_status` | Check if debug mode is enabled |
196+
| System | `list_env_vars` | List all available environment variables |
197+
| Code Execution | `tinker` | Execute arbitrary PHP code with full application context |
198+
| Database | `database_connections` | List all configured database connections |
199+
| Database | `database_schema` | Get detailed schema information for tables (view all tables, inspect columns, constraints, indexes, understand foreign key relationships) |
200+
| Routes | `list_routes` | List all routes with filtering and sorting |
201+
| Routes | `get_route` | Get detailed information about a specific route |
202+
| Routes | `match_url` | Find which route matches a given URL |
203+
| Routes | `detect_route_collisions` | Find potential route conflicts |
204+
| Documentation | `search_docs` | Search documentation with relevance ranking, fuzzy matching, and filtering |
205+
| Documentation | `get_doc` | Retrieve full document content by document ID (format: `source::path`) |
206+
| Documentation | `docs_stats` | View index statistics and available sources |
207+
| Documentation | `docs://search/{query}` | Search CakePHP documentation and return formatted results |
208+
| Documentation | `docs://content/{documentId}` | Retrieve full document content by document ID (format: `source::path`) |
217209

218210
> [!WARNING]
219-
> This tool executes arbitrary code in your application. Use responsibly and avoid modifying data without explicit approval.
220-
221-
### Database Tools
222-
223-
Inspect and query your database:
224-
225-
| Tool | Description |
226-
|------|-------------|
227-
| `database_connections` | List all configured database connections |
228-
| `database_schema` | Get detailed schema information for tables (view all tables, inspect columns, constraints, indexes, understand foreign key relationships) |
211+
> The `tinker` tool executes arbitrary code in your application. Use responsibly and avoid modifying data without explicit approval.
229212
230213
> [!TIP]
231214
> 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.
232215
233-
### Route Tools
234-
235-
Inspect and analyze your application routes:
236-
237-
| Tool | Description |
238-
|------|-------------|
239-
| `list_routes` | List all routes with filtering and sorting |
240-
| `get_route` | Get detailed information about a specific route |
241-
| `match_url` | Find which route matches a given URL |
242-
| `detect_route_collisions` | Find potential route conflicts |
243-
244-
### Documentation Search
245-
246-
Search CakePHP documentation with full-text search powered by SQLite FTS5:
247-
248-
| Tool | Description |
249-
|------|-------------|
250-
| `search_docs` | Search documentation with relevance ranking, fuzzy matching, and filtering |
251-
| `get_doc` | Retrieve full document content by document ID (format: `source::path`) |
252-
| `docs_stats` | View index statistics and available sources |
253-
254216
> [!NOTE]
255217
> 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.
256218
257-
### Resources
258-
259-
Access documentation through resource templates:
260-
261-
| Resource | Description |
262-
|----------|-------------|
263-
| `docs://search/{query}` | Search CakePHP documentation and return formatted results |
264-
| `docs://content/{documentId}` | Retrieve full document content by document ID (format: `source::path`) |
265-
266219
## Built-in Prompts
267220

268221
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.
@@ -283,18 +236,6 @@ Synapse includes pre-defined prompt workflows that guide LLMs through common Cak
283236
| `tinker-workshop` | Interactive PHP exploration and testing guide | `goal` (required: explore/test/debug), `subject` (optional) |
284237
| `quality-assurance` | Coding guidelines and QA best practices for CakePHP | `context` (optional: guidelines/integration/troubleshooting/all), `tools` (optional: all or comma-separated list) |
285238

286-
### Using Prompts
287-
288-
Prompts are workflow templates that guide the LLM through multi-step processes. When using an MCP client like Claude:
289-
290-
```
291-
"Use the documentation-expert prompt to learn about CakePHP Authentication"
292-
293-
"Use debug-helper with error='Call to undefined method' and context='controller'"
294-
295-
"Use feature-builder to implement a REST API endpoint"
296-
```
297-
298239
**Prompts automatically:**
299240
- Search relevant documentation
300241
- Read detailed guides
@@ -307,53 +248,32 @@ Prompts are workflow templates that guide the LLM through multi-step processes.
307248
- **Consistency** - Standardized approaches to common problems
308249
- **Discovery** - See available workflows without remembering tool combinations
309250

310-
### Configuring CakePHP Version
251+
### Configuring prompts
311252

312-
Prompts reference a specific CakePHP version in their guidance. Configure this in `config/synapse.php`:
253+
Prompts can reference a specific CakePHP version and use various quality tools. Configure both in `config/synapse.php`:
313254

314-
```php
315255
return [
316256
'Synapse' => [
317257
'prompts' => [
318-
// Target CakePHP version for prompt responses
319-
// Examples: '5.x', '5.2', '4.5', '4.x'
258+
// Target CakePHP version for prompt responses (e.g. '5.x', '5.2', '4.5', '4.x')
320259
'cakephp_version' => env('MCP_CAKEPHP_VERSION', '5.x'),
321-
],
322-
],
323-
];
324-
```
325260

326-
Or set via environment variable:
327-
328-
```bash
329-
export MCP_CAKEPHP_VERSION=5.2
330-
bin/cake synapse server
331-
```
332-
333-
This allows targeting specific version documentation and conventions when working with different CakePHP versions.
334-
335-
### Quality Assurance Prompt
336-
337-
The `quality-assurance` prompt provides comprehensive coding guidelines and QA best practices for CakePHP development. It supports multiple quality tools including PHPCS, PHPStan, PHPUnit, Rector, and Psalm.
338-
339-
Configure which tools are enabled and their settings in `config/synapse.php`:
340-
341-
```php
342-
'Synapse' => [
343-
'prompts' => [
344-
'quality_tools' => [
345-
'phpcs' => ['enabled' => true, 'standard' => 'cakephp'],
346-
'phpstan' => ['enabled' => true, 'level' => 8],
347-
'phpunit' => ['enabled' => true, 'coverage' => true],
348-
'rector' => ['enabled' => false, 'set' => 'cakephp'],
349-
'psalm' => ['enabled' => false, 'level' => 3],
261+
// Target PHP version for prompt responses (e.g. '8.2', '8.3', '8.x')
262+
'php_version' => env('MCP_PHP_VERSION', PHP_VERSION),
263+
264+
// Quality tools configuration
265+
'quality_tools' => [
266+
'phpcs' => ['enabled' => true, 'standard' => 'cakephp'],
267+
'phpstan' => ['enabled' => true, 'level' => 8],
268+
'phpunit' => ['enabled' => true, 'coverage' => true],
269+
'rector' => ['enabled' => false, 'set' => 'cakephp'],
270+
'psalm' => ['enabled' => false, 'level' => 3],
271+
],
350272
],
351273
],
352-
],
353-
```
274+
];
354275

355-
**Context options:** guidelines, integration, troubleshooting, all
356-
**Tools options:** all, or comma-separated list (phpcs, phpstan, phpunit, rector, psalm)
276+
## CLI usage
357277

358278
Use the CLI to manage and search the index:
359279

0 commit comments

Comments
 (0)