list_published_posts

Instructions

Implementation Reference

• src/server.ts:28-51 (registration)

  Tool registration for list_published_posts via server.tool(). Defined with input schema (offset, limit) and async handler that calls client.getPublishedPosts().

  server.tool(
    "list_published_posts",
    "List published posts with pagination. Returns title, date, slug, and URL for each post.",
    {
      offset: z.number().optional().default(0).describe("Number of posts to skip"),
      limit: z.number().optional().default(25).describe("Max posts to return (1-100)"),
    },
    async ({ offset, limit }) => {
      const { posts, total } = await client.getPublishedPosts(offset, Math.min(limit, 100));
      const summary = posts.map((p) => ({
        id: p.id,
        title: p.title,
        subtitle: p.subtitle,
        slug: p.slug,
        post_date: p.post_date,
        audience: p.audience,
        word_count: p.word_count,
        url: p.canonical_url,
      }));
      return {
        content: [{ type: "text", text: JSON.stringify({ total, posts: summary }, null, 2) }],
      };
    },
  );

• src/server.ts:35-51 (handler)

  Handler logic for list_published_posts. Calls client.getPublishedPosts, maps results to summary objects (id, title, subtitle, slug, post_date, audience, word_count, url), and returns JSON response with total count.

    async ({ offset, limit }) => {
      const { posts, total } = await client.getPublishedPosts(offset, Math.min(limit, 100));
      const summary = posts.map((p) => ({
        id: p.id,
        title: p.title,
        subtitle: p.subtitle,
        slug: p.slug,
        post_date: p.post_date,
        audience: p.audience,
        word_count: p.word_count,
        url: p.canonical_url,
      }));
      return {
        content: [{ type: "text", text: JSON.stringify({ total, posts: summary }, null, 2) }],
      };
    },
  );

• src/server.ts:31-34 (schema)

  Input schema for list_published_posts using Zod: offset (optional, default 0) and limit (optional, default 25, capped at 100).

  {
    offset: z.number().optional().default(0).describe("Number of posts to skip"),
    limit: z.number().optional().default(25).describe("Max posts to return (1-100)"),
  },

• src/api/client.ts:95-103 (helper)

  API client method getPublishedPosts that calls Substack's /api/v1/post_management/published endpoint with offset/limit pagination, ordered by post_date descending. Returns posts array and total count.

  async getPublishedPosts(
    offset = 0,
    limit = 25,
  ): Promise<{ posts: SubstackPost[]; total: number }> {
    const data = await this.request<{ posts: SubstackPost[]; total: number; offset: number; limit: number }>(
      `${this.publicationUrl}/api/v1/post_management/published?offset=${offset}&limit=${limit}&order_by=post_date&order_direction=desc`,
    );
    return { posts: data.posts || [], total: data.total || 0 };
  }

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

  Type definition for SubstackPost used by getPublishedPosts return type and the summary mapping in the handler.

  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;
  }