From 80ab88d3303666d31b22d665ea71bb0a98ad3db5 Mon Sep 17 00:00:00 2001 From: Snider Date: Wed, 28 Jan 2026 14:13:09 +0000 Subject: [PATCH] docs: rewrite CLAUDE.md for core-mcp package specifics Replace generic Core PHP Framework documentation with package-specific guidance covering MCP tool architecture, security layers (SQL validation, workspace context isolation), key services, and testing patterns. Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 151 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 106 insertions(+), 45 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 138e17b..4265e1b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,66 +1,127 @@ -# Core PHP Framework Project +# CLAUDE.md -## Architecture +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -Modular monolith using Core PHP Framework. Modules live in `app/Mod/{Name}/Boot.php`. +## Package Overview -**Event-driven registration:** -```php -class Boot -{ - public static array $listens = [ - WebRoutesRegistering::class => 'onWebRoutes', - ApiRoutesRegistering::class => 'onApiRoutes', - AdminPanelBooting::class => 'onAdminPanel', - ]; -} -``` +This is `host-uk/core-mcp`, a standalone Laravel package providing Model Context Protocol (MCP) tools for AI-powered automation. It implements the JSON-RPC MCP standard for AI agent integrations with security-focused database access. + +**Namespaces:** +- `Core\Mcp\` - Main package code (tools, services, middleware) +- `Core\Website\Mcp\` - Web UI components (Livewire modals, controllers) ## Commands ```bash -composer run dev # Dev server (if configured) -php artisan serve # Laravel dev server -npm run dev # Vite -./vendor/bin/pint --dirty # Format changed files -php artisan test # All tests -php artisan make:mod Blog # Create module +./vendor/bin/pest # Run all tests +./vendor/bin/pest --filter=SqlQuery # Run specific tests +./vendor/bin/pint --dirty # Format changed files +php artisan mcp:agent-server # Run the MCP agent server (stdio) +php artisan mcp:prune-metrics # Prune old analytics data +php artisan mcp:verify-audit-log # Verify audit log integrity ``` -## Module Structure +## Architecture -``` -app/Mod/Blog/ -├── Boot.php # Event listeners -├── Models/ # Eloquent models -├── Routes/ -│ ├── web.php # Web routes -│ └── api.php # API routes -├── Views/ # Blade templates -├── Livewire/ # Livewire components -├── Migrations/ # Database migrations -└── Tests/ # Module tests +### MCP Tool System + +Tools extend `Laravel\Mcp\Server\Tool` and implement: +- `$description` property for tool purpose +- `schema(JsonSchema $schema): array` for input parameters +- `handle(Request $request): Response` for execution logic + +```php +class QueryDatabase extends Tool +{ + protected string $description = 'Execute a read-only SQL SELECT query'; + + public function schema(JsonSchema $schema): array + { + return [ + 'query' => $schema->string('SQL SELECT query'), + 'explain' => $schema->boolean('Run EXPLAIN instead')->default(false), + ]; + } + + public function handle(Request $request): Response + { + // Validate and execute + return Response::text(json_encode($results)); + } +} ``` -## Packages +### Boot Class (Event-Driven Registration) -| Package | Purpose | +`src/Mcp/Boot.php` registers via Core framework events: +- `AdminPanelBooting` - Admin routes, views, Livewire components +- `ConsoleBooting` - Artisan commands +- `McpToolsRegistering` - MCP tool handlers + +### Security Layers + +**SQL Query Validation** (`SqlQueryValidator`): +1. Blocked keywords (INSERT, UPDATE, DELETE, DROP, etc.) +2. Dangerous pattern detection (UNION injection, hex encoding, stacked queries) +3. Whitelist regex matching for allowed query structures +4. Comment stripping before validation + +**Workspace Context Security**: +- `RequiresWorkspaceContext` trait enforces tenant isolation +- Tools throw `MissingWorkspaceContextException` without valid context +- `ValidateWorkspaceContext` middleware injects context from auth + +### Key Services + +| Service | Purpose | |---------|---------| -| `host-uk/core` | Core framework, events, module discovery | -| `host-uk/core-admin` | Admin panel, Livewire modals | -| `host-uk/core-api` | REST API, scopes, rate limiting, webhooks | -| `host-uk/core-mcp` | Model Context Protocol for AI agents | +| `ToolRegistry` | Discovers tools from YAML config, manages schemas | +| `SqlQueryValidator` | Multi-layer SQL injection protection | +| `ToolAnalyticsService` | Usage tracking and metrics | +| `McpQuotaService` | Workspace-level rate limiting | +| `AuditLogService` | Tamper-evident logging | +| `ToolDependencyService` | Validates tool dependencies at runtime | + +### Tool Configuration + +Tools are defined in `resources/mcp/servers/*.yaml`: +```yaml +id: workspace-tools +name: Workspace Tools +tools: + - name: query_database + description: Execute read-only SQL query + inputSchema: + type: object + properties: + query: { type: string } +``` + +## Testing + +Tests use **Pest** and are located in: +- `tests/` - Integration tests (Laravel TestCase) +- `src/Mcp/Tests/` - Package unit tests + +```php +describe('SqlQueryValidator', function () { + it('blocks INSERT statements', function () { + $validator = new SqlQueryValidator(); + + expect(fn () => $validator->validate('INSERT INTO users VALUES (1)')) + ->toThrow(ForbiddenQueryException::class); + }); +}); +``` ## Conventions - UK English (colour, organisation, centre) -- PSR-12 coding style (Laravel Pint) -- Pest for testing -- Livewire + Flux Pro for UI +- `declare(strict_types=1);` in every PHP file +- PSR-12 via Laravel Pint +- Pest for testing (not PHPUnit syntax) +- All parameters and return types must have type hints ## License -- `Core\` namespace and vendor packages: EUPL-1.2 (copyleft) -- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft) - -See LICENSE for full details. +EUPL-1.2 (copyleft applies to `Core\` namespace) \ No newline at end of file