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

substack_api_mcp/substack/markdown.py

@@ -0,0 +1,239 @@
+"""Markdown to and from the ProseMirror documents Substack's editor stores (`draft_body`, `body`, Note `bodyJson`).
+
+Covers what agents write: headings, paragraphs, bullet and numbered lists, quotes, code blocks, rules,
+images by URL, and inline bold, italic, strike, code and links. Node and mark names are the editor's,
+as recorded from drafts typed in it (17.10.2026). Anything else Substack stores (buttons, embeds,
+footnotes) comes back as its plain text.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_INLINE = re.compile(
+    r"(?P<code>`[^`]+`)"
+    r"|(?P<image>!\[(?P<alt>[^\]]*)\]\((?P<src>[^)\s]+)\))"
+    r"|(?P<link>\[(?P<label>[^\]]+)\]\((?P<href>[^)\s]+)\))"
+    r"|(?P<strong>\*\*(?P<strong_text>.+?)\*\*|__(?P<strong_alt>.+?)__)"
+    r"|(?P<strike>~~(?P<strike_text>.+?)~~)"
+    r"|(?P<em>\*(?P<em_text>[^*\s][^*]*?)\*|_(?P<em_alt>[^_\s][^_]*?)_)"
+)
+_HEADING = re.compile(r"^(#{1,6})\s+(.*)$")
+_BULLET = re.compile(r"^\s*[-*+]\s+(.*)$")
+_NUMBERED = re.compile(r"^\s*\d+[.)]\s+(.*)$")
+_IMAGE_LINE = re.compile(r"^!\[([^\]]*)\]\(([^)\s]+)\)$")
+_RULE = re.compile(r"^\s*([-*_])(\s*\1){2,}\s*$")
+
+
+def _text(text: str, marks: list[dict[str, Any]]) -> dict[str, Any]:
+    node: dict[str, Any] = {"type": "text", "text": text}
+    if marks:
+        node["marks"] = marks
+    return node
+
+
+def inline(text: str, marks: list[dict[str, Any]] | None = None) -> list[dict[str, Any]]:
+    """Inline Markdown to text nodes with marks."""
+    marks = marks or []
+    nodes: list[dict[str, Any]] = []
+    position = 0
+    for match in _INLINE.finditer(text):
+        if match.start() > position:
+            nodes.append(_text(text[position : match.start()], marks))
+        if match["code"]:
+            nodes.append(_text(match["code"][1:-1], [*marks, {"type": "code"}]))
+        elif match["image"]:
+            nodes.extend(
+                inline(match["alt"] or match["src"], [*marks, {"type": "link", "attrs": {"href": match["src"]}}])
+            )
+        elif match["link"]:
+            nodes.extend(inline(match["label"], [*marks, {"type": "link", "attrs": {"href": match["href"]}}]))
+        elif match["strong"]:
+            nodes.extend(inline(match["strong_text"] or match["strong_alt"], [*marks, {"type": "strong"}]))
+        elif match["strike"]:
+            nodes.extend(inline(match["strike_text"], [*marks, {"type": "strikethrough"}]))
+        else:
+            nodes.extend(inline(match["em_text"] or match["em_alt"], [*marks, {"type": "em"}]))
+        position = match.end()
+    if position < len(text):
+        nodes.append(_text(text[position:], marks))
+    return [node for node in nodes if node.get("text")]
+
+
+def _paragraph(text: str) -> dict[str, Any]:
+    content = inline(text)
+    return {"type": "paragraph", "content": content} if content else {"type": "paragraph"}
+
+
+def _image(alt: str, src: str) -> dict[str, Any]:
+    return {"type": "captionedImage", "content": [{"type": "image2", "attrs": {"src": src, "alt": alt or None}}]}
+
+
+def _list(kind: str, items: list[str]) -> dict[str, Any]:
+    node: dict[str, Any] = {
+        "type": kind,
+        "content": [{"type": "listItem", "content": [_paragraph(item)]} for item in items],
+    }
+    if kind == "orderedList":
+        node["attrs"] = {"start": 1, "order": 1}
+    return node
+
+
+def to_doc(markdown: str) -> dict[str, Any]:
+    """A Markdown text as a ProseMirror document."""
+    lines = markdown.replace("\r\n", "\n").split("\n")
+    blocks: list[dict[str, Any]] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        stripped = line.strip()
+        if not stripped:
+            index += 1
+            continue
+        if stripped.startswith("```"):
+            code: list[str] = []
+            index += 1
+            while index < len(lines) and not lines[index].strip().startswith("```"):
+                code.append(lines[index])
+                index += 1
+            index += 1
+            text = "\n".join(code)
+            blocks.append({"type": "code_block", "content": [_text(text, [])]} if text else {"type": "code_block"})
+            continue
+        if _RULE.match(stripped):
+            blocks.append({"type": "horizontal_rule"})
+            index += 1
+            continue
+        if heading := _HEADING.match(stripped):
+            content = inline(heading[2].strip())
+            blocks.append({"type": "heading", "attrs": {"level": len(heading[1])}, "content": content})
+            index += 1
+            continue
+        if image := _IMAGE_LINE.match(stripped):
+            blocks.append(_image(image[1], image[2]))
+            index += 1
+            continue
+        for pattern, kind in ((_BULLET, "bulletList"), (_NUMBERED, "orderedList")):
+            if pattern.match(line):
+                items = []
+                while index < len(lines) and (item := pattern.match(lines[index])):
+                    items.append(item[1].strip())
+                    index += 1
+                blocks.append(_list(kind, items))
+                break
+        else:
+            if stripped.startswith(">"):
+                quoted = []
+                while index < len(lines) and lines[index].strip().startswith(">"):
+                    quoted.append(lines[index].strip()[1:].lstrip())
+                    index += 1
+                inner = to_doc("\n".join(quoted))["content"]
+                blocks.append({"type": "blockquote", "content": inner or [{"type": "paragraph"}]})
+                continue
+            paragraph = [stripped]
+            index += 1
+            while index < len(lines) and lines[index].strip() and not _starts_block(lines[index]):
+                paragraph.append(lines[index].strip())
+                index += 1
+            blocks.append(_paragraph(" ".join(paragraph)))
+    return {"type": "doc", "content": blocks or [{"type": "paragraph"}]}
+
+
+def _starts_block(line: str) -> bool:
+    stripped = line.strip()
+    return bool(
+        stripped.startswith(("```", ">", "#"))
+        or _BULLET.match(line)
+        or _NUMBERED.match(line)
+        or _IMAGE_LINE.match(stripped)
+        or _RULE.match(stripped)
+    )
+
+
+def _marked(node: dict[str, Any]) -> str:
+    text = node.get("text") or ""
+    for mark in node.get("marks") or []:
+        match mark.get("type"):
+            case "strong":
+                text = f"**{text}**"
+            case "em":
+                text = f"*{text}*"
+            case "strikethrough":
+                text = f"~~{text}~~"
+            case "code":
+                text = f"`{text}`"
+            case "link":
+                text = f"[{text}]({(mark.get('attrs') or {}).get('href', '')})"
+    return text
+
+
+def _inline_md(nodes: list[dict[str, Any]]) -> str:
+    parts = []
+    for node in nodes or []:
+        if node.get("type") == "text":
+            parts.append(_marked(node))
+        elif node.get("type") == "hard_break":
+            parts.append("\n")
+        else:
+            parts.append(_inline_md(node.get("content") or []))
+    return "".join(parts)
+
+
+def _block_md(node: dict[str, Any]) -> str:
+    content = node.get("content") or []
+    match node.get("type"):
+        case "paragraph":
+            return _inline_md(content)
+        case "heading":
+            return "#" * int((node.get("attrs") or {}).get("level") or 1) + " " + _inline_md(content)
+        case "bulletList" | "bullet_list":
+            return "\n".join(f"- {_block_md({'type': 'doc', 'content': item.get('content')})}" for item in content)
+        case "orderedList" | "ordered_list":
+            return "\n".join(
+                f"{n}. {_block_md({'type': 'doc', 'content': item.get('content')})}"
+                for n, item in enumerate(content, 1)
+            )
+        case "blockquote" | "pullquote":
+            return "\n".join(f"> {line}" for line in _block_md({"type": "doc", "content": content}).split("\n"))
+        case "code_block":
+            return "```\n" + _inline_md(content) + "\n```"
+        case "horizontal_rule":
+            return "---"
+        case "captionedImage" | "image2" | "image":
+            image = (
+                node
+                if node.get("type") != "captionedImage"
+                else next((child for child in content if child.get("type") in ("image2", "image")), {})
+            )
+            attrs = image.get("attrs") or {}
+            return f"![{attrs.get('alt') or ''}]({attrs.get('src') or ''})" if attrs.get("src") else ""
+        case _:
+            blocks = [_block_md(child) for child in content if child.get("type") != "text"]
+            return "\n\n".join(block for block in blocks if block) or _inline_md(content)
+
+
+def to_markdown(doc: dict[str, Any]) -> str:
+    """A ProseMirror document as Markdown."""
+    blocks = [_block_md(node) for node in doc.get("content") or []]
+    return "\n\n".join(block for block in blocks if block).strip()
+
+
+# Notes have their own editor schema (recorded 17.10.2026): paragraphs only, marks `bold`, `italic` and `link`.
+_NOTE_MARKS = {"strong": "bold", "em": "italic", "link": "link"}
+
+
+def to_note_doc(markdown: str) -> dict[str, Any]:
+    """A Note's text as its ProseMirror document: one paragraph per block, unsupported marks dropped."""
+    paragraphs = []
+    for block in re.split(r"\n\s*\n", markdown.replace("\r\n", "\n").strip()):
+        nodes = []
+        for node in inline(" ".join(line.strip() for line in block.split("\n"))):
+            marks = [
+                {**mark, "type": _NOTE_MARKS[mark["type"]]}
+                for mark in node.get("marks") or []
+                if mark["type"] in _NOTE_MARKS
+            ]
+            nodes.append(_text(node["text"], marks))
+        paragraphs.append({"type": "paragraph", "content": nodes} if nodes else {"type": "paragraph"})
+    return {"type": "doc", "attrs": {"schemaVersion": "v1", "title": None}, "content": paragraphs}

