core/php-mcp
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
php-mcp/TODO.md
Snider e536e4586f feat(mcp): add query security features (P1-007, P1-008, P1-009) 
- P1-007: Tier-based query result size limits with truncation warnings
- P1-008: Per-tier query timeout enforcement (MySQL/PostgreSQL/SQLite)
- P1-009: Comprehensive audit logging for all query attempts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 13:15:39 +00:00

12 KiB
Raw Blame History

Core-MCP TODO

Testing & Quality Assurance

High Priority

  • Test Coverage: SQL Query Validator - Test injection prevention

    • Test all forbidden SQL keywords (DROP, INSERT, UPDATE, DELETE, etc.)
    • Test SQL injection attempts (UNION, boolean blinds, etc.)
    • Test parameterized query validation
    • Test subquery restrictions
    • Test multi-statement detection
    • Estimated effort: 4-5 hours

  • Test Coverage: Workspace Context - Test isolation and validation

    • Test WorkspaceContext resolution from headers
    • Test automatic workspace scoping in queries
    • Test MissingWorkspaceContextException
    • Test workspace boundary enforcement
    • Test cross-workspace query prevention
    • Estimated effort: 3-4 hours

  • Test Coverage: Tool Analytics - Test metrics tracking

    • Test ToolAnalyticsService recording
    • Test ToolStats DTO calculations
    • Test performance percentiles (P95, P99)
    • Test error rate calculations
    • Test daily trend aggregation
    • Estimated effort: 3-4 hours

  • Test Coverage: Quota System - Test limits and enforcement

    • Test McpQuotaService tier limits
    • Test quota exceeded detection
    • Test quota reset timing
    • Test workspace-scoped quotas
    • Test custom quota overrides
    • Estimated effort: 3-4 hours

Medium Priority

  • Test Coverage: Tool Dependencies - Test dependency validation

    • Test ToolDependencyService resolution
    • Test MissingDependencyException
    • Test circular dependency detection
    • Test version compatibility checking
    • Estimated effort: 2-3 hours

  • Test Coverage: Query Database Tool - Test complete workflow

    • Test SELECT query execution
    • Test EXPLAIN plan analysis
    • Test connection validation
    • Test result formatting
    • Test error handling
    • Estimated effort: 3-4 hours

Low Priority

  • Test Coverage: Tool Registry - Test tool registration
    • Test AgentToolRegistry with multiple tools
    • Test tool discovery
    • Test tool metadata
    • Estimated effort: 2-3 hours

Security (Critical)

High Priority - Security Fixes Needed

  • COMPLETED: Database Connection Fallback - Throw exception instead of fallback

    • Fixed to throw ForbiddenConnectionException
    • No silent fallback to default connection
    • Prevents accidental production data exposure
    • Completed: January 2026

  • COMPLETED: SQL Validator Regex Strengthening - Stricter WHERE clause validation

    • Replaced permissive .+ with restrictive character classes
    • Added explicit structure validation
    • Better detection of injection attempts
    • Completed: January 2026

Medium Priority - Additional Security

  • COMPLETED: Query Result Size Limits - Prevent data exfiltration

    • Add max_rows configuration per tier (free: 100, starter: 500, professional: 1000, enterprise: 5000, unlimited: 10000)
    • Enforce result set limits via QueryExecutionService
    • Return truncation warnings in response metadata
    • Tests in QueryExecutionServiceTest.php
    • Completed: 29 January 2026
    • Files: src/Mcp/Services/QueryExecutionService.php, src/Mcp/Exceptions/ResultSizeLimitException.php

  • COMPLETED: Query Timeout Enforcement - Prevent resource exhaustion

    • Add per-query timeout configuration per tier (free: 5s, starter: 10s, professional: 30s, enterprise: 60s, unlimited: 120s)
    • Database-specific timeout application (MySQL/MariaDB, PostgreSQL, SQLite)
    • Throw QueryTimeoutException on timeout
    • Log timeout attempts via QueryAuditService
    • Completed: 29 January 2026
    • Files: src/Mcp/Services/QueryExecutionService.php, src/Mcp/Exceptions/QueryTimeoutException.php

  • COMPLETED: Audit Logging for Queries - Complete query audit trail

    • Log all query attempts (success, blocked, timeout, error, truncated)
    • Include user, workspace, query, bindings count, duration, row count
    • Sanitise queries and error messages for security
    • Security channel logging for blocked queries
    • Session and tier context tracking
    • Completed: 29 January 2026
    • Files: src/Mcp/Services/QueryAuditService.php, src/Mcp/Tests/Unit/QueryAuditServiceTest.php

Features & Enhancements

High Priority

  • COMPLETED: EXPLAIN Plan Analysis - Query optimization insights

    • Added explain parameter to QueryDatabase tool
    • Returns human-readable performance analysis
    • Shows index usage and optimization opportunities
    • Completed: January 2026

  • Feature: Query Templates - Reusable parameterized queries

    • Create query template system
    • Support named parameters
    • Add template validation
    • Store templates per workspace
    • Test with complex queries
    • Estimated effort: 5-6 hours
    • Files: src/Mod/Mcp/Templates/

  • Feature: Schema Exploration Tools - Database metadata access

    • Add ListTables tool
    • Add DescribeTable tool
    • Add ListIndexes tool
    • Respect information_schema restrictions
    • Test with multiple database types
    • Estimated effort: 4-5 hours
    • Files: src/Mod/Mcp/Tools/Schema/

