posterly-mcp-server 0.43.8 → 0.45.0

package/dist/lib/alias-transport.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Transport wrapper that keeps renamed MCP tools working on the stdio package
+ * without registering the old names with McpServer (so they never appear in
+ * tools/list).
+ *
+ * Incoming: a tools/call whose name is an alias is rewritten BEFORE McpServer
+ * sees it: params.name becomes the target tool and params.arguments become
+ * the translated arguments, so the SDK validates them against the canonical
+ * schema. The request id is remembered with the alias details.
+ *
+ * Handlers read that per-request info through getCallInfo(extra.requestId):
+ * the called name (for the X-Posterly-Tool telemetry header) and whether the
+ * alias may still confirm in one step. Nothing is stored in the arguments.
+ *
+ * Outgoing: the response for that id gets the rename note APPENDED as a final
+ * text item (content[0] is never touched) plus _meta["posterly/deprecation"],
+ * and the remembered entry is deleted. A notifications/cancelled for that id
+ * also deletes it (the SDK sends no response for a cancelled request).
+ *
+ * Legacy input schemas: when a legacyValidator is given, an alias call's
+ * arguments are first checked against the OLD tool's exact input schema, so a
+ * call the old tool rejected gets the same SDK validation error text (and a
+ * call it accepted gets the same parsed arguments, defaults included) before
+ * translation. The npm package passes the old zod schemas here.
+ *
+ * Tool sets: every tool stays registered (so a call to any tool always
+ * works); when a visible set is given, only the outgoing tools/list result is
+ * filtered to it.
+ *
+ * Only the public Transport interface is used; no SDK private fields.
+ */
+import type { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage, MessageExtraInfo, RequestId } from '@modelcontextprotocol/sdk/types.js';
+import { type ResolvedAlias, type ToolRegistry } from './tool-registry.js';
+export interface AliasCallInfo {
+    /** The name the client called (the alias). */
+    calledName: string;
+    /** The canonical tool the call was routed to. */
+    target: string;
+    /** The alias may confirm with confirm:true alone until its sunset date. */
+    legacyConfirm: boolean;
+    alias: ResolvedAlias;
+}
+/**
+ * Checks an alias call's raw arguments against the old tool's input schema.
+ * Return null when the alias has no legacy schema (no check), the parsed
+ * arguments when they are valid, or the exact error text the old tool gave.
+ */
+export type LegacyAliasValidator = (aliasName: string, args: unknown) => {
+    ok: true;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+} | null;
+export declare class AliasTransport implements Transport {
+    private readonly inner;
+    private readonly registry;
+    private readonly visibleTools;
+    private readonly legacyValidator;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
+    private readonly calls;
+    /** In-flight tools/list request ids, so only their responses are filtered. */
+    private readonly listRequests;
+    /**
+     * @param visibleTools names to list in tools/list, or null to list every
+     *   registered tool unchanged (the default: every set).
+     */
+    constructor(inner: Transport, registry: ToolRegistry, visibleTools?: Set<string> | null, legacyValidator?: LegacyAliasValidator | null);
+    get sessionId(): string | undefined;
+    setProtocolVersion(version: string): void;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    /** Alias details for an in-flight tools/call, or undefined for a canonical call. */
+    getCallInfo(requestId: RequestId | undefined): AliasCallInfo | undefined;
+    send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+    private handleIncoming;
+    /** Answers an alias call directly with a plain isError result; send() appends the rename note. */
+    private respondWithError;
+    private filterToolsList;
+    private decorateResponse;
+}

package/dist/lib/alias-transport.js

