substack-mcp

Instructions

Implementation Reference

• src/server.ts:220-244 (handler)

  The handler function that executes the update_draft tool logic. It accepts draft_id and optional fields (title, subtitle, body, audience), builds an updates object (converting markdown body to ProseMirror format), calls client.updateDraft(), and returns the updated draft information.

  async ({ draft_id, title, subtitle, body, audience }) => {
    const updates: Record<string, unknown> = {};
    if (title !== undefined) updates.draft_title = title;
    if (subtitle !== undefined) updates.draft_subtitle = subtitle;
    if (body !== undefined) updates.draft_body = markdownToProseMirror(body);
    if (audience !== undefined) updates.audience = audience;
  
    const draft = await client.updateDraft(draft_id, updates);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              id: draft.id,
              title: draft.draft_title,
              message: "Draft updated successfully.",
            },
            null,
            2,
          ),
        },
      ],
    };
  },

• src/server.ts:207-245 (registration)

  Registration of the update_draft tool with the MCP server. Includes the tool name, description, and Zod schema defining input parameters (draft_id, title, subtitle, body, audience) with their types and descriptions.

  server.tool(
    "update_draft",
    "Update an existing draft post. Only works on unpublished drafts. Accepts markdown body.",
    {
      draft_id: z.number().describe("The draft ID to update"),
      title: z.string().optional().describe("New title"),
      subtitle: z.string().optional().describe("New subtitle"),
      body: z.string().optional().describe("New body in markdown format"),
      audience: z
        .enum(["everyone", "only_paid", "founding", "only_free"])
        .optional()
        .describe("Who can see this post"),
    },
    async ({ draft_id, title, subtitle, body, audience }) => {
      const updates: Record<string, unknown> = {};
      if (title !== undefined) updates.draft_title = title;
      if (subtitle !== undefined) updates.draft_subtitle = subtitle;
      if (body !== undefined) updates.draft_body = markdownToProseMirror(body);
      if (audience !== undefined) updates.audience = audience;
  
      const draft = await client.updateDraft(draft_id, updates);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                id: draft.id,
                title: draft.draft_title,
                message: "Draft updated successfully.",
              },
              null,
              2,
            ),
          },
        ],
      };
    },
  );

• src/api/client.ts:148-159 (handler)

  The updateDraft method in SubstackClient that makes the actual PUT request to the Substack API endpoint /api/v1/drafts/{id} with the update payload.

  async updateDraft(
    id: number,
    updates: DraftUpdatePayload,
  ): Promise<SubstackDraft> {
    return this.request<SubstackDraft>(
      `${this.publicationUrl}/api/v1/drafts/${id}`,
      {
        method: "PUT",
        body: JSON.stringify(updates),
      },
    );
  }

• src/api/types.ts:63-70 (schema)

  TypeScript interface defining the DraftUpdatePayload structure with optional fields: draft_title, draft_subtitle, draft_body, audience, section_id, and cover_image.

  export interface DraftUpdatePayload {
    draft_title?: string;
    draft_subtitle?: string;
    draft_body?: string;
    audience?: "everyone" | "only_paid" | "founding" | "only_free";
    section_id?: number | null;
    cover_image?: string | null;
  }

• src/utils/markdown-to-prosemirror.ts:21-50 (helper)

  The markdownToProseMirror helper function that converts markdown text to ProseMirror JSON format. Used by the handler to convert the body parameter before sending to the API.

  export function markdownToProseMirror(markdown: string): string {
    const lines = markdown.split("\n");
    const nodes: PMNode[] = [];
    let i = 0;
  
    while (i < lines.length) {
      const line = lines[i];
  
      // Blank line — skip
      if (line.trim() === "") {
        i++;
        continue;
      }
  
      // Fenced code block
      if (line.trimStart().startsWith("```")) {
        const lang = line.trim().slice(3).trim();
        const codeLines: string[] = [];
        i++;
        while (i < lines.length && !lines[i].trimStart().startsWith("```")) {
          codeLines.push(lines[i]);
          i++;
        }
        i++; // skip closing ```
        nodes.push({
          type: "code_block",
          ...(lang ? { attrs: { lang } } : {}),
          content: [{ type: "text", text: codeLines.join("\n") }],
        });
        continue;