php-mcp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package Overview

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

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

Architecture

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

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));
    }
}

Boot Class (Event-Driven Registration)

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

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

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

EUPL-1.2 (copyleft applies to Core\ namespace)