posterly-mcp-server 0.44.0 → 0.45.1

package/src/lib/alias-transport.ts

@@ -0,0 +1,233 @@
+/**
+ * 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 {
+  DEPRECATION_META_KEY,
+  deprecationNote,
+  resolveAlias,
+  translateArgs,
+  validateMode,
+  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;
+
+function requestKey(id: RequestId): string {
+  return `${typeof id}:${String(id)}`;
+}
+
+function isObject(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export class AliasTransport implements Transport {
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: <T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void;
+
+  private readonly calls = new Map<string, AliasCallInfo>();
+  /** In-flight tools/list request ids, so only their responses are filtered. */
+  private readonly listRequests = new Set<string>();
+
+  /**
+   * @param visibleTools names to list in tools/list, or null to list every
+   *   registered tool unchanged (the default: every set).
+   */
+  constructor(
+    private readonly inner: Transport,
+    private readonly registry: ToolRegistry,
+    private readonly visibleTools: Set<string> | null = null,
+    private readonly legacyValidator: LegacyAliasValidator | null = null,
+  ) {
+    inner.onmessage = (message, extra) => this.handleIncoming(message as JSONRPCMessage, extra);
+    inner.onclose = () => this.onclose?.();
+    inner.onerror = (error) => this.onerror?.(error);
+  }
+
+  get sessionId(): string | undefined {
+    return this.inner.sessionId;
+  }
+
+  setProtocolVersion(version: string): void {
+    this.inner.setProtocolVersion?.(version);
+  }
+
+  start(): Promise<void> {
+    return this.inner.start();
+  }
+
+  close(): Promise<void> {
+    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: RequestId | undefined): AliasCallInfo | undefined {
+    if (requestId === undefined || requestId === null) return undefined;
+    return this.calls.get(requestKey(requestId));
+  }
+
+  async send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void> {
+    const outgoing = this.filterToolsList(this.decorateResponse(message));
+    return this.inner.send(outgoing, options);
+  }
+
+  private handleIncoming(message: JSONRPCMessage, extra?: MessageExtraInfo): void {
+    const request = message as { id?: RequestId; method?: string; params?: any };
+    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: AliasCallInfo = {
+      calledName: alias.name,
+      target: alias.target,
+      legacyConfirm: alias.legacyConfirm === true,
+      alias,
+    };
+    this.calls.set(requestKey(request.id), info);
+
+    let callerArgs: unknown = 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 as object),
+      params: { ...request.params, name: alias.target, arguments: validated.args },
+    } as unknown as JSONRPCMessage;
+    this.onmessage?.(rewritten, extra);
+  }
+
+  /** Answers an alias call directly with a plain isError result; send() appends the rename note. */
+  private respondWithError(id: RequestId, text: string): void {
+    void this.send({
+      jsonrpc: '2.0',
+      id,
+      result: { content: [{ type: 'text', text }], isError: true },
+    } as JSONRPCMessage).catch((error) => this.onerror?.(error instanceof Error ? error : new Error(String(error))));
+  }
+
+  private filterToolsList(message: JSONRPCMessage): JSONRPCMessage {
+    const response = message as { id?: RequestId; result?: any; method?: string };
+    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 as object),
+      result: {
+        ...response.result,
+        tools: response.result.tools.filter((tool: { name?: unknown }) => typeof tool?.name === 'string' && visible.has(tool.name)),
+      },
+    };
+    return filtered as unknown as JSONRPCMessage;
+  }
+
+  private decorateResponse(message: JSONRPCMessage): JSONRPCMessage {
+    const response = message as { id?: RequestId; result?: any; error?: unknown; method?: string };
+    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 as object),
+      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 as unknown as JSONRPCMessage;
+  }
+}

package/src/lib/api-client.ts

@@ -1,5 +1,50 @@
 import { readFile } from 'fs/promises';
 import { resolve } from 'path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+
