substack-api-mcp 1.0.2__py3-none-any.whl

substack_api_mcp/substack/tools/reply_to_comment.py

@@ -0,0 +1,63 @@
+"""Reply to comment."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "comment_id": {"type": "string", "description": "Comment ID from list_comments."},
+        "body": {"type": "string", "description": "Reply text."},
+    },
+    "required": ["comment_id", "body"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "comment_id": "363485182",
+    "parent_id": "363478059",
+    "created_at": "2026-10-11T10:07:00Z",
+}
+
+
+@tool(
+    name="reply_to_comment",
+    title="Reply to comment",
+    access="write",
+    confirm=True,
+    description="Reply as you under a comment on your post.",
+    details=(
+        "Posts a reply under one comment on a post of your publication, under your name, visible to everyone "
+        "who can read the post. A comment elsewhere on Substack returns an error. The author gets Substack's "
+        "usual reply notification. By default you confirm each call; you can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /comments/{comment_id}/replies",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def reply_to_comment(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    comment_id = str(args["comment_id"]).strip().removeprefix("c-")
+    if not comment_id.isdigit():
+        raise ToolError("comment_id must be the ID from list_comments.", ErrorCode.INVALID_INPUT)
+    text = args["body"].strip()
+    if not text:
+        raise ToolError("body must not be empty.", ErrorCode.INVALID_INPUT)
+    pub = await publication(ctx)
+    found = await call(ctx, "GET", f"{pub['base']}/api/v1/reader/comment/{comment_id}")
+    parent = (found.get("item") or {}).get("comment") or {}
+    if not parent.get("post_id"):
+        raise ToolError("Substack has no comment with this ID.", ErrorCode.TARGET_ERROR)
+    if parent.get("publication_id") != pub["id"]:
+        raise ToolError("This comment is not on a post of your publication.", ErrorCode.APP_PERMISSION_DENIED)
+    body = {"body": text, "parent_id": int(comment_id)}
+    reply = await call(ctx, "POST", f"{pub['base']}/api/v1/post/{parent['post_id']}/comment", body=body)
+    return {"comment_id": str(reply["id"]), "parent_id": comment_id, "created_at": reply.get("date")}

substack_api_mcp/substack/tools/reply_to_note.py

@@ -0,0 +1,56 @@
+"""Reply to Note."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call, comment_id
+from substack_api_mcp.substack.markdown import to_note_doc
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "note_id": {"type": "string", "description": "Note ID from list_notes, list_note_replies or search_substack."},
+        "body": {"type": "string", "description": "Reply text, up to 1,000 characters."},
+    },
+    "required": ["note_id", "body"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "note_id": "364150283",
+    "parent_id": "364150154",
+    "published_at": "2026-10-18T15:55:08.644Z",
+}
+
+
+@tool(
+    name="reply_to_note",
+    title="Reply to Note",
+    access="write",
+    confirm=True,
+    description="Reply as you under any Note or Note reply.",
+    details=(
+        "Posts a reply under a Note (yours or anyone's) or under a reply to one, visible to everyone who "
+        "sees the Note. Text is 1 to 1,000 characters; Markdown bold, italics and links work. The author gets "
+        "Substack's usual notification. By default you confirm each call; you can switch that off for this "
+        "tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /notes/{note_id}/replies",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def reply_to_note(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    parent = comment_id(args["note_id"], "list_notes")
+    text = str(args["body"]).strip()
+    if not text or len(text) > 1000:
+        raise ToolError("body must be 1 to 1,000 characters.", ErrorCode.INVALID_INPUT)
+    body = {"bodyJson": to_note_doc(text), "parent_id": parent, "replyMinimumRole": "everyone"}
+    reply = await call(ctx, "POST", f"{WEB}/api/v1/comment/feed", body=body)
+    return {"note_id": str(reply["id"]), "parent_id": str(parent), "published_at": reply.get("date")}

substack_api_mcp/substack/tools/schedule_post.py

@@ -0,0 +1,78 @@
+"""Schedule post."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, draft, post_id, publication, require_draft
+from substack_api_mcp.substack.publishing import check_ready, future_time, set_options
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "post_id": {"type": "string", "description": "Post ID from list_posts."},
+        "publish_at": {"type": "string", "format": "date-time", "description": "ISO 8601 with time zone."},
+        "send_email": {"type": "boolean", "description": "Email it to subscribers. Default: true."},
+        "section_id": {
+            "type": "string",
+            "description": "Section ID from list_sections, or main. Default: the draft's section, else main.",
+        },
+    },
+    "required": ["post_id", "publish_at"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "post_id": "148420031",
+    "status": "scheduled",
+    "publish_at": "2026-10-13T08:00:00-04:00",
+    "audience": "everyone",
+    "url": "https://yourname.substack.com/p/notes-on-pricing",
+}
+
+
+@tool(
+    name="schedule_post",
+    title="Schedule post",
+    access="write",
+    confirm=True,
+    description="Publish a draft at a set time, on the web and by email.",
+    details=(
+        "Schedules a draft to go live at the time you set, on the web and, unless send_email is false, by email, "
+        "to the audience set on the draft. The time needs a time zone and must be in the future. Substack's own "
+        "pre-publish check runs first; a missing title or an empty body stops the call. A scheduled post stays "
+        "editable until it goes out. On a publication with sections the post goes to section_id, else to the "
+        "section already set on the draft, else to the main publication. By default you confirm each call; you "
+        "can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PUT /posts/{post_id}/schedule",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def schedule_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    when = future_time(args["publish_at"])
+    post = await draft(ctx, pub, pid)
+    require_draft(post)
+    send_email = args.get("send_email", True)
+    await set_options(ctx, pub, post, send_email, args.get("section_id"))
+    trigger_at = when.strftime("%Y-%m-%dT%H:%M:%S.000Z")
+    await check_ready(ctx, pub, pid, trigger_at)
+    audience = post.get("audience") or "everyone"
+    release = {"trigger_at": trigger_at, "post_audience": audience, "email_audience": audience}
+    await call(ctx, "POST", f"{pub['base']}/api/v1/drafts/{pid}/scheduled_release", body=release)
+    scheduled = await draft(ctx, pub, pid)
+    slug = scheduled.get("slug")
+    return {
+        "post_id": str(pid),
+        "status": "scheduled",
+        "publish_at": args["publish_at"],
+        "audience": audience,
+        "url": f"{pub['base']}/p/{slug}" if slug else None,
+    }

substack_api_mcp/substack/tools/search_substack.py

@@ -0,0 +1,84 @@
+"""Search Substack."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call, person
+from substack_api_mcp.substack.feed import note_item, post_item
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "query": {"type": "string", "description": "Words to search for."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous page."},
+    },
+    "required": ["query"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "people": [{"user_id": "528339521", "name": "Routine Morning", "handle": "routinemorning", "bio": "Small habits."}],
+    "posts": [
+        {
+            "post_id": "197396217",
+            "title": "A Guide to Your Morning Routine",
+            "publication": "Brain Health Decoded",
+            "publication_id": "5262902",
+            "published_at": "2026-05-12T19:25:47.700Z",
+            "likes": 410,
+            "url": "https://example.substack.com/p/a-guide-to-your-morning-routine",
+        }
+    ],
+    "notes": [
+        {
+            "note_id": "322981144",
+            "author": {"user_id": "18270011", "name": "Laura Mills", "handle": "lauramills"},
+            "body": "Morning light beats any supplement.",
+            "published_at": "2026-09-02T07:11:00.000Z",
+            "likes": 88,
+        }
+    ],
+    "next_cursor": "eyJvZmZzZXQiOjIwfQ==",
+}
+
+
+@tool(
+    name="search_substack",
+    title="Search Substack",
+    access="read",
+    confirm=False,
+    description="Search all of Substack for people, posts and Notes.",
+    details=(
+        "Runs Substack's search as the search box does and splits the results into people, posts and Notes. "
+        "Use the IDs with follow_user, like_post, like_comment, reply_to_note, send_message or "
+        "recommend_publication. Page with next_cursor; later pages may hold only posts and Notes."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /search",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def search_substack(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    query = str(args["query"]).strip()
+    if not query:
+        raise ToolError("query must not be empty.", ErrorCode.INVALID_INPUT)
+    params = {"query": query, **({"cursor": args["cursor"]} if args.get("cursor") else {})}
+    answer = await call(ctx, "GET", f"{WEB}/api/v1/top/search", params=params)
+    people: list[dict[str, Any]] = []
+    posts: list[dict[str, Any]] = []
+    notes: list[dict[str, Any]] = []
+    for item in answer.get("items") or []:
+        kind = item.get("type")
+        if kind == "profileSearchResults":
+            people += [{**person(row), "bio": row.get("bio") or ""} for row in item.get("results") or []]
+        elif kind == "post" and item.get("post"):
+            posts.append(post_item(item))
+        elif kind == "comment" and item.get("comment"):
+            notes.append(note_item(item))
+    return {"people": people, "posts": posts, "notes": notes, "next_cursor": answer.get("nextCursor")}

substack_api_mcp/substack/tools/send_message.py

@@ -0,0 +1,65 @@
+"""Send message."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import WEB, call, user_ref
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "conversation_id": {"type": "string", "description": "Reply in this conversation from list_conversations."},
+        "user": {"type": "string", "description": "Or start one with this handle (e.g. @mayachen) or user ID."},
+        "body": {"type": "string", "description": "Message text."},
+    },
+    "required": ["body"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "conversation_id": "112992a4-5356-4bd2-8a16-f940cabbb4df",
+    "sent_at": "2026-10-18T15:55:35.587Z",
+}
+
+
+@tool(
+    name="send_message",
+    title="Send message",
+    access="write",
+    confirm=True,
+    description="Send a direct message on Substack, in a conversation or to a person.",
+    details=(
+        "Sends a private chat message under your name. With conversation_id it replies there; with user it "
+        "writes to that person, in your existing conversation with them or a new one. Someone who does not "
+        "follow you gets it as a message request. Give one of conversation_id or user. A sent message cannot "
+        "be recalled. By default you confirm each call; you can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /messages",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def send_message(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    text = str(args["body"]).strip()
+    if not text:
+        raise ToolError("body must not be empty.", ErrorCode.INVALID_INPUT)
+    if bool(args.get("conversation_id")) == bool(args.get("user")):
+        raise ToolError("Give one of conversation_id or user.", ErrorCode.INVALID_INPUT)
+    if args.get("conversation_id"):
+        thread_id = str(args["conversation_id"]).strip().removeprefix("direct-message-")
+        if "/" in thread_id:
+            raise ToolError("conversation_id must be the ID from list_conversations.", ErrorCode.INVALID_INPUT)
+        answer = await call(ctx, "POST", f"{WEB}/api/v1/messages/dm/{thread_id}", body={"body": text})
+    else:
+        user = await user_ref(ctx, args["user"])
+        answer = await call(ctx, "POST", f"{WEB}/api/v1/messages/dm", body={"user_id": user["id"], "body": text})
+    thread = answer.get("thread") or {}
+    reply = answer.get("reply") or {}
+    sent = (reply.get("comment") or reply).get("created_at")
+    return {"conversation_id": thread.get("id"), "sent_at": sent or thread.get("updated_at")}

substack_api_mcp/substack/tools/tag_post.py

@@ -0,0 +1,55 @@
+"""Tag post."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, post_id, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "post_id": {"type": "string", "description": "Post ID from list_posts."},
+        "tag_id": {"type": "string", "description": "Tag ID from list_post_tags or create_post_tag."},
+        "remove": {"type": "boolean", "description": "Take the tag off instead. Default: false."},
+    },
+    "required": ["post_id", "tag_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "post_id": "148213977",
+    "tag_id": "80ba205f-6de0-4024-860d-0df42720d32a",
+    "tagged": True,
+}
+
+
+@tool(
+    name="tag_post",
+    title="Tag post",
+    access="write",
+    confirm=False,
+    description="Add a tag to a post, or take it off.",
+    details=(
+        "Puts one of your post tags on a draft or published post, or removes it with remove. A post can have "
+        "several tags. Tagging twice keeps one tag."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PUT /posts/{post_id}/tags/{tag_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def tag_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    tag_id = str(args["tag_id"]).strip()
+    if not tag_id or "/" in tag_id:
+        raise ToolError("tag_id must be the ID from list_post_tags.", ErrorCode.INVALID_INPUT)
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    remove = bool(args.get("remove"))
+    await call(ctx, "DELETE" if remove else "POST", f"{pub['base']}/api/v1/post/{pid}/tag/{tag_id}")
+    return {"post_id": str(pid), "tag_id": tag_id, "tagged": not remove}

substack_api_mcp/substack/tools/tag_subscribers.py

@@ -0,0 +1,75 @@
+"""Tag subscribers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, publication
+from substack_api_mcp.substack.subscribers import find_subscriber
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "tag_id": {"type": "string", "description": "Tag ID from list_subscriber_tags or create_subscriber_tag."},
+        "emails": {
+            "type": "array",
+            "items": {"type": "string"},
+            "minItems": 1,
+            "maxItems": 50,
+            "description": "Subscribers' email addresses, up to 50.",
+        },
+        "remove": {"type": "boolean", "description": "Take the tag off instead. Default: false."},
+    },
+    "required": ["tag_id", "emails"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "tag_id": "9357",
+    "tagged": True,
+    "updated": ["reader@example.com"],
+    "not_found": ["someone@example.com"],
+}
+
+
+@tool(
+    name="tag_subscribers",
+    title="Tag subscribers",
+    access="write",
+    confirm=False,
+    description="Put a tag on subscribers by email, or take it off.",
+    details=(
+        "Adds one of your subscriber tags to up to 50 subscribers, or removes it with remove. Emails not on "
+        "your list come back in not_found and nothing else fails. A subscriber added a minute ago may not be "
+        "findable yet; try again shortly."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /subscriber-tags/{tag_id}/subscribers",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def tag_subscribers(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    tag_id = str(args["tag_id"]).strip()
+    if not tag_id.isdigit():
+        raise ToolError("tag_id must be the ID from list_subscriber_tags.", ErrorCode.INVALID_INPUT)
+    pub = await publication(ctx)
+    updated, missing, ids = [], [], []
+    for email in dict.fromkeys(str(email).strip() for email in args["emails"]):
+        row = await find_subscriber(ctx, pub, email) if email else None
+        if row and row.get("subscription_id"):
+            ids.append(row["subscription_id"])
+            updated.append(row["user_email_address"])
+        else:
+            missing.append(email)
+    remove = bool(args.get("remove"))
+    if ids:
+        action = "unassign" if remove else "assign"
+        await call(
+            ctx, "POST", f"{pub['base']}/api/v1/subscriber-tags/{tag_id}/{action}", body={"subscriptionIds": ids}
+        )
+    return {"tag_id": tag_id, "tagged": not remove, "updated": updated, "not_found": missing}

substack_api_mcp/substack/tools/unpublish_post.py

@@ -0,0 +1,50 @@
+"""Unpublish post."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import call, draft, post_id, publication
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "post_id": {"type": "string", "description": "Post ID from list_posts."},
+    },
+    "required": ["post_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"post_id": "148213977", "status": "draft"}
+
+
+@tool(
+    name="unpublish_post",
+    title="Unpublish post",
+    access="write",
+    confirm=True,
+    description="Take a published post off the web and back to drafts.",
+    details=(
+        "Turns a published post back into a draft, as Unpublish in the editor does: it leaves your site, "
+        "archive and the Substack app, and its link stops working. Comments and stats stay with the draft. "
+        "Emails already sent stay in inboxes. Publish it again with publish_post. A post that is not published "
+        "returns an error. By default you confirm each call; you can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="DELETE /posts/{post_id}/publish",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def unpublish_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    post = await draft(ctx, pub, pid)
+    if not post.get("is_published"):
+        raise ToolError("This post is not published.", ErrorCode.INVALID_INPUT)
+    await call(ctx, "POST", f"{pub['base']}/api/v1/drafts/{pid}/unpublish", body={})
+    return {"post_id": str(pid), "status": "draft"}

substack_api_mcp/substack/tools/update_draft.py

@@ -0,0 +1,93 @@
+"""Update draft."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import byline, call, draft, post_id, publication, require_draft
+from substack_api_mcp.substack.markdown import to_doc
+
+_FIELDS = ("title", "subtitle", "body_markdown", "audience")
+_AUDIENCES = ("everyone", "only_paid", "founding")
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "post_id": {"type": "string", "description": "Post ID from list_posts."},
+        "fields": {
+            "type": "string",
+            "description": (
+                'JSON object with any of title, subtitle, body_markdown, audience, e.g. {"title": "New title"}.'
+            ),
+        },
+    },
+    "required": ["post_id", "fields"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"post_id": "148420031", "status": "draft", "updated": ["title", "body_markdown"]}
+
+
+@tool(
+    name="update_draft",
+    title="Update draft",
+    access="write",
+    confirm=False,
+    description="Change the title, subtitle, body or audience of a draft.",
+    details=(
+        "Changes the fields you pass and leaves the others as they are. body_markdown replaces the whole "
+        "body. Drafts and scheduled posts only: a published post returns an error. Nothing reaches your "
+        "subscribers, so it runs without asking."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PATCH /drafts/{post_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def update_draft(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    fields = _fields(args["fields"])
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    post = await draft(ctx, pub, pid)
+    require_draft(post)
+    body = {
+        "draft_title": fields.get("title", post.get("draft_title") or ""),
+        "draft_subtitle": fields.get("subtitle", post.get("draft_subtitle") or ""),
+        "draft_body": json.dumps(to_doc(fields["body_markdown"]))
+        if "body_markdown" in fields
+        else post.get("draft_body"),
+        "draft_bylines": byline(pub),
+        "audience": fields.get("audience", post.get("audience") or "everyone"),
+        "last_updated_at": post.get("draft_updated_at"),
+    }
+    await call(ctx, "PUT", f"{pub['base']}/api/v1/drafts/{pid}", body=body)
+    return {"post_id": str(pid), "status": "draft", "updated": [name for name in _FIELDS if name in fields]}
+
+
+def _fields(value: Any) -> dict[str, Any]:
+    """`fields` is a JSON object with any of title, subtitle, body_markdown, audience."""
+    parsed = value if isinstance(value, dict) else None
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except ValueError:
+            parsed = None
+    if not isinstance(parsed, dict) or not parsed:
+        raise ToolError(
+            'fields must be a JSON object, e.g. {"title": "...", "body_markdown": "..."}.', ErrorCode.INVALID_INPUT
+        )
+    if unknown := sorted(set(parsed) - set(_FIELDS)):
+        raise ToolError(
+            f"Unknown fields: {', '.join(unknown)}. Allowed: {', '.join(_FIELDS)}.", ErrorCode.INVALID_INPUT
+        )
+    if "audience" in parsed and parsed["audience"] not in _AUDIENCES:
+        raise ToolError(f"audience must be one of {', '.join(_AUDIENCES)}.", ErrorCode.INVALID_INPUT)
+    if any(not isinstance(text, str) for text in parsed.values()):
+        raise ToolError("Every field value must be text.", ErrorCode.INVALID_INPUT)
+    return parsed