Release 0.4.0: MCP read operations and safe publishing path

This release makes the optional MCP
     server significantly more useful for inspecting and preparing publications without steering agents toward immediate publishing.

Author: ma2za

.gitignore

@@ -110,6 +110,10 @@ ENV/
 env.bak/
 venv.bak/
 
+# Gemini CLI and Testing artifacts
+.gemini/
+tmp_pytest/
+
 # Spyder project settings
 .spyderproject
 .spyproject

.pre-commit-config.yaml

@@ -14,3 +14,4 @@ repos:
     hooks:
       - id: isort
         name: isort (python)
+        args: ["--profile", "black"]

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0
+
+### Added
+
+- Seven new MCP tools for read operations and safe publishing: `get_status`, `list_publications`, `list_drafts`, `get_draft`, `schedule_draft`, `unschedule_draft`, and `publish_draft_checked`.
+- Pre-publish validation, interactive confirmation requirements, and no-email defaults for the new `publish_draft_checked` MCP tool.
+- Verified MCP client configuration examples in `docs/mcp.md`.
+- Documentation for Gemini CLI with Vertex AI (`docs/gemini-vertex-ai.md`).
+
+### Improved
+
+- Simplify MCP draft creation by routing through the existing `Api.create_draft_from_markdown` SDK helper, preserving response format.
+- Document the legacy `publish_draft` MCP tool as the compatibility interface.
+- Bump `cryptography` dependency from `48.0.1` to `50.0.0` (#68).
+
 ## 0.3.0
 
 ### Added

README.md

@@ -227,6 +227,7 @@ See [MCP server](docs/mcp.md) for the tool list and safety notes.
 - [Low-level Python API](docs/low-level-api.md)
 - [YAML drafts](docs/yaml.md)
 - [MCP server](docs/mcp.md)
+- [Gemini CLI with Vertex AI](docs/gemini-vertex-ai.md)
 - [Safety and publishing behavior](docs/safety.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Compatibility policy](docs/compatibility.md)

docs/mcp.md

@@ -21,16 +21,59 @@ python -c "from substack_mcp.mcp_server import main; main()"
 The server uses the same `EMAIL`, `PASSWORD`, `PUBLICATION_URL`,
 `COOKIES_PATH`, and `COOKIES_STRING` environment variables as the SDK.
 
-Available tools:
+## Available Tools
 
-- `post_draft_from_markdown(...)`
-- `put_draft(draft_id, update_payload)`
-- `add_tags(draft_id, tags)`
-- `prepublish_draft(draft_id)`
-- `publish_draft(draft_id, send=True, share_automatically=False)`
+The server exposes tools for reading content, managing drafts, and publishing.
 
-`post_draft_from_markdown` creates an unpublished draft unless `publish=True`
-is explicitly supplied. `publish_draft` publishes immediately and defaults to
-sending email. Review the draft ID and arguments before invoking it.
+**Read Operations (Safe to run automatically):**
+- `get_status()` - Verify authentication and get basic user/publication information.
+- `list_publications()` - List all publications you have access to.
+- `list_drafts(filter="draft", offset=0, limit=25)` - View recent drafts.
+- `get_draft(draft_id)` - Read the content and metadata of a specific draft.
 
-The server currently exposes the compatibility tools listed above.
+**Draft Creation and Reversible Writes:**
+- `post_draft_from_markdown(...)` - Creates an unpublished draft from Markdown.
+- `put_draft(draft_id, update_payload)` - Update draft metadata (e.g. slug).
+- `add_tags(draft_id, tags)` - Attach tags to a draft.
+- `prepublish_draft(draft_id)` - Run Substack's pre-publication checks on a draft.
+- `schedule_draft(draft_id, at)` - Schedule a draft for publication at an ISO timestamp.
+- `unschedule_draft(draft_id)` - Remove a publication schedule from a draft.
+
+**Publishing Operations (Use with caution):**
+- `publish_draft_checked(draft_id, confirm=False, send=False, share_automatically=False)` - **Recommended**. A safer publishing path that requires explicit confirmation (`confirm=True`), runs prepublish checks automatically, and defaults to *not* sending emails.
+- `publish_draft(draft_id, send=True, share_automatically=False)` - *Legacy compatibility interface*. Publishes immediately and defaults to sending email.
+
+## Client Configuration Examples
+
+### Claude Desktop
+
+You can configure Claude Desktop to use `python-substack` as an MCP server by adding it to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "substack": {
+      "command": "substack-mcp",
+      "env": {
+        "EMAIL": "your-email@example.com",
+        "PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+If you prefer to use session cookies instead of a password, use the `COOKIES_STRING` variable:
+
+```json
+{
+  "mcpServers": {
+    "substack": {
+      "command": "substack-mcp",
+      "env": {
+        "COOKIES_STRING": "cookie1=value1; cookie2=value2"
+      }
+    }
+  }
+}
+```

docs/releases/0.4.0.md

@@ -0,0 +1,22 @@
+---
+layout: default
+title: Release 0.4.0
+parent: Releases
+---
+
+# Release 0.4.0
+
+This release makes the optional MCP server significantly more useful for inspecting and preparing publications without steering agents toward immediate publishing.
+
+### Added
+
+- Seven new MCP tools for read operations and safe publishing: `get_status`, `list_publications`, `list_drafts`, `get_draft`, `schedule_draft`, `unschedule_draft`, and `publish_draft_checked`.
+- Pre-publish validation, interactive confirmation requirements, and no-email defaults for the new `publish_draft_checked` MCP tool.
+- Verified MCP client configuration examples in `docs/mcp.md`.
+- Documentation for Gemini CLI with Vertex AI (`docs/gemini-vertex-ai.md`).
+
+### Improved
+
+- Simplify MCP draft creation by routing through the existing `Api.create_draft_from_markdown` SDK helper, preserving response format.
+- Document the legacy `publish_draft` MCP tool as the compatibility interface.
+- Bump `cryptography` dependency from `48.0.1` to `50.0.0` (#68).

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-substack"
-version = "0.3.0"
+version = "0.4.0"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
 license = "MIT"

substack/__init__.py

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

substack_mcp/mcp_server.py

@@ -163,55 +163,24 @@ async def post_draft_from_markdown(
         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(
+    return client.create_draft_from_markdown(
         title=title,
-        subtitle=subtitle or "",
-        user_id=user_id,
+        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,
     )
 
-    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(
@@ -269,7 +238,11 @@ async def publish_draft(
     send: bool = True,
     share_automatically: bool = False,
 ) -> Dict[str, Any]:
-    """Publish a draft to live post state.
+    """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.
@@ -285,6 +258,126 @@ async def publish_draft(
     )
 
 
+@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")