# Architecture

## Plugin Structure

```
advanced-mcp-plugin/
├── advanced-mcp-plugin.php       ← Entry point, autoloader, boot
├── docs/                         ← This documentation
└── includes/
    ├── Core/
    │   ├── Auth.php              ← Bearer token validation, HTTPS, rate limit, scope check
    │   ├── AdminMenu.php         ← WP Admin UI: API Keys / Settings / Audit Log tabs
    │   ├── TokenManager.php      ← HMAC-SHA256 JWT sign/verify, JTI revocation, secret rotation
    │   └── Installer.php         ← DB table creation on activation
    ├── MCP/
    │   ├── Server.php            ← MCP protocol: initialize / tools/list / tools/call
    │   └── Registry.php          ← Maps tool names → handlers + schemas
    ├── Tools/
    │   ├── PostTools.php
    │   ├── PageTools.php
    │   ├── MediaTools.php
    │   ├── UserTools.php
    │   ├── CommentTools.php
    │   ├── MenuTools.php
    │   ├── TaxonomyTools.php
    │   ├── OptionTools.php
    │   ├── SiteTools.php
    │   ├── PluginTools.php
    │   ├── ThemeTools.php
    │   ├── ThemeDiscoveryTools.php
    │   ├── SeoTools.php
    │   ├── WooTools.php
    │   ├── EmailTools.php
    │   ├── FileManagerTools.php
    │   ├── CliTools.php
    │   ├── RawSqlTools.php
    │   ├── TransientTools.php
    │   ├── WidgetTools.php
    │   ├── ToolHandlers.php      ← Master registry: all 123 tools with schemas + scopes
    │   └── UserTools.php
    └── Elementor/
        ├── Abilities/
        │   └── ElementorTools.php  ← All 30 Elementor build tools
        └── Data/
            └── ElementorData.php   ← Read/write Elementor JSON — CRITICAL CLI fix applied
```

## Request Flow

```
Claude → MCP Client
  → POST /wp-json/asktam-mcp/v1/mcp
    → Server.php (route method)
      → Auth::validate() (Bearer JWT, scope, rate limit, HTTPS)
        → Registry::getHandler($tool_name)
          → ToolXxx::methodName($args)
            → WordPress API / wpdb
              → JSON response
```

## Namespace

All classes use `AskTamMCP\` namespace, PSR-4 autoloaded:
- `AskTamMCP\Core\Auth`
- `AskTamMCP\Core\TokenManager`
- `AskTamMCP\MCP\Server`
- `AskTamMCP\MCP\Registry`
- `AskTamMCP\Tools\PostTools`
- `AskTamMCP\Elementor\Data\ElementorData`
- etc.

## Database Tables

| Table | Purpose |
|---|---|
| `mwp_asktam_mcp_keys` | API keys: id, name, key_hash (bcrypt), scopes, is_active, created_at, last_used |
| `mwp_asktam_mcp_log` | Audit log: key_id, tool, ip, status, duration_ms, created_at |

## MCP Protocol

JSON-RPC 2.0 over HTTP POST. Supported methods:

| Method | Description |
|---|---|
| `initialize` | Returns server info, version, capabilities |
| `tools/list` | Returns all tools with input schemas |
| `tools/call` | Executes a tool, returns result |