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

GEMINI.md

@@ -0,0 +1,55 @@
+# python-substack maintainer instructions
+
+## Project
+
+This repository is a Python 3.10+ library, CLI, and optional MCP server for
+creating and managing Substack drafts from Markdown. Poetry owns dependencies,
+packaging, scripts, and the lock file. The public package is `python-substack`.
+
+Read the relevant implementation, tests, and documentation before editing.
+Keep changes focused and preserve existing public interfaces, defaults, JSON
+keys, environment variables, console scripts, and MCP tool signatures through
+the 1.x series as required by `docs/compatibility.md`.
+
+## Development
+
+- Use the existing style and the simplest working implementation.
+- Add a regression test for every bug fix and offline tests for new behavior.
+- Update user-facing documentation and `CHANGELOG.md` for behavior changes.
+- Do not edit `poetry.lock` unless dependency declarations change.
+- Never expose or commit `.env` contents, passwords, cookies, credentials,
+  tokens, captured request headers, or local service-account files.
+- Preserve user changes in a dirty worktree. Do not reset, restore, or delete
+  unrelated work.
+
+Install and validate with:
+
+```bash
+poetry install --all-extras
+poetry run pytest -q -m "not live" --strict-markers
+poetry run pre-commit run --all-files
+```
+
+Live tests call Substack and create disposable drafts. Run them only after the
+maintainer explicitly authorizes the live operation and confirms suitable test
+credentials. Live tests must never publish, and their drafts must be removed.
+
+## Releases
+
+Follow `docs/releasing.md` exactly. Use `/release:prepare X.Y.Z` to prepare a
+candidate and `/release:verify` to validate it.
+
+- Keep both version files unchanged during ordinary development.
+- For a release candidate, synchronize `pyproject.toml` and
+  `substack/__init__.py`, prepend `CHANGELOG.md`, and add
+  `docs/releases/X.Y.Z.md` using only verified changes.
+- Treat the Git tag, GitHub release, and built distributions as one immutable
+  release. Never reuse a published version.
+- Do not commit, tag, push, create a GitHub release, publish to PyPI, run live
+  tests, or announce a release without explicit maintainer authorization for
+  that action.
+- Never bypass a failing check. Report the failure and preserve its output.
+- Publish only from the exact commit that passed CI, using tag `vX.Y.Z`.
+
+At handoff, state files changed, checks run, checks not run, and any external
+actions still requiring maintainer approval.

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/gemini-vertex-ai.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Gemini CLI with Vertex AI
+---
+
+# Gemini CLI with Vertex AI
+
+The repository includes project settings, maintainer instructions, and release
+commands for Gemini CLI. The project settings require Vertex AI authentication.
+Routine file edits, repository inspection, dependency setup, offline tests, and
+pre-commit checks are pre-approved. Commands that commit, tag, push, publish,
+or run live tests still require explicit approval.
+
+## Prerequisites
+
+- Node.js 20 or later.
+- Gemini CLI installed with `npm install -g @google/gemini-cli`.
+- Google Cloud CLI with Application Default Credentials (ADC).
+- A Google Cloud project with billing and the Vertex AI API enabled.
+- The Vertex AI User role (`roles/aiplatform.user`) on that project.
+
+Authenticate locally:
+
+```powershell
+gcloud auth application-default login
+gcloud services enable aiplatform.googleapis.com --project YOUR_PROJECT_ID
+```
+
+Copy the checked-in environment template and set the project and region:
+
+```powershell
+Copy-Item .gemini/.env.example .gemini/.env
+```
+
+`.gemini/.env` is ignored by Git. Do not put API keys or service-account JSON
+in the repository. ADC is preferred for local maintainer work.
+
+## Start Gemini
+
+Install the project dependencies, then start Gemini from the repository root:
+
+```powershell
+poetry install --all-extras
+gemini
+```
+
+Trust the folder when Gemini CLI asks so it can load the checked-in project
+settings and custom commands. Use `/memory show` to confirm `GEMINI.md` is
+loaded and `/commands list` to confirm the release commands are available.
+
+## Release workflow
+
+Prepare a candidate without publishing it:
+
+```text
+/release:prepare 0.4.0
+```
+
+Review the diff, then run the independent release verification:
+
+```text
+/release:verify
+```
+
+Both commands deliberately stop before live Substack tests, commits, tags,
+pushes, GitHub releases, PyPI publication, and announcements. Authorize those
+steps explicitly only after reviewing the candidate and confirming CI passed.

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__ = (