python-substack 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

substack_mcp/mcp_server.py

@@ -0,0 +1,293 @@
+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()
+    user_id = client.get_user_id()
+
+    post = Post(
+        title=title,
+        subtitle=subtitle or "",
+        user_id=user_id,
+        audience=audience,
+        write_comment_permissions=write_comment_permissions,
+    )
+
+    post.from_markdown(markdown, api=client)
+
+    draft = client.post_draft(post.get_draft())
+
+    update_payload: Dict[str, Any] = {}
+    if search_engine_title:
+        update_payload["search_engine_title"] = search_engine_title
+    if search_engine_description:
+        update_payload["search_engine_description"] = search_engine_description
+    if slug:
+        update_payload["slug"] = slug
+    if draft_section_id is not None:
+        update_payload["draft_section_id"] = draft_section_id
+
+    if update_payload:
+        draft = client.put_draft(draft.get("id"), **update_payload)
+
+    tags_list = _normalize_tags(tags)
+    tags_result = None
+    if tags_list:
+        tags_result = client.add_tags_to_post(draft.get("id"), tags_list)
+
+    prepublish_result = None
+    if prepublish:
+        prepublish_result = client.prepublish_draft(draft.get("id"))
+
+    publish_result = None
+    if publish:
+        publish_result = client.publish_draft(
+            draft.get("id"), send=send, share_automatically=share_automatically
+        )
+
+    return {
+        "draft": draft,
+        "tags": tags_result,
+        "prepublish": prepublish_result,
+        "publish": publish_result,
+    }
+
+
+@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.
+
+    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
+    )
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

python_substack-0.1.23.dist-info/METADATA

