docs: architecture overview

2026-05-31 12:44:24 +00:00
parent 0411771a7d
commit 9f3fe38a1d
1 changed files with 87 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 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 |