joseconti/klytos-desktop-vs-mcp

Klytos: Desktop (Admin) vs MCP (AI) Interfaces

Core Philosophy

MCP is the PRIMARY interface. The Admin Panel is SECONDARY.

Klytos is an AI-First CMS. This means:

1. Every feature MUST be fully controllable via MCP tools
2. The admin panel provides a visual fallback for humans
3. When developing a new feature, implement the MCP tool FIRST, then the admin page

---

Interface Comparison

| Aspect | Admin Panel (Desktop) | MCP (AI) | |---|---|---| | Priority | Secondary | Primary | | User | Humans via browser | AI assistants via API | | Context check | klytos_is_admin() | klytos_is_mcp() | | Auth method | Session cookies | Bearer token / OAuth / App Password | | CSRF | Required on all forms | Not needed (token auth) | | Data format | HTML forms → POST | JSON-RPC 2.0 | | Response | Rendered HTML page | JSON response | | Rate limiting | No | 60/min per identifier | | Session | 30-min inactivity timeout | Stateless (per-request) |

---

Admin Panel (Desktop) Pattern

Request Flow

Browser → admin/{page}.php → bootstrap.php → Session auth → CSRF check → Process → Render HTML

Implementation Template

<?php
declare(strict_types=1);

// 1. Bootstrap: loads App, starts session, checks auth
require_once __DIR__ . '/bootstrap.php';

// 2. Setup
$pageTitle   = 'Feature Name';
$currentPage = 'my-feature'; // Matches sidebar item 'id'
$auth        = $app->getAuth();
$error = $success = '';

// 3. Handle POST (with CSRF)
if ($_SERVER['REQUEST_METHOD'] === 'POST' && klytos_verify_csrf()) {
    try {
        $input = klytos_sanitize_text($_POST['field'] ?? '');
        // ... process
        $success = 'Saved successfully';
    } catch (\Exception $e) {
        $error = $e->getMessage();
    }
}

// 4. Fetch data for display
$data = klytos_app()->getMyManager()->list();

// 5. Render with templates
require_once __DIR__ . '/templates/header.php';
require_once __DIR__ . '/templates/sidebar.php';
?>

<?php if ($error): ?>
    <div class="alert alert-error"><?php echo klytos_esc_html($error); ?></div>
<?php endif; ?>

<div class="card">
    <form method="POST">
        <?php echo klytos_csrf_field(); ?>
        <!-- Form fields with escaping -->
        <button type="submit" class="btn btn-primary">Save</button>
    </form>
</div>

<?php require_once __DIR__ . '/templates/footer.php'; ?>

Key Requirements

• CSRF token on ALL forms
• All output escaped (klytos_esc_html, klytos_esc_attr)
• All input sanitized
• Permission checks (klytos_has_permission())
• Header/sidebar/footer templates included

---

MCP (AI) Pattern

Request Flow

AI Client → /mcp endpoint → JSON-RPC → Token Auth → Rate Limit → Tool Registry → Handler → JSON Response

Implementation Template

// 1. Register tool
klytos_add_filter('mcp.tools_list', function (array $tools): array {
    $tools[] = [
        'name'        => 'my_feature_action',
        'description' => 'Clear description for AI to understand when to use this tool.',
        'inputSchema' => [
            'type'       => 'object',
            'properties' => [
                'field' => ['type' => 'string', 'description' => 'What this field does'],
            ],
            'required' => ['field'],
        ],
        'annotations' => [
            'readOnlyHint'    => false,
            'destructiveHint' => false,
        ],
    ];
    return $tools;
});

// 2. Handle tool call
klytos_add_filter('mcp.handle_tool', function (mixed $result, string $name, array $params): mixed {
    if ($name !== 'my_feature_action') return $result;

    $field = klytos_sanitize_text($params['field'] ?? '');

    try {
        $data = klytos_app()->getMyManager()->doAction($field);
        return [
            'content' => [['type' => 'text', 'text' => json_encode($data)]],
            'isError' => false,
        ];
    } catch (\Exception $e) {
        return [
            'content' => [['type' => 'text', 'text' => 'Error: ' . $e->getMessage()]],
            'isError' => true,
        ];
    }
}, 10);