substack_api_mcp/substack/publishing.py

@@ -0,0 +1,70 @@
+"""Steps the editor's Publish dialog takes before a post goes out, shared by publish_post and schedule_post."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.substack.client import byline, call
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+
+def future_time(value: str) -> datetime:
+    """An ISO 8601 time with a zone, later than now."""
+    try:
+        when = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ToolError("Time must be ISO 8601, e.g. 2026-10-20T08:00:00-04:00.", ErrorCode.INVALID_INPUT) from exc
+    if when.tzinfo is None:
+        raise ToolError("Time must include a time zone, e.g. -04:00 or Z.", ErrorCode.INVALID_INPUT)
+    if when <= datetime.now(UTC):
+        raise ToolError("Time must be in the future.", ErrorCode.INVALID_INPUT)
+    return when.astimezone(UTC)
+
+
+async def set_options(
+    ctx: ToolContext, pub: dict[str, Any], post: dict[str, Any], send_email: bool, section_id: Any = None
+) -> None:
+    """The dialog's "Send via email" box and section choice, saved on the draft before it goes out.
+
+    A publication with sections refuses to publish until the draft names one ("Please choose a section");
+    the editor saves section_chosen with draft_section_id, null for the main publication.
+    """
+    section = _section(section_id)
+    email_same = bool(post.get("should_send_email", True)) == send_email
+    section_same = bool(post.get("section_chosen")) and (section_id is None or post.get("draft_section_id") == section)
+    if email_same and section_same:
+        return
+    body = {
+        "draft_title": post.get("draft_title") or "",
+        "draft_subtitle": post.get("draft_subtitle") or "",
+        "draft_body": post.get("draft_body"),
+        "draft_bylines": byline(pub),
+        "audience": post.get("audience") or "everyone",
+        "should_send_email": send_email,
+        "section_chosen": True,
+        "draft_section_id": section if section_id is not None else post.get("draft_section_id"),
+        "last_updated_at": post.get("draft_updated_at"),
+    }
+    await call(ctx, "PUT", f"{pub['base']}/api/v1/drafts/{post['id']}", body=body)
+
+
+def _section(value: Any) -> int | None:
+    if value is None or str(value).strip() in ("", "main"):
+        return None
+    text = str(value).strip()
+    if not text.isdigit():
+        raise ToolError("section_id must be the ID from list_sections, or main.", ErrorCode.INVALID_INPUT)
+    return int(text)
+
+
+async def check_ready(ctx: ToolContext, pub: dict[str, Any], pid: int, publish_date: str | None) -> None:
+    """Substack's own pre-publish check; its errors (no title, empty body) stop the call, suggestions do not."""
+    params = {"publish_date": publish_date} if publish_date else None
+    answer = await call(ctx, "GET", f"{pub['base']}/api/v1/drafts/{pid}/prepublish", params=params)
+    if errors := answer.get("errors") or []:
+        names = ", ".join(str(error.get("identifier") or error.get("msg") or error) for error in errors)
+        raise ToolError(f"Substack will not publish this draft yet: {names}.", ErrorCode.INVALID_INPUT)

