list_drafts
Retrieve a list of recent unpublished drafts from your Substack publication, including post IDs, titles, and edit URLs, with an adjustable limit between 1 and 50.
Instructions
List recent drafts (unpublished posts).
Args: limit: Max number of drafts to return (1-50). Default 10.
Returns: List of draft summaries with post_id, title, edit_url, etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/substack_mcp/server.py:177-187 (handler)MCP tool handler for 'list_drafts'. Decorated with @mcp.tool(), accepts optional limit (default 10), delegates to SubstackClient.list_drafts().
@mcp.tool() def list_drafts(limit: int = 10) -> list[dict]: """List recent drafts (unpublished posts). Args: limit: Max number of drafts to return (1-50). Default 10. Returns: List of draft summaries with post_id, title, edit_url, etc. """ return _get_client().list_drafts(limit=limit) - src/substack_mcp/server.py:178-188 (schema)Inline schema for the tool: parameter 'limit' (int, default 10, validated 1-50 at client layer).
def list_drafts(limit: int = 10) -> list[dict]: """List recent drafts (unpublished posts). Args: limit: Max number of drafts to return (1-50). Default 10. Returns: List of draft summaries with post_id, title, edit_url, etc. """ return _get_client().list_drafts(limit=limit) - src/substack_mcp/server.py:177-177 (registration)Registration via @mcp.tool() decorator on the list_drafts function in server.py.
@mcp.tool() - src/substack_mcp/client.py:273-277 (handler)Client-side implementation of list_drafts. Validates limit (1-50), calls self._api.get_drafts(filter='draft', limit, offset=0), and summarizes each draft via _summarize_draft.
def list_drafts(self, limit: int = 10) -> list[dict]: if limit < 1 or limit > 50: raise ValueError("limit must be between 1 and 50") raw = self._api.get_drafts(filter="draft", limit=limit, offset=0) or [] return [self._summarize_draft(d) for d in raw] - src/substack_mcp/client.py:336-356 (helper)Helper _summarize_draft used by list_drafts to transform raw API draft dicts into summarized output (post_id, title, subtitle, audience, post_date, is_published, cover_image, edit_url).
def _summarize_draft(self, draft: dict, include_body: bool = False) -> dict: if not isinstance(draft, dict): return {"raw": draft} post_id = draft.get("id") out = { "post_id": str(post_id) if post_id is not None else None, "title": draft.get("draft_title") or draft.get("title"), "subtitle": draft.get("draft_subtitle") or draft.get("subtitle"), "audience": draft.get("audience"), "post_date": draft.get("post_date"), "is_published": draft.get("post_date") is not None, "cover_image": draft.get("cover_image"), "edit_url": ( f"{self.publication_url}/publish/post/{post_id}" if post_id else None ), } if include_body: out["draft_body"] = draft.get("draft_body") or draft.get("body") return out