Key Requirements

• Clear tool description (AI needs to know when to use it)
• JSON Schema for parameters
• Proper annotations (readOnly, destructive, idempotent)
• Sanitized inputs
• Structured JSON response
• Declared in klytos-plugin.json under mcp_tools

---

Authentication Methods (by Priority)

MCP requests are authenticated in this order:

| Priority | Method | Header | Format | |---|---|---|---| | 1 | Bearer Token | Authorization: Bearer {token} | 64-char hex | | 2 | OAuth 2.0 Access Token | Authorization: Bearer {access_token} | OAuth flow | | 3 | Application Password | Authorization: Basic {base64} | HTTP Basic Auth |

Admin panel uses session cookies (started via login.php).

---

Equivalency Table

Every admin feature MUST have an MCP equivalent:

| Admin Page | MCP Tool(s) | |---|---| | pages.php (list) | klytos_list_pages | | page-editor.php (create/edit) | klytos_create_page, klytos_update_page | | page-editor.php (delete) | klytos_delete_page | | theme.php | klytos_get_theme, klytos_set_theme, klytos_set_colors, klytos_set_fonts | | settings.php | klytos_get_site_config, klytos_set_site_config | | users.php | klytos_list_users, klytos_create_user, klytos_update_user | | assets.php | klytos_list_assets, klytos_upload_asset, klytos_delete_asset | | plugins.php | klytos_list_plugins, klytos_activate_plugin, klytos_deactivate_plugin | | post-types.php | klytos_create_post_type, klytos_list_post_types, etc. | | menu.php | klytos_get_menu, klytos_set_menu, klytos_add_menu_item | | scheduled-actions.php | klytos_list_scheduled_actions, klytos_schedule_*, klytos_cancel_* | | webhooks.php | klytos_create_webhook, klytos_list_webhooks, klytos_delete_webhook | | analytics.php | klytos_get_analytics, klytos_get_top_pages | | Build button | klytos_build_site, klytos_build_page |

---

Context Detection Helpers

// Check which interface is being used
if (klytos_is_mcp()) {
    // AI is calling via MCP — return JSON data
    return ['success' => true, 'data' => $result];
} elseif (klytos_is_admin()) {
    // Human is using admin panel — redirect or render HTML
    header('Location: ' . klytos_admin_url('pages.php'));
} elseif (klytos_is_cli()) {
    // Running from command line
    echo "Done.\n";
}

---

Shared Business Logic

IMPORTANT: Business logic should live in Manager classes, NOT in admin pages or MCP handlers. Both interfaces should call the same manager:

// BAD: Logic in admin page
// admin/pages.php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $data = [...];
    klytos_storage()->write('pages', $slug, $data); // Direct storage access!
}

// GOOD: Logic in manager, called by both
// core/page-manager.php
class PageManager {
    public function create(array $data): array { ... }
}

// admin/pages.php calls:
$app->getPages()->create($data);

// MCP handler calls:
$app->getPages()->create($params);

This ensures:

• Same validation in both interfaces
• Same hooks fired in both interfaces
• No feature drift between admin and MCP

---

Plugin Development Checklist

When developing a plugin for Klytos, ensure:

• [ ] MCP tools defined for all functionality (mcp.tools_list + mcp.handle_tool)
• [ ] MCP tools declared in klytos-plugin.json (mcp_tools array)
• [ ] Admin page (optional but recommended) with sidebar item
• [ ] Shared logic in a manager/service class, not in admin or MCP handlers
• [ ] Same hooks fire regardless of which interface triggers the action
• [ ] CSRF on admin forms (klytos_csrf_field() + klytos_verify_csrf())
• [ ] Input sanitized in both interfaces
• [ ] Output escaped in admin pages
• [ ] Permissions checked in both interfaces

---

Source Files

• Admin bootstrap: admin/bootstrap.php
• MCP server: core/mcp/server.php
• MCP auth: core/mcp/token-auth.php
• Admin auth: core/auth.php
• Context checks: core/helpers-global.php (klytos_is_admin, klytos_is_mcp, klytos_is_cli)