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