@@ -0,0 +1,193 @@
+/**
+ * Transport wrapper that keeps renamed MCP tools working on the stdio package
+ * without registering the old names with McpServer (so they never appear in
+ * tools/list).
+ *
+ * Incoming: a tools/call whose name is an alias is rewritten BEFORE McpServer
+ * sees it: params.name becomes the target tool and params.arguments become
+ * the translated arguments, so the SDK validates them against the canonical
+ * schema. The request id is remembered with the alias details.
+ *
+ * Handlers read that per-request info through getCallInfo(extra.requestId):
+ * the called name (for the X-Posterly-Tool telemetry header) and whether the
+ * alias may still confirm in one step. Nothing is stored in the arguments.
+ *
+ * Outgoing: the response for that id gets the rename note APPENDED as a final
+ * text item (content[0] is never touched) plus _meta["posterly/deprecation"],
+ * and the remembered entry is deleted. A notifications/cancelled for that id
+ * also deletes it (the SDK sends no response for a cancelled request).
+ *
+ * Legacy input schemas: when a legacyValidator is given, an alias call's
+ * arguments are first checked against the OLD tool's exact input schema, so a
+ * call the old tool rejected gets the same SDK validation error text (and a
+ * call it accepted gets the same parsed arguments, defaults included) before
+ * translation. The npm package passes the old zod schemas here.
+ *
+ * Tool sets: every tool stays registered (so a call to any tool always
+ * works); when a visible set is given, only the outgoing tools/list result is
+ * filtered to it.
+ *
+ * Only the public Transport interface is used; no SDK private fields.
+ */
+import { DEPRECATION_META_KEY, deprecationNote, resolveAlias, translateArgs, validateMode, } from './tool-registry.js';
+function requestKey(id) {
+    return `${typeof id}:${String(id)}`;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export class AliasTransport {
+    inner;
+    registry;
+    visibleTools;
+    legacyValidator;
+    onclose;
+    onerror;
+    onmessage;
+    calls = new Map();
+    /** In-flight tools/list request ids, so only their responses are filtered. */
+    listRequests = new Set();
+    /**
+     * @param visibleTools names to list in tools/list, or null to list every
+     *   registered tool unchanged (the default: every set).
+     */
+    constructor(inner, registry, visibleTools = null, legacyValidator = null) {
+        this.inner = inner;
+        this.registry = registry;
+        this.visibleTools = visibleTools;
+        this.legacyValidator = legacyValidator;
+        inner.onmessage = (message, extra) => this.handleIncoming(message, extra);
+        inner.onclose = () => this.onclose?.();
+        inner.onerror = (error) => this.onerror?.(error);
+    }
+    get sessionId() {
+        return this.inner.sessionId;
+    }
+    setProtocolVersion(version) {
+        this.inner.setProtocolVersion?.(version);
+    }
+    start() {
+        return this.inner.start();
+    }
+    close() {
+        this.calls.clear();
+        this.listRequests.clear();
+        return this.inner.close();
+    }
+    /** Alias details for an in-flight tools/call, or undefined for a canonical call. */
+    getCallInfo(requestId) {
+        if (requestId === undefined || requestId === null)
+            return undefined;
+        return this.calls.get(requestKey(requestId));
+    }
+    async send(message, options) {
+        const outgoing = this.filterToolsList(this.decorateResponse(message));
+        return this.inner.send(outgoing, options);
+    }
+    handleIncoming(message, extra) {
+        const request = message;
+        if (request.method === 'notifications/cancelled') {
+            const cancelled = isObject(request.params) ? request.params.requestId : undefined;
+            if (typeof cancelled === 'string' || typeof cancelled === 'number') {
+                this.calls.delete(requestKey(cancelled));
+                this.listRequests.delete(requestKey(cancelled));
+            }
+            this.onmessage?.(message, extra);
+            return;
+        }
+        if (request.method === 'tools/list' && this.visibleTools && request.id !== undefined && request.id !== null) {
+            this.listRequests.add(requestKey(request.id));
+            this.onmessage?.(message, extra);
+            return;
+        }
+        if (request.method !== 'tools/call' || request.id === undefined || request.id === null || !isObject(request.params)) {
+            this.onmessage?.(message, extra);
+            return;
+        }
+        const name = request.params.name;
+        const alias = typeof name === 'string' ? resolveAlias(this.registry, name) : null;
+        if (!alias) {
+            this.onmessage?.(message, extra);
+            return;
+        }
+        const info = {
+            calledName: alias.name,
+            target: alias.target,
+            legacyConfirm: alias.legacyConfirm === true,
+            alias,
+        };
+        this.calls.set(requestKey(request.id), info);
+        let callerArgs = request.params.arguments;
+        const legacy = this.legacyValidator ? this.legacyValidator(alias.name, callerArgs) : null;
+        if (legacy && !legacy.ok) {
+            this.respondWithError(request.id, legacy.message);
+            return;
+        }
+        if (legacy?.ok)
+            callerArgs = legacy.args;
+        // alias.mode pins a param-driven target to the old tool's mode.
+        const validated = validateMode(this.registry, alias.target, translateArgs(alias, callerArgs), alias.mode);
+        if (!validated.ok) {
+            // A plain error before any request, same as the hosted endpoint; the
+            // rename note is still appended by send() so the caller learns the new
+            // name either way.
+            this.respondWithError(request.id, validated.error);
+            return;
+        }
+        const rewritten = {
+            ...message,
+            params: { ...request.params, name: alias.target, arguments: validated.args },
+        };
+        this.onmessage?.(rewritten, extra);
+    }
+    /** Answers an alias call directly with a plain isError result; send() appends the rename note. */
+    respondWithError(id, text) {
+        void this.send({
+            jsonrpc: '2.0',
+            id,
+            result: { content: [{ type: 'text', text }], isError: true },
+        }).catch((error) => this.onerror?.(error instanceof Error ? error : new Error(String(error))));
+    }
+    filterToolsList(message) {
+        const response = message;
+        if (!this.visibleTools || response.method !== undefined || response.id === undefined || response.id === null)
+            return message;
+        const key = requestKey(response.id);
+        if (!this.listRequests.has(key))
+            return message;
+        this.listRequests.delete(key);
+        if (!isObject(response.result) || !Array.isArray(response.result.tools))
+            return message;
+        const visible = this.visibleTools;
+        const filtered = {
+            ...message,
+            result: {
+                ...response.result,
+                tools: response.result.tools.filter((tool) => typeof tool?.name === 'string' && visible.has(tool.name)),
+            },
+        };
+        return filtered;
+    }
+    decorateResponse(message) {
+        const response = message;
+        if (response.method !== undefined || response.id === undefined || response.id === null)
+            return message;
+        const key = requestKey(response.id);
+        const info = this.calls.get(key);
+        if (!info)
+            return message;
+        this.calls.delete(key);
+        if (!isObject(response.result) || !Array.isArray(response.result.content))
+            return message;
+        const note = deprecationNote(info.alias);
+        const decorated = {
+            ...message,
+            result: {
+                ...response.result,
+                content: [...response.result.content, { type: 'text', text: note.text }],
+                _meta: { ...(isObject(response.result._meta) ? response.result._meta : {}), [DEPRECATION_META_KEY]: note.meta },
+            },
+        };
+        return decorated;
+    }
+}

package/dist/lib/api-client.d.ts

@@ -1,3 +1,14 @@
+export declare function setMcpClientNameResolver(resolver: () => string | undefined): void;
+/**
+ * HTTP header values must be printable Latin-1 with no control characters;
+ * Node's fetch throws (not returns an error, THROWS) on a header value
+ * containing anything else, so an MCP client reporting a non-ASCII name
+ * (e.g. "通义灵码") or one with an en/em dash would otherwise break every
+ * single tool call. Strips anything outside printable ASCII rather than
+ * encoding it, since this is just a display label, not data that needs to
+ * round-trip losslessly.
+ */
+export declare function sanitizeClientHeaderValue(value: string): string;
 export interface Account {
     id: string;
     platform: string;
@@ -320,6 +331,67 @@ export type AskSupportPayload = {
     confirm_escalation?: boolean;
 };
 export type ApiKeyScope = 'accounts:read' | 'accounts:write' | 'posts:read' | 'posts:write' | 'media:write' | 'analytics:read' | 'billing:read' | 'billing:write';
+export type WorkspaceMemberRole = 'publisher' | 'editor' | 'viewer';
+export type WorkspaceMemberSummary = {
+    id: string;
+    user_id: string | null;
+    email: string | null;
+    name: string | null;
+    role: string | null;
+    status: string | null;
+    /** [] = every brand; missing = not visible to a brand-limited caller. */
+    brand_ids?: string[];
+    joined_at: string | null;
+    created_at: string | null;
+};
+export type WorkspaceInviteSummary = {
+    id: string;
+    email: string | null;
+    role: string | null;
+    status: string | null;
+    brand_ids?: string[];
+    expires_at: string | null;
+    created_at: string | null;
+};
+export type WorkspaceMembersResponse = {
+    workspace_id: string;
+    members: WorkspaceMemberSummary[];
+    invites: WorkspaceInviteSummary[];
+    usage: {
+        active_members: number;
+        pending_invites: number;
+        seats_used: number;
+    };
+};
+export type WorkspaceMemberPreview = {
+    action: string;
+    summary: string;
+    email: string | null;
+    role: string | null;
+    previous_role: string | null;
+    brand_ids: string[] | null;
+    previous_brand_ids: string[] | null;
+    sends_email: boolean;
+    counts_toward_seats: boolean;
+    seats_used: number | null;
+    seat_limit: number | null;
+};
+export type WorkspaceMemberChangeResponse = {
+    requires_confirmation?: boolean;
+    preview?: WorkspaceMemberPreview;
+    preview_id?: string;
+    preview_expires_at?: string;
+    status?: string;
+    message?: string;
+    invite?: WorkspaceInviteSummary;
+    member?: WorkspaceMemberSummary;
+    email_sent?: boolean;
+    owner_notified?: boolean;
+};
+export type WorkspaceMemberConfirmFields = {
+    confirm?: boolean;
+    preview_id?: string;
+};
 export type CreateApiKeyPayload = {
     name?: string;
     scopes?: ApiKeyScope[];
@@ -988,6 +1060,13 @@ export declare class PosterlyClient {
     constructor(apiKey?: string, baseUrl?: string);
     hasApiKey(): boolean;
     getBaseUrl(): string;
+    /**
+     * Runs `fn` with a fresh per-call tool name/id scoped via AsyncLocalStorage,
+     * so any request() calls made inside it (directly or nested) are tagged
+     * with X-Posterly-Tool / X-Posterly-Tool-Call. Called once per tool
+     * invocation from index.ts's server.tool() handlers.
+     */
+    runToolCall<T>(toolName: string, fn: () => Promise<T>): Promise<T>;
     probeWhoami(timeoutMs?: number): Promise<{
         ok: boolean;
         status?: number;
@@ -1005,6 +1084,24 @@ export declare class PosterlyClient {
     deleteApiKey(keyId: string, data: {
         confirm: true;
     }): Promise<DeleteApiKeyResponse>;
+    listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMembersResponse>;
+    inviteWorkspaceMember(workspaceId: string, data: {
+        email: string;
+        role: WorkspaceMemberRole;
+        brand_ids?: string[];
+        resend?: boolean;
+    } & WorkspaceMemberConfirmFields): Promise<WorkspaceMemberChangeResponse>;
+    updateWorkspaceMember(workspaceId: string, target: {
+        member_id?: string;
+        invite_id?: string;
+    }, data: {
+        role?: WorkspaceMemberRole;
+        brand_ids?: string[];
+    } & WorkspaceMemberConfirmFields): Promise<WorkspaceMemberChangeResponse>;
+    removeWorkspaceMember(workspaceId: string, target: {
+        member_id?: string;
+        invite_id?: string;
+    }, data: WorkspaceMemberConfirmFields): Promise<WorkspaceMemberChangeResponse>;
     getSubscription(): Promise<SubscriptionSummaryResponse>;
     getCredits(): Promise<CreditsSummaryResponse>;
     cancelSubscription(data: CancelSubscriptionPayload): Promise<CancelSubscriptionResponse>;

package/dist/lib/api-client.js

@@ -1,5 +1,41 @@
 import { readFile } from 'fs/promises';
 import { resolve } from 'path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+/**
+ * Scopes the current tool name/call id to the async execution of a single
+ * tool call, so request() can tag its headers without a mutable "current
+ * tool" field on the shared PosterlyClient singleton (index.ts registers one
+ * client instance for every tool). AsyncLocalStorage keeps overlapping calls
+ * from clobbering each other's context if the stdio transport ever
+ * dispatches tool calls concurrently.
+ */
+const toolCallStorage = new AsyncLocalStorage();
+/**
+ * Resolves the connected MCP client's name (e.g. "claude-ai", "chatgpt"), set
+ * once by index.ts after the server is constructed. A resolver function
+ * rather than a static value because the SDK only learns the client's
+ * identity once the initialize handshake completes, which happens after this
+ * module is first loaded; reading through the resolver on every request
+ * always gets the current value instead of whatever was available at import
+ * time (undefined).
+ */
+let clientNameResolver = null;
+export function setMcpClientNameResolver(resolver) {
+    clientNameResolver = resolver;
+}
+/**
+ * HTTP header values must be printable Latin-1 with no control characters;
+ * Node's fetch throws (not returns an error, THROWS) on a header value
+ * containing anything else, so an MCP client reporting a non-ASCII name
+ * (e.g. "通义灵码") or one with an en/em dash would otherwise break every
+ * single tool call. Strips anything outside printable ASCII rather than
+ * encoding it, since this is just a display label, not data that needs to
+ * round-trip losslessly.
+ */
+export function sanitizeClientHeaderValue(value) {
+    return value.replace(/[^\x20-\x7e]/g, '').trim().slice(0, 200);
+}
 export class PosterlyClient {
     baseUrl;
     apiKey;
@@ -16,6 +52,15 @@ export class PosterlyClient {
     getBaseUrl() {
         return this.baseUrl;
     }
+    /**
+     * Runs `fn` with a fresh per-call tool name/id scoped via AsyncLocalStorage,
+     * so any request() calls made inside it (directly or nested) are tagged
+     * with X-Posterly-Tool / X-Posterly-Tool-Call. Called once per tool
+     * invocation from index.ts's server.tool() handlers.
+     */
+    async runToolCall(toolName, fn) {
+        return toolCallStorage.run({ toolName, toolCallId: randomUUID() }, fn);
+    }
     async probeWhoami(timeoutMs = 2500) {
         const startedAt = Date.now();
         if (!this.apiKey) {
@@ -78,6 +123,16 @@ export class PosterlyClient {
             Authorization: `Bearer ${this.apiKey}`,
             'X-Posterly-Source': 'mcp_stdio',
         };
+        const toolCall = toolCallStorage.getStore();
+        if (toolCall) {
+            headers['X-Posterly-Tool'] = toolCall.toolName;
+            headers['X-Posterly-Tool-Call'] = toolCall.toolCallId;
+        }
+        const clientName = clientNameResolver?.();
+        const clientLabel = clientName ? sanitizeClientHeaderValue(clientName) : '';
+        if (clientLabel) {
+            headers['X-Posterly-Client'] = clientLabel;
+        }
         const init = { method, headers };
         if (body instanceof FormData) {
             init.body = body;
@@ -123,6 +178,32 @@ export class PosterlyClient {
     async deleteApiKey(keyId, data) {
         return this.request('DELETE', `/api-keys/${encodeURIComponent(keyId)}`, data);
     }
+    async listWorkspaceMembers(workspaceId) {
+        return this.request('GET', `/workspaces/${encodeURIComponent(workspaceId)}/members`);
+    }
+    async inviteWorkspaceMember(workspaceId, data) {
+        return this.request('POST', `/workspaces/${encodeURIComponent(workspaceId)}/members`, data);
+    }
+    async updateWorkspaceMember(workspaceId, target, data) {
+        const base = `/workspaces/${encodeURIComponent(workspaceId)}`;
+        const path = target.member_id
+            ? `${base}/members/${encodeURIComponent(target.member_id)}`
+            : `${base}/invites/${encodeURIComponent(target.invite_id || '')}`;
+        return this.request('PATCH', path, data);
+    }
+    async removeWorkspaceMember(workspaceId, target, data) {
+        const base = `/workspaces/${encodeURIComponent(workspaceId)}`;
+        const path = target.member_id
+            ? `${base}/members/${encodeURIComponent(target.member_id)}`
+            : `${base}/invites/${encodeURIComponent(target.invite_id || '')}`;
+        const params = new URLSearchParams();
+        if (data.confirm === true)
+            params.set('confirm', 'true');
+        if (data.preview_id)
+            params.set('preview_id', data.preview_id);
+        const qs = params.toString();
+        return this.request('DELETE', `${path}${qs ? `?${qs}` : ''}`);
+    }
     async getSubscription() {
         return this.request('GET', '/subscription');
     }

package/dist/lib/preview-token-core.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Preview-then-confirm tokens for MCP write actions, shared by both surfaces.
+ * Depends on node:crypto only.
+ *
+ * Format: pv1.<exp>.<nonce>.<mac>
+ *   exp   unix seconds when the preview stops being confirmable
+ *   nonce random, base64url; also the one-time-use key for nonce actions
+ *   mac   base64url HMAC-SHA256(key,
+ *           "posterly-mcp-preview-v1|" + exp + "|" + nonce + "|" + userId
+ *           + "|" + tool + "|" + action + "|" + canonicalJson(args))
+ *
+ * The token binds the preview to one user, one tool, one action, and the
+ * exact (normalised) arguments, so a confirm call with different args, from a
+ * different user, or after expiry is refused. It is UX protection that a
+ * human saw what will change, not authorization: REST scopes and ownership
+ * checks still decide what is allowed.
+ *
+ * Callers own the key (hosted: derived from a server secret; stdio: random
+ * per process) and the one-time-use store (hosted: Redis; stdio: memory).
+ */
+export declare const PREVIEW_TOKEN_VERSION = "pv1";
+export interface PreviewBinding {
+    userId: string;
+    tool: string;
+    action: string;
+    /** Arguments AFTER validation/normalisation (defaults applied, numbers coerced). */
+    args: unknown;
+}
+export type VerifyPreviewResult = {
+    ok: true;
+    exp: number;
+    nonce: string;
+    remainingSeconds: number;
+} | {
+    ok: false;
+    reason: 'malformed' | 'expired' | 'mismatch';
+};
+/**
+ * Canonical JSON of a call's arguments: `confirm` and `preview_id` removed
+ * (top level), undefined dropped, keys sorted recursively, arrays kept in
+ * order, no whitespace. Same rules as canonicalArgs in tool-registry.ts.
+ */
+export declare function canonicalJson(args: unknown): string;
+/** Derives the MAC key from a server secret with a domain prefix, so the raw secret is never the key. */
+export declare function derivePreviewKey(secret: string | Buffer, domain?: string): Buffer;
+export declare function createPreviewToken(key: Buffer, binding: PreviewBinding, options: {
+    ttlSeconds: number;
+    nowMs?: number;
+    nonce?: string;
+}): string;
+export declare function parsePreviewToken(token: unknown): {
+    exp: number;
+    nonce: string;
+    mac: string;
+} | null;
+export declare function verifyPreviewToken(key: Buffer, token: unknown, binding: PreviewBinding, options?: {
+    nowMs?: number;
+}): VerifyPreviewResult;
+/** Stable fingerprint of a token for one-time-use bookkeeping (never store the raw token). */
+export declare function previewTokenFingerprint(token: string): string;
+/** Plain-language refusal for each verification failure. */
+export declare function previewFailureMessage(reason: 'malformed' | 'expired' | 'mismatch' | 'used' | 'missing' | 'unavailable'): string;