cue-ai 0.4.0 → 0.5.0

package/resources/mcps/mcps/marva-blog/server.py

@@ -1,843 +0,0 @@
-#!/usr/bin/env -S uv run -q --script
-# /// script
-# requires-python = ">=3.10"
-# dependencies = [
-#     "mcp>=1.0.0",
-#     "httpx>=0.27",
-# ]
-# ///
-"""Marva Blog MCP server.
-
-Stdio MCP that wraps the MARVA Home Medusa v2 admin blog API so Claude can
-draft, list, update, publish, and revalidate posts on
-https://admin.marvahome.com without leaving the conversation. Thumbnails
-are produced upstream (Higgsfield MCP, S3, or any hosted URL) and attached
-by URL via `marva_blog_set_thumbnail` — this server does not generate
-images itself.
-
-Authentication: Medusa v2 admin JWT. Provide either a pre-fetched
-`MARVA_ADMIN_TOKEN` or admin `MARVA_ADMIN_EMAIL` / `MARVA_ADMIN_PASSWORD`
-credentials; the server will exchange them via
-POST /auth/user/emailpass and cache the JWT in-process for ~30 minutes.
-
-Config (env):
-    MARVA_BACKEND_URL      default https://admin.marvahome.com
-    MARVA_ADMIN_EMAIL      admin login email (used if no MARVA_ADMIN_TOKEN)
-    MARVA_ADMIN_PASSWORD   admin login password
-    MARVA_ADMIN_TOKEN      optional pre-fetched JWT, bypasses login
-    MARVA_PUBLISHABLE_KEY  optional, only used for /store/* reads
-
-Tools:
-    marva_blog_list                 — list posts (status=all|draft|published)
-    marva_blog_get                  — fetch one post by slug
-    marva_blog_create_draft         — POST action=create
-    marva_blog_update               — POST action=update with patch
-    marva_blog_set_thumbnail        — convenience: update thumbnail_url
-    marva_blog_publish              — POST action=publish + revalidate
-    marva_blog_unpublish            — POST action=unpublish + revalidate
-    marva_blog_delete               — POST action=delete + revalidate
-    marva_blog_revalidate           — manual cache bust
-    marva_blog_validate_sections    — local section linter
-
-Run: uv run ~/Documents/soul/mcps/mcps/marva-blog/server.py
-Register in ~/.claude.json mcpServers as `marva-blog`.
-"""
-from __future__ import annotations
-
-import os
-import re
-import time
-from typing import Any
-
-import httpx
-from mcp.server.fastmcp import FastMCP
-
-# ---------------------------------------------------------------------------
-# Config (read once at import time so the values survive across tool calls).
-# ---------------------------------------------------------------------------
-
-BACKEND_URL = os.environ.get(
-    "MARVA_BACKEND_URL", "https://admin.marvahome.com"
-).rstrip("/")
-ADMIN_EMAIL = os.environ.get("MARVA_ADMIN_EMAIL", "").strip()
-ADMIN_PASSWORD = os.environ.get("MARVA_ADMIN_PASSWORD", "").strip()
-ADMIN_TOKEN_ENV = os.environ.get("MARVA_ADMIN_TOKEN", "").strip()
-PUBLISHABLE_KEY = os.environ.get("MARVA_PUBLISHABLE_KEY", "").strip()
-
-HTTP_TIMEOUT = 20.0
-# Soft TTL on a fetched admin JWT. Medusa's default access token lifetime is
-# longer than this; we re-login proactively to avoid in-flight expirations.
-TOKEN_TTL_SECS = 30 * 60
-
-_token_cache: dict[str, Any] = {"token": "", "fetched_at": 0.0}
-
-mcp = FastMCP("marva-blog")
-
-
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-
-class BlogError(RuntimeError):
-    """Raised for any user-visible failure. The tool wrappers translate this
-    into a structured `{ok: false, ...}` response so the MCP transport never
-    sees an unhandled exception."""
-
-
-async def _admin_token() -> str:
-    """Return a valid admin JWT. Order:
-
-    1. `MARVA_ADMIN_TOKEN` env var if set (never expires from our POV).
-    2. Cached token from a prior `/auth/user/emailpass` login that's still
-       within the soft TTL.
-    3. Fresh login with `MARVA_ADMIN_EMAIL` / `MARVA_ADMIN_PASSWORD`.
-
-    Raises BlogError with an actionable message if no auth path is viable.
-    """
-    if ADMIN_TOKEN_ENV:
-        return ADMIN_TOKEN_ENV
-
-    cached = _token_cache.get("token") or ""
-    fetched_at = float(_token_cache.get("fetched_at") or 0.0)
-    if cached and (time.time() - fetched_at) < TOKEN_TTL_SECS:
-        return cached
-
-    if not ADMIN_EMAIL or not ADMIN_PASSWORD:
-        raise BlogError(
-            "No admin credentials configured. Set MARVA_ADMIN_TOKEN, or both "
-            "MARVA_ADMIN_EMAIL and MARVA_ADMIN_PASSWORD."
-        )
-
-    url = f"{BACKEND_URL}/auth/user/emailpass"
-    try:
-        async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
-            resp = await client.post(
-                url,
-                json={"email": ADMIN_EMAIL, "password": ADMIN_PASSWORD},
-                headers={"content-type": "application/json"},
-            )
-    except httpx.HTTPError as e:
-        raise BlogError(f"login transport error to {url}: {e}") from e
-
-    if resp.status_code >= 400:
-        body = (resp.text or "").strip()[:400]
-        raise BlogError(
-            f"admin login failed: HTTP {resp.status_code} from {url}: {body}"
-        )
-
-    try:
-        data = resp.json()
-    except ValueError as e:
-        raise BlogError(f"admin login returned non-JSON: {resp.text[:200]}") from e
-
-    token = (data or {}).get("token") or ""
-    if not token:
-        raise BlogError(f"admin login returned no token: {data!r}")
-
-    _token_cache["token"] = token
-    _token_cache["fetched_at"] = time.time()
-    return token
-
-
-async def _admin_request(
-    method: str,
-    path: str,
-    *,
-    json_body: dict | None = None,
-) -> dict:
-    """Authenticated request against /admin/*. Returns parsed JSON. Raises
-    BlogError with the upstream status + truncated body on non-2xx."""
-    token = await _admin_token()
-    url = f"{BACKEND_URL}{path}"
-    headers = {
-        "authorization": f"Bearer {token}",
-        "content-type": "application/json",
-    }
-    try:
-        async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
-            resp = await client.request(
-                method, url, headers=headers, json=json_body
-            )
-    except httpx.HTTPError as e:
-        raise BlogError(f"transport error {method} {url}: {e}") from e
-
-    if resp.status_code >= 400:
-        body = (resp.text or "").strip()[:600]
-        raise BlogError(
-            f"upstream {method} {path} -> HTTP {resp.status_code}: {body}"
-        )
-
-    if not resp.content:
-        return {}
-    try:
-        return resp.json()
-    except ValueError as e:
-        raise BlogError(
-            f"upstream {method} {path} returned non-JSON: {resp.text[:200]}"
-        ) from e
-
-
-async def _store_request(path: str) -> dict:
-    """Public /store/* GET. Sends MARVA_PUBLISHABLE_KEY if configured."""
-    url = f"{BACKEND_URL}{path}"
-    headers: dict[str, str] = {}
-    if PUBLISHABLE_KEY:
-        headers["x-publishable-api-key"] = PUBLISHABLE_KEY
-    try:
-        async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
-            resp = await client.get(url, headers=headers)
-    except httpx.HTTPError as e:
-        raise BlogError(f"transport error GET {url}: {e}") from e
-    if resp.status_code >= 400:
-        body = (resp.text or "").strip()[:600]
-        raise BlogError(f"upstream GET {path} -> HTTP {resp.status_code}: {body}")
-    try:
-        return resp.json() if resp.content else {}
-    except ValueError as e:
-        raise BlogError(f"upstream GET {path} non-JSON: {resp.text[:200]}") from e
-
-
-def _id_or_slug_body(slug_or_id: str, **rest: Any) -> dict:
-    """Decide whether the supplied identifier is a Medusa-style internal id
-    (anything starting with `bpost_`) or a slug, and place it on the right
-    field of the request body. Extra fields are merged in."""
-    body: dict[str, Any] = dict(rest)
-    if not slug_or_id:
-        raise BlogError("slug_or_id is required")
-    if slug_or_id.startswith("bpost_") or slug_or_id.startswith("post_"):
-        body["id"] = slug_or_id
-    else:
-        body["slug"] = slug_or_id
-    return body
-
-
-async def _revalidate(slugs: list[str]) -> dict:
-    """POST /admin/blog/revalidate. Always returns a dict (empty on no-op)."""
-    clean = [s for s in (slugs or []) if isinstance(s, str) and s]
-    if not clean:
-        return {"ok": True, "skipped": True, "reason": "no slugs"}
-    return await _admin_request(
-        "POST",
-        "/admin/blog/revalidate",
-        json_body={"slugs": clean},
-    )
-
-
-def _safe(coro_callable):
-    """Decorator that turns BlogError + arbitrary exceptions into a structured
-    `{ok: false, error, ...}` response so MCP tool calls never crash. The
-    wrapped coroutine must return a dict-like payload on success."""
-
-    async def wrapper(*args, **kwargs):
-        try:
-            result = await coro_callable(*args, **kwargs)
-            return result
-        except BlogError as e:
-            return {"ok": False, "error": str(e)}
-        except Exception as e:  # pragma: no cover - defensive
-            return {
-                "ok": False,
-                "error": f"{type(e).__name__}: {e}",
-            }
-
-    wrapper.__name__ = coro_callable.__name__
-    wrapper.__doc__ = coro_callable.__doc__
-    return wrapper
-
-
-def _resolve_slug(slug_or_id: str, post: dict | None) -> str | None:
-    """Pull a slug out of the upstream response (preferred) or fall back to
-    whichever identifier the caller passed in if it already looks like a
-    slug. Used to drive the post-mutation revalidate call."""
-    if isinstance(post, dict):
-        s = post.get("slug")
-        if isinstance(s, str) and s:
-            return s
-    if slug_or_id and not (
-        slug_or_id.startswith("bpost_") or slug_or_id.startswith("post_")
-    ):
-        return slug_or_id
-    return None
-
-
-# ---------------------------------------------------------------------------
-# Tools — read
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_list(status: str = "all", limit: int = 50) -> list[dict]:
-    """List Marva Home blog posts via the admin API.
-
-    Args:
-        status: "all" | "draft" | "published". Filtered client-side after
-            the admin list returns (the upstream returns everything).
-        limit: max rows to return after filtering (1-500).
-
-    Returns: list of post DTOs (newest first per the admin endpoint).
-    Each DTO has at least: id, slug, title, description, status,
-    thumbnail_url, author_name, tags, sections, created_at, updated_at,
-    published_at.
-    """
-    status_norm = (status or "all").lower().strip()
-    if status_norm not in {"all", "draft", "published"}:
-        raise BlogError(
-            f"status must be 'all', 'draft', or 'published'; got '{status}'"
-        )
-    limit = max(1, min(500, int(limit)))
-
-    payload = await _admin_request("GET", "/admin/blog/posts")
-    posts = payload.get("posts") if isinstance(payload, dict) else None
-    if not isinstance(posts, list):
-        return []
-
-    def _matches(p: dict) -> bool:
-        if status_norm == "all":
-            return True
-        s = (p.get("status") or "").lower()
-        if status_norm == "published":
-            return s == "published" or bool(p.get("published_at"))
-        # draft
-        return s == "draft" or (not s and not p.get("published_at"))
-
-    return [p for p in posts if isinstance(p, dict) and _matches(p)][:limit]
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_get(slug: str) -> dict:
-    """Fetch one blog post by slug. Uses the admin list and filters locally
-    so drafts are reachable too (the public /store endpoint only returns
-    published posts).
-
-    Args:
-        slug: the post's url slug, e.g. "hello-world".
-    """
-    if not slug:
-        raise BlogError("slug is required")
-    payload = await _admin_request("GET", "/admin/blog/posts")
-    posts = payload.get("posts") if isinstance(payload, dict) else None
-    if isinstance(posts, list):
-        for p in posts:
-            if isinstance(p, dict) and p.get("slug") == slug:
-                return p
-    # Fallback to the public endpoint in case the slug is published but
-    # somehow missing from the admin list response.
-    try:
-        store = await _store_request(f"/store/blog/posts/{slug}")
-        post = store.get("post") if isinstance(store, dict) else None
-        if isinstance(post, dict):
-            return post
-    except BlogError:
-        pass
-    raise BlogError(f"no post with slug '{slug}'")
-
-
-# ---------------------------------------------------------------------------
-# Tools — write
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_create_draft(
-    slug: str,
-    title: str,
-    description: str,
-    sections: list[dict],
-    tags: list[str] | None = None,
-    thumbnail_url: str | None = None,
-    author_name: str = "Marva Home",
-    author_role: str | None = None,
-) -> dict:
-    """Create a new blog post in draft status.
-
-    Args:
-        slug: kebab-case url slug, must be unique. Required.
-        title: human-readable title. Required.
-        description: short summary shown on listings. May be "" while still
-            a draft; must be non-empty before publish.
-        sections: list of {id, title, paragraphs, bullets?, code?} blocks.
-            `id` must be kebab-case, each section needs >=1 paragraph.
-            Run `marva_blog_validate_sections` first if unsure.
-        tags: list of free-form tag strings.
-        thumbnail_url: absolute https URL or site-relative "/uploads/..." path.
-        author_name: defaults to "Marva Home".
-        author_role: optional role line under the author name.
-
-    Returns: `{post: {...full DTO...}}` on success.
-    """
-    if not slug or not title:
-        raise BlogError("slug and title are required")
-
-    post_body: dict[str, Any] = {
-        "slug": slug,
-        "title": title,
-        "description": description or "",
-        "author_name": author_name or "Marva Home",
-        "tags": list(tags or []),
-        "sections": list(sections or []),
-    }
-    if thumbnail_url is not None:
-        post_body["thumbnail_url"] = thumbnail_url
-    if author_role is not None:
-        post_body["author_role"] = author_role
-
-    return await _admin_request(
-        "POST",
-        "/admin/blog/posts",
-        json_body={"action": "create", "post": post_body},
-    )
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_update(slug_or_id: str, patch: dict) -> dict:
-    """Update an existing blog post. Pass either the slug or the internal id.
-
-    Args:
-        slug_or_id: identifier of the post to update. IDs starting with
-            "bpost_" or "post_" are routed as id; everything else as slug.
-        patch: partial post object. Any of slug, title, description,
-            thumbnail_url, author_name, author_role, author_avatar_url,
-            tags, sections, metadata. Empty patch is rejected upstream.
-
-    Returns: `{post: {...full DTO...}}` on success.
-    """
-    if not isinstance(patch, dict) or not patch:
-        raise BlogError("patch must be a non-empty object")
-    body = _id_or_slug_body(slug_or_id, action="update", patch=patch)
-    return await _admin_request("POST", "/admin/blog/posts", json_body=body)
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_set_thumbnail(slug_or_id: str, thumbnail_url: str) -> dict:
-    """Convenience wrapper around `marva_blog_update` that sets just the
-    thumbnail. Accepts a full https URL or a site-relative "/uploads/..."
-    path (matches the backend zod validator).
-
-    Use this after generating an image with the Higgsfield MCP or uploading
-    one to S3 — pass the resulting URL in.
-    """
-    if not thumbnail_url:
-        raise BlogError("thumbnail_url is required")
-    if not (
-        thumbnail_url.startswith("/")
-        or re.match(r"^https?://", thumbnail_url, re.IGNORECASE)
-    ):
-        raise BlogError(
-            "thumbnail_url must start with http(s):// or be a site-relative "
-            "path starting with '/'"
-        )
-    body = _id_or_slug_body(
-        slug_or_id, action="update", patch={"thumbnail_url": thumbnail_url}
-    )
-    return await _admin_request("POST", "/admin/blog/posts", json_body=body)
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_publish(slug_or_id: str) -> dict:
-    """Publish a blog post and bust the storefront cache. The post must have
-    a non-empty description (enforced by the create/upsert workflow).
-
-    Returns: `{post: {...DTO...}, revalidate: {...}}`.
-    """
-    body = _id_or_slug_body(slug_or_id, action="publish")
-    result = await _admin_request("POST", "/admin/blog/posts", json_body=body)
-    post = result.get("post") if isinstance(result, dict) else None
-    slug = _resolve_slug(slug_or_id, post)
-    revalidate = await _revalidate([slug] if slug else [])
-    return {"post": post, "revalidate": revalidate}
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_unpublish(slug_or_id: str) -> dict:
-    """Unpublish a blog post (returns it to draft status) and revalidate the
-    storefront cache."""
-    body = _id_or_slug_body(slug_or_id, action="unpublish")
-    result = await _admin_request("POST", "/admin/blog/posts", json_body=body)
-    post = result.get("post") if isinstance(result, dict) else None
-    slug = _resolve_slug(slug_or_id, post)
-    revalidate = await _revalidate([slug] if slug else [])
-    return {"post": post, "revalidate": revalidate}
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_delete(slug_or_id: str) -> dict:
-    """Permanently delete a blog post and revalidate the storefront."""
-    # Capture the slug BEFORE deletion so we can still revalidate it after
-    # the row is gone (the response post field may be null for deletes).
-    slug_hint: str | None = None
-    if not (
-        slug_or_id.startswith("bpost_") or slug_or_id.startswith("post_")
-    ):
-        slug_hint = slug_or_id
-
-    body = _id_or_slug_body(slug_or_id, action="delete")
-    result = await _admin_request("POST", "/admin/blog/posts", json_body=body)
-    post = result.get("post") if isinstance(result, dict) else None
-    slug = _resolve_slug(slug_or_id, post) or slug_hint
-    revalidate = await _revalidate([slug] if slug else [])
-    return {"deleted": True, "post": post, "revalidate": revalidate}
-
-
-@mcp.tool()
-@_safe
-async def marva_blog_revalidate(slugs: list[str] | None = None) -> dict:
-    """Manually bust the storefront cache for one or more slugs. Pass an
-    empty list (or omit `slugs`) to no-op safely.
-
-    Returns the upstream `/admin/blog/revalidate` payload, typically
-    `{ok: true, status: 200, ...}`.
-    """
-    return await _revalidate(list(slugs or []))
-
-
-# ---------------------------------------------------------------------------
-# Tools — local-only utility
-# ---------------------------------------------------------------------------
-
-
-_SECTION_ID_RE = re.compile(r"^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$")
-
-
-@mcp.tool()
-async def marva_blog_validate_sections(sections: list[dict]) -> dict:
-    """Lint a sections array before posting it to the backend.
-
-    Rules:
-      * sections must be a non-empty list.
-      * each section needs `id`, `title`, and at least one paragraph.
-      * `id` must be kebab-case (a-z, 0-9, dashes).
-      * paragraph entries, bullet entries, and `code` must be strings if set.
-
-    Returns: `{ok: bool, issues: [str, ...], section_count: int}`.
-    Does not call the backend.
-    """
-    issues: list[str] = []
-    if not isinstance(sections, list) or not sections:
-        return {"ok": False, "issues": ["sections must be a non-empty list"], "section_count": 0}
-
-    seen_ids: set[str] = set()
-    for i, sec in enumerate(sections):
-        prefix = f"sections[{i}]"
-        if not isinstance(sec, dict):
-            issues.append(f"{prefix}: must be an object")
-            continue
-
-        sid = sec.get("id")
-        if not isinstance(sid, str) or not sid:
-            issues.append(f"{prefix}.id: required non-empty string")
-        elif not _SECTION_ID_RE.match(sid):
-            issues.append(
-                f"{prefix}.id: '{sid}' must be kebab-case (a-z, 0-9, dashes)"
-            )
-        elif sid in seen_ids:
-            issues.append(f"{prefix}.id: '{sid}' duplicates an earlier section")
-        else:
-            seen_ids.add(sid)
-
-        title = sec.get("title")
-        if not isinstance(title, str) or not title.strip():
-            issues.append(f"{prefix}.title: required non-empty string")
-
-        paragraphs = sec.get("paragraphs")
-        if not isinstance(paragraphs, list) or not paragraphs:
-            issues.append(f"{prefix}.paragraphs: at least one paragraph required")
-        else:
-            for j, para in enumerate(paragraphs):
-                if not isinstance(para, str):
-                    issues.append(f"{prefix}.paragraphs[{j}]: must be a string")
-                elif not para.strip():
-                    issues.append(f"{prefix}.paragraphs[{j}]: empty string")
-
-        bullets = sec.get("bullets")
-        if bullets is not None:
-            if not isinstance(bullets, list):
-                issues.append(f"{prefix}.bullets: must be a list if set")
-            else:
-                for j, b in enumerate(bullets):
-                    if not isinstance(b, str):
-                        issues.append(f"{prefix}.bullets[{j}]: must be a string")
-
-        code = sec.get("code")
-        if code is not None and not isinstance(code, str):
-            issues.append(f"{prefix}.code: must be a string if set")
-
-    return {
-        "ok": len(issues) == 0,
-        "issues": issues,
-        "section_count": len(sections),
-    }
-
-
-# ---------------------------------------------------------------------------
-# Content Plan — helpers + tools
-# ---------------------------------------------------------------------------
-
-_PLAN_TONES: set[str] = {"explainer", "how-to", "listicle", "product"}
-_PLAN_STATUSES: set[str] = {
-    "queued",
-    "drafting",
-    "draft_ready",
-    "published",
-    "skipped",
-}
-_PLAN_DIFFICULTY: set[str] = {"low", "med", "high"}
-_PLAN_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
-
-
-def _validate_iso_date(value: str, field: str = "planned_date") -> str:
-    """Ensure `value` is a YYYY-MM-DD calendar date the backend will accept."""
-    if not isinstance(value, str) or not _PLAN_DATE_RE.match(value):
-        raise BlogError(f"{field} must be ISO 'YYYY-MM-DD'; got {value!r}")
-    # Reject obvious month/day overflow (e.g. 2026-13-40).
-    try:
-        from datetime import date as _date
-
-        y, m, d = (int(p) for p in value.split("-"))
-        _date(y, m, d)
-    except ValueError as e:
-        raise BlogError(f"{field} is not a real date: {value} ({e})") from e
-    return value
-
-
-def _validate_tone(tone: str) -> str:
-    if tone not in _PLAN_TONES:
-        raise BlogError(
-            f"tone must be one of {sorted(_PLAN_TONES)}; got {tone!r}"
-        )
-    return tone
-
-
-def _validate_status(status: str) -> str:
-    if status not in _PLAN_STATUSES:
-        raise BlogError(
-            f"status must be one of {sorted(_PLAN_STATUSES)}; got {status!r}"
-        )
-    return status
-
-
-def _validate_difficulty(value: str) -> str:
-    if value not in _PLAN_DIFFICULTY:
-        raise BlogError(
-            f"difficulty must be one of {sorted(_PLAN_DIFFICULTY)}; got {value!r}"
-        )
-    return value
-
-
-@mcp.tool()
-@_safe
-async def marva_plan_list(
-    date_from: str | None = None,
-    date_to: str | None = None,
-    status: str | None = None,
-    tone: str | None = None,
-) -> list[dict]:
-    """List Content Plan articles in a date range, optionally filtered by status/tone.
-
-    Use to inspect the editorial calendar before drafting. All filters are optional;
-    omit them to fetch everything the backend returns.
-    """
-    params: list[str] = []
-    if date_from is not None:
-        params.append(f"from={_validate_iso_date(date_from, 'date_from')}")
-    if date_to is not None:
-        params.append(f"to={_validate_iso_date(date_to, 'date_to')}")
-    if status is not None:
-        params.append(f"status={_validate_status(status)}")
-    if tone is not None:
-        params.append(f"tone={_validate_tone(tone)}")
-
-    qs = ("?" + "&".join(params)) if params else ""
-    payload = await _admin_request("GET", f"/admin/content-plan/articles{qs}")
-    if isinstance(payload, dict):
-        articles = payload.get("articles")
-        if isinstance(articles, list):
-            return [a for a in articles if isinstance(a, dict)]
-    return []
-
-
-@mcp.tool()
-@_safe
-async def marva_plan_get(id: str) -> dict:
-    """Fetch one Content Plan article by id.
-
-    Use after `marva_plan_list` to inspect a specific slot before promoting/editing.
-    """
-    if not id:
-        raise BlogError("id is required")
-    payload = await _admin_request("GET", f"/admin/content-plan/articles?id={id}")
-    if isinstance(payload, dict):
-        articles = payload.get("articles")
-        if isinstance(articles, list):
-            for a in articles:
-                if isinstance(a, dict) and a.get("id") == id:
-                    return a
-    raise BlogError(f"no planned article with id '{id}'")
-
-
-@mcp.tool()
-@_safe
-async def marva_plan_create(
-    planned_date: str,
-    title: str,
-    tone: str,
-    brief: str | None = None,
-    volume: int | None = None,
-    difficulty: str | None = None,
-) -> dict:
-    """Create a new Content Plan slot for a future article.
-
-    Use when scheduling a new article on the editorial calendar before drafting.
-    `planned_date` is ISO `YYYY-MM-DD`; `tone` must match the plan vocabulary.
-    """
-    if not title:
-        raise BlogError("title is required")
-    article: dict[str, Any] = {
-        "planned_date": _validate_iso_date(planned_date),
-        "title": title,
-        "tone": _validate_tone(tone),
-    }
-    if brief is not None:
-        article["brief"] = brief
-    if volume is not None:
-        article["volume"] = int(volume)
-    if difficulty is not None:
-        article["difficulty"] = _validate_difficulty(difficulty)
-    return await _admin_request(
-        "POST",
-        "/admin/content-plan/articles",
-        json_body={"action": "create", "article": article},
-    )
-
-
-@mcp.tool()
-@_safe
-async def marva_plan_update(id: str, patch: dict) -> dict:
-    """Update a Content Plan slot with a partial patch (title/tone/brief/status/etc).
-
-    Use to retitle, reschedule, change tone, or move a slot through its status
-    lifecycle. Validates `tone`, `status`, `difficulty`, and `planned_date` shape.
-    """
-    if not id:
-        raise BlogError("id is required")
-    if not isinstance(patch, dict) or not patch:
-        raise BlogError("patch must be a non-empty object")
-
-    normalized: dict[str, Any] = {}
-    for key, value in patch.items():
-        if value is None:
-            normalized[key] = None
-            continue
-        if key == "tone":
-            normalized[key] = _validate_tone(value)
-        elif key == "status":
-            normalized[key] = _validate_status(value)
-        elif key == "difficulty":
-            normalized[key] = _validate_difficulty(value)
-        elif key == "planned_date":
-            normalized[key] = _validate_iso_date(value)
-        elif key == "volume":
-            normalized[key] = int(value)
-        else:
-            normalized[key] = value
-    return await _admin_request(
-        "POST",
-        "/admin/content-plan/articles",
-        json_body={"action": "update", "id": id, "patch": normalized},
-    )
-
-
-@mcp.tool()
-@_safe
-async def marva_plan_delete(id: str) -> dict:
-    """Delete a Content Plan slot (does NOT delete any promoted BlogPost draft).
-
-    Use to cancel a calendar entry that won't be written. To remove a published
-    article instead, use `marva_blog_delete` on the resulting post.
-    """
-    if not id:
-        raise BlogError("id is required")
-    return await _admin_request(
-        "POST",
-        "/admin/content-plan/articles",
-        json_body={"action": "delete", "id": id},
-    )
-
-
-@mcp.tool()
-@_safe
-async def marva_plan_promote(
-    id: str,
-    sections: list[dict] | None = None,
-    thumbnail_url: str | None = None,
-    publish: bool = False,
-) -> dict:
-    """Promote a plan slot to a real BlogPost draft (optionally publishing it).
-
-    Use at the end of drafting: the backend creates a BlogPost from the plan and
-    links it back. With `publish=True`, also publishes the resulting post and
-    revalidates the storefront cache.
-    """
-    if not id:
-        raise BlogError("id is required")
-    body: dict[str, Any] = {}
-    if sections is not None:
-        body["sections"] = list(sections)
-    if thumbnail_url is not None:
-        body["thumbnail_url"] = thumbnail_url
-    # Let the backend decide whether to publish itself if it supports the flag,
-    # but we still do the storefront-side publish + revalidate below for safety.
-    if publish:
-        body["publish"] = True
-
-    promote_result = await _admin_request(
-        "POST",
-        f"/admin/content-plan/articles/{id}/promote",
-        json_body=body or None,
-    )
-
-    post = (
-        promote_result.get("post") if isinstance(promote_result, dict) else None
-    )
-    plan = (
-        promote_result.get("plan") if isinstance(promote_result, dict) else None
-    )
-
-    publish_result: dict | None = None
-    revalidate_result: dict | None = None
-    if publish and isinstance(post, dict):
-        slug_or_id = post.get("slug") or post.get("id")
-        post_status = (post.get("status") or "").lower()
-        if post_status != "published" and slug_or_id:
-            pub_body = _id_or_slug_body(str(slug_or_id), action="publish")
-            publish_result = await _admin_request(
-                "POST", "/admin/blog/posts", json_body=pub_body
-            )
-            pub_post = (
-                publish_result.get("post")
-                if isinstance(publish_result, dict)
-                else None
-            )
-            if isinstance(pub_post, dict):
-                post = pub_post
-        slug = _resolve_slug(str(slug_or_id or ""), post)
-        revalidate_result = await _revalidate([slug] if slug else [])
-
-    return {
-        "plan": plan,
-        "post": post,
-        "publish": publish_result,
-        "revalidate": revalidate_result,
-    }
-
-
-if __name__ == "__main__":
-    mcp.run()