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