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 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
fc1c2ef573
commit
80ab88d330
1 changed files with 106 additions and 45 deletions
151
CLAUDE.md
151
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)
|
||||
Loading…
Add table
Reference in a new issue