list_drafts
Retrieve draft posts from Substack with titles, creation dates, and audience details for review and management.
Instructions
List draft posts. Returns title, creation date, and audience for each draft.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | Number of drafts to skip | |
| limit | No | Max drafts to return (1-100) |
Implementation Reference
- src/server.ts:60-74 (handler)The handler function for the list_drafts tool. Takes offset and limit parameters, calls client.getDrafts() to fetch drafts from the Substack API, maps the results to a summary format with id, title, subtitle, audience, word_count, created_at, and updated_at fields, and returns the JSON response.
async ({ offset, limit }) => { const drafts = await client.getDrafts(offset, Math.min(limit, 100)); const summary = drafts.map((d) => ({ id: d.id, title: d.draft_title, subtitle: d.draft_subtitle, audience: d.audience, word_count: d.word_count, created_at: d.draft_created_at, updated_at: d.draft_updated_at, })); return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }], }; }, - src/api/client.ts:105-109 (helper)The getDrafts method in SubstackClient class that makes the actual HTTP GET request to the Substack API endpoint /api/v1/drafts with offset and limit query parameters. Returns an array of SubstackDraft objects.
async getDrafts(offset = 0, limit = 25): Promise<SubstackDraft[]> { return this.request<SubstackDraft[]>( `${this.publicationUrl}/api/v1/drafts?offset=${offset}&limit=${limit}`, ); } - src/api/types.ts:38-51 (schema)TypeScript interface definition for SubstackDraft, defining the structure of draft objects returned by the API including id, draft_title, draft_subtitle, draft_body, draft_bylines, audience, type, word_count, cover_image, section_id, draft_created_at, and draft_updated_at fields.
export interface SubstackDraft { id: number; draft_title: string; draft_subtitle: string | null; draft_body: string | null; draft_bylines: Array<{ id: number; is_guest: boolean }>; audience: string; type: string; word_count: number; cover_image: string | null; section_id: number | null; draft_created_at: string; draft_updated_at: string; } - src/server.ts:53-75 (registration)Registration of the list_drafts tool with the MCP server. Defines the tool name, description, input schema using Zod (offset and limit parameters with defaults), and the async handler function.
server.tool( "list_drafts", "List draft posts. Returns title, creation date, and audience for each draft.", { offset: z.number().optional().default(0).describe("Number of drafts to skip"), limit: z.number().optional().default(25).describe("Max drafts to return (1-100)"), }, async ({ offset, limit }) => { const drafts = await client.getDrafts(offset, Math.min(limit, 100)); const summary = drafts.map((d) => ({ id: d.id, title: d.draft_title, subtitle: d.draft_subtitle, audience: d.audience, word_count: d.word_count, created_at: d.draft_created_at, updated_at: d.draft_updated_at, })); return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }], }; }, );