python-substack 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

{python_substack-0.6.0.dist-info → python_substack-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.6.0
+Version: 0.7.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
 License: MIT
 License-File: LICENSE
@@ -22,7 +22,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: mcp
 Requires-Dist: PyYAML (>=6.0,<7.0)
-Requires-Dist: fastmcp (>=3.1.1,<4.0.0) ; extra == "mcp"
+Requires-Dist: fastmcp (>=3.1.1,<5.0.0) ; extra == "mcp"
 Requires-Dist: markdown-it-py (>=3,<5)
 Requires-Dist: mdit-py-plugins (>=0.5,<0.7)
 Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)

python_substack-0.7.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+substack/__init__.py,sha256=soBT45w3E1XVhTYcV9Y_1D363e35S4_Q0mFrF13pHHM,450
+substack/api.py,sha256=nBEnD2ipxSAWR99iwNgCfGD4-y8YYwKNmilq2y1VP8M,29903
+substack/cli.py,sha256=L-nR45tJDTuvZrinj-dApXzw6-CgXcwaodyX7CpYFm4,25720
+substack/exceptions.py,sha256=Y61XSPyxDxXPbVlioFvKhb94MRY0tpD389F5YdL1rGM,1390
+substack/mdexport.py,sha256=_pSjioPJIA1wuJ6hYpvODZVswPSUROuzEndVoYnv-yU,13541
+substack/mdrender.py,sha256=QGJkdp1isFmhVyTRMogIabAK8OO2xQh9CrjnXZvFTY4,9308
+substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
+substack/post.py,sha256=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
+substack_mcp/mcp_server.py,sha256=M5XH3C4iWjzvCw3uOPbY2NFljTQAl8FLt14RKaTzka0,11324
+python_substack-0.7.0.dist-info/METADATA,sha256=-_DF7Ln42oZYd1uPqaFQgAAZHsgka8-FqwP6VfbshVQ,8689
+python_substack-0.7.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+python_substack-0.7.0.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
+python_substack-0.7.0.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
+python_substack-0.7.0.dist-info/RECORD,,

substack/__init__.py

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = (

substack/api.py

@@ -464,6 +464,95 @@ class Api:
             "unsupported_nodes": unsupported_nodes,
         }
 
