list_published_posts

Retrieve published posts with pagination to view titles, dates, slugs, and URLs for content management.

Instructions

List published posts with pagination. Returns title, date, slug, and URL for each post.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`offset`	No	Number of posts to skip
`limit`	No	Max posts to return (1-100)

Implementation Reference

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

Registration of the 'list_published_posts' tool using server.tool(), defining the tool name, description, input schema with zod, and the handler function

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-50 (handler)

The handler function for 'list_published_posts' that calls client.getPublishedPosts(), maps the results to a summary format with id, title, subtitle, slug, post_date, audience, word_count, and url, and returns the JSON response

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 definition using Zod: offset (optional number, default 0) and limit (optional number, default 25, max 100) for pagination

{
  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)

The getPublishedPosts method in SubstackClient that makes the actual HTTP request to Substack's /api/v1/post_management/published endpoint with pagination parameters

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)

TypeScript interface SubstackPost defining the structure of post data returned by the API (id, title, subtitle, slug, post_date, audience, type, canonical_url, word_count, etc.)

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

substack-mcp