Skip to content

πŸ“¨ The ultimate agentic social media scheduling tool πŸ€–

feat: point MCP upload tools to the CLI and public API for private files

Gilad Resisi0992c460588d
diff --git a/libraries/nestjs-libraries/src/chat/tools/upload.from.url.tool.ts b/libraries/nestjs-libraries/src/chat/tools/upload.from.url.tool.ts
index 9ea693e33..c6778b7fa 100644
--- a/libraries/nestjs-libraries/src/chat/tools/upload.from.url.tool.ts
+++ b/libraries/nestjs-libraries/src/chat/tools/upload.from.url.tool.ts
@@ -13,7 +13,8 @@ export class UploadFromUrlTool implements AgentToolInterface {
run() {
return createTool({
id: 'uploadFromUrlTool',
- description: `Upload a remote image or video into the media library from a public URL.
+ description: `Upload a remote image or video into the media library from a public http(s) URL.
+Local or private files cannot be fetched by this tool: upload them with the Postiz CLI (postiz upload, https://docs.postiz.com/cli/introduction) or the public API (POST /public/v1/upload with an API key, https://docs.postiz.com/public-api/introduction).
Use this before scheduling a post when the user provides an external media URL (not already hosted on our domain),
so the attachment passes the upload-domain validation. Returns the hosted media { id, path } to use as an attachment (or as the src of an <img> in the content, when the channel rules say pictures go inside the content), or { error } on failure.`,
mcp: {
@@ -29,7 +30,9 @@ so the attachment passes the upload-domain validation. Returns the hosted media
url: z
.string()
.url()
- .describe('The public URL of the image or video to upload'),
+ .describe(
+ 'The public http(s) URL of the image or video to upload. Local files and private hosts are not supported, use the Postiz CLI (postiz upload) or POST /public/v1/upload instead'
+ ),
}),
// Mastra validates a tool's return against this schema, so it must also
// allow the graceful { error } shape. Fields are optional (rather than
@@ -68,7 +71,7 @@ so the attachment passes the upload-domain validation. Returns the hosted media
const causeText = causes.length ? ` (${causes.join(': ')})` : '';
return {
- error: `Failed to upload media from URL: ${message}${causeText}`,
+ error: `Failed to upload media from URL: ${message}${causeText}. Only public http(s) URLs work: upload local or private files with the Postiz CLI (postiz upload, https://docs.postiz.com/cli/introduction) or the public API (POST /public/v1/upload with an API key, https://docs.postiz.com/public-api/introduction)`,
};
}
},
diff --git a/libraries/nestjs-libraries/src/chat/tools/upload.widget.status.tool.ts b/libraries/nestjs-libraries/src/chat/tools/upload.widget.status.tool.ts
index ce32d1259..9b7584efd 100644
--- a/libraries/nestjs-libraries/src/chat/tools/upload.widget.status.tool.ts
+++ b/libraries/nestjs-libraries/src/chat/tools/upload.widget.status.tool.ts
@@ -15,6 +15,7 @@ export class UploadWidgetStatusTool implements AgentToolInterface {
return createTool({
id: 'uploadWidgetStatusTool',
description: `List the media the user uploaded with the upload widget, using the sessionId returned by uploadWidgetTool.
+It lists only the files uploaded in that widget session, not the whole media library.
An empty list means the user did not upload anything yet. A media with the status "processing" is still being prepared: wait about 10 seconds and call again.
A media with the status "ready" can be used as a post attachment with its { id, path }.`,
mcp: {
diff --git a/libraries/nestjs-libraries/src/chat/tools/upload.widget.tool.ts b/libraries/nestjs-libraries/src/chat/tools/upload.widget.tool.ts
index 826b927ad..a74a3901f 100644
--- a/libraries/nestjs-libraries/src/chat/tools/upload.widget.tool.ts
+++ b/libraries/nestjs-libraries/src/chat/tools/upload.widget.tool.ts
@@ -17,7 +17,7 @@ export class UploadWidgetTool implements AgentToolInterface {
id: 'uploadWidgetTool',
description: `Show the user an upload widget to add images or videos from their own device to the media library.
Use this when the user wants to attach a local file to a post. When the media is already available on a public URL, use uploadFromUrlTool instead.
-The widget is only displayed by apps that support MCP Apps (interactive UI); in any other app no widget appears and uploadFromUrlTool with a public URL is the way to add media.
+The widget is only displayed by apps that support MCP Apps (interactive UI); in any other app no widget appears, and local files go through the Postiz CLI (postiz upload, https://docs.postiz.com/cli/introduction) or the public API (POST /public/v1/upload with an API key, https://docs.postiz.com/public-api/introduction). uploadFromUrlTool is only for public URLs.
Returns a sessionId: the files the user uploads are reported in the conversation, and can also be read with uploadWidgetStatusTool.`,
mcp: {
annotations: {