substack-mcp

Instructions

Implementation Reference

• src/api/client.ts:117-121 (handler)

  The getPost method in SubstackClient class executes the core logic for the get_post tool. It makes an HTTP GET request to the Substack API endpoint /api/v1/posts/${id} and returns a SubstackPost object containing the full post content including title, body HTML, metadata, and other details.

  async getPost(id: number): Promise<SubstackPost> {
    return this.request<SubstackPost>(
      `${this.publicationUrl}/api/v1/posts/${id}`,
    );
  }

• src/server.ts:77-108 (registration)

  Registration of the get_post tool with the MCP server. Defines the tool name, description, input schema (post_id as a number using Zod validation), and the async handler function that calls client.getPost() and formats the response as JSON with post metadata including id, title, subtitle, slug, post_date, audience, word_count, body_html, and canonical_url.

  server.tool(
    "get_post",
    "Get the full content of a published post by ID. Returns title, body HTML, metadata.",
    {
      post_id: z.number().describe("The post ID to retrieve"),
    },
    async ({ post_id }) => {
      const post = await client.getPost(post_id);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                id: post.id,
                title: post.title,
                subtitle: post.subtitle,
                slug: post.slug,
                post_date: post.post_date,
                audience: post.audience,
                word_count: post.word_count,
                body_html: post.body_html,
                url: post.canonical_url,
              },
              null,
              2,
            ),
          },
        ],
      };
    },
  );

• src/api/types.ts:19-36 (schema)

  TypeScript interface definition for SubstackPost, which defines the schema/structure of the data returned by the get_post tool. Includes fields: id, title, subtitle, slug, post_date, audience, type, body_html, canonical_url, word_count, description, cover_image, and section_id.

  export interface SubstackPost {
    id: number;
    title: string;
    subtitle: string | null;
    slug: string;
    post_date: string | null;
    audience: string;
    type: string;
    draft_title?: string;
    draft_subtitle?: string;
    draft_body?: string;
    body_html?: string;
    canonical_url: string;
    word_count: number;
    description: string | null;
    cover_image: string | null;
    section_id: number | null;
  }