Medium Priority

  • Enhancement: Query Result Caching - Cache frequent queries

    • Implement result caching with TTL
    • Add cache key generation
    • Support cache invalidation
    • Test cache hit rates
    • Estimated effort: 3-4 hours

  • Enhancement: Query History - Track agent queries

    • Store query history per workspace
    • Add query rerun capability
    • Create history browser UI
    • Add favorite queries
    • Estimated effort: 4-5 hours
    • Files: src/Mod/Mcp/History/

  • Enhancement: Advanced Analytics - Deeper insights

    • Add query complexity scoring
    • Track table access patterns
    • Identify slow query patterns
    • Create optimization recommendations
    • Estimated effort: 5-6 hours
    • Files: src/Mod/Mcp/Analytics/

Low Priority

  • Enhancement: Multi-Database Support - Query multiple databases

    • Support cross-database queries
    • Add database selection parameter
    • Test with MySQL, PostgreSQL, SQLite
    • Estimated effort: 4-5 hours

  • Enhancement: Query Builder UI - Visual query construction

    • Create Livewire query builder component
    • Add table/column selection
    • Support WHERE clause builder
    • Generate safe SQL
    • Estimated effort: 8-10 hours
    • Files: src/Mod/Mcp/QueryBuilder/

Tool Development

High Priority

  • Tool: Create/Update Records - Controlled data modification

    • Create InsertRecord tool with strict validation
    • Create UpdateRecord tool with WHERE requirements
    • Implement record-level permissions
    • Require explicit confirmation for modifications
    • Test with workspace scoping
    • Estimated effort: 6-8 hours
    • Files: src/Mod/Mcp/Tools/Modify/
    • Note: Requires careful security review

  • Tool: Export Data - Export query results

    • Add ExportResults tool
    • Support CSV, JSON, Excel formats
    • Add row limits per tier
    • Implement streaming for large exports
    • Estimated effort: 4-5 hours
    • Files: src/Mod/Mcp/Tools/Export/

Medium Priority

  • Tool: Analyze Performance - Database health insights

    • Add TableStats tool (row count, size, etc.)
    • Add SlowQueries tool
    • Add IndexUsage tool
    • Create performance dashboard
    • Estimated effort: 5-6 hours
    • Files: src/Mod/Mcp/Tools/Performance/

  • Tool: Data Validation - Validate data quality

    • Add ValidateData tool
    • Check for NULL values, duplicates
    • Validate foreign key integrity
    • Generate data quality report
    • Estimated effort: 4-5 hours
    • Files: src/Mod/Mcp/Tools/Validation/

Documentation

  • Guide: Creating MCP Tools - Comprehensive tutorial

    • Document tool interface
    • Show parameter validation
    • Explain workspace context
    • Add dependency examples
    • Include security best practices
    • Completed: January 2026
    • File: docs/packages/mcp/creating-mcp-tools.md

  • Guide: SQL Security - Safe query patterns

    • Document allowed SQL patterns
    • Show parameterized query examples
    • Explain validation rules
    • List forbidden operations
    • Completed: January 2026
    • File: docs/packages/mcp/sql-security.md

  • API Reference: All MCP Tools - Complete tool catalog

    • Document each tool's parameters
    • Add usage examples
    • Show response formats
    • Include error cases
    • Completed: January 2026
    • File: docs/packages/mcp/tools-reference.md

Code Quality

  • Refactor: Extract SQL Parser - Better query validation

    • Create proper SQL parser
    • Replace regex with AST parsing
    • Support dialect-specific syntax
    • Add comprehensive tests
    • Estimated effort: 8-10 hours

  • Refactor: Standardize Tool Responses - Consistent API

    • Create ToolResult DTO
    • Standardize error responses
    • Add response metadata
    • Update all tools
    • Estimated effort: 3-4 hours

  • PHPStan: Fix Level 5 Errors - Improve type safety

    • Fix property type declarations
    • Add missing return types
    • Fix array shape types
    • Estimated effort: 2-3 hours

Performance

  • Optimization: Query Result Streaming - Handle large results

    • Implement cursor-based result streaming
    • Add chunked response delivery
    • Test with millions of rows
    • Estimated effort: 3-4 hours

  • Optimization: Connection Pooling - Reuse database connections

    • Implement connection pool
    • Add connection health checks
    • Test connection lifecycle
    • Estimated effort: 3-4 hours

Infrastructure

  • Monitoring: Alert on Suspicious Queries - Security monitoring

    • Detect unusual query patterns
    • Alert on potential injection attempts
    • Track query anomalies
    • Create security dashboard
    • Estimated effort: 4-5 hours

  • CI/CD: Add Security Regression Tests - Prevent vulnerabilities

    • Test SQL injection prevention
    • Test workspace isolation
    • Test quota enforcement
    • Fail CI on security issues
    • Estimated effort: 3-4 hours

Completed (January 2026)

  • Security: Database Connection Validation - Throws exception for invalid connections
  • Security: SQL Validator Strengthening - Stricter WHERE clause patterns
  • Security: Query Result Size Limits - Tier-based max_rows with truncation warnings (P1-007)
  • Security: Query Timeout Enforcement - Per-query timeout with database-specific implementation (P1-008)
  • Security: Audit Logging for Queries - Comprehensive logging of all query attempts (P1-009)
  • Feature: EXPLAIN Plan Analysis - Query optimization insights
  • Tool Analytics System - Complete usage tracking and metrics
  • Quota System - Tier-based limits with enforcement
  • Workspace Context - Automatic query scoping and validation
  • Documentation: Creating MCP Tools Guide - Complete tutorial with workspace context, dependencies, security
  • Documentation: SQL Security Guide - Allowed patterns, forbidden operations, injection prevention
  • Documentation: MCP Tools API Reference - All tools with parameters, examples, error handling

See changelog/2026/jan/ for completed features and security fixes.