+    def update_draft_from_markdown(
+        self,
+        draft_id: int,
+        markdown: str,
+        *,
+        subtitle: str = None,
+        audience: str = None,
+        write_comment_permissions: str = None,
+        search_engine_title: str = None,
+        search_engine_description: str = None,
+        slug: str = None,
+        draft_section_id: int = None,
+        tags=None,
+        dry_run: bool = False,
+    ) -> dict:
+        """
+        Update an existing draft body from Markdown, with optional metadata changes.
+        """
+        from substack.mdexport import document_to_markdown
+        from substack.post import Post
+
+        draft = self.get_draft(draft_id)
+        draft_body = draft.get("draft_body")
+        if isinstance(draft_body, str):
+            try:
+                draft_body = json.loads(draft_body)
+            except json.JSONDecodeError as exc:
+                raise ValueError(
+                    "Malformed draft body: draft_body is not valid JSON"
+                ) from exc
+        if not isinstance(draft_body, dict):
+            raise ValueError("Malformed draft body: draft_body must be a JSON object")
+
+        _, unsupported_nodes = document_to_markdown(draft_body)
+        if unsupported_nodes:
+            raise ValueError(
+                "Refusing to update: remote draft contains unsupported Substack nodes. "
+                "Export it first or remove the nodes manually to avoid data loss."
+            )
+
+        post = Post(
+            title=draft.get("title", ""),
+            subtitle=(
+                subtitle if subtitle is not None else (draft.get("subtitle") or "")
+            ),
+            user_id=self.get_user_id(),
+            audience=audience,
+            write_comment_permissions=write_comment_permissions,
+        )
+        post.from_markdown(markdown, api=self)
+
+        update_payload = {"draft_body": json.dumps(post.draft_body)}
+
+        if subtitle is not None:
+            update_payload["subtitle"] = subtitle
+        if audience is not None:
+            update_payload["audience"] = audience
+        if write_comment_permissions is not None:
+            update_payload["write_comment_permissions"] = write_comment_permissions
+        if search_engine_title is not None:
+            update_payload["search_engine_title"] = search_engine_title
+        if search_engine_description is not None:
+            update_payload["search_engine_description"] = search_engine_description
+        if slug is not None:
+            update_payload["slug"] = slug
+        if draft_section_id is not None:
+            update_payload["draft_section_id"] = draft_section_id
+
+        tags_result = None
+        updated_draft = draft
+
+        if not dry_run:
+            updated_draft = self.put_draft(draft_id, **update_payload)
+
+            tags_list = Api._normalize_tags(tags)
+            if tags_list:
+                tags_result = self.add_tags_to_post(draft_id, tags_list)
+
+        return {
+            "action": "update",
+            "draft_id": draft_id,
+            "dry_run": dry_run,
+            "changed": not dry_run,
+            "payload": update_payload,
+            "draft": updated_draft,
+            "tags": tags_result,
+            "unsupported_nodes": unsupported_nodes,
+        }
+
     def delete_draft(self, draft_id):
         """
 

substack/cli.py

@@ -309,6 +309,53 @@ def _drafts_create(api, args):
         print(f"Created draft {draft.get('id')}: {title}")
 
 
+def _drafts_update(api, args):
+    if not args.yes and (args.json_output or not sys.stdin.isatty()):
+        raise CLIUsageError("--yes is required in non-interactive or JSON mode")
+
+    markdown_file = Path(args.markdown_file)
+    if not markdown_file.exists():
+        raise CLIUsageError(f"File not found: {markdown_file}")
+
+    if not args.yes:
+        action = "update" if not args.dry_run else "dry-run update"
+        print(f"Ready to {action} draft {args.draft_id} from {markdown_file}")
+        print("Substack nodes that are not supported by Markdown export/import")
+        print("will cause the update to be refused to prevent data loss.")
+        print()
+        try:
+            response = input(f"Confirm {action}? [y/N]: ")
+            if response.lower() not in ["y", "yes"]:
+                print("Aborted.")
+                return
+        except EOFError as exc:
+            raise CLIUsageError(
+                f"Confirm {action} requires confirmation or --yes"
+            ) from exc
+
+    markdown = markdown_file.read_text(encoding="utf-8")
+
+    result = api.update_draft_from_markdown(
+        args.draft_id,
+        markdown,
+        subtitle=args.subtitle,
+        audience=args.audience,
+        write_comment_permissions=args.write_comment_permissions,
+        search_engine_title=args.search_engine_title,
+        search_engine_description=args.search_engine_description,
+        slug=args.slug,
+        draft_section_id=args.draft_section_id,
+        tags=args.tags,
+        dry_run=args.dry_run,
+    )
+
+    if args.json_output:
+        _print_json(result)
+    else:
+        status = "Dry-run updated" if args.dry_run else "Updated"
+        print(f"{status} draft {args.draft_id}")
+
+
 def _drafts_export(api, args):
     output_path = Path(args.output) if args.output else None
     if output_path is not None and output_path.exists() and not args.force:
@@ -447,6 +494,23 @@ def _build_parser():
     drafts_create.add_argument("--tag", action="append", dest="tags", metavar="TAG")
     drafts_create.set_defaults(handler=_drafts_create)
 
+    drafts_update = draft_commands.add_parser(
+        "update", help="Update a draft from a Markdown file."
+    )
+    drafts_update.add_argument("draft_id", type=int)
+    drafts_update.add_argument("markdown_file", metavar="MARKDOWN_FILE")
+    drafts_update.add_argument("--subtitle")
+    drafts_update.add_argument("--audience")
+    drafts_update.add_argument("--write-comment-permissions")
+    drafts_update.add_argument("--search-engine-title")
+    drafts_update.add_argument("--search-engine-description")
+    drafts_update.add_argument("--slug")
+    drafts_update.add_argument("--draft-section-id", type=int)
+    drafts_update.add_argument("--tag", action="append", dest="tags", metavar="TAG")
+    drafts_update.add_argument("--dry-run", action="store_true")
+    drafts_update.add_argument("--yes", action="store_true")
+    drafts_update.set_defaults(handler=_drafts_update)
+
     drafts_export = draft_commands.add_parser(
         "export", help="Export a draft to Markdown without modifying it."
     )

substack_mcp/mcp_server.py

@@ -1,386 +1,386 @@
-from __future__ import annotations
-
-import os
-from typing import Any, Dict, List, Optional
-
-try:
-    from dotenv import load_dotenv
-except ImportError:
-    load_dotenv = None
-
-from mcp.server.fastmcp import FastMCP
-
-from substack.api import Api
-from substack.post import Post
-
-if load_dotenv is not None:
-    load_dotenv()
-
-
-def get_api() -> Api:
-    email = os.getenv("EMAIL")
-    password = os.getenv("PASSWORD")
-    cookies_path = os.getenv("COOKIES_PATH")
-    cookies_string = os.getenv("COOKIES_STRING")
-    publication_url = os.getenv("PUBLICATION_URL")
-
-    if cookies_path or cookies_string:
-        return Api(
-            cookies_path=cookies_path,
-            cookies_string=cookies_string,
-            publication_url=publication_url,
-        )
-
-    if email and password:
-        return Api(
-            email=email,
-            password=password,
-            publication_url=publication_url,
-        )
-
-    raise ValueError(
-        "Missing Substack auth configuration: set EMAIL/PASSWORD or COOKIES_PATH/COOKIES_STRING"
-    )
-
-
-def _normalize_tags(tags: Optional[Any]) -> List[str]:
-    if tags is None:
-        return []
-    if isinstance(tags, str):
-        return [tags]
-    if isinstance(tags, list):
-        return [str(tag) for tag in tags]
-    raise ValueError("tags must be a string or a list of strings")
-
-
-mcp = FastMCP("substack")
-
-
-@mcp.tool()
-async def post_draft_from_markdown(
-    title: str,
-    markdown: str,
-    subtitle: Optional[str] = "",
-    audience: str = "everyone",
-    write_comment_permissions: str = "everyone",
-    search_engine_title: Optional[str] = None,
-    search_engine_description: Optional[str] = None,
-    slug: Optional[str] = None,
-    draft_section_id: Optional[int] = None,
-    tags: Optional[Any] = None,
-    prepublish: bool = False,
-    publish: bool = False,
-    send: bool = True,
-    share_automatically: bool = False,
-) -> Dict[str, Any]:
-    """Create or update a Substack draft from Markdown.
-
-    This tool builds a Substack `Post` from markdown content and posts a draft.
-    It supports optional tag assignment, prepublish (setup check), and publishing.
-
-    Args:
-        title: Draft title.
-        markdown: Markdown body content.
-        subtitle: Optional subtitle text.
-        audience: One of `everyone`, `only_paid`, `founding`, `only_free`.
-        write_comment_permissions: One of `none`, `only_paid`, `everyone`.
-        search_engine_title: Optional title for search engine optimization.
-        search_engine_description: Optional description for search engine optimization.
-        slug: Optional URL slug for the post.
-        draft_section_id: Optional section ID for the draft.
-        tags: Tag or list of tags to attach to the post.
-        prepublish: If true, calls `prepublish_draft` after creation.
-        publish: If true, calls `publish_draft` after creation (and optionally prepublish).
-        send: Passed to `publish_draft` for newsletter delivery.
-        share_automatically: Passed to `publish_draft`.
-
-    Returns:
-        dict containing drafted post (`draft`), optional `tags`, `prepublish`, `publish` results.
-
-    Examples:
-        With the YAML structure from the README, a caller can map fields like:
-
-        ```yaml
-        title: "My Post Title"
-        subtitle: "My Post Subtitle"
-        audience: "everyone"
-        write_comment_permissions: "everyone"
-        markdown: |
-          # Hello
-
-          This is the body.
-
-        tags:
-          - python
-          - substack
-        prepublish: true
-        publish: true
-        send: false
-        share_automatically: true
-        ```
-
-        Then invoke via MCP directly:
-
-        ```python
-        from substack_mcp.mcp_server import post_draft_from_markdown
-
-        result = await post_draft_from_markdown(
-            title='My Post Title',
-            markdown='# Hello\n\nThis is the body.',
-            subtitle='My Post Subtitle',
-            audience='everyone',
-            write_comment_permissions='everyone',
-            tags=['python', 'substack'],
-            prepublish=True,
-            publish=False,  # set true when ready
-        )
-        print(result)
-        ```
-
-        A longer process with manual prepublish/publish calls:
-
-        ```python
-        from substack_mcp.mcp_server import (
-            post_draft_from_markdown,
-            prepublish_draft,
-            publish_draft,
-            add_tags,
-        )
-
-        d = await post_draft_from_markdown(
-            title='Long flow',
-            markdown='Content',
-            tags=['a','b'],
-            publish=False,
-        )
-        draft_id = d['draft']['id']
-
-        await add_tags(draft_id, ['post-tag', 'news'])
-        await prepublish_draft(draft_id)
-        await publish_draft(draft_id, send=True, share_automatically=True)
-        ```
-
-        This docstring example is meant to mirror the YAML-driven workflow and show how to decompose the same operations into explicit tool calls.
-    """
-    client = get_api()
-
-    return client.create_draft_from_markdown(
-        title=title,
-        markdown=markdown,
-        subtitle=subtitle,
-        audience=audience,
-        write_comment_permissions=write_comment_permissions,
-        search_engine_title=search_engine_title,
-        search_engine_description=search_engine_description,
-        slug=slug,
-        draft_section_id=draft_section_id,
-        tags=tags,
-        prepublish=prepublish,
-        publish=publish,
-        send=send,
-        share_automatically=share_automatically,
-    )
-
-
-@mcp.tool()
-async def put_draft(
-    draft_id: int,
-    update_payload: Dict[str, Any],
-) -> Dict[str, Any]:
-    """Update an existing draft by draft ID.
-
-    Args:
-        draft_id: target draft identifier.
-        update_payload: dict of fields supported by Substack `put_draft` (e.g. `slug`, `draft_section_id`).
-
-    Returns:
-        API response dict for the updated draft.
-    """
-    client = get_api()
-    return client.put_draft(draft_id, **update_payload)
-
-
-@mcp.tool()
-async def add_tags(draft_id: int, tags: Any) -> Dict[str, Any]:
-    """Add tags to a specific draft/post.
-
-    Args:
-        draft_id: target draft identifier.
-        tags: string or list of tag names (e.g. `"tech"` or `["tech", "python"]`).
-
-    Returns:
-        Response from `add_tags_to_post` (tag IDs + names).
-    """
-    client = get_api()
-    tags_list = _normalize_tags(tags)
-    if not tags_list:
-        raise ValueError("tags is required and cannot be empty")
-    return client.add_tags_to_post(draft_id, tags_list)
-
-
-@mcp.tool()
-async def prepublish_draft(draft_id: int) -> Dict[str, Any]:
-    """Invoke prepublish checks for a draft.
-
-    Args:
-        draft_id: target draft identifier.
-
-    Returns:
-        Prepublish response dict from Substack API.
-    """
-    client = get_api()
-    return client.prepublish_draft(draft_id)
-
-
-@mcp.tool()
-async def publish_draft(
-    draft_id: int,
-    send: bool = True,
-    share_automatically: bool = False,
-) -> Dict[str, Any]:
-    """Publish a draft to live post state. (Legacy compatibility interface).
-
-    This tool remains for backward compatibility. It is recommended to use
-    `publish_draft_checked` instead, which provides a safer publishing path
-    with explicit confirmation and prepublish validation.
-
-    Args:
-        draft_id: target draft identifier.
-        send: if False then do not send email to subscribers.
-        share_automatically: whether to auto-share (e.g. social propagation).
-
-    Returns:
-        Response from Substack `publish_draft`.
-    """
-    client = get_api()
-    return client.publish_draft(
-        draft_id, send=send, share_automatically=share_automatically
-    )
-
-
-@mcp.tool()
-async def publish_draft_checked(
-    draft_id: int,
-    confirm: bool = False,
-    send: bool = False,
-    share_automatically: bool = False,
-) -> Dict[str, Any]:
-    """A safer publishing path that requires confirmation and runs prepublish checks.
-
-    Args:
-        draft_id: target draft identifier.
-        confirm: Must be True to proceed with publication.
-        send: if False then do not send email to subscribers. Defaults to False.
-        share_automatically: whether to auto-share.
-
-    Returns:
-        Response from Substack `publish_draft`.
-    """
-    if not confirm:
-        raise ValueError("Publishing rejected: confirm parameter must be True.")
-
-    client = get_api()
-    client.prepublish_draft(draft_id)
-    return client.publish_draft(
-        draft_id, send=send, share_automatically=share_automatically
-    )
-
-
-@mcp.tool()
-async def get_status() -> Dict[str, Any]:
-    """Get the authentication status and basic user information.
-
-    Returns:
-        A dictionary containing user profile and primary publication details.
-    """
-    client = get_api()
-    profile = client.get_user_profile()
-    primary_pub = client.get_user_primary_publication()
-    return {"profile": profile, "primary_publication": primary_pub}
-
-
-@mcp.tool()
-async def list_publications() -> List[Dict[str, Any]]:
-    """List all publications available to the authenticated user.
-
-    Returns:
-        A list of publications.
-    """
-    client = get_api()
-    return client.get_user_publications()
-
-
-@mcp.tool()
-async def list_drafts(
-    filter: str = "draft", offset: int = 0, limit: int = 25
-) -> List[Dict[str, Any]]:
-    """List drafts for the current publication.
-
-    Args:
-        filter: Filter string, defaults to "draft".
-        offset: Pagination offset.
-        limit: Max number of drafts to return.
-
-    Returns:
-        A list of drafts.
-    """
-    client = get_api()
-    return client.get_drafts(filter=filter, offset=offset, limit=limit)
-
-
-@mcp.tool()
-async def get_draft(draft_id: int) -> Dict[str, Any]:
-    """Get a specific draft by its ID.
-
-    Args:
-        draft_id: The identifier of the draft.
-
-    Returns:
-        The draft details.
-    """
-    client = get_api()
-    return client.get_draft(draft_id)
-
-
-@mcp.tool()
-async def schedule_draft(draft_id: int, at: str) -> Dict[str, Any]:
-    """Schedule a draft for release.
-
-    Args:
-        draft_id: target draft identifier.
-        at: ISO 8601 formatted datetime string (e.g., "2024-01-01T12:00:00Z").
-
-    Returns:
-        API response dict for the scheduled draft.
-    """
-    from datetime import datetime
-
-    try:
-        draft_datetime = datetime.fromisoformat(at.replace("Z", "+00:00"))
-    except ValueError as e:
-        raise ValueError(f"Invalid ISO datetime string for 'at': {e}")
-
-    client = get_api()
-    return client.schedule_draft(draft_id, draft_datetime)
-
-
-@mcp.tool()
-async def unschedule_draft(draft_id: int) -> Dict[str, Any]:
-    """Unschedule a previously scheduled draft.
-
-    Args:
-        draft_id: target draft identifier.
-
-    Returns:
-        API response dict for unscheduling.
-    """
-    client = get_api()
-    return client.unschedule_draft(draft_id)
-
-
-def main() -> None:
-    mcp.run(transport="stdio")
-
-
-if __name__ == "__main__":
-    main()
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = None
+
+from fastmcp import FastMCP
+
+from substack.api import Api
+from substack.post import Post
+
+if load_dotenv is not None:
+    load_dotenv()
+
+
+def get_api() -> Api:
+    email = os.getenv("EMAIL")
+    password = os.getenv("PASSWORD")
+    cookies_path = os.getenv("COOKIES_PATH")
+    cookies_string = os.getenv("COOKIES_STRING")
+    publication_url = os.getenv("PUBLICATION_URL")
+
+    if cookies_path or cookies_string:
+        return Api(
+            cookies_path=cookies_path,
+            cookies_string=cookies_string,
+            publication_url=publication_url,
+        )
+
+    if email and password:
+        return Api(
+            email=email,
+            password=password,
+            publication_url=publication_url,
+        )
+
+    raise ValueError(
+        "Missing Substack auth configuration: set EMAIL/PASSWORD or COOKIES_PATH/COOKIES_STRING"
+    )
+
+
+def _normalize_tags(tags: Optional[Any]) -> List[str]:
+    if tags is None:
+        return []
+    if isinstance(tags, str):
+        return [tags]
+    if isinstance(tags, list):
+        return [str(tag) for tag in tags]
+    raise ValueError("tags must be a string or a list of strings")
+
+
+mcp = FastMCP("substack")
+
+
+@mcp.tool()
+async def post_draft_from_markdown(
+    title: str,
+    markdown: str,
+    subtitle: Optional[str] = "",
+    audience: str = "everyone",
+    write_comment_permissions: str = "everyone",
+    search_engine_title: Optional[str] = None,
+    search_engine_description: Optional[str] = None,
+    slug: Optional[str] = None,
+    draft_section_id: Optional[int] = None,
+    tags: Optional[Any] = None,
+    prepublish: bool = False,
+    publish: bool = False,
+    send: bool = True,
+    share_automatically: bool = False,
+) -> Dict[str, Any]:
+    """Create or update a Substack draft from Markdown.
+
+    This tool builds a Substack `Post` from markdown content and posts a draft.
+    It supports optional tag assignment, prepublish (setup check), and publishing.
+
+    Args:
+        title: Draft title.
+        markdown: Markdown body content.
+        subtitle: Optional subtitle text.
+        audience: One of `everyone`, `only_paid`, `founding`, `only_free`.
+        write_comment_permissions: One of `none`, `only_paid`, `everyone`.
+        search_engine_title: Optional title for search engine optimization.
+        search_engine_description: Optional description for search engine optimization.
+        slug: Optional URL slug for the post.
+        draft_section_id: Optional section ID for the draft.
+        tags: Tag or list of tags to attach to the post.
+        prepublish: If true, calls `prepublish_draft` after creation.
+        publish: If true, calls `publish_draft` after creation (and optionally prepublish).
+        send: Passed to `publish_draft` for newsletter delivery.
+        share_automatically: Passed to `publish_draft`.
+
+    Returns:
+        dict containing drafted post (`draft`), optional `tags`, `prepublish`, `publish` results.
+
+    Examples:
+        With the YAML structure from the README, a caller can map fields like:
+
+        ```yaml
+        title: "My Post Title"
+        subtitle: "My Post Subtitle"
+        audience: "everyone"
+        write_comment_permissions: "everyone"
+        markdown: |
+          # Hello
+
+          This is the body.
+
+        tags:
+          - python
+          - substack
+        prepublish: true
+        publish: true
+        send: false
+        share_automatically: true
+        ```
+
+        Then invoke via MCP directly:
+
+        ```python
+        from substack_mcp.mcp_server import post_draft_from_markdown
+
+        result = await post_draft_from_markdown(
+            title='My Post Title',
+            markdown='# Hello\n\nThis is the body.',
+            subtitle='My Post Subtitle',
+            audience='everyone',
+            write_comment_permissions='everyone',
+            tags=['python', 'substack'],
+            prepublish=True,
+            publish=False,  # set true when ready
+        )
+        print(result)
+        ```
+
+        A longer process with manual prepublish/publish calls:
+
+        ```python
+        from substack_mcp.mcp_server import (
+            post_draft_from_markdown,
+            prepublish_draft,
+            publish_draft,
+            add_tags,
+        )
+
+        d = await post_draft_from_markdown(
+            title='Long flow',
+            markdown='Content',
+            tags=['a','b'],
+            publish=False,
+        )
+        draft_id = d['draft']['id']
+
+        await add_tags(draft_id, ['post-tag', 'news'])
+        await prepublish_draft(draft_id)
+        await publish_draft(draft_id, send=True, share_automatically=True)
+        ```
+
+        This docstring example is meant to mirror the YAML-driven workflow and show how to decompose the same operations into explicit tool calls.
+    """
+    client = get_api()
+
+    return client.create_draft_from_markdown(
+        title=title,
+        markdown=markdown,
+        subtitle=subtitle,
+        audience=audience,
+        write_comment_permissions=write_comment_permissions,
+        search_engine_title=search_engine_title,
+        search_engine_description=search_engine_description,
+        slug=slug,
+        draft_section_id=draft_section_id,
+        tags=tags,
+        prepublish=prepublish,
+        publish=publish,
+        send=send,
+        share_automatically=share_automatically,
+    )
+
+
+@mcp.tool()
+async def put_draft(
+    draft_id: int,
+    update_payload: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Update an existing draft by draft ID.
+
+    Args:
+        draft_id: target draft identifier.
+        update_payload: dict of fields supported by Substack `put_draft` (e.g. `slug`, `draft_section_id`).
+
+    Returns:
+        API response dict for the updated draft.
+    """
+    client = get_api()
+    return client.put_draft(draft_id, **update_payload)
+
+
+@mcp.tool()
+async def add_tags(draft_id: int, tags: Any) -> Dict[str, Any]:
+    """Add tags to a specific draft/post.
+
+    Args:
+        draft_id: target draft identifier.
+        tags: string or list of tag names (e.g. `"tech"` or `["tech", "python"]`).
+
+    Returns:
+        Response from `add_tags_to_post` (tag IDs + names).
+    """
+    client = get_api()
+    tags_list = _normalize_tags(tags)
+    if not tags_list:
+        raise ValueError("tags is required and cannot be empty")
+    return client.add_tags_to_post(draft_id, tags_list)
+
+
+@mcp.tool()
+async def prepublish_draft(draft_id: int) -> Dict[str, Any]:
+    """Invoke prepublish checks for a draft.
+
+    Args:
+        draft_id: target draft identifier.
+
+    Returns:
+        Prepublish response dict from Substack API.
+    """
+    client = get_api()
+    return client.prepublish_draft(draft_id)
+
+
+@mcp.tool()
+async def publish_draft(
+    draft_id: int,
+    send: bool = True,
+    share_automatically: bool = False,
+) -> Dict[str, Any]:
+    """Publish a draft to live post state. (Legacy compatibility interface).
+
+    This tool remains for backward compatibility. It is recommended to use
+    `publish_draft_checked` instead, which provides a safer publishing path
+    with explicit confirmation and prepublish validation.
+
+    Args:
+        draft_id: target draft identifier.
+        send: if False then do not send email to subscribers.
+        share_automatically: whether to auto-share (e.g. social propagation).
+
+    Returns:
+        Response from Substack `publish_draft`.
+    """
+    client = get_api()
+    return client.publish_draft(
+        draft_id, send=send, share_automatically=share_automatically
+    )
+
+
+@mcp.tool()
+async def publish_draft_checked(
+    draft_id: int,
+    confirm: bool = False,
+    send: bool = False,
+    share_automatically: bool = False,
+) -> Dict[str, Any]:
+    """A safer publishing path that requires confirmation and runs prepublish checks.
+
+    Args:
+        draft_id: target draft identifier.
+        confirm: Must be True to proceed with publication.
+        send: if False then do not send email to subscribers. Defaults to False.
+        share_automatically: whether to auto-share.
+
+    Returns:
+        Response from Substack `publish_draft`.
+    """
+    if not confirm:
+        raise ValueError("Publishing rejected: confirm parameter must be True.")
+
+    client = get_api()
+    client.prepublish_draft(draft_id)
+    return client.publish_draft(
+        draft_id, send=send, share_automatically=share_automatically
+    )
+
+
+@mcp.tool()
+async def get_status() -> Dict[str, Any]:
+    """Get the authentication status and basic user information.
+
+    Returns:
+        A dictionary containing user profile and primary publication details.
+    """
+    client = get_api()
+    profile = client.get_user_profile()
+    primary_pub = client.get_user_primary_publication()
+    return {"profile": profile, "primary_publication": primary_pub}
+
+
+@mcp.tool()
+async def list_publications() -> List[Dict[str, Any]]:
+    """List all publications available to the authenticated user.
+
+    Returns:
+        A list of publications.
+    """
+    client = get_api()
+    return client.get_user_publications()
+
+
+@mcp.tool()
+async def list_drafts(
+    filter: str = "draft", offset: int = 0, limit: int = 25
+) -> List[Dict[str, Any]]:
+    """List drafts for the current publication.
+
+    Args:
+        filter: Filter string, defaults to "draft".
+        offset: Pagination offset.
+        limit: Max number of drafts to return.
+
+    Returns:
+        A list of drafts.
+    """
+    client = get_api()
+    return client.get_drafts(filter=filter, offset=offset, limit=limit)
+
+
+@mcp.tool()
+async def get_draft(draft_id: int) -> Dict[str, Any]:
+    """Get a specific draft by its ID.
+
+    Args:
+        draft_id: The identifier of the draft.
+
+    Returns:
+        The draft details.
+    """
+    client = get_api()
+    return client.get_draft(draft_id)
+
+
+@mcp.tool()
+async def schedule_draft(draft_id: int, at: str) -> Dict[str, Any]:
+    """Schedule a draft for release.
+
+    Args:
+        draft_id: target draft identifier.
+        at: ISO 8601 formatted datetime string (e.g., "2024-01-01T12:00:00Z").
+
+    Returns:
+        API response dict for the scheduled draft.
+    """
+    from datetime import datetime
+
+    try:
+        draft_datetime = datetime.fromisoformat(at.replace("Z", "+00:00"))
+    except ValueError as e:
+        raise ValueError(f"Invalid ISO datetime string for 'at': {e}")
+
+    client = get_api()
+    return client.schedule_draft(draft_id, draft_datetime)
+
+
+@mcp.tool()
+async def unschedule_draft(draft_id: int) -> Dict[str, Any]:
+    """Unschedule a previously scheduled draft.
+
+    Args:
+        draft_id: target draft identifier.
+
+    Returns:
+        API response dict for unscheduling.
+    """
+    client = get_api()
+    return client.unschedule_draft(draft_id)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

