Feature/sql query tool

[jack-arturo]

Overview

This PR adds a new execute_sql_query tool that enables read-only SQL queries against the WordPress database through a configurable custom REST API endpoint.

Key Features

🔐 Security-First Design

• Read-only queries only: Supports SELECT, WITH...SELECT, and EXPLAIN queries
• Multi-layer validation: Both client-side and server-side validation
• Pattern blocking: Rejects queries containing dangerous SQL keywords (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, GRANT, REVOKE)
• Multi-statement prevention: Blocks SQL injection attempts via semicolon detection
• WordPress permissions: Requires manage_options capability
• Result size limiting: Truncates large results (>50K characters) to prevent memory issues

⚙️ Configurable Endpoint

• Environment variable: WORDPRESS_SQL_ENDPOINT allows custom endpoint configuration
• Sensible default: Uses /mcp/v1/query (vendor-neutral namespace)
• No hard-coded dependencies: Users can choose any namespace they prefer

🛠️ Implementation

• New Tool: execute_sql_query in src/tools/sql-query.ts
• Type Safety: Full TypeScript support with Zod schema validation
• Error Handling: Provides helpful setup instructions when endpoint is not found
• Logging: All queries and results logged to logs/wordpress-api.log

📚 Comprehensive Documentation

• README.md: Complete setup instructions with PHP code example
• CLAUDE.md: Updated tool listing and configuration details
• Security warnings: Clear guidance on permissions, logging, and PII handling
• Configuration examples: Shows both default and custom endpoint usage

Use Cases

This tool enables:

• Advanced data analysis and reporting
• Custom database queries not covered by existing REST API tools
• Debugging and troubleshooting
• Data exploration and discovery
• Complex JOIN queries across WordPress tables

Setup Required

Users must add a custom REST API endpoint to their WordPress site. The PR includes a complete PHP code example that can be added via a custom plugin or theme's functions.php.

Example Configuration

# Optional: Customize SQL endpoint (default: /mcp/v1/query)
WORDPRESS_SQL_ENDPOINT=/mcp/v1/query

Example Query

SELECT post_title, post_date, post_status 
FROM wp_posts 
WHERE post_type = 'post' 
AND post_status = 'publish' 
ORDER BY post_date DESC 
LIMIT 10

CodeRabbit Review Improvements

Incorporated all actionable feedback from CodeRabbit's automated review:

• ✅ Broader read-only query support (WITH, EXPLAIN)
• ✅ Multi-statement blocking via semicolon detection
• ✅ Explicit JSON Content-Type header
• ✅ Large result truncation (50K limit)
• ✅ Concise error messages with README references
• ✅ Fixed markdown linting issues (code block language, list indentation)
• ✅ Accurate tool count documentation (~39 tools total)
• ✅ Security warnings about logging and PII
• ✅ Configurable endpoint namespace (removed hard-coded vendor namespace)

Testing

• ✅ TypeScript compilation passes
• ✅ Successfully validates SELECT queries
• ✅ Correctly rejects dangerous SQL statements
• ✅ Blocks multi-statement SQL injection attempts
• ✅ Provides helpful error messages with configuration details
• ✅ No breaking changes to existing functionality
• ✅ Large result sets properly truncated

Security Considerations

This tool implements defense-in-depth:

1. Client-side validation: Query validation before sending to WordPress
2. Server-side validation: WordPress endpoint validates query structure
3. Permission checking: Requires WordPress admin permissions
4. Pattern matching: Detects and blocks dangerous keywords
5. Single-statement enforcement: Prevents SQL injection via multiple statements
6. Read-only operations: Only SELECT-based queries allowed
7. Explicit setup: Users must intentionally enable the endpoint

Files Changed

• src/tools/sql-query.ts (new): SQL query tool implementation
• src/tools/index.ts: Added SQL query tool to exports
• README.md: Setup instructions, security notes, and usage documentation
• CLAUDE.md: Updated tool listing and configuration
• .gitignore: Added .claude/ directory

Breaking Changes

None. This is a purely additive feature that requires explicit opt-in setup.