@dopost/mcp-server 1.0.1 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +66 -20
- package/bin/dopost-mcp.js +3 -0
- package/dist/api.d.ts +50 -7
- package/dist/api.js +163 -43
- package/dist/api.js.map +1 -1
- package/dist/download-types.d.ts +78 -0
- package/dist/download-types.js +7 -0
- package/dist/download-types.js.map +1 -0
- package/dist/index.js +8 -7
- package/dist/index.js.map +1 -1
- package/dist/server.d.ts +7 -0
- package/dist/server.js +22 -0
- package/dist/server.js.map +1 -0
- package/dist/tools.d.ts +6 -1
- package/dist/tools.js +1496 -102
- package/dist/tools.js.map +1 -1
- package/package.json +28 -7
package/dist/tools.js
CHANGED
|
@@ -1,89 +1,883 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
-
import {
|
|
3
|
-
|
|
2
|
+
import { readFile, stat } from "node:fs/promises";
|
|
3
|
+
import { basename } from "node:path";
|
|
4
|
+
import { asToolError, safePath } from "./api.js";
|
|
5
|
+
const analyticsPlatforms = [
|
|
6
|
+
"FACEBOOK",
|
|
7
|
+
"INSTAGRAM",
|
|
8
|
+
"INSTAGRAM_DIRECT",
|
|
9
|
+
"THREADS",
|
|
10
|
+
"PINTEREST",
|
|
11
|
+
"YOUTUBE",
|
|
12
|
+
"LINKEDIN",
|
|
13
|
+
"LINKEDIN_ORGANIZATION",
|
|
14
|
+
"BLUESKY",
|
|
15
|
+
"X",
|
|
16
|
+
"MASTODON",
|
|
17
|
+
"GOOGLE_BUSINESS",
|
|
18
|
+
];
|
|
19
|
+
const analyticsMetrics = [
|
|
20
|
+
"followers",
|
|
21
|
+
"followerGrowth",
|
|
22
|
+
"views",
|
|
23
|
+
"reach",
|
|
24
|
+
"engagements",
|
|
25
|
+
"likes",
|
|
26
|
+
"comments",
|
|
27
|
+
"shares",
|
|
28
|
+
"saves",
|
|
29
|
+
"impressions",
|
|
30
|
+
"clicks",
|
|
31
|
+
"profileViews",
|
|
32
|
+
"profileVisits",
|
|
33
|
+
"replies",
|
|
34
|
+
"reposts",
|
|
35
|
+
"quotes",
|
|
36
|
+
"reactions",
|
|
37
|
+
"pinClicks",
|
|
38
|
+
"outboundClicks",
|
|
39
|
+
"pinClickRate",
|
|
40
|
+
"outboundClickRate",
|
|
41
|
+
"saveRate",
|
|
42
|
+
"engagementRate",
|
|
43
|
+
"videoViews",
|
|
44
|
+
"engagedViews",
|
|
45
|
+
"watchTimeMin",
|
|
46
|
+
"avgViewDuration",
|
|
47
|
+
"averageViewPercentage",
|
|
48
|
+
"follows",
|
|
49
|
+
"unfollows",
|
|
50
|
+
"subscribersGained",
|
|
51
|
+
"subscribersLost",
|
|
52
|
+
"googleSearchDesktopImpressions",
|
|
53
|
+
"googleSearchMobileImpressions",
|
|
54
|
+
"googleMapsDesktopImpressions",
|
|
55
|
+
"googleMapsMobileImpressions",
|
|
56
|
+
"websiteClicks",
|
|
57
|
+
"callClicks",
|
|
58
|
+
"directionRequests",
|
|
59
|
+
"messagingClicks",
|
|
60
|
+
"bookings",
|
|
61
|
+
"menuClicks",
|
|
62
|
+
];
|
|
63
|
+
const analyticsFilterSchema = {
|
|
64
|
+
workspaceId: z
|
|
65
|
+
.string()
|
|
66
|
+
.optional()
|
|
67
|
+
.describe("Workspace ID from list_workspaces. Required for workspace-wide analytics when the connection has access to multiple workspaces; omit when accountId uniquely identifies the target"),
|
|
68
|
+
days: z
|
|
69
|
+
.number()
|
|
70
|
+
.int()
|
|
71
|
+
.min(1)
|
|
72
|
+
.max(732)
|
|
73
|
+
.optional()
|
|
74
|
+
.describe("Rolling day range. Defaults to 30"),
|
|
75
|
+
startDate: z
|
|
76
|
+
.string()
|
|
77
|
+
.optional()
|
|
78
|
+
.describe("Custom range start date (ISO 8601); requires endDate"),
|
|
79
|
+
endDate: z
|
|
80
|
+
.string()
|
|
81
|
+
.optional()
|
|
82
|
+
.describe("Custom range end date (ISO 8601); requires startDate"),
|
|
83
|
+
platform: z.enum(analyticsPlatforms).optional(),
|
|
84
|
+
accountId: z.string().optional(),
|
|
85
|
+
accountIds: z.array(z.string()).min(1).max(100).optional(),
|
|
86
|
+
groupId: z.string().optional(),
|
|
87
|
+
comparison: z
|
|
88
|
+
.enum(["previous", "none"])
|
|
89
|
+
.optional()
|
|
90
|
+
.describe('Defaults to "previous"'),
|
|
91
|
+
metrics: z.array(z.enum(analyticsMetrics)).min(1).optional(),
|
|
92
|
+
includeSeries: z
|
|
93
|
+
.boolean()
|
|
94
|
+
.optional()
|
|
95
|
+
.describe("Include daily series. Defaults to false and is limited to 90 days"),
|
|
96
|
+
};
|
|
97
|
+
const analyticsMetricOutputSchema = z.object({
|
|
98
|
+
key: z.enum(analyticsMetrics),
|
|
99
|
+
label: z.string(),
|
|
100
|
+
value: z.number().nullable(),
|
|
101
|
+
unit: z.string(),
|
|
102
|
+
aggregation: z.enum(["DAY", "WEEK", "MONTH", "POINT", "RANGE", "LIFETIME"]),
|
|
103
|
+
availability: z.enum(["available", "unavailable", "partial"]),
|
|
104
|
+
periodStart: z.string(),
|
|
105
|
+
periodEnd: z.string(),
|
|
106
|
+
comparison: z
|
|
107
|
+
.object({
|
|
108
|
+
value: z.number(),
|
|
109
|
+
change: z.number().nullable(),
|
|
110
|
+
changePercent: z.number().nullable(),
|
|
111
|
+
})
|
|
112
|
+
.nullable()
|
|
113
|
+
.optional(),
|
|
114
|
+
series: z.array(z.object({ date: z.string(), value: z.number() })).optional(),
|
|
115
|
+
});
|
|
116
|
+
const analyticsMetaOutputSchema = z.object({
|
|
117
|
+
requestedRange: z.object({ startDate: z.string(), endDate: z.string() }),
|
|
118
|
+
asOf: z.string(),
|
|
119
|
+
dataThrough: z.string().nullable(),
|
|
120
|
+
lastUpdatedAt: z.string().nullable(),
|
|
121
|
+
comparison: z.enum(["previous", "none"]),
|
|
122
|
+
comparisonCoverage: z.enum(["complete", "partial", "unavailable"]),
|
|
123
|
+
filters: z.object({
|
|
124
|
+
platform: z.string().optional(),
|
|
125
|
+
accountId: z.string().optional(),
|
|
126
|
+
accountIds: z.array(z.string()).optional(),
|
|
127
|
+
groupId: z.string().optional(),
|
|
128
|
+
metrics: z.array(z.enum(analyticsMetrics)).optional(),
|
|
129
|
+
}),
|
|
130
|
+
});
|
|
131
|
+
const analyticsPostOutputSchema = z.object({
|
|
132
|
+
postId: z.string(),
|
|
133
|
+
accountId: z.string(),
|
|
134
|
+
platform: z.string(),
|
|
135
|
+
username: z.string(),
|
|
136
|
+
caption: z.string().nullable(),
|
|
137
|
+
thumbnailUrl: z.string().nullable(),
|
|
138
|
+
publishedAt: z.string(),
|
|
139
|
+
dataThrough: z.string(),
|
|
140
|
+
providerLinkAvailable: z.boolean(),
|
|
141
|
+
metrics: z.array(analyticsMetricOutputSchema),
|
|
142
|
+
});
|
|
143
|
+
const insightReadinessOutputSchema = z.object({
|
|
144
|
+
analyzedPosts: z.number(),
|
|
145
|
+
requiredPosts: z.number(),
|
|
146
|
+
reason: z.enum(["no-posts", "collecting", "needs-variety", "ready"]),
|
|
147
|
+
});
|
|
148
|
+
const insightItemOutputSchema = z.object({
|
|
149
|
+
key: z.string(),
|
|
150
|
+
score: z.number(),
|
|
151
|
+
sampleSize: z.number(),
|
|
152
|
+
contributingMetricCount: z.number(),
|
|
153
|
+
startHour: z.number().optional(),
|
|
154
|
+
endHour: z.number().optional(),
|
|
155
|
+
weekday: z.number().optional(),
|
|
156
|
+
format: z.string().optional(),
|
|
157
|
+
platform: z.string().optional(),
|
|
158
|
+
successfulPosts: z.number().optional(),
|
|
159
|
+
analyzedPosts: z.number().optional(),
|
|
160
|
+
});
|
|
161
|
+
const insightSectionOutputSchema = z.object({
|
|
162
|
+
status: z.enum(["ready", "insufficient", "empty"]),
|
|
163
|
+
items: z.array(insightItemOutputSchema),
|
|
164
|
+
readiness: insightReadinessOutputSchema,
|
|
165
|
+
});
|
|
166
|
+
const platformOptionsSchema = z.object({
|
|
167
|
+
postType: z
|
|
168
|
+
.enum([
|
|
169
|
+
"feed",
|
|
170
|
+
"story",
|
|
171
|
+
"reel",
|
|
172
|
+
"carousel",
|
|
173
|
+
"standard",
|
|
174
|
+
"event",
|
|
175
|
+
"offer",
|
|
176
|
+
"media",
|
|
177
|
+
])
|
|
178
|
+
.optional()
|
|
179
|
+
.describe('Instagram: "feed" | "story" | "reel"; Google Business: "standard" | "event" | "offer" | "media"'),
|
|
180
|
+
shareToFeed: z
|
|
181
|
+
.boolean()
|
|
182
|
+
.optional()
|
|
183
|
+
.describe("Instagram Reels: also show the Reel in Feed"),
|
|
184
|
+
videoType: z
|
|
185
|
+
.enum(["video", "short"])
|
|
186
|
+
.optional()
|
|
187
|
+
.describe("YouTube video type"),
|
|
188
|
+
title: z.string().max(100).optional().describe("YouTube video title"),
|
|
189
|
+
privacyStatus: z
|
|
190
|
+
.enum(["public", "private", "unlisted"])
|
|
191
|
+
.optional()
|
|
192
|
+
.describe("YouTube video privacy"),
|
|
193
|
+
privacyLevel: z
|
|
194
|
+
.enum([
|
|
195
|
+
"PUBLIC_TO_EVERYONE",
|
|
196
|
+
"MUTUAL_FOLLOW_FRIENDS",
|
|
197
|
+
"FOLLOWER_OF_CREATOR",
|
|
198
|
+
"SELF_ONLY",
|
|
199
|
+
])
|
|
200
|
+
.optional()
|
|
201
|
+
.describe("TikTok privacy level"),
|
|
202
|
+
disableDuet: z.boolean().optional().describe("TikTok: disable duets"),
|
|
203
|
+
disableStitch: z.boolean().optional().describe("TikTok: disable stitches"),
|
|
204
|
+
disableComment: z.boolean().optional().describe("TikTok: disable comments"),
|
|
205
|
+
discloseContent: z
|
|
206
|
+
.boolean()
|
|
207
|
+
.optional()
|
|
208
|
+
.describe("TikTok: disclose promotional or branded content"),
|
|
209
|
+
isYourBrand: z
|
|
210
|
+
.boolean()
|
|
211
|
+
.optional()
|
|
212
|
+
.describe("TikTok disclosure: the post promotes your own brand"),
|
|
213
|
+
isBrandedContent: z
|
|
214
|
+
.boolean()
|
|
215
|
+
.optional()
|
|
216
|
+
.describe("TikTok disclosure: the post promotes a third-party brand"),
|
|
217
|
+
board: z.string().min(1).optional().describe("Pinterest board ID"),
|
|
218
|
+
pin: z
|
|
219
|
+
.boolean()
|
|
220
|
+
.optional()
|
|
221
|
+
.describe("Telegram: pin the published message or media album"),
|
|
222
|
+
communityId: z
|
|
223
|
+
.string()
|
|
224
|
+
.optional()
|
|
225
|
+
.describe("X: numeric Community ID or x.com Community URL"),
|
|
226
|
+
shareWithFollowers: z
|
|
227
|
+
.boolean()
|
|
228
|
+
.optional()
|
|
229
|
+
.describe("X Communities: also distribute the same Community Post to followers; defaults to true"),
|
|
230
|
+
ctaType: z
|
|
231
|
+
.enum(["book", "order", "shop", "learn_more", "sign_up", "call"])
|
|
232
|
+
.optional()
|
|
233
|
+
.describe("Google Business: call-to-action type"),
|
|
234
|
+
ctaUrl: z
|
|
235
|
+
.string()
|
|
236
|
+
.url()
|
|
237
|
+
.optional()
|
|
238
|
+
.describe("Google Business: public HTTP(S) CTA URL; omit for call"),
|
|
239
|
+
eventTitle: z
|
|
240
|
+
.string()
|
|
241
|
+
.max(58)
|
|
242
|
+
.optional()
|
|
243
|
+
.describe("Google Business event or offer title"),
|
|
244
|
+
eventStart: z
|
|
245
|
+
.string()
|
|
246
|
+
.datetime({ offset: true, local: true })
|
|
247
|
+
.optional()
|
|
248
|
+
.describe("Google Business event start: defaults to workspace timezone; an explicit offset is respected"),
|
|
249
|
+
eventEnd: z
|
|
250
|
+
.string()
|
|
251
|
+
.datetime({ offset: true, local: true })
|
|
252
|
+
.optional()
|
|
253
|
+
.describe("Google Business event end in the selected timezone"),
|
|
254
|
+
couponCode: z
|
|
255
|
+
.string()
|
|
256
|
+
.max(100)
|
|
257
|
+
.optional()
|
|
258
|
+
.describe("Google Business offer coupon"),
|
|
259
|
+
redeemOnlineUrl: z
|
|
260
|
+
.string()
|
|
261
|
+
.url()
|
|
262
|
+
.optional()
|
|
263
|
+
.describe("Google Business offer redemption URL"),
|
|
264
|
+
termsConditions: z
|
|
265
|
+
.string()
|
|
266
|
+
.max(5000)
|
|
267
|
+
.optional()
|
|
268
|
+
.describe("Google Business offer terms"),
|
|
269
|
+
mediaCategory: z
|
|
270
|
+
.enum([
|
|
271
|
+
"ADDITIONAL",
|
|
272
|
+
"COVER",
|
|
273
|
+
"PROFILE",
|
|
274
|
+
"LOGO",
|
|
275
|
+
"EXTERIOR",
|
|
276
|
+
"INTERIOR",
|
|
277
|
+
"PRODUCT",
|
|
278
|
+
"AT_WORK",
|
|
279
|
+
"FOOD_AND_DRINK",
|
|
280
|
+
"MENU",
|
|
281
|
+
"COMMON_AREA",
|
|
282
|
+
"ROOMS",
|
|
283
|
+
"TEAMS",
|
|
284
|
+
])
|
|
285
|
+
.optional()
|
|
286
|
+
.describe("Google Business profile media category"),
|
|
287
|
+
});
|
|
288
|
+
const publishPlatformOptionsSchema = platformOptionsSchema.extend({
|
|
289
|
+
communityName: z
|
|
290
|
+
.string()
|
|
291
|
+
.min(1)
|
|
292
|
+
.optional()
|
|
293
|
+
.describe("X: name of a saved Community returned by list_x_communities. The MCP server resolves its ID internally"),
|
|
294
|
+
});
|
|
295
|
+
const downloadFormatOutputSchema = z.object({
|
|
296
|
+
id: z.string(),
|
|
297
|
+
label: z.string(),
|
|
298
|
+
container: z.enum(["mp4", "mp3"]),
|
|
299
|
+
hasVideo: z.boolean(),
|
|
300
|
+
hasAudio: z.boolean(),
|
|
301
|
+
height: z.number().optional(),
|
|
302
|
+
bitrateKbps: z.number().optional(),
|
|
303
|
+
sizeBytes: z.number().optional(),
|
|
304
|
+
downloadUrl: z.string(),
|
|
305
|
+
expiresAt: z.string(),
|
|
306
|
+
});
|
|
307
|
+
const downloadInfoOutputSchema = z.object({
|
|
308
|
+
platform: z.enum(["youtube", "instagram", "tiktok"]),
|
|
309
|
+
sourceUrl: z.string(),
|
|
310
|
+
title: z.string(),
|
|
311
|
+
thumbnailUrl: z.string().nullable(),
|
|
312
|
+
durationSeconds: z.number().nullable(),
|
|
313
|
+
authorName: z.string().nullable(),
|
|
314
|
+
formats: z.array(downloadFormatOutputSchema),
|
|
315
|
+
});
|
|
316
|
+
const xCommunityOutputSchema = z.object({
|
|
317
|
+
name: z.string(),
|
|
318
|
+
description: z.string().optional(),
|
|
319
|
+
thumbnailUrl: z.string().optional(),
|
|
320
|
+
isValid: z.boolean(),
|
|
321
|
+
lastError: z.string().optional(),
|
|
322
|
+
communityId: z.string().optional(),
|
|
323
|
+
});
|
|
324
|
+
const publishContentFields = {
|
|
325
|
+
text: z.string().optional().describe("Post text content"),
|
|
326
|
+
media: z
|
|
327
|
+
.array(z.string().url())
|
|
328
|
+
.max(10)
|
|
329
|
+
.optional()
|
|
330
|
+
.describe("Up to 10 public HTTPS media URLs. External files are copied to dopost storage and validated against the destination requirements before publishing or scheduling"),
|
|
331
|
+
replyTo: z
|
|
332
|
+
.string()
|
|
333
|
+
.min(1)
|
|
334
|
+
.max(200)
|
|
335
|
+
.optional()
|
|
336
|
+
.describe("External platform post ID to reply to. Supported for X and Threads; this is not a dopost post ID"),
|
|
337
|
+
thread: z
|
|
338
|
+
.array(z.object({
|
|
339
|
+
text: z.string().min(1).describe("Text for this follow-up post"),
|
|
340
|
+
media: z
|
|
341
|
+
.array(z.string().url())
|
|
342
|
+
.max(4)
|
|
343
|
+
.optional()
|
|
344
|
+
.describe("Optional public media URLs for this follow-up post"),
|
|
345
|
+
}))
|
|
346
|
+
.min(1)
|
|
347
|
+
.max(20)
|
|
348
|
+
.optional()
|
|
349
|
+
.describe("Ordered follow-up posts. Supported for X, Threads, and Mastodon; each item replies to the previous one"),
|
|
350
|
+
platformOptions: publishPlatformOptionsSchema
|
|
351
|
+
.optional()
|
|
352
|
+
.describe("Platform-specific options. Only include keys relevant to the target platform. " +
|
|
353
|
+
"Instagram: postType, shareToFeed. TikTok: privacyLevel, disableDuet, disableStitch, disableComment, discloseContent, isYourBrand, isBrandedContent. " +
|
|
354
|
+
"YouTube: videoType, title, privacyStatus. Pinterest: board. " +
|
|
355
|
+
"Telegram: pin. X Communities: communityName (preferred), communityId, shareWithFollowers. " +
|
|
356
|
+
"Google Business: postType, ctaType, ctaUrl, eventTitle, eventStart, eventEnd, couponCode, redeemOnlineUrl, termsConditions, mediaCategory."),
|
|
357
|
+
};
|
|
358
|
+
async function resolvePublishOptions(client, accountId, options) {
|
|
359
|
+
const name = options?.communityName?.trim();
|
|
360
|
+
if (!name)
|
|
361
|
+
return options;
|
|
362
|
+
if (options?.communityId)
|
|
363
|
+
throw new Error("Use either communityName or communityId, not both.");
|
|
364
|
+
const catalog = await client.requestRaw("GET", `/api/v1/social/accounts/${safePath(accountId)}/x-communities`);
|
|
365
|
+
const communities = Array.isArray(catalog.communities)
|
|
366
|
+
? catalog.communities
|
|
367
|
+
: [];
|
|
368
|
+
const matches = communities.filter((value) => {
|
|
369
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
370
|
+
return false;
|
|
371
|
+
const community = value;
|
|
372
|
+
return (community.isValid !== false &&
|
|
373
|
+
typeof community.name === "string" &&
|
|
374
|
+
community.name.localeCompare(name, undefined, { sensitivity: "base" }) ===
|
|
375
|
+
0 &&
|
|
376
|
+
typeof community.communityId === "string");
|
|
377
|
+
});
|
|
378
|
+
if (matches.length !== 1)
|
|
379
|
+
throw new Error(matches.length === 0
|
|
380
|
+
? `No valid saved X Community is named "${name}". Call list_x_communities and choose one of the returned names.`
|
|
381
|
+
: `More than one saved X Community is named "${name}". Use communityId to disambiguate.`);
|
|
382
|
+
const { communityName: _name, ...rest } = options;
|
|
383
|
+
return { ...rest, communityId: matches[0].communityId };
|
|
384
|
+
}
|
|
385
|
+
export function registerTools(server, client, options = {}) {
|
|
386
|
+
// ── Public social media downloads ────────────────────────────────
|
|
387
|
+
server.registerTool("get_social_media_download_options", {
|
|
388
|
+
title: "Get Social Media Download Options",
|
|
389
|
+
description: "Get the MP4 and MP3 download options available for a public YouTube, Instagram, or TikTok URL. " +
|
|
390
|
+
"This public tool does not require a dopost API key. Download URLs are temporary. " +
|
|
391
|
+
"Only download content you own or have permission to use.",
|
|
392
|
+
annotations: {
|
|
393
|
+
readOnlyHint: true,
|
|
394
|
+
destructiveHint: false,
|
|
395
|
+
idempotentHint: true,
|
|
396
|
+
openWorldHint: true,
|
|
397
|
+
},
|
|
398
|
+
inputSchema: {
|
|
399
|
+
url: z
|
|
400
|
+
.string()
|
|
401
|
+
.url()
|
|
402
|
+
.describe("Public YouTube, Instagram, or TikTok media URL"),
|
|
403
|
+
mode: z
|
|
404
|
+
.enum(["video", "audio", "both"])
|
|
405
|
+
.optional()
|
|
406
|
+
.describe('Return video formats, audio formats, or both. Defaults to "both"'),
|
|
407
|
+
},
|
|
408
|
+
outputSchema: {
|
|
409
|
+
data: downloadInfoOutputSchema,
|
|
410
|
+
message: z.string().optional(),
|
|
411
|
+
},
|
|
412
|
+
}, async ({ url, mode }) => {
|
|
413
|
+
try {
|
|
414
|
+
const result = await client.publicRequestRaw("POST", "/api/v1/public/social-media/downloads", { url, mode: mode || "both" });
|
|
415
|
+
return structuredToolResult(result);
|
|
416
|
+
}
|
|
417
|
+
catch (error) {
|
|
418
|
+
return toolError(error instanceof Error
|
|
419
|
+
? error.message
|
|
420
|
+
: "Could not load the available download options.");
|
|
421
|
+
}
|
|
422
|
+
});
|
|
423
|
+
server.registerTool("prepare_social_media_download", {
|
|
424
|
+
title: "Prepare Social Media Download",
|
|
425
|
+
description: "Prepare one temporary download URL for public YouTube, Instagram, or TikTok media. " +
|
|
426
|
+
"Select MP4 or MP3 and optionally request a video height or audio bitrate. " +
|
|
427
|
+
"The closest available option is used when the exact quality is unavailable. " +
|
|
428
|
+
"This tool does not download binary data into the conversation and does not require a dopost API key.",
|
|
429
|
+
annotations: {
|
|
430
|
+
readOnlyHint: true,
|
|
431
|
+
destructiveHint: false,
|
|
432
|
+
idempotentHint: true,
|
|
433
|
+
openWorldHint: true,
|
|
434
|
+
},
|
|
435
|
+
inputSchema: {
|
|
436
|
+
url: z
|
|
437
|
+
.string()
|
|
438
|
+
.url()
|
|
439
|
+
.describe("Public YouTube, Instagram, or TikTok media URL"),
|
|
440
|
+
format: z
|
|
441
|
+
.enum(["mp4", "mp3"])
|
|
442
|
+
.optional()
|
|
443
|
+
.describe('Output container. Defaults to "mp4"'),
|
|
444
|
+
quality: z
|
|
445
|
+
.number()
|
|
446
|
+
.int()
|
|
447
|
+
.min(144)
|
|
448
|
+
.max(4320)
|
|
449
|
+
.optional()
|
|
450
|
+
.describe("Preferred MP4 height in pixels, for example 720 or 1080"),
|
|
451
|
+
audioBitrateKbps: z
|
|
452
|
+
.number()
|
|
453
|
+
.int()
|
|
454
|
+
.min(64)
|
|
455
|
+
.max(320)
|
|
456
|
+
.optional()
|
|
457
|
+
.describe("Preferred MP3 bitrate in kbps, for example 192 or 320"),
|
|
458
|
+
},
|
|
459
|
+
outputSchema: {
|
|
460
|
+
platform: z.enum(["youtube", "instagram", "tiktok"]),
|
|
461
|
+
sourceUrl: z.string(),
|
|
462
|
+
title: z.string(),
|
|
463
|
+
thumbnailUrl: z.string().nullable(),
|
|
464
|
+
authorName: z.string().nullable(),
|
|
465
|
+
durationSeconds: z.number().nullable(),
|
|
466
|
+
format: downloadFormatOutputSchema,
|
|
467
|
+
note: z.string(),
|
|
468
|
+
},
|
|
469
|
+
}, async ({ url, format = "mp4", quality, audioBitrateKbps }) => {
|
|
470
|
+
try {
|
|
471
|
+
const raw = await client.publicRequestRaw("POST", "/api/v1/public/social-media/downloads", { url, mode: format === "mp3" ? "audio" : "video" });
|
|
472
|
+
const response = raw;
|
|
473
|
+
const candidates = response.data?.formats?.filter((candidate) => candidate.container === format);
|
|
474
|
+
if (!candidates?.length) {
|
|
475
|
+
throw new Error(`No ${format.toUpperCase()} format is available.`);
|
|
476
|
+
}
|
|
477
|
+
const preferredValue = format === "mp4" ? quality : audioBitrateKbps;
|
|
478
|
+
const selected = selectClosestFormat(candidates, preferredValue, format);
|
|
479
|
+
return structuredToolResult({
|
|
480
|
+
platform: response.data.platform,
|
|
481
|
+
sourceUrl: response.data.sourceUrl,
|
|
482
|
+
title: response.data.title,
|
|
483
|
+
thumbnailUrl: response.data.thumbnailUrl,
|
|
484
|
+
authorName: response.data.authorName,
|
|
485
|
+
durationSeconds: response.data.durationSeconds,
|
|
486
|
+
format: selected,
|
|
487
|
+
note: "The download URL is temporary. Open it before expiresAt.",
|
|
488
|
+
});
|
|
489
|
+
}
|
|
490
|
+
catch (err) {
|
|
491
|
+
return {
|
|
492
|
+
content: [
|
|
493
|
+
{
|
|
494
|
+
type: "text",
|
|
495
|
+
text: `Could not prepare the download: ${err instanceof Error ? err.message : String(err)}`,
|
|
496
|
+
},
|
|
497
|
+
],
|
|
498
|
+
isError: true,
|
|
499
|
+
};
|
|
500
|
+
}
|
|
501
|
+
});
|
|
502
|
+
// ── Analytics ────────────────────────────────────────────────────
|
|
503
|
+
server.registerTool("get_analytics_overview", {
|
|
504
|
+
title: "Get Analytics Overview",
|
|
505
|
+
description: "Read canonical account KPIs, account and platform rankings, coverage, comparisons, and freshness. " +
|
|
506
|
+
"Requires analytics:read and an active paid plan.",
|
|
507
|
+
annotations: {
|
|
508
|
+
readOnlyHint: true,
|
|
509
|
+
destructiveHint: false,
|
|
510
|
+
idempotentHint: true,
|
|
511
|
+
openWorldHint: false,
|
|
512
|
+
},
|
|
513
|
+
inputSchema: analyticsFilterSchema,
|
|
514
|
+
outputSchema: {
|
|
515
|
+
overview: z.object({
|
|
516
|
+
metrics: z.array(analyticsMetricOutputSchema),
|
|
517
|
+
accounts: z.array(z.object({
|
|
518
|
+
rank: z.number(),
|
|
519
|
+
accountId: z.string(),
|
|
520
|
+
platform: z.string(),
|
|
521
|
+
username: z.string(),
|
|
522
|
+
score: z.number().nullable(),
|
|
523
|
+
metrics: z.array(analyticsMetricOutputSchema),
|
|
524
|
+
})),
|
|
525
|
+
platforms: z.array(z.object({
|
|
526
|
+
rank: z.number(),
|
|
527
|
+
platform: z.string(),
|
|
528
|
+
accountCount: z.number(),
|
|
529
|
+
score: z.number().nullable(),
|
|
530
|
+
metrics: z.array(analyticsMetricOutputSchema),
|
|
531
|
+
})),
|
|
532
|
+
}),
|
|
533
|
+
meta: analyticsMetaOutputSchema,
|
|
534
|
+
},
|
|
535
|
+
}, async (input) => {
|
|
536
|
+
const validation = validateAnalyticsToolRange(input.days, input.startDate, input.endDate, input.includeSeries);
|
|
537
|
+
if (validation)
|
|
538
|
+
return validation;
|
|
539
|
+
return analyticsRequest(client, `/api/v1/analytics/overview?${analyticsQuery(input)}`);
|
|
540
|
+
});
|
|
541
|
+
server.registerTool("get_google_business_search_terms", {
|
|
542
|
+
title: "Get Google Business Search Terms",
|
|
543
|
+
description: "Read stored monthly search keywords for Google Business locations. Months touched by the range are included in full. Preserve privacy thresholds; these are location discovery data, not per-post metrics. Requires analytics:read and an active paid plan.",
|
|
544
|
+
annotations: {
|
|
545
|
+
readOnlyHint: true,
|
|
546
|
+
destructiveHint: false,
|
|
547
|
+
idempotentHint: true,
|
|
548
|
+
openWorldHint: false,
|
|
549
|
+
},
|
|
550
|
+
inputSchema: {
|
|
551
|
+
workspaceId: analyticsFilterSchema.workspaceId,
|
|
552
|
+
days: analyticsFilterSchema.days,
|
|
553
|
+
startDate: analyticsFilterSchema.startDate,
|
|
554
|
+
endDate: analyticsFilterSchema.endDate,
|
|
555
|
+
accountId: analyticsFilterSchema.accountId,
|
|
556
|
+
accountIds: analyticsFilterSchema.accountIds,
|
|
557
|
+
groupId: analyticsFilterSchema.groupId,
|
|
558
|
+
limit: z.number().int().min(1).max(100).optional(),
|
|
559
|
+
cursor: z.string().max(256).optional(),
|
|
560
|
+
},
|
|
561
|
+
outputSchema: {
|
|
562
|
+
searchTerms: z.array(z.object({
|
|
563
|
+
accountId: z.string(),
|
|
564
|
+
username: z.string(),
|
|
565
|
+
month: z.string(),
|
|
566
|
+
keyword: z.string(),
|
|
567
|
+
value: z.number().nullable(),
|
|
568
|
+
threshold: z.number().nullable(),
|
|
569
|
+
})),
|
|
570
|
+
nextCursor: z.string().nullable(),
|
|
571
|
+
hasMore: z.boolean(),
|
|
572
|
+
meta: analyticsMetaOutputSchema.extend({
|
|
573
|
+
aggregation: z.literal("MONTH"),
|
|
574
|
+
monthlyRange: z.object({
|
|
575
|
+
startMonth: z.string(),
|
|
576
|
+
endMonth: z.string(),
|
|
577
|
+
}),
|
|
578
|
+
total: z.number(),
|
|
579
|
+
}),
|
|
580
|
+
},
|
|
581
|
+
}, async (input) => {
|
|
582
|
+
const validation = validateAnalyticsToolRange(input.days, input.startDate, input.endDate, false);
|
|
583
|
+
if (validation)
|
|
584
|
+
return validation;
|
|
585
|
+
const params = analyticsQuery(input);
|
|
586
|
+
if (input.limit !== undefined)
|
|
587
|
+
params.set("limit", String(input.limit));
|
|
588
|
+
if (input.cursor)
|
|
589
|
+
params.set("cursor", input.cursor);
|
|
590
|
+
return analyticsRequest(client, `/api/v1/analytics/search-terms?${params}`);
|
|
591
|
+
});
|
|
592
|
+
server.registerTool("list_post_performance", {
|
|
593
|
+
title: "List Post Performance",
|
|
594
|
+
description: "List analytics for posts published through dopost, sorted by a supported performance metric. " +
|
|
595
|
+
"Returns posts with available analytics. Requires analytics:read.",
|
|
596
|
+
annotations: {
|
|
597
|
+
readOnlyHint: true,
|
|
598
|
+
destructiveHint: false,
|
|
599
|
+
idempotentHint: true,
|
|
600
|
+
openWorldHint: false,
|
|
601
|
+
},
|
|
602
|
+
inputSchema: {
|
|
603
|
+
...analyticsFilterSchema,
|
|
604
|
+
sortBy: z
|
|
605
|
+
.enum([
|
|
606
|
+
"overall",
|
|
607
|
+
"likes",
|
|
608
|
+
"engagements",
|
|
609
|
+
"comments",
|
|
610
|
+
"reach",
|
|
611
|
+
"views",
|
|
612
|
+
"shares",
|
|
613
|
+
"saves",
|
|
614
|
+
])
|
|
615
|
+
.optional(),
|
|
616
|
+
limit: z
|
|
617
|
+
.number()
|
|
618
|
+
.int()
|
|
619
|
+
.min(1)
|
|
620
|
+
.max(20)
|
|
621
|
+
.optional()
|
|
622
|
+
.describe("Results per call. Defaults to 20"),
|
|
623
|
+
cursor: z.string().optional(),
|
|
624
|
+
},
|
|
625
|
+
outputSchema: {
|
|
626
|
+
posts: z.array(analyticsPostOutputSchema),
|
|
627
|
+
nextCursor: z.string().nullable(),
|
|
628
|
+
hasMore: z.boolean(),
|
|
629
|
+
meta: analyticsMetaOutputSchema.extend({
|
|
630
|
+
counts: z.object({ eligible: z.number(), analyzed: z.number() }),
|
|
631
|
+
}),
|
|
632
|
+
},
|
|
633
|
+
}, async (input) => {
|
|
634
|
+
const validation = validateAnalyticsToolRange(input.days, input.startDate, input.endDate, input.includeSeries);
|
|
635
|
+
if (validation)
|
|
636
|
+
return validation;
|
|
637
|
+
const params = analyticsQuery(input);
|
|
638
|
+
if (input.sortBy)
|
|
639
|
+
params.set("sortBy", input.sortBy);
|
|
640
|
+
params.set("limit", String(input.limit ?? 20));
|
|
641
|
+
if (input.cursor)
|
|
642
|
+
params.set("cursor", input.cursor);
|
|
643
|
+
return analyticsRequest(client, `/api/v1/analytics/posts?${params}`);
|
|
644
|
+
});
|
|
645
|
+
server.registerTool("get_post_performance", {
|
|
646
|
+
title: "Get Post Performance",
|
|
647
|
+
description: "Read current metrics, cumulative snapshots, collection progress, and external-link availability for one dopost post. Requires analytics:read.",
|
|
648
|
+
annotations: {
|
|
649
|
+
readOnlyHint: true,
|
|
650
|
+
destructiveHint: false,
|
|
651
|
+
idempotentHint: true,
|
|
652
|
+
openWorldHint: false,
|
|
653
|
+
},
|
|
654
|
+
inputSchema: { postId: z.string().min(1).describe("dopost post ID") },
|
|
655
|
+
outputSchema: {
|
|
656
|
+
post: analyticsPostOutputSchema.extend({
|
|
657
|
+
finalizedAt: z.string().nullable(),
|
|
658
|
+
collection: z.object({
|
|
659
|
+
state: z.enum(["awaiting", "collecting", "finalized"]),
|
|
660
|
+
completedCheckpoints: z.number(),
|
|
661
|
+
totalCheckpoints: z.number(),
|
|
662
|
+
}),
|
|
663
|
+
snapshots: z.array(z.object({
|
|
664
|
+
observedAt: z.string(),
|
|
665
|
+
elapsedHours: z.number(),
|
|
666
|
+
metrics: z.array(analyticsMetricOutputSchema),
|
|
667
|
+
})),
|
|
668
|
+
}),
|
|
669
|
+
meta: z.object({
|
|
670
|
+
asOf: z.string(),
|
|
671
|
+
lastUpdatedAt: z.string().nullable(),
|
|
672
|
+
}),
|
|
673
|
+
},
|
|
674
|
+
}, async ({ postId }) => analyticsRequest(client, `/api/v1/analytics/posts/${safePath(postId)}`));
|
|
675
|
+
server.registerTool("get_content_insights", {
|
|
676
|
+
title: "Get Content Insights",
|
|
677
|
+
description: "Read Best Time, Best Day, Format Opportunity, and Platform Pulse with readiness and sample counts. " +
|
|
678
|
+
"Insufficient samples are returned as readiness state, not a tool error. Requires analytics:read.",
|
|
679
|
+
annotations: {
|
|
680
|
+
readOnlyHint: true,
|
|
681
|
+
destructiveHint: false,
|
|
682
|
+
idempotentHint: true,
|
|
683
|
+
openWorldHint: false,
|
|
684
|
+
},
|
|
685
|
+
inputSchema: analyticsFilterSchema,
|
|
686
|
+
outputSchema: {
|
|
687
|
+
insights: z.object({
|
|
688
|
+
timezone: z.string(),
|
|
689
|
+
bestTime: insightSectionOutputSchema,
|
|
690
|
+
bestDay: insightSectionOutputSchema,
|
|
691
|
+
formatOpportunity: insightSectionOutputSchema,
|
|
692
|
+
platformPulse: insightSectionOutputSchema,
|
|
693
|
+
}),
|
|
694
|
+
meta: analyticsMetaOutputSchema,
|
|
695
|
+
},
|
|
696
|
+
}, async (input) => {
|
|
697
|
+
const validation = validateAnalyticsToolRange(input.days, input.startDate, input.endDate, input.includeSeries);
|
|
698
|
+
if (validation)
|
|
699
|
+
return validation;
|
|
700
|
+
return analyticsRequest(client, `/api/v1/analytics/insights?${analyticsQuery(input)}`);
|
|
701
|
+
});
|
|
702
|
+
server.registerTool("get_audience_analytics", {
|
|
703
|
+
title: "Get Audience Analytics",
|
|
704
|
+
description: "Read the available audience breakdowns for one account. Requires analytics:read.",
|
|
705
|
+
annotations: {
|
|
706
|
+
readOnlyHint: true,
|
|
707
|
+
destructiveHint: false,
|
|
708
|
+
idempotentHint: true,
|
|
709
|
+
openWorldHint: false,
|
|
710
|
+
},
|
|
711
|
+
inputSchema: {
|
|
712
|
+
accountId: z.string().min(1),
|
|
713
|
+
metric: z
|
|
714
|
+
.enum([
|
|
715
|
+
"followerDemographics",
|
|
716
|
+
"engagedAudienceDemographics",
|
|
717
|
+
"pageFansLocale",
|
|
718
|
+
"pageFansCity",
|
|
719
|
+
"pageFansCountry",
|
|
720
|
+
])
|
|
721
|
+
.optional(),
|
|
722
|
+
dimension: z
|
|
723
|
+
.enum(["age", "city", "country", "gender", "locale"])
|
|
724
|
+
.optional(),
|
|
725
|
+
timeframe: z.enum(["this_week", "this_month", "day"]).optional(),
|
|
726
|
+
days: z.number().int().min(1).max(732).optional(),
|
|
727
|
+
startDate: z.string().optional(),
|
|
728
|
+
endDate: z.string().optional(),
|
|
729
|
+
},
|
|
730
|
+
outputSchema: {
|
|
731
|
+
audience: z.object({
|
|
732
|
+
accountId: z.string(),
|
|
733
|
+
platform: z.string(),
|
|
734
|
+
metric: z.string(),
|
|
735
|
+
snapshots: z.array(z.object({
|
|
736
|
+
observedAt: z.string(),
|
|
737
|
+
timeframe: z.string(),
|
|
738
|
+
dimension: z.string(),
|
|
739
|
+
availability: z.enum(["available", "unavailable"]),
|
|
740
|
+
values: z.array(z.object({ label: z.string(), value: z.number() })),
|
|
741
|
+
})),
|
|
742
|
+
}),
|
|
743
|
+
meta: analyticsMetaOutputSchema,
|
|
744
|
+
},
|
|
745
|
+
}, async (input) => {
|
|
746
|
+
const validation = validateAnalyticsToolRange(input.days, input.startDate, input.endDate, false);
|
|
747
|
+
if (validation)
|
|
748
|
+
return validation;
|
|
749
|
+
const params = new URLSearchParams({ accountId: input.accountId });
|
|
750
|
+
if (input.metric)
|
|
751
|
+
params.set("metric", input.metric);
|
|
752
|
+
if (input.dimension)
|
|
753
|
+
params.set("dimension", input.dimension);
|
|
754
|
+
if (input.timeframe)
|
|
755
|
+
params.set("timeframe", input.timeframe);
|
|
756
|
+
if (input.days)
|
|
757
|
+
params.set("days", String(input.days));
|
|
758
|
+
if (input.startDate)
|
|
759
|
+
params.set("startDate", input.startDate);
|
|
760
|
+
if (input.endDate)
|
|
761
|
+
params.set("endDate", input.endDate);
|
|
762
|
+
return analyticsRequest(client, `/api/v1/analytics/audience?${params}`);
|
|
763
|
+
});
|
|
4
764
|
// ── Post ──────────────────────────────────────────────────────────
|
|
5
765
|
server.registerTool("publish_post", {
|
|
6
766
|
title: "Publish Post",
|
|
7
|
-
description: "
|
|
8
|
-
"
|
|
9
|
-
"
|
|
10
|
-
"
|
|
767
|
+
description: "Publish or schedule a social media post, save a draft, reply to an existing post, or create a thread. " +
|
|
768
|
+
"Before publishing or scheduling (draft is false or omitted), call get_platform_limits for each distinct destination platform. Check the text and the selected post type's requirements for each account, including thread entries and per-account overrides. If a known limit is exceeded, explain the affected field, actual value and allowed limit to the user before attempting to publish. Only assess file properties from verified metadata; do not infer dimensions, duration or codecs from a filename or URL. " +
|
|
769
|
+
"Use accountId for one account, or posts for one group across several accounts in the same workspace. Shared media is imported once; every account is validated before any post is created. Each item may override text, media, platformOptions, replyTo or thread. " +
|
|
770
|
+
"Set draft=true to save in dopost without publishing or scheduling; omit publishAt. Drafts may be incomplete and can be edited or published in the dopost dashboard. " +
|
|
771
|
+
"Provide at least text or media (or both) when publishing or scheduling. " +
|
|
772
|
+
"When draft is false or omitted, set publishAt to an ISO 8601 date to schedule, or omit to publish immediately. " +
|
|
773
|
+
"For X, Threads, and Mastodon, use thread to publish follow-up posts in one operation. " +
|
|
774
|
+
"For X and Threads, replyTo can target an existing platform post ID. " +
|
|
775
|
+
"Use platformOptions to pass platform-specific settings (see parameter description for details). Files are verified on receipt; destination publishing requirements are checked when publishing or scheduling. A processing response means the request was accepted; use get_post to confirm PUBLISHED or inspect a FAILED result.",
|
|
776
|
+
annotations: {
|
|
777
|
+
readOnlyHint: false,
|
|
778
|
+
destructiveHint: true,
|
|
779
|
+
idempotentHint: false,
|
|
780
|
+
openWorldHint: true,
|
|
781
|
+
},
|
|
11
782
|
inputSchema: {
|
|
12
|
-
accountId: z
|
|
13
|
-
text: z.string().optional().describe("Post text content"),
|
|
14
|
-
media: z
|
|
15
|
-
.array(z.string())
|
|
16
|
-
.optional()
|
|
17
|
-
.describe("Array of public media URLs"),
|
|
18
|
-
publishAt: z
|
|
783
|
+
accountId: z
|
|
19
784
|
.string()
|
|
785
|
+
.min(1)
|
|
20
786
|
.optional()
|
|
21
|
-
.describe("
|
|
22
|
-
|
|
787
|
+
.describe("Connected social account ID for a single post. Use either accountId or posts"),
|
|
788
|
+
posts: z
|
|
789
|
+
.array(z
|
|
23
790
|
.object({
|
|
24
|
-
|
|
25
|
-
.string()
|
|
26
|
-
.optional()
|
|
27
|
-
.describe('Instagram: "feed" | "story" | "reel". Automatically "carousel" when multiple media items are provided.'),
|
|
28
|
-
videoType: z
|
|
29
|
-
.string()
|
|
30
|
-
.optional()
|
|
31
|
-
.describe('YouTube: "video" | "short"'),
|
|
32
|
-
title: z
|
|
33
|
-
.string()
|
|
34
|
-
.optional()
|
|
35
|
-
.describe("YouTube: Video title. Defaults to first 100 chars of text."),
|
|
36
|
-
privacyStatus: z
|
|
791
|
+
accountId: z
|
|
37
792
|
.string()
|
|
38
|
-
.
|
|
39
|
-
.describe(
|
|
40
|
-
|
|
41
|
-
.string()
|
|
42
|
-
.optional()
|
|
43
|
-
.describe('TikTok: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY"'),
|
|
44
|
-
disableDuet: z
|
|
45
|
-
.boolean()
|
|
46
|
-
.optional()
|
|
47
|
-
.describe("TikTok: Prevent others from creating duets"),
|
|
48
|
-
disableStitch: z
|
|
49
|
-
.boolean()
|
|
50
|
-
.optional()
|
|
51
|
-
.describe("TikTok: Prevent others from stitching your video"),
|
|
52
|
-
disableComment: z
|
|
53
|
-
.boolean()
|
|
54
|
-
.optional()
|
|
55
|
-
.describe("TikTok: Disable comments on the video"),
|
|
56
|
-
board: z
|
|
57
|
-
.string()
|
|
58
|
-
.optional()
|
|
59
|
-
.describe("Pinterest: Board ID to pin to (required for Pinterest)"),
|
|
793
|
+
.min(1)
|
|
794
|
+
.describe("Connected account in the group's workspace"),
|
|
795
|
+
...publishContentFields,
|
|
60
796
|
})
|
|
797
|
+
.strict())
|
|
798
|
+
.min(1)
|
|
799
|
+
.max(20)
|
|
800
|
+
.optional()
|
|
801
|
+
.describe("Create one group for up to 20 different accounts in the same workspace. Items inherit top-level content fields; supplied item fields replace those defaults. Put draft, publishAt and timezone at the top level. Shared media URLs are imported once"),
|
|
802
|
+
...publishContentFields,
|
|
803
|
+
draft: z
|
|
804
|
+
.boolean()
|
|
805
|
+
.optional()
|
|
806
|
+
.describe("Set true to save a DRAFT in dopost without publishing or scheduling. Omit publishAt. Defaults to false"),
|
|
807
|
+
publishAt: z
|
|
808
|
+
.string()
|
|
809
|
+
.optional()
|
|
810
|
+
.describe("ISO date to schedule; defaults to workspace timezone when unzoned. Omit to publish now"),
|
|
811
|
+
timezone: z
|
|
812
|
+
.string()
|
|
61
813
|
.optional()
|
|
62
|
-
.describe("
|
|
63
|
-
"Instagram: postType. TikTok: privacyLevel, disableDuet, disableStitch, disableComment. " +
|
|
64
|
-
"YouTube: videoType, title, privacyStatus. Pinterest: board."),
|
|
814
|
+
.describe("Optional IANA timezone override. Unzoned dates default to the workspace timezone; explicit Z or offsets are respected"),
|
|
65
815
|
},
|
|
66
|
-
}, async ({ accountId, text, media, publishAt, platformOptions }) => {
|
|
67
|
-
|
|
68
|
-
accountId,
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
816
|
+
}, async ({ accountId, posts, text, media, publishAt, draft, timezone, replyTo, thread, platformOptions, }) => {
|
|
817
|
+
if ((accountId !== undefined) === (posts !== undefined))
|
|
818
|
+
return asToolError(new Error("Use either accountId or posts, not both."));
|
|
819
|
+
try {
|
|
820
|
+
if (posts !== undefined) {
|
|
821
|
+
const resolvedPosts = [];
|
|
822
|
+
for (const post of posts) {
|
|
823
|
+
const options = await resolvePublishOptions(client, post.accountId, post.platformOptions ?? platformOptions);
|
|
824
|
+
resolvedPosts.push({
|
|
825
|
+
...post,
|
|
826
|
+
...(options !== undefined ? { platformOptions: options } : {}),
|
|
827
|
+
});
|
|
828
|
+
}
|
|
829
|
+
return client.request("POST", "/api/v1/post/publish", {
|
|
830
|
+
posts: resolvedPosts,
|
|
831
|
+
text,
|
|
832
|
+
media,
|
|
833
|
+
publishAt,
|
|
834
|
+
replyTo,
|
|
835
|
+
thread,
|
|
836
|
+
...(draft !== undefined ? { draft } : {}),
|
|
837
|
+
...(timezone !== undefined ? { timezone } : {}),
|
|
838
|
+
});
|
|
839
|
+
}
|
|
840
|
+
const options = await resolvePublishOptions(client, accountId, platformOptions);
|
|
841
|
+
return client.request("POST", "/api/v1/post/publish", {
|
|
842
|
+
accountId,
|
|
843
|
+
text,
|
|
844
|
+
media,
|
|
845
|
+
publishAt,
|
|
846
|
+
...(draft !== undefined ? { draft } : {}),
|
|
847
|
+
...(timezone !== undefined ? { timezone } : {}),
|
|
848
|
+
replyTo,
|
|
849
|
+
thread,
|
|
850
|
+
...(options && Object.keys(options).length
|
|
851
|
+
? { platformOptions: options }
|
|
852
|
+
: {}),
|
|
853
|
+
});
|
|
854
|
+
}
|
|
855
|
+
catch (error) {
|
|
856
|
+
return asToolError(error);
|
|
857
|
+
}
|
|
75
858
|
});
|
|
76
859
|
server.registerTool("list_posts", {
|
|
77
860
|
title: "List Posts",
|
|
78
|
-
description: "List posts
|
|
861
|
+
description: "List posts across every authorized workspace by default. " +
|
|
79
862
|
"Supports filtering by status and cursor-based pagination.",
|
|
863
|
+
annotations: {
|
|
864
|
+
readOnlyHint: true,
|
|
865
|
+
destructiveHint: false,
|
|
866
|
+
idempotentHint: true,
|
|
867
|
+
openWorldHint: false,
|
|
868
|
+
},
|
|
80
869
|
inputSchema: {
|
|
870
|
+
workspaceId: z
|
|
871
|
+
.string()
|
|
872
|
+
.optional()
|
|
873
|
+
.describe("Optional workspace ID to limit results"),
|
|
81
874
|
status: z
|
|
82
875
|
.enum(["DRAFT", "PENDING", "PUBLISHED", "FAILED"])
|
|
83
876
|
.optional()
|
|
84
877
|
.describe("Filter by post status"),
|
|
85
878
|
limit: z
|
|
86
879
|
.number()
|
|
880
|
+
.int()
|
|
87
881
|
.min(1)
|
|
88
882
|
.max(100)
|
|
89
883
|
.optional()
|
|
@@ -93,8 +887,10 @@ export function registerTools(server) {
|
|
|
93
887
|
.optional()
|
|
94
888
|
.describe("Pagination cursor from a previous response"),
|
|
95
889
|
},
|
|
96
|
-
}, async ({ status, limit, cursor }) => {
|
|
890
|
+
}, async ({ workspaceId, status, limit, cursor }) => {
|
|
97
891
|
const params = new URLSearchParams();
|
|
892
|
+
if (workspaceId)
|
|
893
|
+
params.set("workspaceId", workspaceId);
|
|
98
894
|
if (status)
|
|
99
895
|
params.set("status", status);
|
|
100
896
|
if (limit)
|
|
@@ -102,83 +898,575 @@ export function registerTools(server) {
|
|
|
102
898
|
if (cursor)
|
|
103
899
|
params.set("cursor", cursor);
|
|
104
900
|
const qs = params.toString();
|
|
105
|
-
return
|
|
901
|
+
return client.request("GET", `/api/v1/post${qs ? `?${qs}` : ""}`);
|
|
106
902
|
});
|
|
107
903
|
server.registerTool("get_post", {
|
|
108
904
|
title: "Get Post",
|
|
109
|
-
description: "Get full details of a specific post including content, status, schedule, and social account info.",
|
|
905
|
+
description: "Get full details of a specific post including content, status, schedule, and social account info. If status is FAILED, inspect error.message, error.code, and error.retryable; a successful status query does not mean the post was published.",
|
|
906
|
+
annotations: {
|
|
907
|
+
readOnlyHint: true,
|
|
908
|
+
destructiveHint: false,
|
|
909
|
+
idempotentHint: true,
|
|
910
|
+
openWorldHint: false,
|
|
911
|
+
},
|
|
110
912
|
inputSchema: {
|
|
111
913
|
postId: z.string().describe("The post ID"),
|
|
112
914
|
},
|
|
113
915
|
}, async ({ postId }) => {
|
|
114
|
-
return
|
|
916
|
+
return client.request("GET", `/api/v1/post/${safePath(postId)}`);
|
|
115
917
|
});
|
|
116
918
|
server.registerTool("reschedule_post", {
|
|
117
919
|
title: "Reschedule Post",
|
|
118
|
-
description: "
|
|
119
|
-
"
|
|
920
|
+
description: "Replace the delivery time of a pending post. Only works on posts with status PENDING. " +
|
|
921
|
+
"The post publishes automatically at the new time, so confirm the exact post and time before calling this tool.",
|
|
922
|
+
annotations: {
|
|
923
|
+
readOnlyHint: false,
|
|
924
|
+
destructiveHint: true,
|
|
925
|
+
idempotentHint: false,
|
|
926
|
+
openWorldHint: true,
|
|
927
|
+
},
|
|
120
928
|
inputSchema: {
|
|
121
929
|
postId: z.string().describe("The post ID to reschedule"),
|
|
122
930
|
publishAt: z
|
|
123
931
|
.string()
|
|
124
|
-
.describe("
|
|
932
|
+
.describe("Future ISO date. Unzoned dates use the workspace timezone; Z or explicit offsets are respected"),
|
|
933
|
+
timezone: z
|
|
934
|
+
.string()
|
|
935
|
+
.optional()
|
|
936
|
+
.describe("Optional IANA timezone override"),
|
|
125
937
|
},
|
|
126
|
-
}, async ({ postId, publishAt }) => {
|
|
127
|
-
return
|
|
938
|
+
}, async ({ postId, publishAt, timezone }) => {
|
|
939
|
+
return client.request("PATCH", `/api/v1/post/${safePath(postId)}`, {
|
|
940
|
+
publishAt,
|
|
941
|
+
...(timezone !== undefined ? { timezone } : {}),
|
|
942
|
+
});
|
|
943
|
+
});
|
|
944
|
+
// ── Recurring posts ──────────────────────────────────────────────
|
|
945
|
+
server.registerTool("create_recurring_post", {
|
|
946
|
+
title: "Create Recurring Post",
|
|
947
|
+
description: "Create a recurring social media post. The first occurrence must be at least two minutes in the future. " +
|
|
948
|
+
"Weekly schedules use weekdays from 0 (Sunday) to 6 (Saturday). " +
|
|
949
|
+
"Every occurrence publishes automatically, so confirm the content, account, schedule, and end condition before calling this tool.",
|
|
950
|
+
annotations: {
|
|
951
|
+
readOnlyHint: false,
|
|
952
|
+
destructiveHint: true,
|
|
953
|
+
idempotentHint: false,
|
|
954
|
+
openWorldHint: true,
|
|
955
|
+
},
|
|
956
|
+
inputSchema: {
|
|
957
|
+
accountId: z.string().describe("ID of the connected social account"),
|
|
958
|
+
text: z.string().optional().describe("Post text content"),
|
|
959
|
+
media: z
|
|
960
|
+
.array(z.string().url())
|
|
961
|
+
.max(10)
|
|
962
|
+
.optional()
|
|
963
|
+
.describe("Public media URLs"),
|
|
964
|
+
startsAt: z.string().describe("ISO 8601 date for the first occurrence"),
|
|
965
|
+
timezone: z
|
|
966
|
+
.string()
|
|
967
|
+
.optional()
|
|
968
|
+
.describe("IANA timezone. Defaults to the workspace timezone"),
|
|
969
|
+
frequency: z.enum(["DAILY", "WEEKLY", "MONTHLY"]),
|
|
970
|
+
interval: z.number().int().min(1).max(365).optional(),
|
|
971
|
+
weekdays: z
|
|
972
|
+
.array(z.number().int().min(0).max(6))
|
|
973
|
+
.optional()
|
|
974
|
+
.describe("Required for weekly schedules"),
|
|
975
|
+
endType: z.enum(["NEVER", "ON_DATE", "AFTER_OCCURRENCES"]).optional(),
|
|
976
|
+
endDate: z.string().optional(),
|
|
977
|
+
occurrenceCount: z.number().int().min(2).max(500).optional(),
|
|
978
|
+
platformOptions: platformOptionsSchema.optional(),
|
|
979
|
+
},
|
|
980
|
+
}, async ({ accountId, text, media, startsAt, timezone, frequency, interval = 1, weekdays = [], endType = "NEVER", endDate, occurrenceCount, platformOptions, }) => {
|
|
981
|
+
return client.request("POST", "/api/v1/recurring-post", {
|
|
982
|
+
accountId,
|
|
983
|
+
text,
|
|
984
|
+
media,
|
|
985
|
+
startsAt,
|
|
986
|
+
timezone,
|
|
987
|
+
recurrence: {
|
|
988
|
+
frequency,
|
|
989
|
+
interval,
|
|
990
|
+
weekdays,
|
|
991
|
+
endType,
|
|
992
|
+
endDate,
|
|
993
|
+
occurrenceCount,
|
|
994
|
+
},
|
|
995
|
+
platformOptions,
|
|
996
|
+
});
|
|
997
|
+
});
|
|
998
|
+
server.registerTool("list_recurring_posts", {
|
|
999
|
+
title: "List Recurring Posts",
|
|
1000
|
+
description: "List recurring post series with their status, schedule, accounts, next run, and latest result.",
|
|
1001
|
+
annotations: {
|
|
1002
|
+
readOnlyHint: true,
|
|
1003
|
+
destructiveHint: false,
|
|
1004
|
+
idempotentHint: true,
|
|
1005
|
+
openWorldHint: false,
|
|
1006
|
+
},
|
|
1007
|
+
inputSchema: {
|
|
1008
|
+
workspaceId: z
|
|
1009
|
+
.string()
|
|
1010
|
+
.optional()
|
|
1011
|
+
.describe("Optional workspace ID to limit results"),
|
|
1012
|
+
status: z
|
|
1013
|
+
.enum(["ACTIVE", "PAUSED", "COMPLETED"])
|
|
1014
|
+
.optional()
|
|
1015
|
+
.describe("Optional lifecycle status filter"),
|
|
1016
|
+
},
|
|
1017
|
+
}, async ({ workspaceId, status }) => {
|
|
1018
|
+
const params = new URLSearchParams();
|
|
1019
|
+
if (workspaceId)
|
|
1020
|
+
params.set("workspaceId", workspaceId);
|
|
1021
|
+
if (status)
|
|
1022
|
+
params.set("status", status);
|
|
1023
|
+
const query = params.toString();
|
|
1024
|
+
return client.request("GET", `/api/v1/recurring-post${query ? `?${query}` : ""}`);
|
|
1025
|
+
});
|
|
1026
|
+
server.registerTool("update_recurring_post", {
|
|
1027
|
+
title: "Update Recurring Post",
|
|
1028
|
+
description: "Replace the next occurrence, recurrence rules, content, media, or platform options of an active or paused recurring series. " +
|
|
1029
|
+
"startsAt must be at least two minutes in the future. Future occurrences publish automatically, so confirm the replacement values before calling this tool.",
|
|
1030
|
+
annotations: {
|
|
1031
|
+
readOnlyHint: false,
|
|
1032
|
+
destructiveHint: true,
|
|
1033
|
+
idempotentHint: false,
|
|
1034
|
+
openWorldHint: true,
|
|
1035
|
+
},
|
|
1036
|
+
inputSchema: {
|
|
1037
|
+
recurringPostId: z.string().describe("Recurring series ID"),
|
|
1038
|
+
startsAt: z.string().describe("New next occurrence as ISO 8601"),
|
|
1039
|
+
text: z.string().optional().describe("Replacement post text"),
|
|
1040
|
+
media: z
|
|
1041
|
+
.array(z.string().url())
|
|
1042
|
+
.max(10)
|
|
1043
|
+
.optional()
|
|
1044
|
+
.describe("Replacement public media URLs"),
|
|
1045
|
+
frequency: z.enum(["DAILY", "WEEKLY", "MONTHLY"]).optional(),
|
|
1046
|
+
interval: z.number().int().min(1).max(365).optional(),
|
|
1047
|
+
weekdays: z.array(z.number().int().min(0).max(6)).optional(),
|
|
1048
|
+
endType: z.enum(["NEVER", "ON_DATE", "AFTER_OCCURRENCES"]).optional(),
|
|
1049
|
+
endDate: z.string().optional(),
|
|
1050
|
+
occurrenceCount: z.number().int().min(2).max(500).optional(),
|
|
1051
|
+
platformOptions: platformOptionsSchema.optional(),
|
|
1052
|
+
},
|
|
1053
|
+
}, async ({ recurringPostId, startsAt, text, media, frequency, interval, weekdays, endType, endDate, occurrenceCount, platformOptions, }) => {
|
|
1054
|
+
return client.request("PATCH", `/api/v1/recurring-post/${safePath(recurringPostId)}`, {
|
|
1055
|
+
startsAt,
|
|
1056
|
+
text,
|
|
1057
|
+
media,
|
|
1058
|
+
recurrence: {
|
|
1059
|
+
frequency,
|
|
1060
|
+
interval,
|
|
1061
|
+
weekdays,
|
|
1062
|
+
endType,
|
|
1063
|
+
endDate,
|
|
1064
|
+
occurrenceCount,
|
|
1065
|
+
},
|
|
1066
|
+
platformOptions,
|
|
1067
|
+
});
|
|
128
1068
|
});
|
|
129
1069
|
server.registerTool("delete_post", {
|
|
130
1070
|
title: "Delete Post",
|
|
131
|
-
description: "Delete
|
|
1071
|
+
description: "Delete an unpublished dopost draft or pending post. A pending delivery is cancelled automatically. " +
|
|
1072
|
+
"If the post belongs to a group, this deletes the entire group; any published or processing member blocks deletion. " +
|
|
1073
|
+
"This does not delete content that was already published on a social network.",
|
|
1074
|
+
annotations: {
|
|
1075
|
+
readOnlyHint: false,
|
|
1076
|
+
destructiveHint: true,
|
|
1077
|
+
idempotentHint: true,
|
|
1078
|
+
openWorldHint: false,
|
|
1079
|
+
},
|
|
132
1080
|
inputSchema: {
|
|
133
1081
|
postId: z.string().describe("The post ID to delete"),
|
|
134
1082
|
},
|
|
135
1083
|
}, async ({ postId }) => {
|
|
136
|
-
return
|
|
1084
|
+
return client.request("DELETE", `/api/v1/post/delete/${safePath(postId)}`);
|
|
137
1085
|
});
|
|
138
1086
|
// ── Social Accounts ───────────────────────────────────────────────
|
|
1087
|
+
server.registerTool("list_workspaces", {
|
|
1088
|
+
title: "List Workspaces",
|
|
1089
|
+
description: "List every workspace this connection can currently access, including names, slugs, roles, and timezone metadata. " +
|
|
1090
|
+
"Use this only when a workspace-wide operation is ambiguous; resource and account IDs resolve their workspace automatically.",
|
|
1091
|
+
annotations: {
|
|
1092
|
+
readOnlyHint: true,
|
|
1093
|
+
destructiveHint: false,
|
|
1094
|
+
idempotentHint: true,
|
|
1095
|
+
openWorldHint: false,
|
|
1096
|
+
},
|
|
1097
|
+
inputSchema: {},
|
|
1098
|
+
}, async () => client.request("GET", "/api/v1/workspaces"));
|
|
139
1099
|
server.registerTool("list_accounts", {
|
|
140
1100
|
title: "List Social Accounts",
|
|
141
|
-
description: "List
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
1101
|
+
description: "List connected social media accounts across every authorized workspace by default. " +
|
|
1102
|
+
"Each account includes structured workspace metadata. Use the returned account ID for publishing so the workspace is resolved automatically.",
|
|
1103
|
+
annotations: {
|
|
1104
|
+
readOnlyHint: true,
|
|
1105
|
+
destructiveHint: false,
|
|
1106
|
+
idempotentHint: true,
|
|
1107
|
+
openWorldHint: false,
|
|
1108
|
+
},
|
|
1109
|
+
inputSchema: {
|
|
1110
|
+
workspaceId: z
|
|
1111
|
+
.string()
|
|
1112
|
+
.optional()
|
|
1113
|
+
.describe("Optional workspace ID to limit results"),
|
|
1114
|
+
query: z
|
|
1115
|
+
.string()
|
|
1116
|
+
.optional()
|
|
1117
|
+
.describe("Search by workspace name, slug, or account username"),
|
|
1118
|
+
platform: z
|
|
1119
|
+
.string()
|
|
1120
|
+
.optional()
|
|
1121
|
+
.describe("Optional platform slug or enum name"),
|
|
1122
|
+
},
|
|
1123
|
+
}, async ({ workspaceId, query, platform }) => {
|
|
1124
|
+
const params = new URLSearchParams();
|
|
1125
|
+
if (workspaceId)
|
|
1126
|
+
params.set("workspaceId", workspaceId);
|
|
1127
|
+
if (query)
|
|
1128
|
+
params.set("query", query);
|
|
1129
|
+
if (platform)
|
|
1130
|
+
params.set("platform", platform);
|
|
1131
|
+
const search = params.toString();
|
|
1132
|
+
return client.request("GET", `/api/v1/social/accounts${search ? `?${search}` : ""}`);
|
|
1133
|
+
});
|
|
1134
|
+
server.registerTool("list_x_communities", {
|
|
1135
|
+
title: "List Saved X Communities",
|
|
1136
|
+
description: "List the Communities saved for one connected X account. Present their names to the user. To publish, pass the selected name as publish_post platformOptions.communityName; keep communityId as an internal fallback only when names are ambiguous.",
|
|
1137
|
+
annotations: {
|
|
1138
|
+
readOnlyHint: true,
|
|
1139
|
+
destructiveHint: false,
|
|
1140
|
+
idempotentHint: true,
|
|
1141
|
+
openWorldHint: false,
|
|
1142
|
+
},
|
|
1143
|
+
inputSchema: {
|
|
1144
|
+
accountId: z
|
|
1145
|
+
.string()
|
|
1146
|
+
.min(1)
|
|
1147
|
+
.describe("Connected X account ID returned by list_accounts"),
|
|
1148
|
+
},
|
|
1149
|
+
outputSchema: {
|
|
1150
|
+
account: z
|
|
1151
|
+
.object({
|
|
1152
|
+
id: z.string(),
|
|
1153
|
+
platform: z.literal("X"),
|
|
1154
|
+
platformUsername: z.string(),
|
|
1155
|
+
})
|
|
1156
|
+
.optional(),
|
|
1157
|
+
communities: z.array(xCommunityOutputSchema),
|
|
1158
|
+
},
|
|
1159
|
+
}, async ({ accountId }) => {
|
|
1160
|
+
let catalog;
|
|
1161
|
+
try {
|
|
1162
|
+
catalog = await client.requestRaw("GET", `/api/v1/social/accounts/${safePath(accountId)}/x-communities`);
|
|
1163
|
+
}
|
|
1164
|
+
catch (error) {
|
|
1165
|
+
return {
|
|
1166
|
+
content: [
|
|
1167
|
+
{
|
|
1168
|
+
type: "text",
|
|
1169
|
+
text: error instanceof Error
|
|
1170
|
+
? error.message
|
|
1171
|
+
: "Could not load saved X Communities.",
|
|
1172
|
+
},
|
|
1173
|
+
],
|
|
1174
|
+
isError: true,
|
|
1175
|
+
};
|
|
1176
|
+
}
|
|
1177
|
+
const rawCommunities = Array.isArray(catalog.communities)
|
|
1178
|
+
? catalog.communities.filter((value) => Boolean(value) &&
|
|
1179
|
+
typeof value === "object" &&
|
|
1180
|
+
!Array.isArray(value) &&
|
|
1181
|
+
typeof value.name === "string")
|
|
1182
|
+
: [];
|
|
1183
|
+
const nameCounts = new Map();
|
|
1184
|
+
for (const community of rawCommunities) {
|
|
1185
|
+
const key = String(community.name).trim().toLocaleLowerCase();
|
|
1186
|
+
nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
|
|
1187
|
+
}
|
|
1188
|
+
const communities = rawCommunities.map((community) => {
|
|
1189
|
+
const name = String(community.name);
|
|
1190
|
+
const duplicateName = (nameCounts.get(name.trim().toLocaleLowerCase()) ?? 0) > 1;
|
|
1191
|
+
return {
|
|
1192
|
+
name,
|
|
1193
|
+
...(typeof community.description === "string"
|
|
1194
|
+
? { description: community.description }
|
|
1195
|
+
: {}),
|
|
1196
|
+
...(typeof community.thumbnailUrl === "string"
|
|
1197
|
+
? { thumbnailUrl: community.thumbnailUrl }
|
|
1198
|
+
: {}),
|
|
1199
|
+
isValid: community.isValid !== false,
|
|
1200
|
+
...(typeof community.lastError === "string"
|
|
1201
|
+
? { lastError: community.lastError }
|
|
1202
|
+
: {}),
|
|
1203
|
+
...(duplicateName && typeof community.communityId === "string"
|
|
1204
|
+
? { communityId: community.communityId }
|
|
1205
|
+
: {}),
|
|
1206
|
+
};
|
|
1207
|
+
});
|
|
1208
|
+
return structuredToolResult({ account: catalog.account, communities });
|
|
1209
|
+
});
|
|
1210
|
+
server.registerTool("add_x_community", {
|
|
1211
|
+
title: "Add Saved X Community",
|
|
1212
|
+
description: "Validate and save an X Community for one connected X account. Accepts a Community URL or numeric ID, avoids duplicates, and returns its display name for later use with publish_post platformOptions.communityName. " +
|
|
1213
|
+
"Calling it again for an existing Community refreshes that entry's last-used metadata.",
|
|
1214
|
+
annotations: {
|
|
1215
|
+
readOnlyHint: false,
|
|
1216
|
+
destructiveHint: false,
|
|
1217
|
+
idempotentHint: false,
|
|
1218
|
+
openWorldHint: true,
|
|
1219
|
+
},
|
|
1220
|
+
inputSchema: {
|
|
1221
|
+
accountId: z
|
|
1222
|
+
.string()
|
|
1223
|
+
.min(1)
|
|
1224
|
+
.describe("Connected X account ID returned by list_accounts"),
|
|
1225
|
+
community: z
|
|
1226
|
+
.string()
|
|
1227
|
+
.min(1)
|
|
1228
|
+
.describe("Numeric X Community ID or x.com Community URL"),
|
|
1229
|
+
},
|
|
1230
|
+
outputSchema: {
|
|
1231
|
+
created: z.boolean(),
|
|
1232
|
+
name: z.string().optional(),
|
|
1233
|
+
isValid: z.boolean(),
|
|
1234
|
+
message: z.string(),
|
|
1235
|
+
},
|
|
1236
|
+
}, async ({ accountId, community }) => {
|
|
1237
|
+
try {
|
|
1238
|
+
const result = await client.requestRaw("POST", `/api/v1/social/accounts/${safePath(accountId)}/x-communities`, { community });
|
|
1239
|
+
const saved = result.community &&
|
|
1240
|
+
typeof result.community === "object" &&
|
|
1241
|
+
!Array.isArray(result.community)
|
|
1242
|
+
? result.community
|
|
1243
|
+
: {};
|
|
1244
|
+
return structuredToolResult({
|
|
1245
|
+
created: result.created === true,
|
|
1246
|
+
...(typeof saved.name === "string" ? { name: saved.name } : {}),
|
|
1247
|
+
isValid: saved.isValid !== false,
|
|
1248
|
+
message: result.created === true
|
|
1249
|
+
? "X Community saved."
|
|
1250
|
+
: "X Community was already saved and is now selected for reuse.",
|
|
1251
|
+
});
|
|
1252
|
+
}
|
|
1253
|
+
catch (error) {
|
|
1254
|
+
return {
|
|
1255
|
+
content: [
|
|
1256
|
+
{
|
|
1257
|
+
type: "text",
|
|
1258
|
+
text: error instanceof Error
|
|
1259
|
+
? error.message
|
|
1260
|
+
: "Could not add X Community.",
|
|
1261
|
+
},
|
|
1262
|
+
],
|
|
1263
|
+
isError: true,
|
|
1264
|
+
};
|
|
1265
|
+
}
|
|
1266
|
+
});
|
|
1267
|
+
server.registerTool("remove_x_community", {
|
|
1268
|
+
title: "Remove Saved X Community",
|
|
1269
|
+
description: "Remove a Community from one connected X account's saved catalog. Prefer communityName; use communityId only to disambiguate duplicate names. Confirm the removal with the user before calling this tool.",
|
|
1270
|
+
annotations: {
|
|
1271
|
+
readOnlyHint: false,
|
|
1272
|
+
destructiveHint: true,
|
|
1273
|
+
idempotentHint: true,
|
|
1274
|
+
openWorldHint: false,
|
|
1275
|
+
},
|
|
1276
|
+
inputSchema: {
|
|
1277
|
+
accountId: z
|
|
1278
|
+
.string()
|
|
1279
|
+
.min(1)
|
|
1280
|
+
.describe("Connected X account ID returned by list_accounts"),
|
|
1281
|
+
communityName: z
|
|
1282
|
+
.string()
|
|
1283
|
+
.min(1)
|
|
1284
|
+
.optional()
|
|
1285
|
+
.describe("Display name returned by list_x_communities"),
|
|
1286
|
+
communityId: z
|
|
1287
|
+
.string()
|
|
1288
|
+
.min(1)
|
|
1289
|
+
.optional()
|
|
1290
|
+
.describe("Technical fallback when saved Community names collide"),
|
|
1291
|
+
},
|
|
1292
|
+
outputSchema: {
|
|
1293
|
+
removed: z.boolean(),
|
|
1294
|
+
name: z.string().optional(),
|
|
1295
|
+
message: z.string(),
|
|
1296
|
+
},
|
|
1297
|
+
}, async ({ accountId, communityName, communityId }) => {
|
|
1298
|
+
const normalizedName = communityName?.trim();
|
|
1299
|
+
const normalizedId = communityId?.trim();
|
|
1300
|
+
if ((!normalizedName && !normalizedId) ||
|
|
1301
|
+
(normalizedName && normalizedId)) {
|
|
1302
|
+
return {
|
|
1303
|
+
content: [
|
|
1304
|
+
{
|
|
1305
|
+
type: "text",
|
|
1306
|
+
text: "Use either communityName or communityId.",
|
|
1307
|
+
},
|
|
1308
|
+
],
|
|
1309
|
+
isError: true,
|
|
1310
|
+
};
|
|
1311
|
+
}
|
|
1312
|
+
try {
|
|
1313
|
+
const result = await client.requestRaw("DELETE", `/api/v1/social/accounts/${safePath(accountId)}/x-communities`, normalizedName
|
|
1314
|
+
? { communityName: normalizedName }
|
|
1315
|
+
: { communityId: normalizedId });
|
|
1316
|
+
const removed = result.community &&
|
|
1317
|
+
typeof result.community === "object" &&
|
|
1318
|
+
!Array.isArray(result.community)
|
|
1319
|
+
? result.community
|
|
1320
|
+
: {};
|
|
1321
|
+
return structuredToolResult({
|
|
1322
|
+
removed: result.removed === true,
|
|
1323
|
+
...(typeof removed.name === "string" ? { name: removed.name } : {}),
|
|
1324
|
+
message: "X Community removed from the saved catalog.",
|
|
1325
|
+
});
|
|
1326
|
+
}
|
|
1327
|
+
catch (error) {
|
|
1328
|
+
return {
|
|
1329
|
+
content: [
|
|
1330
|
+
{
|
|
1331
|
+
type: "text",
|
|
1332
|
+
text: error instanceof Error
|
|
1333
|
+
? error.message
|
|
1334
|
+
: "Could not remove X Community.",
|
|
1335
|
+
},
|
|
1336
|
+
],
|
|
1337
|
+
isError: true,
|
|
1338
|
+
};
|
|
1339
|
+
}
|
|
145
1340
|
});
|
|
146
1341
|
server.registerTool("get_platform_limits", {
|
|
147
1342
|
title: "Get Platform Limits",
|
|
148
|
-
description: "Get content limits for a platform: max text length, media count, supported formats, and file
|
|
1343
|
+
description: "Get content limits for a platform: max text length, media count, supported formats, file sizes and available media specifications. Call this before publish_post when publishing or scheduling, once for each distinct destination platform. Use the selected post type's requirements (for example feed, story, reel or carousel) to check the text and any verified media metadata. These limits do not inspect a file or guarantee publishing eligibility; the server validates received files and destination requirements before creating posts. Drafts may contain incomplete platform content.",
|
|
1344
|
+
annotations: {
|
|
1345
|
+
readOnlyHint: true,
|
|
1346
|
+
destructiveHint: false,
|
|
1347
|
+
idempotentHint: true,
|
|
1348
|
+
openWorldHint: false,
|
|
1349
|
+
},
|
|
149
1350
|
inputSchema: {
|
|
150
1351
|
platform: z
|
|
151
1352
|
.string()
|
|
152
|
-
.describe("Platform slug: instagram, tiktok, youtube, facebook, linkedin, x, threads, bluesky, mastodon, pinterest"),
|
|
1353
|
+
.describe("Platform slug: instagram, tiktok, youtube, google-business, facebook, linkedin, x, threads, bluesky, mastodon, pinterest"),
|
|
153
1354
|
},
|
|
154
1355
|
}, async ({ platform }) => {
|
|
155
|
-
return
|
|
1356
|
+
return client.request("GET", `/api/v1/social/limits/${safePath(platform)}`);
|
|
156
1357
|
});
|
|
157
1358
|
// ── Media ─────────────────────────────────────────────────────────
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
"
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
1359
|
+
if (options.enableLocalFileTools !== false) {
|
|
1360
|
+
server.registerTool("upload_media", {
|
|
1361
|
+
title: "Upload Media",
|
|
1362
|
+
description: "Upload a local file to dopost. Defaults to the media library; use purpose=post for an attachment outside the library quota. " +
|
|
1363
|
+
"Provide the absolute path to the file on disk. " +
|
|
1364
|
+
"The tool uploads and verifies the file, then returns its public URL. A successful upload confirms file receipt and upload checks; it does not confirm compatibility with a destination platform. Before publishing or scheduling, call get_platform_limits for each distinct destination platform. Platform-specific publishing rules are checked when you call publish_post.",
|
|
1365
|
+
annotations: {
|
|
1366
|
+
readOnlyHint: false,
|
|
1367
|
+
destructiveHint: false,
|
|
1368
|
+
idempotentHint: false,
|
|
1369
|
+
openWorldHint: true,
|
|
1370
|
+
},
|
|
1371
|
+
inputSchema: {
|
|
1372
|
+
workspaceId: z
|
|
1373
|
+
.string()
|
|
1374
|
+
.optional()
|
|
1375
|
+
.describe("Workspace ID. Required only when this OAuth connection can access multiple workspaces; API keys infer their fixed workspace"),
|
|
1376
|
+
purpose: z
|
|
1377
|
+
.enum(["library", "post"])
|
|
1378
|
+
.optional()
|
|
1379
|
+
.describe("library saves to Media; post prepares an attachment without adding it to the library"),
|
|
1380
|
+
filePath: z
|
|
1381
|
+
.string()
|
|
1382
|
+
.describe("Absolute path to the file on disk (e.g. /Users/me/photo.jpg)"),
|
|
1383
|
+
contentType: z
|
|
1384
|
+
.string()
|
|
1385
|
+
.optional()
|
|
1386
|
+
.describe("MIME type (e.g. image/jpeg, video/mp4). Auto-detected from extension if omitted"),
|
|
1387
|
+
},
|
|
1388
|
+
}, async ({ workspaceId, filePath, contentType, purpose }) => {
|
|
1389
|
+
try {
|
|
1390
|
+
const fileStats = await stat(filePath);
|
|
1391
|
+
const fileName = basename(filePath);
|
|
1392
|
+
const mime = contentType || detectMime(fileName) || "application/octet-stream";
|
|
1393
|
+
// Step 1: Request presigned URL
|
|
1394
|
+
const data = await client.requestRaw("POST", "/api/v1/media", {
|
|
1395
|
+
fileName,
|
|
1396
|
+
contentType: mime,
|
|
1397
|
+
sizeInBytes: fileStats.size,
|
|
1398
|
+
workspaceId,
|
|
1399
|
+
purpose: purpose ?? "library",
|
|
1400
|
+
});
|
|
1401
|
+
const uploadUrl = data.uploadUrl;
|
|
1402
|
+
const publicUrl = data.publicUrl;
|
|
1403
|
+
const id = data.id;
|
|
1404
|
+
// Step 2: Read file and PUT to presigned URL
|
|
1405
|
+
const fileBuffer = await readFile(filePath);
|
|
1406
|
+
const putRes = await fetch(uploadUrl, {
|
|
1407
|
+
method: "PUT",
|
|
1408
|
+
headers: { "Content-Type": data.contentType || mime },
|
|
1409
|
+
body: fileBuffer,
|
|
1410
|
+
signal: AbortSignal.timeout(300_000),
|
|
1411
|
+
});
|
|
1412
|
+
if (!putRes.ok) {
|
|
1413
|
+
return {
|
|
1414
|
+
content: [
|
|
1415
|
+
{
|
|
1416
|
+
type: "text",
|
|
1417
|
+
text: `Upload to storage failed with status ${putRes.status}`,
|
|
1418
|
+
},
|
|
1419
|
+
],
|
|
1420
|
+
isError: true,
|
|
1421
|
+
};
|
|
1422
|
+
}
|
|
1423
|
+
// A file is usable only after authoritative size/type/quota validation.
|
|
1424
|
+
const confirmData = await client.requestRaw("POST", `/api/v1/media/${id}/finalize`, {});
|
|
1425
|
+
if (confirmData.status !== "READY")
|
|
1426
|
+
throw new Error("The upload could not be verified, so the file is not ready to use. Do not publish this file until upload verification succeeds.");
|
|
1427
|
+
const confirmed = {
|
|
1428
|
+
id,
|
|
1429
|
+
publicUrl,
|
|
1430
|
+
fileName,
|
|
1431
|
+
contentType: confirmData.type ?? data.contentType ?? mime,
|
|
1432
|
+
purpose: purpose ?? "library",
|
|
1433
|
+
sizeInBytes: confirmData.sizeInBytes,
|
|
1434
|
+
width: confirmData.width ?? null,
|
|
1435
|
+
height: confirmData.height ?? null,
|
|
1436
|
+
durationSeconds: confirmData.durationSeconds ?? null,
|
|
1437
|
+
thumbnailUrl: confirmData.thumbnailUrl ?? null,
|
|
1438
|
+
};
|
|
1439
|
+
return {
|
|
1440
|
+
content: [
|
|
1441
|
+
{
|
|
1442
|
+
type: "text",
|
|
1443
|
+
text: JSON.stringify(confirmed, null, 2),
|
|
1444
|
+
},
|
|
1445
|
+
],
|
|
1446
|
+
};
|
|
1447
|
+
}
|
|
1448
|
+
catch (err) {
|
|
1449
|
+
return asToolError(err);
|
|
1450
|
+
}
|
|
174
1451
|
});
|
|
175
|
-
}
|
|
1452
|
+
}
|
|
176
1453
|
server.registerTool("list_media", {
|
|
177
1454
|
title: "List Media",
|
|
178
|
-
description: "List uploaded media
|
|
1455
|
+
description: "List uploaded media across every authorized workspace by default with cursor-based pagination.",
|
|
1456
|
+
annotations: {
|
|
1457
|
+
readOnlyHint: true,
|
|
1458
|
+
destructiveHint: false,
|
|
1459
|
+
idempotentHint: true,
|
|
1460
|
+
openWorldHint: false,
|
|
1461
|
+
},
|
|
179
1462
|
inputSchema: {
|
|
1463
|
+
workspaceId: z
|
|
1464
|
+
.string()
|
|
1465
|
+
.optional()
|
|
1466
|
+
.describe("Optional workspace ID to limit results"),
|
|
180
1467
|
limit: z
|
|
181
1468
|
.number()
|
|
1469
|
+
.int()
|
|
182
1470
|
.min(1)
|
|
183
1471
|
.max(100)
|
|
184
1472
|
.optional()
|
|
@@ -188,23 +1476,129 @@ export function registerTools(server) {
|
|
|
188
1476
|
.optional()
|
|
189
1477
|
.describe("Pagination cursor from a previous response"),
|
|
190
1478
|
},
|
|
191
|
-
}, async ({ limit, cursor }) => {
|
|
1479
|
+
}, async ({ workspaceId, limit, cursor }) => {
|
|
192
1480
|
const params = new URLSearchParams();
|
|
1481
|
+
if (workspaceId)
|
|
1482
|
+
params.set("workspaceId", workspaceId);
|
|
193
1483
|
if (limit)
|
|
194
1484
|
params.set("limit", String(limit));
|
|
195
1485
|
if (cursor)
|
|
196
1486
|
params.set("cursor", cursor);
|
|
197
1487
|
const qs = params.toString();
|
|
198
|
-
return
|
|
1488
|
+
return client.request("GET", `/api/v1/media${qs ? `?${qs}` : ""}`);
|
|
199
1489
|
});
|
|
200
1490
|
server.registerTool("delete_media", {
|
|
201
1491
|
title: "Delete Media",
|
|
202
1492
|
description: "Delete a media file from storage by its ID.",
|
|
1493
|
+
annotations: {
|
|
1494
|
+
readOnlyHint: false,
|
|
1495
|
+
destructiveHint: true,
|
|
1496
|
+
idempotentHint: true,
|
|
1497
|
+
openWorldHint: false,
|
|
1498
|
+
},
|
|
203
1499
|
inputSchema: {
|
|
204
1500
|
mediaId: z.string().describe("The media ID to delete"),
|
|
205
1501
|
},
|
|
206
1502
|
}, async ({ mediaId }) => {
|
|
207
|
-
return
|
|
1503
|
+
return client.request("DELETE", `/api/v1/media/${safePath(mediaId)}`);
|
|
208
1504
|
});
|
|
209
1505
|
}
|
|
1506
|
+
function selectClosestFormat(formats, preferredValue, container) {
|
|
1507
|
+
if (preferredValue === undefined)
|
|
1508
|
+
return formats[0];
|
|
1509
|
+
const getValue = (format) => container === "mp4" ? format.height : format.bitrateKbps;
|
|
1510
|
+
return [...formats].sort((left, right) => {
|
|
1511
|
+
const leftValue = getValue(left);
|
|
1512
|
+
const rightValue = getValue(right);
|
|
1513
|
+
const leftDistance = leftValue === undefined
|
|
1514
|
+
? Number.POSITIVE_INFINITY
|
|
1515
|
+
: Math.abs(leftValue - preferredValue);
|
|
1516
|
+
const rightDistance = rightValue === undefined
|
|
1517
|
+
? Number.POSITIVE_INFINITY
|
|
1518
|
+
: Math.abs(rightValue - preferredValue);
|
|
1519
|
+
return leftDistance - rightDistance;
|
|
1520
|
+
})[0];
|
|
1521
|
+
}
|
|
1522
|
+
function analyticsQuery(input) {
|
|
1523
|
+
const params = new URLSearchParams();
|
|
1524
|
+
if (input.workspaceId)
|
|
1525
|
+
params.set("workspaceId", input.workspaceId);
|
|
1526
|
+
if (input.days)
|
|
1527
|
+
params.set("days", String(input.days));
|
|
1528
|
+
if (input.startDate)
|
|
1529
|
+
params.set("startDate", input.startDate);
|
|
1530
|
+
if (input.endDate)
|
|
1531
|
+
params.set("endDate", input.endDate);
|
|
1532
|
+
if (input.platform)
|
|
1533
|
+
params.set("platform", input.platform);
|
|
1534
|
+
if (input.accountId)
|
|
1535
|
+
params.set("accountId", input.accountId);
|
|
1536
|
+
if (input.accountIds?.length)
|
|
1537
|
+
params.set("accountIds", input.accountIds.join(","));
|
|
1538
|
+
if (input.groupId)
|
|
1539
|
+
params.set("groupId", input.groupId);
|
|
1540
|
+
if (input.comparison)
|
|
1541
|
+
params.set("comparison", input.comparison);
|
|
1542
|
+
if (input.metrics?.length)
|
|
1543
|
+
params.set("metrics", input.metrics.join(","));
|
|
1544
|
+
params.set("includeSeries", String(input.includeSeries ?? false));
|
|
1545
|
+
return params;
|
|
1546
|
+
}
|
|
1547
|
+
function structuredToolResult(data) {
|
|
1548
|
+
return {
|
|
1549
|
+
structuredContent: data,
|
|
1550
|
+
content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
|
|
1551
|
+
};
|
|
1552
|
+
}
|
|
1553
|
+
function toolError(message) {
|
|
1554
|
+
return {
|
|
1555
|
+
content: [{ type: "text", text: message }],
|
|
1556
|
+
isError: true,
|
|
1557
|
+
};
|
|
1558
|
+
}
|
|
1559
|
+
function analyticsToolError(message) {
|
|
1560
|
+
return toolError(message);
|
|
1561
|
+
}
|
|
1562
|
+
function validateAnalyticsToolRange(days, startDate, endDate, includeSeries) {
|
|
1563
|
+
if ((startDate && !endDate) || (!startDate && endDate)) {
|
|
1564
|
+
return analyticsToolError("startDate and endDate must be provided together");
|
|
1565
|
+
}
|
|
1566
|
+
if (!includeSeries)
|
|
1567
|
+
return null;
|
|
1568
|
+
let rangeDays = days ?? 30;
|
|
1569
|
+
if (startDate && endDate) {
|
|
1570
|
+
const start = new Date(startDate);
|
|
1571
|
+
const end = new Date(endDate);
|
|
1572
|
+
if (Number.isNaN(start.getTime()) ||
|
|
1573
|
+
Number.isNaN(end.getTime()) ||
|
|
1574
|
+
start > end) {
|
|
1575
|
+
return analyticsToolError("The analytics date range is invalid");
|
|
1576
|
+
}
|
|
1577
|
+
rangeDays = Math.floor((end.getTime() - start.getTime()) / 86_400_000) + 1;
|
|
1578
|
+
}
|
|
1579
|
+
return rangeDays > 90
|
|
1580
|
+
? analyticsToolError("Daily series are limited to ranges of 90 days or less")
|
|
1581
|
+
: null;
|
|
1582
|
+
}
|
|
1583
|
+
async function analyticsRequest(client, path) {
|
|
1584
|
+
try {
|
|
1585
|
+
const data = await client.requestRaw("GET", path);
|
|
1586
|
+
return structuredToolResult(data);
|
|
1587
|
+
}
|
|
1588
|
+
catch (error) {
|
|
1589
|
+
return analyticsToolError(error instanceof Error ? error.message : String(error));
|
|
1590
|
+
}
|
|
1591
|
+
}
|
|
1592
|
+
const MIME_MAP = {
|
|
1593
|
+
".jpg": "image/jpeg",
|
|
1594
|
+
".jpeg": "image/jpeg",
|
|
1595
|
+
".png": "image/png",
|
|
1596
|
+
".gif": "image/gif",
|
|
1597
|
+
".mp4": "video/mp4",
|
|
1598
|
+
".mov": "video/quicktime",
|
|
1599
|
+
};
|
|
1600
|
+
function detectMime(fileName) {
|
|
1601
|
+
const ext = fileName.slice(fileName.lastIndexOf(".")).toLowerCase();
|
|
1602
|
+
return MIME_MAP[ext];
|
|
1603
|
+
}
|
|
210
1604
|
//# sourceMappingURL=tools.js.map
|