substack-mcp

Instructions

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) }],
      };
    },
  );