postfast-mcp 0.1.24 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "postfast",
       "description": "Schedule, manage, and analyze social media posts via PostFast. Supports Facebook, Instagram, X, TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, and Google Business Profile.",
-      "version": "0.1.24",
+      "version": "0.3.0",
       "author": {
         "name": "PostFast",
         "email": "me@peturgeorgievv.com"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "postfast",
   "description": "Schedule, manage, and analyze social media posts via PostFast. Supports Facebook, Instagram, X, TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, and Google Business Profile. After installing, tell Cowork: 'Set my PostFast API key' — get your key at https://app.postfa.st/dashboard → API.",
-  "version": "0.1.24",
+  "version": "0.3.0",
   "author": {
     "name": "PostFast",
     "email": "me@peturgeorgievv.com"

package/README.md

@@ -189,9 +189,16 @@ Full REST API documentation: [postfa.st/docs](https://postfa.st/docs)
 ```bash
 npm install
 npm run build
-node dist/index.js
+node dist/stdio/index.js
 ```
 
+Tools are authored once in `src/core` (the catalog — schemas, descriptions,
+annotations, per-binding availability) and exposed to consumers as
+`postfast-mcp/core`; `src/stdio` binds the catalog to the public REST API.
+Releases: PRs add a `.changeset/*.md`; `npm run version` folds them into the
+bump + changelog, and pushing the `vX.Y.Z` tag publishes npm + MCP Registry +
+the MCPB release from CI (OIDC — no tokens anywhere).
+
 ## Badges
 
 [![peturgeorgievv-factory/postfast-mcp MCP server](https://glama.ai/mcp/servers/peturgeorgievv-factory/postfast-mcp/badges/score.svg)](https://glama.ai/mcp/servers/peturgeorgievv-factory/postfast-mcp)

package/dist/core/backend-port.d.ts

@@ -0,0 +1,138 @@
+import type { AnalyticsResponse, FollowerHistory, GbpLocation, PaginatedPosts, PinterestBoard, Place, SignedUploadUrl, SocialAccount, YouTubePlaylist } from './types.js';
+export interface ListPostsArgs {
+    page: number;
+    limit: number;
+    ids?: string[];
+    platforms?: string[];
+    statuses?: string[];
+    from?: string;
+    to?: string;
+}
+export interface CreatePostsArgs {
+    posts: unknown[];
+    status: string;
+    approvalStatus: string;
+    controls?: Record<string, unknown>;
+}
+export interface ApprovePostsArgs {
+    postIds: string[];
+    approvalStatus: string;
+}
+export interface AnalyticsArgs {
+    startDate: string;
+    endDate: string;
+    platforms?: string[];
+    socialMediaIds?: string[];
+}
+export interface FollowerHistoryArgs {
+    socialMediaId: string;
+    from?: string;
+    to?: string;
+}
+export interface ConnectLinkArgs {
+    expiryDays: number;
+    sendEmail: boolean;
+    email?: string;
+}
+export interface UploadUrlsArgs {
+    contentType: string;
+    count: number;
+}
+export interface ListInboxConversationsArgs {
+    page: number;
+    limit: number;
+    platforms?: string[];
+    socialMediaIds?: string[];
+    statuses?: string[];
+    unreadOnly?: boolean;
+    assignedToUserId?: string;
+}
+export interface ListInboxItemsArgs {
+    conversationId: string;
+    page: number;
+    limit: number;
+    order?: 'ASC' | 'DESC';
+}
+export interface InboxReplyArgs {
+    itemId: string;
+    text: string;
+}
+export interface SetInboxItemStateArgs {
+    itemId: string;
+    action: string;
+}
+export interface SetInboxConversationStatusArgs {
+    conversationId: string;
+    status: string;
+}
+export interface AssignInboxConversationArgs {
+    conversationId: string;
+    assigneeUserId?: string;
+}
+export interface UploadFromUrlArgs {
+    sourceUrl: string;
+    contentType?: string;
+}
+/** Remote conversation-media upload: a client-provided file ref or base64 bytes. */
+export interface UploadMediaArgs {
+    file?: {
+        download_url: string;
+        file_id: string;
+        mime_type?: string;
+        file_name?: string;
+    };
+    data?: string;
+    contentType?: string;
+}
+export interface LocalUploadResult {
+    key: string;
+    type: 'IMAGE' | 'VIDEO';
+    contentType: string;
+}
+/**
+ * Everything the catalog tools need from a backend. The stdio bin implements
+ * it over the public REST API (pf-api-key); the deployed host implements it
+ * over its command gateway + upload service. `workspaceId` is only ever set on
+ * the remote binding — adapters without workspace switching ignore it.
+ *
+ * Adapters may throw from methods whose tools they never register
+ * (e.g. the REST adapter for the remote-only conversation-media uploads).
+ */
+export interface BackendPort {
+    listWorkspaces(): Promise<unknown>;
+    listAccounts(workspaceId?: string): Promise<SocialAccount[] | unknown>;
+    getFollowerHistory(args: FollowerHistoryArgs, workspaceId?: string): Promise<FollowerHistory | unknown>;
+    listPinterestBoards(socialMediaId: string, workspaceId?: string): Promise<PinterestBoard[] | unknown>;
+    listYoutubePlaylists(socialMediaId: string, workspaceId?: string): Promise<YouTubePlaylist[] | unknown>;
+    listGbpLocations(socialMediaId: string, workspaceId?: string): Promise<GbpLocation[] | unknown>;
+    searchPlaces(query: string, workspaceId?: string): Promise<Place[] | unknown>;
+    generateConnectLink(args: ConnectLinkArgs, workspaceId?: string): Promise<{
+        connectUrl: string;
+    } | unknown>;
+    listPosts(args: ListPostsArgs, workspaceId?: string): Promise<PaginatedPosts | unknown>;
+    createPosts(args: CreatePostsArgs, workspaceId?: string): Promise<{
+        postIds: string[];
+    } | unknown>;
+    approvePosts(args: ApprovePostsArgs, workspaceId?: string): Promise<unknown>;
+    deletePost(id: string, workspaceId?: string): Promise<{
+        deleted: boolean;
+    } | unknown>;
+    getPostAnalytics(args: AnalyticsArgs, workspaceId?: string): Promise<AnalyticsResponse | unknown>;
+    getUploadUrls(args: UploadUrlsArgs, workspaceId?: string): Promise<SignedUploadUrl[] | unknown>;
+    /** stdio only: read a local file and push it through the signed-URL flow. */
+    uploadLocalFile(filePath: string): Promise<LocalUploadResult>;
+    /** Remote only: server-side fetch of a public https URL (SSRF-guarded in the host). */
+    uploadFromUrl(args: UploadFromUrlArgs, workspaceId?: string): Promise<unknown>;
+    /** Remote only: upload a conversation-attached file or base64 bytes. */
+    uploadMedia(args: UploadMediaArgs, workspaceId?: string): Promise<unknown>;
+    listInboxConversations?(args: ListInboxConversationsArgs, workspaceId?: string): Promise<unknown>;
+    getInboxConversation?(id: string, workspaceId?: string): Promise<unknown>;
+    listInboxItems?(args: ListInboxItemsArgs, workspaceId?: string): Promise<unknown>;
+    getInboxUnreadCount?(workspaceId?: string): Promise<unknown>;
+    replyToInboxItem?(args: InboxReplyArgs, workspaceId?: string): Promise<unknown>;
+    sendInboxPrivateReply?(args: InboxReplyArgs, workspaceId?: string): Promise<unknown>;
+    setInboxItemState?(args: SetInboxItemStateArgs, workspaceId?: string): Promise<unknown>;
+    markInboxConversationRead?(conversationId: string, workspaceId?: string): Promise<unknown>;
+    setInboxConversationStatus?(args: SetInboxConversationStatusArgs, workspaceId?: string): Promise<unknown>;
+    assignInboxConversation?(args: AssignInboxConversationArgs, workspaceId?: string): Promise<unknown>;
+}

package/dist/core/backend-port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backend-port.js.map

package/dist/core/backend-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-port.js","sourceRoot":"","sources":["../../src/core/backend-port.ts"],"names":[],"mappings":""}

package/dist/core/build-tools.d.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { BackendPort } from './backend-port.js';
+import type { Binding, ResolvedTool } from './tool-def.js';
+export interface BuildToolsOptions {
+    binding: Binding;
+    /**
+     * Inject an optional `workspaceId` field into every workspace-scoped tool
+     * (the remote host's multi-workspace connections). The stdio bin never sets
+     * this — its pf-api-key is already workspace-scoped.
+     */
+    withWorkspaceField?: boolean;
+    /**
+     * When given, tools whose `portMethod` the port instance does not implement
+     * are skipped with a stderr log — so an adapter built against an older
+     * catalog keeps working when a newer catalog adds tools it can't serve yet.
+     */
+    port?: BackendPort;
+}
+/** Resolve the catalog for one binding: filter, flatten binding-variant fields. */
+export declare function buildTools(options: BuildToolsOptions): ResolvedTool[];
+/**
+ * Wrap backend data as MCP content: a JSON text block (proven across all
+ * clients — and byte-stable for existing stdio consumers) plus
+ * structuredContent for clients that consume outputSchema. Bare-array
+ * responses are wrapped as { data } there, since structuredContent must be an
+ * object; the text block stays the raw response.
+ */
+export declare function toolResult(data: unknown): CallToolResult;
+/** A business/tool error the model should see and react to (not a protocol error). */
+export declare function toolError(message: string): CallToolResult;
+/** Run a handler, converting thrown errors into `isError` tool results. */
+export declare function runTool(fn: () => Promise<unknown>): Promise<CallToolResult>;
+export interface RegisterToolsOptions extends BuildToolsOptions {
+    port: BackendPort;
+}
+/** Register the resolved catalog for a binding on an MCP server. */
+export declare function registerCatalogTools(server: McpServer, options: RegisterToolsOptions): void;

package/dist/core/build-tools.js

@@ -0,0 +1,84 @@
+import { workspaceIdField } from './shared.js';
+import { ALL_TOOLS } from './tools/index.js';
+/** Resolve the catalog for one binding: filter, flatten binding-variant fields. */
+export function buildTools(options) {
+    const { binding, withWorkspaceField = false, port } = options;
+    return ALL_TOOLS.filter((def) => {
+        if (def.binding !== 'both' && def.binding !== binding)
+            return false;
+        if (port &&
+            def.portMethod &&
+            typeof port[def.portMethod] !== 'function') {
+            console.error(`[postfast-mcp/core] skipping tool "${def.name}": the backend port does not implement ${def.portMethod}() yet (older adapter, newer catalog)`);
+            return false;
+        }
+        return true;
+    }).map((def) => {
+        const inputSchema = typeof def.inputSchema === 'function' ? def.inputSchema(binding) : def.inputSchema;
+        return {
+            name: def.name,
+            title: def.title,
+            description: typeof def.description === 'function' ? def.description(binding) : def.description,
+            inputSchema: withWorkspaceField && def.workspaceScoped !== false
+                ? { ...inputSchema, workspaceId: workspaceIdField }
+                : inputSchema,
+            outputSchema: def.outputSchema,
+            annotations: def.annotations,
+            _meta: def._meta,
+            portMethod: def.portMethod,
+            run: def.run,
+        };
+    });
+}
+/**
+ * Wrap backend data as MCP content: a JSON text block (proven across all
+ * clients — and byte-stable for existing stdio consumers) plus
+ * structuredContent for clients that consume outputSchema. Bare-array
+ * responses are wrapped as { data } there, since structuredContent must be an
+ * object; the text block stays the raw response.
+ */
+export function toolResult(data) {
+    const result = {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+    if (data && typeof data === 'object') {
+        result.structuredContent = Array.isArray(data)
+            ? { data }
+            : data;
+    }
+    return result;
+}
+/** A business/tool error the model should see and react to (not a protocol error). */
+export function toolError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+/** Run a handler, converting thrown errors into `isError` tool results. */
+export async function runTool(fn) {
+    try {
+        return toolResult(await fn());
+    }
+    catch (err) {
+        return toolError(err.message || 'Tool execution failed.');
+    }
+}
+/** Register the resolved catalog for a binding on an MCP server. */
+export function registerCatalogTools(server, options) {
+    const { port } = options;
+    for (const tool of buildTools(options)) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+            annotations: tool.annotations,
+            ...(tool._meta ? { _meta: tool._meta } : {}),
+        }, (args) => runTool(() => {
+            const { workspaceId, ...rest } = args ?? {};
+            return tool.run(port, rest, workspaceId);
+        }));
+    }
+}
+//# sourceMappingURL=build-tools.js.map

package/dist/core/build-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-tools.js","sourceRoot":"","sources":["../../src/core/build-tools.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The PostFast MCP tool catalog — the single place tools are authored.
+ * Consumed by two bindings: the stdio bin in this package and the deployed
+ * remote host (social-schedule-mcp). Import as "postfast-mcp/core".
+ */
+export * from './backend-port.js';
+export { buildTools, registerCatalogTools, runTool, toolError, toolResult, type BuildToolsOptions, type RegisterToolsOptions, } from './build-tools.js';
+export { SERVER_INSTRUCTIONS, instructionsFor } from './instructions.js';
+export { CREATE_APPROVAL_STATUSES, CREATE_STATUSES, IMAGE_MIME_TYPES, PLATFORMS, POST_STATUSES, SET_APPROVAL_STATUSES, VIDEO_MIME_TYPES, dataListOutputSchema, jsonParse, workspaceIdField, } from './shared.js';
+export type { Binding, ResolvedTool, ToolAnnotations, ToolDef, } from './tool-def.js';
+export { ALL_TOOLS } from './tools/index.js';
+export * from './types.js';

package/dist/core/index.js

@@ -0,0 +1,12 @@
+/**
+ * The PostFast MCP tool catalog — the single place tools are authored.
+ * Consumed by two bindings: the stdio bin in this package and the deployed
+ * remote host (social-schedule-mcp). Import as "postfast-mcp/core".
+ */
+export * from './backend-port.js';
+export { buildTools, registerCatalogTools, runTool, toolError, toolResult, } from './build-tools.js';
+export { SERVER_INSTRUCTIONS, instructionsFor } from './instructions.js';
+export { CREATE_APPROVAL_STATUSES, CREATE_STATUSES, IMAGE_MIME_TYPES, PLATFORMS, POST_STATUSES, SET_APPROVAL_STATUSES, VIDEO_MIME_TYPES, dataListOutputSchema, jsonParse, workspaceIdField, } from './shared.js';
+export { ALL_TOOLS } from './tools/index.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,OAAO,EACP,SAAS,EACT,UAAU,GAGX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAOrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,cAAc,YAAY,CAAC"}

package/dist/core/instructions.d.ts

@@ -0,0 +1,3 @@
+import type { Binding } from './tool-def.js';
+export declare const SERVER_INSTRUCTIONS: Record<Binding, string>;
+export declare function instructionsFor(binding: Binding): string;

package/dist/core/instructions.js

@@ -0,0 +1,63 @@
+/**
+ * Server `instructions` sent at MCP `initialize` — standing guidance the client
+ * model reads before calling tools. Grounded in the PostFast docs + the
+ * backend's actual create-posts validation, so it matches what the API
+ * enforces (prevents the model discovering rules by failing).
+ *
+ * The two bindings differ only where their tool surfaces differ: workspace
+ * switching and conversation-media/URL uploads exist on the remote host, the
+ * stdio bin uploads local files instead.
+ */
+const SHARED_TAIL = `Before scheduling, confirm the target account's connectionStatus is CONNECTED. A DISABLED account will not publish (disconnected accounts are the #1 cause of failed posts) — saving a DRAFT is still allowed.
+
+Status & timing: status=SCHEDULED requires scheduledAt on every post (ISO-8601, in the future, within 1 year); status=DRAFT must omit scheduledAt. approvalStatus=APPROVED publishes; PENDING_APPROVAL holds it for review. There is no instant "publish now" — for an immediate post, set scheduledAt a few minutes ahead of now (a time at or before the current moment is rejected).
+
+Media: use the key returned by an upload tool, and set mediaItems[].type to match the file (IMAGE for image/* keys, VIDEO for video/* keys — a mismatch is rejected). Videos are capped at 250MB (Telegram 50MB, Bluesky 100MB). Media is REQUIRED on TikTok, YouTube (video only), Instagram, Pinterest, and Google Business Profile; X, LinkedIn, Facebook, Threads, Bluesky, and Telegram allow text-only posts. This requirement applies even to DRAFTS — a draft to a media-required platform without media is rejected. So if the user asks to post to a media-required platform and provides no media, ask them for an image/video (or generate and upload one) BEFORE calling create_posts; don't attempt the post without media.
+
+Per-platform limits (media counts / characters):
+- X: up to 4 images or 1 video (no mixing); 280 chars (4,000 with X Premium).
+- TikTok: 1 video OR up to 10 images; 4,000 chars.
+- Instagram: up to 10 images + 10 videos (mixed OK); 2,200 chars, max 30 hashtags.
+- YouTube: 1 video, no images; title max 100 chars.
+- Facebook / LinkedIn: up to 10 images + 1 video.
+- Threads: up to 10 images + 10 videos; 500 chars.
+- Pinterest: up to 5 images or 1 video; title max 100, description max 800.
+- Google Business Profile: 1 image; 1,500 chars.
+- Bluesky: up to 4 images or 1 video. Telegram: up to 10 images + 3 videos.
+If content exceeds the target platform's character limit, don't schedule it as-is — tell the user and offer to shorten or split it (X is 280 unless the account has X Premium = 4,000).
+
+Platform-specific options go in the controls object, e.g.:
+- Pinterest: controls.pinterestBoardId is REQUIRED — it is a board's boardId from list_pinterest_boards, NOT the Pinterest account's socialMediaId.
+- Google Business Profile: controls.gbpLocationId is required — the locationId from list_gbp_locations.
+- YouTube: controls.youtubePlaylistId is the playlistId from list_youtube_playlists; youtubeIsShort defaults true; title falls back to the first 100 chars of content.
+- TikTok: controls.tiktokPrivacy is deprecated (videos use the account default, photos default to public); tiktokTitle applies to photo carousels only (max 90); firstComment supported on Business accounts (max 150, comments must be enabled).
+- Instagram: controls.instagramPublishType = TIMELINE | STORY | REEL.
+- Facebook: controls.facebookContentType = POST | REEL | STORY. controls.facebookTargetCountries limits who can see a FEED post by country (ISO 3166-1 alpha-2, max 25; not Reels/Stories).
+- Geotag a place (Facebook/Instagram): call search_places, then pass a returned id as controls.facebookPlaceId (Facebook feed posts only — not Reels/Stories/video) and/or controls.instagramLocationId (Instagram single media only — not carousels). One id works for both.
+- LinkedIn: attach a document via controls.linkedinAttachmentKey.
+- X: controls.xRetweetUrl reposts an existing tweet (content/media are ignored).
+Note: list_pinterest_boards / list_youtube_playlists / list_gbp_locations take the account's socialMediaId; each returned item has BOTH an internal id and the platform id (boardId / playlistId / locationId) — pass the PLATFORM id to controls, not the internal id or the account id.
+
+Failed posts carry lastError — usually a disconnected account (reconnect, then retry) or platform-rejected media.`;
+const STDIO_INSTRUCTIONS = `PostFast schedules and publishes social posts across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram, and Google Business Profile.
+
+Flow: list_accounts to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_media (a local file, by absolute path) or get_upload_urls (signed PUT upload for raw bytes) → a post publishes when status=SCHEDULED and approvalStatus=APPROVED.
+
+The POSTFAST_API_KEY is workspace-scoped — every tool acts in that workspace.
+
+${SHARED_TAIL}`;
+const REMOTE_INSTRUCTIONS = `PostFast schedules and publishes social posts across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram, and Google Business Profile.
+
+Flow: list_accounts (+ list_workspaces) to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_from_url (a public https URL) or upload_media (a ChatGPT-attached/generated image, or base64) → a post publishes when status=SCHEDULED and approvalStatus=APPROVED.
+
+Workspaces: omit workspaceId to use the connection's default; pass a workspaceId (from list_workspaces) to act in another workspace.
+
+${SHARED_TAIL}`;
+export const SERVER_INSTRUCTIONS = {
+    stdio: STDIO_INSTRUCTIONS,
+    remote: REMOTE_INSTRUCTIONS,
+};
+export function instructionsFor(binding) {
+    return SERVER_INSTRUCTIONS[binding];
+}
+//# sourceMappingURL=instructions.js.map

package/dist/core/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/core/instructions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kHA8B8F,CAAC;AAEnH,MAAM,kBAAkB,GAAG;;;;;;EAMzB,WAAW,EAAE,CAAC;AAEhB,MAAM,mBAAmB,GAAG;;;;;;EAM1B,WAAW,EAAE,CAAC;AAEhB,MAAM,CAAC,MAAM,mBAAmB,GAA4B;IAC1D,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;CAC5B,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/core/shared.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const PLATFORMS: readonly ["FACEBOOK", "INSTAGRAM", "X", "TIKTOK", "LINKEDIN", "YOUTUBE", "BLUESKY", "THREADS", "PINTEREST", "TELEGRAM", "GOOGLE_BUSINESS_PROFILE"];
+export declare const POST_STATUSES: readonly ["DRAFT", "SCHEDULED", "PUBLISHED", "FAILED"];
+export declare const INBOX_CONVERSATION_STATUSES: readonly ["OPEN", "SNOOZED", "CLOSED"];
+export declare const INBOX_ITEM_STATE_ACTIONS: readonly ["HIDE", "UNHIDE", "DELETE"];
+export declare const CREATE_STATUSES: readonly ["DRAFT", "SCHEDULED"];
+export declare const CREATE_APPROVAL_STATUSES: readonly ["PENDING_APPROVAL", "APPROVED"];
+export declare const SET_APPROVAL_STATUSES: readonly ["PENDING_APPROVAL", "IN_PROGRESS", "APPROVED", "REJECTED", "NEEDS_WORK"];
+export declare const IMAGE_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp"];
+export declare const VIDEO_MIME_TYPES: readonly ["video/mp4", "video/webm", "video/quicktime"];
+/** Some MCP clients stringify complex params — parse them back before validation. */
+export declare function jsonParse<T extends z.ZodTypeAny>(schema: T): z.ZodPreprocess<T>;
+/**
+ * Permissive output schema for list-style tools: { data: [...] }. Items are
+ * unknown (never type-rejected) and extra top-level keys (totalCount, pageInfo)
+ * pass through — so structuredContent is advertised without breaking on real
+ * backend responses.
+ */
+export declare const dataListOutputSchema: {
+    data: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+};
+/** Optional per-call workspace selector, injected only on the remote binding. */
+export declare const workspaceIdField: z.ZodOptional<z.ZodUUID>;

package/dist/core/shared.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+export const PLATFORMS = [
+    'FACEBOOK',
+    'INSTAGRAM',
+    'X',
+    'TIKTOK',
+    'LINKEDIN',
+    'YOUTUBE',
+    'BLUESKY',
+    'THREADS',
+    'PINTEREST',
+    'TELEGRAM',
+    'GOOGLE_BUSINESS_PROFILE',
+];
+export const POST_STATUSES = ['DRAFT', 'SCHEDULED', 'PUBLISHED', 'FAILED'];
+export const INBOX_CONVERSATION_STATUSES = ['OPEN', 'SNOOZED', 'CLOSED'];
+export const INBOX_ITEM_STATE_ACTIONS = ['HIDE', 'UNHIDE', 'DELETE'];
+export const CREATE_STATUSES = ['DRAFT', 'SCHEDULED'];
+export const CREATE_APPROVAL_STATUSES = ['PENDING_APPROVAL', 'APPROVED'];
+export const SET_APPROVAL_STATUSES = [
+    'PENDING_APPROVAL',
+    'IN_PROGRESS',
+    'APPROVED',
+    'REJECTED',
+    'NEEDS_WORK',
+];
+export const IMAGE_MIME_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+];
+export const VIDEO_MIME_TYPES = ['video/mp4', 'video/webm', 'video/quicktime'];
+/** Some MCP clients stringify complex params — parse them back before validation. */
+export function jsonParse(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === 'string') {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, schema);
+}
+/**
+ * Permissive output schema for list-style tools: { data: [...] }. Items are
+ * unknown (never type-rejected) and extra top-level keys (totalCount, pageInfo)
+ * pass through — so structuredContent is advertised without breaking on real
+ * backend responses.
+ */
+export const dataListOutputSchema = { data: z.array(z.unknown()).optional() };
+/** Optional per-call workspace selector, injected only on the remote binding. */
+export const workspaceIdField = z
+    .uuid()
+    .optional()
+    .describe("Target workspace id (from list_workspaces). Omit to use the connection's default workspace.");
+//# sourceMappingURL=shared.js.map

package/dist/core/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/core/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU;IACV,WAAW;IACX,GAAG;IACH,QAAQ;IACR,UAAU;IACV,SAAS;IACT,SAAS;IACT,SAAS;IACT,WAAW;IACX,UAAU;IACV,yBAAyB;CACjB,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AACpF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAClF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,WAAW,CAAU,CAAC;AAC/D,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,kBAAkB,EAAE,UAAU,CAAU,CAAC;AAClF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,kBAAkB;IAClB,aAAa;IACb,UAAU;IACV,UAAU;IACV,YAAY;CACJ,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,YAAY;IACZ,WAAW;IACX,WAAW;IACX,YAAY;CACJ,CAAC;AACX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,YAAY,EAAE,iBAAiB,CAAU,CAAC;AAExF,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAyB,MAAS;IACzD,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,EAAE;QAC1B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,GAAG,CAAC;YACb,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;AAE9E,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,IAAI,EAAE;KACN,QAAQ,EAAE;KACV,QAAQ,CACP,6FAA6F,CAC9F,CAAC"}

package/dist/core/tool-def.d.ts

@@ -0,0 +1,55 @@
+import type { ZodRawShape } from 'zod';
+import type { BackendPort } from './backend-port.js';
+/** The two deployments a catalog tool can ship in. */
+export type Binding = 'stdio' | 'remote';
+export interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint?: boolean;
+    openWorldHint: boolean;
+}
+/**
+ * One tool as authored in the catalog. `description`/`inputSchema` may be a
+ * function of the binding for the few spots where the surfaces genuinely
+ * differ (upload-tool references — stdio uploads local files, the remote
+ * uploads conversation media/URLs). Everything else is binding-invariant.
+ */
+export interface ToolDef {
+    name: string;
+    /** Which binding(s) expose the tool. */
+    binding: Binding | 'both';
+    title: string;
+    description: string | ((binding: Binding) => string);
+    inputSchema: ZodRawShape | ((binding: Binding) => ZodRawShape);
+    outputSchema?: ZodRawShape;
+    annotations: ToolAnnotations;
+    /** Extra tool metadata, e.g. the ChatGPT file-param marker on upload_media. */
+    _meta?: Record<string, unknown>;
+    /** False only for tools that are not scoped to a workspace (list_workspaces). */
+    workspaceScoped?: boolean;
+    /**
+     * The BackendPort method this tool's run() dispatches to. When set and the
+     * port instance lacks the method (an older adapter running a newer catalog),
+     * the tool is skipped at registration with a stderr log instead of shipping
+     * a broken tool — lets bindings adopt new tool waves on their own schedule.
+     */
+    portMethod?: keyof BackendPort;
+    /**
+     * Dispatch to the backend. `args` are the validated tool arguments minus
+     * `workspaceId`, which is split off by the registrar and passed separately
+     * (always undefined on stdio — the pf-api-key is already workspace-scoped).
+     */
+    run: (port: BackendPort, args: Record<string, unknown>, workspaceId?: string) => Promise<unknown>;
+}
+/** A ToolDef with binding-dependent fields resolved for one concrete binding. */
+export interface ResolvedTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    outputSchema?: ZodRawShape;
+    annotations: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+    portMethod?: keyof BackendPort;
+    run: ToolDef['run'];
+}

package/dist/core/tool-def.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-def.js.map

package/dist/core/tool-def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-def.js","sourceRoot":"","sources":["../../src/core/tool-def.ts"],"names":[],"mappings":""}

package/dist/core/tools/accounts.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tool-def.js';
+export declare const accountTools: ToolDef[];