mastodon_create_toot
Post text content to Mastodon with options for visibility, media attachments, scheduling, and content warnings.
Instructions
Create a new toot (status) on Mastodon, optionally with media attachments
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The text content of the toot | |
| visibility | No | The visibility level of the toot | public |
| sensitive | No | Mark the toot as sensitive content | |
| spoiler_text | No | Text to be shown as a warning before the actual content | |
| media_file | No | Path to a media file to attach (image, video, or audio) | |
| media_description | No | Alt text / description for the attached media | |
| scheduled_at | No | Optional ISO 8601 datetime string to schedule the toot for a future time. Examples: 2024-01-01T10:00:00Z, 2024-01-01T10:00:00+01:00 |
Implementation Reference
- src/mastodon_tool.ts:106-160 (handler)The main handler function for the 'mastodon_create_toot' tool. It handles media upload if provided, calls the Mastodon API to create or schedule a toot, and formats a success response with link or schedule details.async (params: TootParams) => { let media_ids: string[] | undefined; if (params.media_file) { try { const fileData = await readFile(params.media_file); const media = await client.uploadMedia( fileData, params.media_file.split("/").pop() || "image", params.media_description ); media_ids = [media.id]; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; throw new Error(`Failed to upload media: ${errorMessage}`); } } const result = await client.createStatus({ status: params.content, visibility: params.visibility, sensitive: params.sensitive, spoiler_text: params.spoiler_text, media_ids, scheduled_at: params.scheduled_at, }); let successMessage: string; // Check if 'url' property exists to differentiate MastodonStatus from ScheduledMastodonStatus if ('url' in result) { // It's a MastodonStatus (posted immediately) const mediaInfo = result.media_attachments.length > 0 ? `\nMedia: ${result.media_attachments.map((m) => m.url).join(", ")}` : ""; successMessage = `Successfully created toot! View it at: ${result.url}${mediaInfo}`; } else { // It's a ScheduledMastodonStatus const scheduledTime = new Date(result.scheduled_at).toLocaleString(); let mediaInfo = ""; if (result.media_attachments && result.media_attachments.length > 0) { mediaInfo = `\nMedia will be attached: ${result.media_attachments.length} item(s).`; } successMessage = `Successfully scheduled toot! ID: ${result.id}. It will be posted at: ${scheduledTime}.${mediaInfo}`; } return { content: [ { type: "text", text: successMessage, }, ], }; }
- src/mastodon_tool.ts:7-34 (schema)Zod schema defining the input parameters and validation for the 'mastodon_create_toot' tool.const TootSchema = z.object({ content: z.string().describe("The text content of the toot"), visibility: z .enum(["public", "unlisted", "private", "direct"]) .describe("The visibility level of the toot") .default("public"), sensitive: z .boolean() .describe("Mark the toot as sensitive content") .default(false), spoiler_text: z .string() .describe("Text to be shown as a warning before the actual content") .default(""), media_file: z .string() .describe("Path to a media file to attach (image, video, or audio)") .optional(), media_description: z .string() .describe("Alt text / description for the attached media") .optional(), scheduled_at: z .string() .datetime({ offset: true, message: "Invalid datetime string, expected ISO 8601 format (e.g., YYYY-MM-DDTHH:mm:ss.sssZ, YYYY-MM-DDTHH:mm:ss.sss+HH:MM)" }) .describe("Optional ISO 8601 datetime string to schedule the toot for a future time. Examples: 2024-01-01T10:00:00Z, 2024-01-01T10:00:00+01:00") .optional(), });
- src/mastodon_tool.ts:102-161 (registration)Registration of the 'mastodon_create_toot' tool using server.tool(), including name, description, input schema, and handler function.server.tool( "mastodon_create_toot", "Create a new toot (status) on Mastodon, optionally with media attachments", TootSchema.shape, async (params: TootParams) => { let media_ids: string[] | undefined; if (params.media_file) { try { const fileData = await readFile(params.media_file); const media = await client.uploadMedia( fileData, params.media_file.split("/").pop() || "image", params.media_description ); media_ids = [media.id]; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; throw new Error(`Failed to upload media: ${errorMessage}`); } } const result = await client.createStatus({ status: params.content, visibility: params.visibility, sensitive: params.sensitive, spoiler_text: params.spoiler_text, media_ids, scheduled_at: params.scheduled_at, }); let successMessage: string; // Check if 'url' property exists to differentiate MastodonStatus from ScheduledMastodonStatus if ('url' in result) { // It's a MastodonStatus (posted immediately) const mediaInfo = result.media_attachments.length > 0 ? `\nMedia: ${result.media_attachments.map((m) => m.url).join(", ")}` : ""; successMessage = `Successfully created toot! View it at: ${result.url}${mediaInfo}`; } else { // It's a ScheduledMastodonStatus const scheduledTime = new Date(result.scheduled_at).toLocaleString(); let mediaInfo = ""; if (result.media_attachments && result.media_attachments.length > 0) { mediaInfo = `\nMedia will be attached: ${result.media_attachments.length} item(s).`; } successMessage = `Successfully scheduled toot! ID: ${result.id}. It will be posted at: ${scheduledTime}.${mediaInfo}`; } return { content: [ { type: "text", text: successMessage, }, ], }; } );