docs: add architecture doc

2026-05-31 12:40:56 +00:00
parent 262bcb0daf
commit 289f611f11
1 changed files with 177 additions and 0 deletions
@@ -0,0 +1,177 @@
+# Architecture
+
+## Directory Structure
+
+```
+advanced-mcp-plugin/
+├── advanced-mcp-plugin.php      ← Entry point, autoloader, boot
+├── docs/                        ← This documentation
+└── includes/
+    ├── Core/
+    │   ├── Auth.php             ← Bearer token auth, HTTPS, rate limit, scope
+    │   ├── AdminMenu.php        ← WP Admin UI (API Keys, Settings, Audit Log tabs)
+    │   ├── TokenManager.php     ← HMAC-SHA256 JWT, 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
+    │   └── WooTools.php
+    └── Elementor/
+        ├── Abilities/
+        │   └── ElementorTools.php  ← All 30 Elementor build tools
+        └── Data/
+            └── ElementorData.php   ← Read/write Elementor JSON — critical CLI fix
+```
+
+---
+
+## Request Flow
+
+```
+MCP Client (Claude)
+    │
+    ▼
+POST /wp-json/asktam-mcp/v1/mcp
+    │
+    ▼
+Server.php::handle()
+    ├── Auth::validate()          ← Bearer JWT + scope + rate limit
+    │       ├── extract token from Authorization header
+    │       ├── TokenManager::verify() — HMAC-SHA256, exp, iss, jti
+    │       ├── scope check against requested tool's required scope
+    │       └── rate limit via transient (60 req/min default)
+    │
+    ├── method = "initialize"     → return server info
+    ├── method = "tools/list"     → Registry::getTools()
+    └── method = "tools/call"
+            │
+            ▼
+        Registry::getHandler($tool_name)
+            │
+            ▼
+        Tool class method($args)
+            │
+            ▼
+        JSON response
+```
+
+---
+
+## Authentication Detail
+
+Every request requires:
+```
+Authorization: Bearer <jwt_token>
+```
+
+**JWT payload:**
+```json
+{
+  "key_id": 3,
+  "iss": "https://mainwp.asktam.net",
+  "exp": 1234567890,
+  "jti": "unique-token-id"
+}
+```
+
+**Signing:** HMAC-SHA256 with 64-char hex secret stored in `wp_options.asktam_mcp_jwt_secret`.
+
+**Verification (TokenManager.php):**
+1. Split JWT into header.payload.signature
+2. Recompute HMAC and compare with `hash_equals()` (timing-safe)
+3. Check `exp` > `time()`
+4. Check `iss` matches `get_site_url()`
+5. Check `jti` not in revocation list
+6. Load API key from DB by `key_id`, confirm `is_active = 1`
+
+**API Keys** stored in `mwp_asktam_mcp_keys`:
+```sql
+id, name, key_hash (bcrypt), scopes (comma-separated), is_active, created_at, last_used
+```
+
+---
+
+## Scopes
+
+| Scope | Access |
+|---|---|
+| `read` | GET / list operations |
+| `write` | Create, update, delete |
+| `admin` | Plugin management, raw SQL, CLI, options |
+| `elementor` | All Elementor builder tools |
+| `woo` | WooCommerce tools |
+
+Each tool in `ToolHandlers.php` declares a required scope. Auth.php enforces it before dispatch.
+
+---
+
+## DB Tables Created on Activation
+
+```sql
+-- API keys
+CREATE TABLE mwp_asktam_mcp_keys (
+    id         BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    name       VARCHAR(100) NOT NULL,
+    key_hash   VARCHAR(255) NOT NULL,
+    scopes     VARCHAR(500) DEFAULT 'read',
+    is_active  TINYINT(1) DEFAULT 1,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    last_used  DATETIME DEFAULT NULL
+);
+
+-- Audit log
+CREATE TABLE mwp_asktam_mcp_log (
+    id         BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    key_id     BIGINT UNSIGNED DEFAULT NULL,
+    tool_name  VARCHAR(100) NOT NULL,
+    ip_address VARCHAR(45) DEFAULT NULL,
+    status     VARCHAR(20) DEFAULT 'success',
+    duration   FLOAT DEFAULT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## WP Admin Panel
+
+**Location:** WP Admin → AskTam MCP (top-level menu)
+
+| Tab | Purpose |
+|---|---|
+| API Keys | Generate JWT tokens, set scopes, revoke keys |
+| Settings | HTTPS enforcement, rate limit, request logging, raw SQL toggle |
+| Audit Log | Last 1000 tool calls: key_id, tool, IP, timestamp |
+
+---
+
+## Namespace
+
+`AskTamMCP\` — PSR-4 autoloader registered in `advanced-mcp-plugin.php`.
+
+All classes map to `includes/` directory:
+- `AskTamMCP\Core\Auth` → `includes/Core/Auth.php`
+- `AskTamMCP\Tools\PostTools` → `includes/Tools/PostTools.php`
+- `AskTamMCP\Elementor\Abilities\ElementorTools` → `includes/Elementor/Abilities/ElementorTools.php`