kura-mcp-admin 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# kura-mcp-admin
+
+MCP server exposing Kura's **admin** orchestrator endpoints as first-class tool calls for Claude Desktop, Cursor, and Claude Code.
+
+This is the admin counterpart to [`kura-mcp-agent-import`](https://www.npmjs.com/package/kura-mcp-agent-import) (which is customer-facing, scoped to `/api/agent/*`). The admin MCP gives Ben's agent full project management — list projects, edit pages, update brand kits, trigger deploys, manage media, purge caches, read SEO data.
+
+## Install
+
+Use via `npx` (no global install needed):
+
+```jsonc
+// ~/.claude/.mcp.json  (or Claude Desktop / Cursor MCP settings)
+{
+  "mcpServers": {
+    "kura-admin": {
+      "command": "npx",
+      "args": ["-y", "kura-mcp-admin"],
+      "env": {
+        "KURA_API_KEY": "kura_<48-hex>",
+        "KURA_BASE_URL": "https://orchestrator-production-1d88.up.railway.app"
+      }
+    }
+  }
+}
+```
+
+Or install globally:
+
+```bash
+npm install -g kura-mcp-admin
+```
+
+### Get the API key
+
+The `KURA_API_KEY` must have **`admin-full`** scope. Mint one at:
+**[www.kurawebsites.com/admin/settings/api-keys](https://www.kurawebsites.com/admin/settings/api-keys)**
+
+Customer-scope (`agent-import`) keys are rejected by the orchestrator with `403 insufficient_scope` on every admin route. Use the customer MCP server (`kura-mcp-agent-import`) for those keys.
+
+## Tools (11)
+
+### Projects
+
+| Tool | Args | What it does |
+| --- | --- | --- |
+| `kura_list_projects` | `{ includeArchived? }` | List all your projects (id, slug, status, framework, timestamps) |
+| `kura_get_project` | `{ projectId }` | Full project metadata including brand kit, design DNA, domain status |
+
+### Brand kit
+
+| Tool | Args | What it does |
+| --- | --- | --- |
+| `kura_get_brand_kit` | `{ projectId }` | Read current brand kit JSON |
+| `kura_update_brand_kit` | `{ projectId, brandKit }` | Replace brand kit (full object — see schema in tools.ts) |
+
+### Pages
+
+| Tool | Args | What it does |
+| --- | --- | --- |
+| `kura_list_pages` | `{ projectId }` | List all pages with id/slug/title/type/status |
+| `kura_get_page` | `{ projectId, slug }` | Read full HTML content + metadata |
+| `kura_update_page` | `{ projectId, slug, content }` | Replace page HTML (writes to live) |
+
+### Deploy
+
+| Tool | Args | What it does |
+| --- | --- | --- |
+| `kura_trigger_deploy` | `{ projectId, message? }` | Publish current state to live |
+
+### Media + ops
+
+| Tool | Args | What it does |
+| --- | --- | --- |
+| `kura_list_media` | `{ projectId }` | Project's media library |
+| `kura_purge_cache` | `{ projectId }` | Bust Cloudways caches |
+| `kura_list_tracked_keywords` | `{ projectId }` | SEO keywords + latest rank positions |
+
+## Common workflows
+
+**Find a project, then operate on it:**
+
+```
+1. kura_list_projects() → find the projectId
+2. kura_get_project({ projectId }) → see metadata
+3. kura_list_pages({ projectId }) → see pages
+4. kura_get_page({ projectId, slug: 'home' }) → read content
+5. kura_update_page({ projectId, slug: 'home', content: '<new html>' })
+6. kura_trigger_deploy({ projectId, message: 'Update hero copy' })
+```
+
+**Brand kit refresh:**
+
+```
+1. kura_get_brand_kit({ projectId })  → see current kit
+2. kura_update_brand_kit({ projectId, brandKit: {...full new kit...} })
+3. kura_purge_cache({ projectId })   → ensure fresh assets land
+```
+
+## Protocol
+
+Newline-delimited JSON-RPC 2.0 over stdio. Methods: `initialize`, `tools/list`, `tools/call`, `notifications/initialized`, `notifications/cancelled`, `ping`. Implemented directly without `@modelcontextprotocol/sdk` for zero deps beyond `tsx`.
+
+## What's not (yet) included
+
+Per the [admin agent integration design](https://github.com/benbybee/kura-web/blob/main/docs/plans/2026-05-13-admin-agent-integration.md), the full surface includes form submissions, change requests, and audit log writes — those route through kura-web's API (not orchestrator) and will land in a v0.2 follow-up that adds orchestrator passthrough routes.
+
+## Source
+
+[github.com/benbybee/kura-orchestrator/tree/main/mcp/admin](https://github.com/benbybee/kura-orchestrator/tree/main/mcp/admin).

package/bin/server.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Bin wrapper for the kura-mcp-admin server. Same tsx-runtime pattern
+// as the agent-import MCP — no build step at install time.
+
+import { spawn } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const server = resolve(here, '..', 'server.ts');
+const require = createRequire(import.meta.url);
+
+let tsxBin;
+try {
+  tsxBin = require.resolve('tsx/dist/cli.mjs');
+} catch {
+  tsxBin = require.resolve('tsx');
+}
+
+const child = spawn(process.execPath, [tsxBin, server, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 1);
+});

package/lib/config.ts

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Local copy of the CLI's CliConfig type + loader. Duplicated here so
+// the MCP package is publishable without depending on kura-cli (avoiding
+// the chicken-and-egg of "install kura-cli to install kura-mcp").
+//
+// Read order:
+//   1. KURA_API_KEY + KURA_BASE_URL env vars (highest precedence)
+//   2. ~/.kurarc JSON file: { "api_key": "kura_…", "base_url": "https://…" }
+//   3. Fallback base URL: production Railway orchestrator
+
+export type CliConfig = {
+  baseUrl: string;
+  apiKey: string;
+};
+
+const DEFAULT_BASE_URL = 'https://orchestrator-production-1d88.up.railway.app';
+
+export async function loadConfig(): Promise<CliConfig> {
+  const envKey = process.env['KURA_API_KEY']?.trim();
+  const envUrl = process.env['KURA_BASE_URL']?.trim();
+
+  let fileKey: string | undefined;
+  let fileUrl: string | undefined;
+  try {
+    const raw = await readFile(join(homedir(), '.kurarc'), 'utf-8');
+    const parsed = JSON.parse(raw) as { api_key?: string; base_url?: string };
+    fileKey = parsed.api_key?.trim();
+    fileUrl = parsed.base_url?.trim();
+  } catch {
+    // missing or unreadable; env-only is fine
+  }
+
+  const apiKey = envKey ?? fileKey;
+  if (!apiKey) {
+    throw new Error(
+      'No Kura API key found. Set KURA_API_KEY env var or create ~/.kurarc with { "api_key": "kura_..." }.\n' +
+        'Generate a key at https://www.kurawebsites.com/account/api-keys',
+    );
+  }
+  if (!/^kura_[0-9a-f]{48}$/.test(apiKey)) {
+    throw new Error(
+      `KURA_API_KEY format invalid (expected kura_<48 hex>); got "${apiKey.slice(0, 12)}…"`,
+    );
+  }
+  return {
+    baseUrl: (envUrl ?? fileUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
+    apiKey,
+  };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "kura-mcp-admin",
+  "version": "0.1.0",
+  "description": "MCP server exposing Kura's admin orchestrator endpoints as first-class tool calls for Claude Desktop, Cursor, and Claude Code. Requires an admin-full scope API key.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Kura",
+  "homepage": "https://www.kurawebsites.com/agent-docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/benbybee/kura-orchestrator",
+    "directory": "mcp/admin"
+  },
+  "keywords": [
+    "kura",
+    "mcp",
+    "model-context-protocol",
+    "admin",
+    "claude-desktop",
+    "cursor",
+    "claude-code"
+  ],
+  "bin": {
+    "kura-mcp-admin": "bin/server.mjs"
+  },
+  "files": [
+    "bin/server.mjs",
+    "server.ts",
+    "tools.ts",
+    "lib/**/*.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  }
+}

package/server.ts

@@ -0,0 +1,154 @@
+// Minimal MCP-protocol stdio server for the kura-mcp-admin tools.
+// Same protocol implementation as mcp/agent-import/server.ts (no SDK
+// dep). 11 tools covering project list/get, brand kit get/update,
+// pages list/get/update, deploy trigger, media list, cache purge,
+// keywords list.
+//
+// Requires an admin-full scope API key (from /admin/settings/api-keys).
+// Customer-scope keys are rejected by the orchestrator with 403
+// insufficient_scope.
+
+import * as readline from 'node:readline';
+import { loadConfig, type CliConfig } from './lib/config.js';
+import { TOOL_SCHEMAS, callTool } from './tools.js';
+
+const SERVER_INFO = { name: 'kura-mcp-admin', version: '0.1.0' };
+const CAPABILITIES = { tools: {} };
+
+type JsonRpcRequest = {
+  jsonrpc: '2.0';
+  id?: number | string | null;
+  method: string;
+  params?: unknown;
+};
+
+type JsonRpcResponse =
+  | { jsonrpc: '2.0'; id: number | string | null; result: unknown }
+  | {
+      jsonrpc: '2.0';
+      id: number | string | null;
+      error: { code: number; message: string; data?: unknown };
+    };
+
+export async function runMcpServer(opts?: {
+  cfgOverride?: CliConfig;
+  input?: NodeJS.ReadableStream;
+  output?: NodeJS.WritableStream;
+}): Promise<void> {
+  const cfg = opts?.cfgOverride ?? (await loadConfig());
+  const input = opts?.input ?? process.stdin;
+  const output = opts?.output ?? process.stdout;
+  const rl = readline.createInterface({ input, terminal: false });
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let req: JsonRpcRequest;
+    try {
+      req = JSON.parse(trimmed);
+    } catch (err) {
+      writeResponse(output, {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: `parse_error: ${(err as Error).message}` },
+      });
+      continue;
+    }
+
+    const id = req.id ?? null;
+    const isNotification = req.id === undefined;
+
+    try {
+      switch (req.method) {
+        case 'initialize':
+          if (isNotification) break;
+          writeResponse(output, {
+            jsonrpc: '2.0',
+            id,
+            result: {
+              protocolVersion: '2024-11-05',
+              capabilities: CAPABILITIES,
+              serverInfo: SERVER_INFO,
+            },
+          });
+          break;
+        case 'tools/list':
+          if (isNotification) break;
+          writeResponse(output, {
+            jsonrpc: '2.0',
+            id,
+            result: { tools: Object.values(TOOL_SCHEMAS) },
+          });
+          break;
+        case 'tools/call': {
+          if (isNotification) break;
+          const params = (req.params ?? {}) as {
+            name?: string;
+            arguments?: unknown;
+          };
+          if (typeof params.name !== 'string') {
+            writeResponse(output, {
+              jsonrpc: '2.0',
+              id,
+              error: { code: -32602, message: 'invalid_params: name required' },
+            });
+            break;
+          }
+          const result = await callTool(params.name, params.arguments, { cfg });
+          writeResponse(output, {
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+              isError: !result.ok,
+            },
+          });
+          break;
+        }
+        case 'notifications/initialized':
+        case 'notifications/cancelled':
+          break;
+        case 'ping':
+          if (isNotification) break;
+          writeResponse(output, { jsonrpc: '2.0', id, result: {} });
+          break;
+        default:
+          if (isNotification) break;
+          writeResponse(output, {
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32601, message: `method_not_found: ${req.method}` },
+          });
+      }
+    } catch (err) {
+      if (!isNotification) {
+        writeResponse(output, {
+          jsonrpc: '2.0',
+          id,
+          error: {
+            code: -32603,
+            message: `internal_error: ${(err as Error).message}`,
+          },
+        });
+      }
+      process.stderr.write(
+        `[kura-mcp-admin] error in method "${req.method}": ${(err as Error).message}\n`,
+      );
+    }
+  }
+}
+
+function writeResponse(out: NodeJS.WritableStream, resp: JsonRpcResponse): void {
+  out.write(JSON.stringify(resp) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] &&
+  import.meta.url === new URL(`file://${process.argv[1].replace(/\\/g, '/')}`).href;
+if (invokedDirectly) {
+  runMcpServer().catch((err) => {
+    process.stderr.write(`[kura-mcp-admin] fatal: ${(err as Error).message}\n`);
+    process.exit(1);
+  });
+}

package/tools.ts

@@ -0,0 +1,414 @@
+import type { CliConfig } from './lib/config.js';
+
+// ---------- kura-mcp-admin tool implementations ----------
+//
+// 11 tools wrapping Kura orchestrator admin endpoints. Used by Ben's
+// local Claude Code (or any MCP-aware client) to manage existing
+// projects from inside an agent session.
+//
+// Auth: admin-full scope API key (see /admin/settings/api-keys in
+// kura-web). Tools that need scope='admin-full' WILL be rejected with
+// 403 insufficient_scope if the user's key is scope='agent-import'.
+//
+// All tools return ToolResult — the MCP server wraps in the
+// { content: [...], isError } shape MCP clients expect.
+
+export type ToolResult =
+  | { ok: true; data: unknown }
+  | { ok: false; error: string; data?: unknown };
+
+export type ToolContext = { cfg: CliConfig };
+
+// ---------- Tool schemas (advertised via tools/list) ----------
+
+export const TOOL_SCHEMAS = {
+  // Projects
+  kura_list_projects: {
+    name: 'kura_list_projects',
+    description:
+      "List every project the authenticated admin owns. Returns each project's id, slug, businessName, status, platform, framework, liveUrl, customDomain, and timestamps. Use this as the entry point to find a projectId before calling project-scoped tools.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        includeArchived: {
+          type: 'boolean',
+          description: 'Include archived projects in the result. Default: false.',
+        },
+      },
+    },
+  },
+  kura_get_project: {
+    name: 'kura_get_project',
+    description:
+      'Get a single project by id with full metadata (brand kit, design DNA, domain status, lock state, etc.). Encrypted fields are returned as "<encrypted>" placeholders.',
+    inputSchema: {
+      type: 'object',
+      properties: { projectId: { type: 'string' } },
+      required: ['projectId'],
+    },
+  },
+  // Brand kit
+  kura_get_brand_kit: {
+    name: 'kura_get_brand_kit',
+    description:
+      "Read the project's brand kit JSON (colors, fonts, type scale, radii, logo). Returns null if the brand kit hasn't been set yet.",
+    inputSchema: {
+      type: 'object',
+      properties: { projectId: { type: 'string' } },
+      required: ['projectId'],
+    },
+  },
+  kura_update_brand_kit: {
+    name: 'kura_update_brand_kit',
+    description:
+      "Replace the project's brand kit. Pass the FULL brand kit object (not a patch). On success the orchestrator projects the new tokens to WP (for WP-canonical) or writes the tokens.css file (for github-files) automatically.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        brandKit: {
+          type: 'object',
+          description:
+            'Full brand kit object. Shape: { version: 1, colors: {primary, accent, ink, surface, border}, fonts: {heading, body}, typeScale: {h1,h2,h3,body}, radii: {sm,md,lg,full}, spacing?: {xs,sm,md,lg,xl}, logo: {mediaId, alt} | null, favicon?: {mediaId} | null }',
+        },
+      },
+      required: ['projectId', 'brandKit'],
+    },
+  },
+  // Pages
+  kura_list_pages: {
+    name: 'kura_list_pages',
+    description:
+      "List all pages on a project. Returns each page's id, title, slug, type (home/about/services/...), and status. Works for both WP-canonical and github-files projects via the platform-adapter abstraction.",
+    inputSchema: {
+      type: 'object',
+      properties: { projectId: { type: 'string' } },
+      required: ['projectId'],
+    },
+  },
+  kura_get_page: {
+    name: 'kura_get_page',
+    description:
+      "Read a single page's full HTML content + metadata. For github-files projects this returns the raw file content. For WP projects this returns the rendered HTML body.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        slug: {
+          type: 'string',
+          description: 'Page slug or platform-native id (URL-encoded if needed).',
+        },
+      },
+      required: ['projectId', 'slug'],
+    },
+  },
+  kura_update_page: {
+    name: 'kura_update_page',
+    description:
+      "Replace a page's full HTML content. Returns the new revisionId for optimistic concurrency. WARNING: this writes to live — there's no draft step. For edits that should land via the visual editor pipeline (with data-kura-id anchoring), use /api/edit/* endpoints instead.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        slug: { type: 'string' },
+        content: {
+          type: 'string',
+          description: 'Full new HTML body (post-shortcode for WP).',
+        },
+      },
+      required: ['projectId', 'slug', 'content'],
+    },
+  },
+  // Deploy
+  kura_trigger_deploy: {
+    name: 'kura_trigger_deploy',
+    description:
+      "Publish the project's current draft state to live. For WP-canonical projects this materialises any pending kura_edits CSS and pushes via WP REST. For github-files projects this commits the working tree to the configured branch + deploys via Cloudways.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        message: {
+          type: 'string',
+          description: 'Optional commit/deploy message for the audit trail.',
+        },
+      },
+      required: ['projectId'],
+    },
+  },
+  // Media
+  kura_list_media: {
+    name: 'kura_list_media',
+    description:
+      "List a project's media library (images, videos, SVGs). Returns each item's id, url, mime, width/height (for images), size, and alt text. Includes WP-imported items and Kura-uploaded ones.",
+    inputSchema: {
+      type: 'object',
+      properties: { projectId: { type: 'string' } },
+      required: ['projectId'],
+    },
+  },
+  // Cache
+  kura_purge_cache: {
+    name: 'kura_purge_cache',
+    description:
+      "Purge Varnish + Memcached + filesystem caches for the project's Cloudways app. Returns immediately — the actual purge is queued by Cloudways.",
+    inputSchema: {
+      type: 'object',
+      properties: { projectId: { type: 'string' } },
+      required: ['projectId'],
+    },
+  },
+  // SEO / keywords
+  kura_list_tracked_keywords: {
+    name: 'kura_list_tracked_keywords',
+    description:
+      'List keywords being tracked for SERP rankings on a project. Returns each keyword + its latest rank position (if available).',
+    inputSchema: {
+      type: 'object',
+      properties: { projectId: { type: 'string' } },
+      required: ['projectId'],
+    },
+  },
+} as const;
+
+export type ToolName = keyof typeof TOOL_SCHEMAS;
+
+// ---------- Tool dispatcher ----------
+
+export async function callTool(
+  name: string,
+  args: unknown,
+  ctx: ToolContext,
+): Promise<ToolResult> {
+  try {
+    switch (name) {
+      case 'kura_list_projects':
+        return await listProjects(args, ctx);
+      case 'kura_get_project':
+        return await getProject(args, ctx);
+      case 'kura_get_brand_kit':
+        return await getBrandKit(args, ctx);
+      case 'kura_update_brand_kit':
+        return await updateBrandKit(args, ctx);
+      case 'kura_list_pages':
+        return await listPages(args, ctx);
+      case 'kura_get_page':
+        return await getPage(args, ctx);
+      case 'kura_update_page':
+        return await updatePage(args, ctx);
+      case 'kura_trigger_deploy':
+        return await triggerDeploy(args, ctx);
+      case 'kura_list_media':
+        return await listMedia(args, ctx);
+      case 'kura_purge_cache':
+        return await purgeCache(args, ctx);
+      case 'kura_list_tracked_keywords':
+        return await listKeywords(args, ctx);
+      default:
+        return { ok: false, error: `unknown_tool:${name}` };
+    }
+  } catch (err) {
+    return { ok: false, error: `tool_threw:${(err as Error).message}` };
+  }
+}
+
+// ============================================================
+// Tool implementations
+// ============================================================
+
+async function listProjects(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const includeArchived = readBoolArg(args, 'includeArchived', false);
+  const url = new URL(`${ctx.cfg.baseUrl}/api/projects`);
+  if (includeArchived) url.searchParams.set('includeArchived', 'true');
+  return apiGet(url.toString(), ctx);
+}
+
+async function getProject(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  return apiGet(
+    `${ctx.cfg.baseUrl}/api/projects/by-id/${encodeURIComponent(projectId.value)}`,
+    ctx,
+  );
+}
+
+async function getBrandKit(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  // The brand-kit GET endpoint accepts projectId via query param.
+  const url = new URL(`${ctx.cfg.baseUrl}/api/projects/brand-kit`);
+  url.searchParams.set('projectId', projectId.value);
+  return apiGet(url.toString(), ctx);
+}
+
+async function updateBrandKit(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  const brandKit = readObjectArg(args, 'brandKit');
+  if (!brandKit.ok) return brandKit;
+  return apiSend('PUT', `${ctx.cfg.baseUrl}/api/projects/brand-kit`, ctx, {
+    projectId: projectId.value,
+    brandKit: brandKit.value,
+  });
+}
+
+async function listPages(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  return apiGet(
+    `${ctx.cfg.baseUrl}/api/projects/${encodeURIComponent(projectId.value)}/pages`,
+    ctx,
+  );
+}
+
+async function getPage(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  const slug = readStringArg(args, 'slug');
+  if (!slug.ok) return slug;
+  return apiGet(
+    `${ctx.cfg.baseUrl}/api/projects/${encodeURIComponent(projectId.value)}/pages/${encodeURIComponent(slug.value)}`,
+    ctx,
+  );
+}
+
+async function updatePage(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  const slug = readStringArg(args, 'slug');
+  if (!slug.ok) return slug;
+  const content = readStringArg(args, 'content');
+  if (!content.ok) return content;
+  return apiSend(
+    'PUT',
+    `${ctx.cfg.baseUrl}/api/projects/${encodeURIComponent(projectId.value)}/pages/${encodeURIComponent(slug.value)}`,
+    ctx,
+    { content: content.value },
+  );
+}
+
+async function triggerDeploy(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  const message = readOptionalStringArg(args, 'message');
+  return apiSend(
+    'POST',
+    `${ctx.cfg.baseUrl}/api/projects/${encodeURIComponent(projectId.value)}/publish`,
+    ctx,
+    message ? { message } : {},
+  );
+}
+
+async function listMedia(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  const url = new URL(`${ctx.cfg.baseUrl}/api/media`);
+  url.searchParams.set('projectId', projectId.value);
+  return apiGet(url.toString(), ctx);
+}
+
+async function purgeCache(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  return apiSend(
+    'POST',
+    `${ctx.cfg.baseUrl}/api/projects/${encodeURIComponent(projectId.value)}/cache/purge`,
+    ctx,
+    {},
+  );
+}
+
+async function listKeywords(args: unknown, ctx: ToolContext): Promise<ToolResult> {
+  const projectId = readStringArg(args, 'projectId');
+  if (!projectId.ok) return projectId;
+  return apiGet(
+    `${ctx.cfg.baseUrl}/api/projects/${encodeURIComponent(projectId.value)}/keywords`,
+    ctx,
+  );
+}
+
+// ============================================================
+// HTTP helpers
+// ============================================================
+
+async function apiGet(url: string, ctx: ToolContext): Promise<ToolResult> {
+  const resp = await fetch(url, {
+    headers: { Authorization: `Bearer ${ctx.cfg.apiKey}` },
+  });
+  return parseFetchAsToolResult(resp);
+}
+
+async function apiSend(
+  method: 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+  url: string,
+  ctx: ToolContext,
+  body: unknown,
+): Promise<ToolResult> {
+  const resp = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.cfg.apiKey}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  return parseFetchAsToolResult(resp);
+}
+
+async function parseFetchAsToolResult(resp: Response): Promise<ToolResult> {
+  const text = await resp.text();
+  let parsed: unknown;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = { raw: text };
+  }
+  if (!resp.ok) {
+    return { ok: false, error: `http_${resp.status}`, data: parsed };
+  }
+  return { ok: true, data: parsed };
+}
+
+// ============================================================
+// Arg parsing helpers
+// ============================================================
+
+type ReadOk<T> = { ok: true; value: T };
+type ReadErr = { ok: false; error: string };
+
+function readStringArg(args: unknown, key: string): ReadOk<string> | ReadErr {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+    return { ok: false, error: 'missing_args_object' };
+  }
+  const v = (args as Record<string, unknown>)[key];
+  if (typeof v !== 'string' || v.length === 0) {
+    return { ok: false, error: `missing_or_empty_arg:${key}` };
+  }
+  return { ok: true, value: v };
+}
+
+function readOptionalStringArg(args: unknown, key: string): string | undefined {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) return undefined;
+  const v = (args as Record<string, unknown>)[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+function readObjectArg(
+  args: unknown,
+  key: string,
+): ReadOk<Record<string, unknown>> | ReadErr {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+    return { ok: false, error: 'missing_args_object' };
+  }
+  const v = (args as Record<string, unknown>)[key];
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+    return { ok: false, error: `missing_or_invalid_arg:${key}` };
+  }
+  return { ok: true, value: v as Record<string, unknown> };
+}
+
+function readBoolArg(args: unknown, key: string, defaultValue: boolean): boolean {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) return defaultValue;
+  const v = (args as Record<string, unknown>)[key];
+  return typeof v === 'boolean' ? v : defaultValue;
+}