substack_api_mcp/substack/subscribers.py

@@ -0,0 +1,94 @@
+"""The dashboard's subscriber table (Audience > Subscribers) and its CSV export.
+
+The table is `POST /api/v1/subscriber-stats` with the dashboard's filters. Substack fills it from its own
+index in the background, so a subscriber added a minute ago may not be listed yet.
+The export builds a subscriber set from the same order, asks for a CSV of it and polls until Substack
+hands out the file, as the dashboard's Export button does (`exportSubscriberSet` in its bundle, 17.10.2026).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qs, urlsplit
+
+from substack_api_mcp.core.errors import ErrorCode, ToolError
+from substack_api_mcp.substack.client import call
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+_ORDER = {"order_by_desc_nulls_last": "subscription_created_at"}
+_COLUMNS = ["user_email_address", "user_name", "subscription_type", "activity_rating", "subscription_created_at"]
+# Seconds between polls for the export file, as the dashboard waits: 1, 5, 10, then 30.
+_POLL_S = (1, 4, 5, 10, 10, 15)
+
+
+def plan_of(row: dict[str, Any]) -> str:
+    """free, paid, comp or founding, as the subscriber table labels the row."""
+    if row.get("is_comp"):
+        return "comp"
+    if row.get("is_founding"):
+        return "founding"
+    kind = str(row.get("subscription_type") or "").lower()
+    return "free" if not kind or "free" in kind else "paid"
+
+
+async def subscriber_page(
+    ctx: ToolContext, pub: dict[str, Any], offset: int, size: int, since: str | None
+) -> list[dict[str, Any]]:
+    """One page of the table, newest first; `since` stops at subscribers who joined before that date."""
+    body = {"filters": _ORDER, "limit": size, "offset": offset, "includeTags": False}
+    answer = await call(ctx, "POST", f"{pub['base']}/api/v1/subscriber-stats", body=body)
+    rows = answer.get("subscribers") or []
+    if since:
+        rows = [row for row in rows if (row.get("subscription_created_at") or "")[:10] >= since[:10]]
+    return rows
+
+
+async def export(ctx: ToolContext, pub: dict[str, Any]) -> dict[str, Any]:
+    base = f"{pub['base']}/api/v1"
+    subscriber_set = await call(ctx, "POST", f"{base}/subscriber_set", body={"query": _ORDER})
+    if not subscriber_set.get("id"):
+        raise ToolError("Substack did not start the export.", ErrorCode.TARGET_ERROR)
+    body = {"subscriberSetId": subscriber_set["id"], "columns": _COLUMNS}
+    job = await call(ctx, "POST", f"{base}/subscriber_set/export", body=body)
+    for wait_s in _POLL_S:
+        await asyncio.sleep(wait_s)
+        response = await ctx.call("GET", f"{base}/subscriber_set/export/{job.get('export_id')}")
+        path = response.json().get("url") if response.status == 200 else None
+        if path:
+            return await _file(ctx, pub, path)
+    raise ToolError("Substack is still building the export; try again in a few minutes.", ErrorCode.TIMEOUT)
+
+
+async def _file(ctx: ToolContext, pub: dict[str, Any], path: str) -> dict[str, Any]:
+    """The export's `/file` path redirects to a presigned S3 link: that link is the answer, valid without cookies."""
+    response = await call_file(ctx, f"{pub['base']}{path}")
+    query = parse_qs(urlsplit(response.url).query)
+    signed = datetime.strptime(query["X-Amz-Date"][0], "%Y%m%dT%H%M%SZ").replace(tzinfo=UTC)
+    lines = [line for line in response.text.splitlines() if line.strip()]
+    return {
+        "download_url": response.url,
+        "rows": max(len(lines) - 1, 0),
+        "expires_at": (signed + timedelta(seconds=int(query["X-Amz-Expires"][0]))).isoformat(),
+    }
+
+
+async def call_file(ctx: ToolContext, url: str) -> Any:
+    response = await ctx.call("GET", url, headers={"accept": "text/csv"})
+    if response.status != 200 or "X-Amz-Expires" not in response.url:
+        raise ToolError("Substack did not hand out the export file.", ErrorCode.TARGET_ERROR)
+    return response
+
+
+async def find_subscriber(ctx: ToolContext, pub: dict[str, Any], email: str) -> dict[str, Any] | None:
+    """The table row of one email: the dashboard's search box, then an exact match on the address."""
+    body = {"filters": {**_ORDER, "search": email}, "limit": 10, "offset": 0, "includeTags": False}
+    answer = await call(ctx, "POST", f"{pub['base']}/api/v1/subscriber-stats", body=body)
+    wanted = email.strip().lower()
+    return next(
+        (row for row in answer.get("subscribers") or [] if str(row.get("user_email_address")).lower() == wanted),
+        None,
+    )