python_substack-0.6.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-substack/__init__.py,sha256=AOBZry1Ww9TjPAvZmD6jBifVD5vjDGYo9_6Pay1wNPY,449
-substack/api.py,sha256=9YYLi4410zSUiNd84ZNCHA-gSo08R4pS5JdpXFHUXiQ,26550
-substack/cli.py,sha256=-3HI99ewA6IFNluiKr_LMW4J-rAzxDzW6b1E3ar8cJU,23125
-substack/exceptions.py,sha256=Y61XSPyxDxXPbVlioFvKhb94MRY0tpD389F5YdL1rGM,1390
-substack/mdexport.py,sha256=_pSjioPJIA1wuJ6hYpvODZVswPSUROuzEndVoYnv-yU,13541
-substack/mdrender.py,sha256=QGJkdp1isFmhVyTRMogIabAK8OO2xQh9CrjnXZvFTY4,9308
-substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
-substack/post.py,sha256=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
-substack_mcp/mcp_server.py,sha256=3VTSSsiAmr4btImWpfoEl7irpTgqI-FH4q5r9r3u3w8,10949
-python_substack-0.6.0.dist-info/METADATA,sha256=krTBh9COgQai1eRfZbWNSriJt51OfEu3iDwEgnRrYPA,8689
-python_substack-0.6.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
-python_substack-0.6.0.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
-python_substack-0.6.0.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.6.0.dist-info/RECORD,,