@@ -1,328 +0,0 @@
-Metadata-Version: 2.4
-Name: python-substack
-Version: 0.1.23
-Summary: A Python wrapper around the Substack API.
-License: MIT
-License-File: LICENSE
-Keywords: substack
-Author: Paolo Mazza
-Author-email: mazzapaolo2019@gmail.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: PyYAML (>=6.0,<7.0)
-Requires-Dist: python-dotenv (>=1.2.1,<2.0.0)
-Requires-Dist: requests (>=2.32.0,<3.0.0)
-Project-URL: Homepage, https://github.com/ma2za/python-substack
-Project-URL: Repository, https://github.com/ma2za/python-substack
-Description-Content-Type: text/markdown
-
-# Python Substack
-
-This is an unofficial library providing a Python interface for [Substack](https://substack.com/).
-I am in no way affiliated with Substack.
-
-[![Downloads](https://static.pepy.tech/badge/python-substack/month)](https://pepy.tech/project/python-substack)
-![Release Build](https://github.com/ma2za/python-substack/actions/workflows/ci_publish.yml/badge.svg)
----
-
-# Installation
-
-You can install python-substack using:
-
-    $ pip install python-substack
-
-For the MCP server tools, install the extra dependency set:
-
-    $ poetry install --with mcp
-
-> NOTE: We had to upgrade the package requirements to support Python 3.10 because 3.9 is basically vintage now. If you still run 3.9, please join us in the future (or bring snacks).
-
----
-
-# Setup
-
-Set the following environment variables by creating a **.env** file:
-
-    EMAIL=
-    PASSWORD=
-    PUBLICATION_URL=  # Optional: your publication URL
-    COOKIES_PATH=     # Optional: path to cookies JSON file
-    COOKIES_STRING=   # Optional: cookie string for authentication
-
-## If you don't have a password
-
-Recently Substack has been setting up new accounts without a password. If you sign out and sign back in, it just uses
-your email address with a "magic" link.
-
-Set a password:
-
-- Sign out of Substack
-- At the sign-in page, click "Sign in with password" under the `Email` text box
-- Then choose, "Set a new password"
-
-The .env file will be ignored by git but always be careful.
-
----
-
-# Usage
-
-Check out the examples folder for some examples 😃 🚀
-
-## Basic Authentication
-
-```python
-import os
-from dotenv import load_dotenv
-
-from substack import Api
-from substack.post import Post
-
-load_dotenv()
-
-# Authenticate with email and password
-api = Api(
-    email=os.getenv("EMAIL"),
-    password=os.getenv("PASSWORD"),
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-```
-
-## Cookie-based Authentication
-
-You can also authenticate using cookies instead of email/password:
-
-```python
-import os
-from dotenv import load_dotenv
-
-from substack import Api
-
-load_dotenv()
-
-# Authenticate with cookies (alternative to email/password)
-api = Api(
-    cookies_path=os.getenv("COOKIES_PATH"),  # Path to cookies JSON file
-    # OR
-    cookies_string=os.getenv("COOKIES_STRING"),  # Cookie string
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-```
-
-## Creating and Publishing Posts
-
-```python
-user_id = api.get_user_id()
-
-# Switch Publications - The library defaults to your user's primary publication. You can retrieve all your publications and change which one you want to use.
-
-# primary publication
-user_publication = api.get_user_primary_publication()
-# all publications
-user_publications = api.get_user_publications()
-
-# This step is only necessary if you are not using your primary publication
-# api.change_publication(user_publication)
-
-# Create a post with basic settings
-post = Post(
-    title="How to publish a Substack post using the Python API",
-    subtitle="This post was published using the Python API",
-    user_id=user_id
-)
-
-# Create a post with audience and comment permissions
-post = Post(
-    title="My Post Title",
-    subtitle="My Post Subtitle",
-    user_id=user_id,
-    audience="everyone",  # Options: "everyone", "only_paid", "founding", "only_free"
-    write_comment_permissions="everyone"  # Options: "none", "only_paid", "everyone"
-)
-
-post.add({'type': 'paragraph', 'content': 'This is how you add a new paragraph to your post!'})
-
-# bolden text
-post.add({'type': "paragraph",
-          'content': [{'content': "This is how you "}, {'content': "bolden ", 'marks': [{'type': "strong"}]},
-                      {'content': "a word."}]})
-
-# add hyperlink to text
-post.add({'type': 'paragraph', 'content': [
-    {'content': "View Link", 'marks': [{'type': "link", 'href': 'https://whoraised.substack.com/'}]}]})
-
-# set paywall boundary
-post.add({'type': 'paywall'})
-
-# add image
-post.add({'type': 'captionedImage', 'src': "https://media.tenor.com/7B4jMa-a7bsAAAAC/i-am-batman.gif"})
-
-# add local image
-image = api.get_image('image.png')
-post.add({"type": "captionedImage", "src": image.get("url")})
-
-# embed publication
-embedded = api.publication_embed("https://jackio.substack.com/")
-post.add({"type": "embeddedPublication", "url": embedded})
-
-# create post from Markdown
-markdown_content = """
-# My Heading
-
-This is a paragraph with **bold** and *italic* text.
-
-![Image Alt](https://example.com/image.jpg)
-"""
-post.from_markdown(markdown_content, api=api)
-
-# Markdown footnotes are supported too. References become inline anchors and
-# definitions become footnote blocks, numbered by order of first appearance.
-# Labels can be numbers or names (e.g. [^1] or [^source]).
-footnote_markdown = """
-A claim that needs support.[^1] Another, with a named label.[^source]
-
-[^1]: The supporting detail, with a [link](https://example.com).
-[^source]: Author, *Title* (2025).
-"""
-post.from_markdown(footnote_markdown, api=api)
-
-# Or build footnotes manually:
-post.paragraph(content=[{"content": "Some claim."}]).footnote_anchor(1)
-post.footnote(1, "The note text, with **formatting** allowed.")
-
-draft = api.post_draft(post.get_draft())
-
-# set section (can only be done after first posting the draft)
-# post.set_section("rick rolling", api.get_sections())
-# api.put_draft(draft.get("id"), draft_section_id=post.draft_section_id)
-
-api.prepublish_draft(draft.get("id"))
-
-api.publish_draft(draft.get("id"))
-```
-
-## Loading Posts from YAML Files
-
-You can define your posts in YAML files for easier management:
-
-```python
-import yaml
-import os
-from dotenv import load_dotenv
-
-from substack import Api
-from substack.post import Post
-
-load_dotenv()
-
-# Load post data from YAML file
-with open("draft.yaml", "r") as fp:
-    post_data = yaml.safe_load(fp)
-
-# Authenticate (using cookies or email/password)
-cookies_path = os.getenv("COOKIES_PATH")
-cookies_string = os.getenv("COOKIES_STRING")
-
-api = Api(
-    email=os.getenv("EMAIL") if not cookies_path and not cookies_string else None,
-    password=os.getenv("PASSWORD") if not cookies_path and not cookies_string else None,
-    cookies_path=cookies_path,
-    cookies_string=cookies_string,
-    publication_url=os.getenv("PUBLICATION_URL"),
-)
-
-user_id = api.get_user_id()
-
-# Create post from YAML data
-post = Post(
-    post_data.get("title"),
-    post_data.get("subtitle", ""),
-    user_id,
-    audience=post_data.get("audience", "everyone"),
-    write_comment_permissions=post_data.get("write_comment_permissions", "everyone"),
-)
-
-# Add body content from YAML
-body = post_data.get("body", {})
-for _, item in body.items():
-    # Handle local images - upload them first
-    if item.get("type") == "captionedImage" and not item.get("src").startswith("http"):
-        image = api.get_image(item.get("src"))
-        item.update({"src": image.get("url")})
-    post.add(item)
-
-draft = api.post_draft(post.get_draft())
-put_draft_kwargs = {
-    "draft_section_id": post.draft_section_id,
-    "search_engine_title": post_data.get("search_engine_title"),
-    "search_engine_description": post_data.get("search_engine_description"),
-    "slug": post_data.get("slug"),
-}
-put_draft_kwargs = {k: v for k, v in put_draft_kwargs.items() if v is not None}
-api.put_draft(draft.get("id"), **put_draft_kwargs)
-
-# Publish the draft
-api.prepublish_draft(draft.get("id"))
-api.publish_draft(draft.get("id"))
-```
-
-Example YAML structure:
-
-```yaml
-title: "My Post Title"
-subtitle: "My Post Subtitle"
-audience: "everyone"  # everyone, only_paid, founding, only_free
-write_comment_permissions: "everyone"  # none, only_paid, everyone
-section: "my-section"
-body:
-  0:
-    type: "heading"
-    level: 1
-    content: "Introduction"
-  1:
-    type: "paragraph"
-    content: "This is a paragraph."
-  2:
-    type: "captionedImage"
-    src: "local_image.jpg"  # Local images will be uploaded automatically
-```
-
-## MCP FastMCP server
-
-This package now includes a FastMCP server in `substack/mcp_fastmcp.py` with the following tools:
-
-- `post_draft_from_markdown(...)`: create draft from markdown, optional tag/add/prepublish/publish, and control send/share_automatically.
-- `put_draft(draft_id, update_payload)`: update draft fields.
-- `add_tags(draft_id, tags)`: add tags to a draft/post.
-- `prepublish_draft(draft_id)`: prepublish a draft.
-- `publish_draft(draft_id, send=True, share_automatically=False)`: publish a draft.
-
-Use via stdio transport:
-
-```bash
-python -c "from substack.mcp_fastmcp import main; main()"
-```
-
-# Contributing
-
-Install pre-commit:
-
-```shell
-pip install pre-commit
-```
-
-Set up pre-commit
-
-```shell
-pre-commit install
-```
-
-## Cookie Help
-
-To get a cookie string, after login, go to dev tools (F12), network tab, refresh and find one of the requests like subscription/unred/subscriptions, right click and copy as fetch (Node.js), paste somewhere and get the entire cookie string assigned to the cookie header and put it in the env variables as COOKIES_STRING, et voila!
-

python_substack-0.1.23.dist-info/RECORD

@@ -1,8 +0,0 @@
-substack/__init__.py,sha256=I3u5zUvxfPpbPYQTCV0VR3lGS4gyQQISC_0_GPN3FGk,390
-substack/api.py,sha256=VPzQ_bpqGcE4ZXWD2lUppnvWsuLRjvtBN7bHmW4Bgww,20422
-substack/exceptions.py,sha256=BbP5W5UpzFcM5SYIxx6snWD_Rmj7F_YjYIYC_r03gZY,911
-substack/post.py,sha256=ZObXe62J7iXhSI_XBpadVTMXpN6xqLNHXUrOHSidkgM,39440
-python_substack-0.1.23.dist-info/METADATA,sha256=90wvACIgduBlYv9RyB6euQq59V0ZJXgl39mB-isWWb8,9780
-python_substack-0.1.23.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
-python_substack-0.1.23.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.1.23.dist-info/RECORD,,