+interface ToolCallContext {
+  toolName: string;
+  toolCallId: string;
+}
+
+/**
+ * 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<ToolCallContext>();
+
+/**
+ * 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: (() => string | undefined) | null = null;
+
+export function setMcpClientNameResolver(resolver: () => string | undefined): void {
+  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: string): string {
+  return value.replace(/[^\x20-\x7e]/g, '').trim().slice(0, 200);
+}
 
 export interface Account {
   id: string;
@@ -1113,6 +1158,16 @@ export class PosterlyClient {
     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<T>(toolName: string, fn: () => Promise<T>): Promise<T> {
+    return toolCallStorage.run({ toolName, toolCallId: randomUUID() }, fn);
+  }
+
   async probeWhoami(timeoutMs = 2500): Promise<{
     ok: boolean;
     status?: number;
@@ -1190,6 +1245,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: RequestInit = { method, headers };
 

package/src/lib/preview-token-core.ts

@@ -0,0 +1,157 @@
+/**
+ * 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).
+ */
+
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+export const PREVIEW_TOKEN_VERSION = 'pv1';
+const MAC_DOMAIN = 'posterly-mcp-preview-v1';
+
+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' };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map((item) => (item === undefined ? null : sortKeysDeep(item)));
+  if (isPlainObject(value)) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = value[key];
+      if (item === undefined) continue;
+      out[key] = sortKeysDeep(item);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * 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 function canonicalJson(args: unknown): string {
+  const source = isPlainObject(args) ? args : {};
+  const stripped: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (key === 'confirm' || key === 'preview_id') continue;
+    stripped[key] = value;
+  }
+  return JSON.stringify(sortKeysDeep(stripped));
+}
+
+/** Derives the MAC key from a server secret with a domain prefix, so the raw secret is never the key. */
+export function derivePreviewKey(secret: string | Buffer, domain = 'posterly-mcp-preview-key-v1'): Buffer {
+  return createHmac('sha256', secret).update(domain).digest();
+}
+
+function field(value: string): string {
+  // Pipes separate fields; ids never contain them, but never let one shift a
+  // boundary. Percent is escaped first so the encoding is injective: a value
+  // that already contains "%7C" cannot collide with one that contains "|".
+  return value.replace(/%/g, '%25').replace(/\|/g, '%7C');
+}
+
+function computeMac(key: Buffer, exp: number, nonce: string, binding: PreviewBinding): string {
+  const payload = [
+    MAC_DOMAIN,
+    String(exp),
+    nonce,
+    field(binding.userId),
+    field(binding.tool),
+    field(binding.action),
+    canonicalJson(binding.args),
+  ].join('|');
+  return createHmac('sha256', key).update(payload).digest('base64url');
+}
+
+export function createPreviewToken(
+  key: Buffer,
+  binding: PreviewBinding,
+  options: { ttlSeconds: number; nowMs?: number; nonce?: string },
+): string {
+  const now = Math.floor((options.nowMs ?? Date.now()) / 1000);
+  const exp = now + Math.max(1, Math.floor(options.ttlSeconds));
+  const nonce = options.nonce ?? randomBytes(16).toString('base64url');
+  const mac = computeMac(key, exp, nonce, binding);
+  return `${PREVIEW_TOKEN_VERSION}.${exp}.${nonce}.${mac}`;
+}
+
+export function parsePreviewToken(token: unknown): { exp: number; nonce: string; mac: string } | null {
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 4 || parts[0] !== PREVIEW_TOKEN_VERSION) return null;
+  const [, expRaw, nonce, mac] = parts;
+  if (!/^\d{1,12}$/.test(expRaw) || !/^[A-Za-z0-9_-]{8,64}$/.test(nonce) || !/^[A-Za-z0-9_-]{20,100}$/.test(mac)) return null;
+  return { exp: Number(expRaw), nonce, mac };
+}
+
+export function verifyPreviewToken(
+  key: Buffer,
+  token: unknown,
+  binding: PreviewBinding,
+  options: { nowMs?: number } = {},
+): VerifyPreviewResult {
+  const parsed = parsePreviewToken(token);
+  if (!parsed) return { ok: false, reason: 'malformed' };
+  const expected = Buffer.from(computeMac(key, parsed.exp, parsed.nonce, binding));
+  const actual = Buffer.from(parsed.mac);
+  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+    return { ok: false, reason: 'mismatch' };
+  }
+  const now = Math.floor((options.nowMs ?? Date.now()) / 1000);
+  if (parsed.exp <= now) return { ok: false, reason: 'expired' };
+  return { ok: true, exp: parsed.exp, nonce: parsed.nonce, remainingSeconds: parsed.exp - now };
+}
+
+/** Stable fingerprint of a token for one-time-use bookkeeping (never store the raw token). */
+export function previewTokenFingerprint(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+/** Plain-language refusal for each verification failure. */
+export function previewFailureMessage(reason: 'malformed' | 'expired' | 'mismatch' | 'used' | 'missing' | 'unavailable'): string {
+  switch (reason) {
+    case 'missing':
+      return 'confirm: true needs the preview_id from a preview call. Call once without confirm, show the preview to the user, then confirm with its preview_id.';
+    case 'expired':
+      return 'This preview expired, so nothing was changed. Call again without confirm to get a fresh preview.';
+    case 'mismatch':
+      return 'This preview does not match these arguments, so nothing was changed. Call again without confirm to get a fresh preview for exactly what should happen.';
+    case 'used':
+      return 'This preview was already used, so nothing was changed. Call again without confirm to get a fresh preview.';
+    case 'unavailable':
+      return 'posterly could not check this preview right now, so nothing was changed. Please retry in a moment.';
+    default:
+      return 'preview_id is not valid, so nothing was changed. Call again without confirm to get a fresh preview.';
+  }
+}

package/src/lib/preview-token.ts

@@ -0,0 +1,54 @@
+/**
+ * Stdio (npm package) preview tokens: a random key per process and an
+ * in-memory one-time-use set. A preview only survives as long as the local
+ * MCP process does, which matches how a local client uses it (preview and
+ * confirm happen in the same session). This is UX protection only: REST
+ * authorization on the posterly API is unchanged.
+ */
+
+import { randomBytes } from 'node:crypto';
+import {
+  createPreviewToken,
+  previewTokenFingerprint,
+  verifyPreviewToken,
+  type PreviewBinding,
+  type VerifyPreviewResult,
+} from './preview-token-core.js';
+
+export const STDIO_PREVIEW_TTL_SECONDS = 10 * 60;
+
+export class StdioPreviewTokens {
+  private readonly key: Buffer;
+  private readonly used = new Map<string, number>();
+
+  constructor(key: Buffer = randomBytes(32), private readonly ttlSeconds = STDIO_PREVIEW_TTL_SECONDS) {
+    this.key = key;
+  }
+
+  create(binding: PreviewBinding, nowMs?: number): string {
+    return createPreviewToken(this.key, binding, { ttlSeconds: this.ttlSeconds, nowMs });
+  }
+
+  verify(token: unknown, binding: PreviewBinding, nowMs?: number): VerifyPreviewResult {
+    return verifyPreviewToken(this.key, token, binding, { nowMs });
+  }
+
+  /**
+   * Marks a verified token as used. Returns false when it was already used
+   * (a second confirm with the same preview_id). Call only after verify().
+   */
+  claimOnce(token: string, expSeconds: number, nowMs = Date.now()): boolean {
+    this.sweep(nowMs);
+    const fingerprint = previewTokenFingerprint(token);
+    if (this.used.has(fingerprint)) return false;
+    this.used.set(fingerprint, expSeconds);
+    return true;
+  }
+
+  private sweep(nowMs: number): void {
+    const now = Math.floor(nowMs / 1000);
+    for (const [fingerprint, exp] of this.used) {
+      if (exp <= now) this.used.delete(fingerprint);
+    }
+  }
+}