substack_api_mcp/substack/tools/add_subscriber.py

@@ -0,0 +1,60 @@
+"""Add subscriber."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+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
+
+_EMAIL = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "email": {"type": "string", "description": "Subscriber email."},
+    },
+    "required": ["email"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "email": "maya@example.com",
+    "plan": "free",
+    "status": "added",
+    "joined_at": "2026-10-11T10:09:00Z",
+}
+
+
+@tool(
+    name="add_subscriber",
+    title="Add subscriber",
+    access="write",
+    confirm=True,
+    description="Add one email to your list as a free subscriber.",
+    details=(
+        "Adds one email as a free subscriber, the same as Add subscribers in the dashboard, and Substack sends "
+        "its usual welcome email. Substack adds the email in the background, so list_subscribers may show it "
+        "a minute later. Add only people who agreed to hear from you. By default you confirm each call; you "
+        "can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /subscribers",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def add_subscriber(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    email = args["email"].strip().lower()
+    if not _EMAIL.match(email):
+        raise ToolError("email must be one email address.", ErrorCode.INVALID_INPUT)
+    pub = await publication(ctx)
+    # The dashboard's "Add subscribers by email" with the welcome email on; Substack adds the email in the background.
+    body = {"email": email, "subscription": False, "sendEmail": True}
+    await call(ctx, "POST", f"{pub['base']}/api/v1/subscriber/add", body=body)
+    return {"email": email, "plan": "free", "status": "added", "joined_at": datetime.now(UTC).isoformat()}

substack_api_mcp/substack/tools/cancel_scheduled_post.py

@@ -0,0 +1,54 @@
+"""Cancel scheduled 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, scheduled_at
+
+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",
+    "was_scheduled_for": "2026-10-20T12:00:00Z",
+}
+
+
+@tool(
+    name="cancel_scheduled_post",
+    title="Cancel scheduled post",
+    access="write",
+    confirm=False,
+    description="Stop a scheduled post from going out; it stays as a draft.",
+    details=(
+        "Removes the scheduled time from a post, so nothing is published or emailed then; the post stays a "
+        "draft with its content. Schedule it again with schedule_post. A post with no schedule returns an "
+        "error."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="DELETE /posts/{post_id}/schedule",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def cancel_scheduled_post(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    pid = post_id(args["post_id"])
+    post = await draft(ctx, pub, pid)
+    when = scheduled_at(post)
+    if post.get("is_published") or not when:
+        raise ToolError("This post is not scheduled.", ErrorCode.INVALID_INPUT)
+    await call(ctx, "DELETE", f"{pub['base']}/api/v1/drafts/{pid}/scheduled_release")
+    return {"post_id": str(pid), "status": "draft", "was_scheduled_for": when}

substack_api_mcp/substack/tools/create_draft.py

@@ -0,0 +1,75 @@
+"""Create draft."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from substack_api_mcp.core.tools import tool
+from substack_api_mcp.substack.client import byline, call, publication
+from substack_api_mcp.substack.markdown import to_doc
+
+if TYPE_CHECKING:
+    from substack_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "title": {"type": "string", "description": "Post title."},
+        "body_markdown": {"type": "string", "description": "Post body in Markdown. Images by public URL."},
+        "subtitle": {"type": "string", "description": "Shown under the title and in the email preview."},
+        "audience": {
+            "type": "string",
+            "enum": ["everyone", "only_paid", "founding"],
+            "description": "everyone, only_paid or founding. Default: everyone.",
+        },
+    },
+    "required": ["title", "body_markdown"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "post_id": "148420031",
+    "status": "draft",
+    "audience": "everyone",
+    "edit_url": "https://yourname.substack.com/publish/post/148420031",
+}
+
+
+@tool(
+    name="create_draft",
+    title="Create draft",
+    access="write",
+    confirm=False,
+    description="New draft from Markdown. Nothing is sent until you publish or schedule it.",
+    details=(
+        "Creates a draft in your publication and returns its post_id and editor link. Markdown covers "
+        "headings, paragraphs, bullet and numbered lists, quotes, code blocks, rules, images by public URL, "
+        "bold, italic, strikethrough, inline code and links; local image files cannot be used. Sending is a "
+        "separate step: schedule_post or publish_post. A draft reaches no one, so it runs without asking."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /drafts",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def create_draft(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    pub = await publication(ctx)
+    audience = args.get("audience") or "everyone"
+    body = {
+        "draft_title": args["title"],
+        "draft_subtitle": args.get("subtitle") or "",
+        "draft_body": json.dumps(to_doc(args["body_markdown"])),
+        "draft_bylines": byline(pub),
+        "audience": audience,
+        "type": "newsletter",
+        "section_chosen": False,
+        "draft_section_id": None,
+    }
+    post = await call(ctx, "POST", f"{pub['base']}/api/v1/drafts", body=body)
+    return {
+        "post_id": str(post["id"]),
+        "status": "draft",
+        "audience": post.get("audience") or audience,
+        "edit_url": f"{pub['base']}/publish/post/{post['id']}",
+    }

substack_api_mcp/substack/tools/create_post_tag.py

@@ -0,0 +1,49 @@
+"""Create post tag."""
+
+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": {"name": {"type": "string", "description": "Tag name, e.g. Habits."}},
+    "required": ["name"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "tag_id": "80ba205f-6de0-4024-860d-0df42720d32a",
+    "name": "Habits",
+    "slug": "habits",
+}
+
+
+@tool(
+    name="create_post_tag",
+    title="Create post tag",
+    access="write",
+    confirm=False,
+    description="New tag for grouping your posts.",
+    details=(
+        "Creates a post tag on your publication; Substack makes the slug from the name. A tag with no posts "
+        "shows nowhere. Put posts under it with tag_post."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /post-tags",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def create_post_tag(ctx: ToolContext, args: dict[str, Any]) -> Any:
+
+    name = str(args["name"]).strip()
+    if not name or len(name) > 100:
+        raise ToolError("name must be 1 to 100 characters.", ErrorCode.INVALID_INPUT)
+    pub = await publication(ctx)
+    tag = await call(ctx, "POST", f"{pub['base']}/api/v1/publication/post-tag", body={"name": name})
+    return {"tag_id": str(tag["id"]), "name": tag.get("name") or name, "slug": tag.get("slug") or ""}