@muxoai/sdk 1.3.0 → 1.4.2

package/dist/mcp-schema.d.ts

@@ -0,0 +1,286 @@
+import type { HumanHandoff } from "./types.js";
+export interface McpToolAnnotations {
+    title?: string;
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint?: boolean;
+    openWorldHint: boolean;
+}
+export declare const LATEST_MCP_PROTOCOL_VERSION = "2026-07-28";
+export declare const DEFAULT_LEGACY_MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * Dual-era MCP protocol versions supported by Muxo:
+ * - Modern stateless era: 2026-07-28 (SEP-2575 server/discover, SEP-2549 caching, MRTR resultType)
+ * - Legacy session era: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
+ */
+export declare const SUPPORTED_MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const MCP_ERR_HEADER_MISMATCH = -32020;
+export declare const MCP_ERR_MISSING_REQUIRED_CLIENT_CAPABILITY = -32021;
+export declare const MCP_ERR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
+export declare function isSupportedMcpProtocolVersion(version: unknown): boolean;
+/**
+ * Decodes an MCP Streamable HTTP header value (`Mcp-Name`, `Mcp-Param-*`),
+ * supporting plain ASCII as well as the 2026-07-28 Base64 sentinel format (`=:base64:...:`)
+ * and RFC 2047 `=?utf-8?B?...?=`.
+ */
+export declare function decodeMcpHeaderValue(raw: string): string;
+export interface McpHttpHeaderValidationInput {
+    protocolVersion?: string | null;
+    method?: string | null;
+    name?: string | null;
+}
+export interface McpJsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Validates MCP 2026-07-28 Streamable HTTP headers (`MCP-Protocol-Version`, `Mcp-Method`,
+ * `Mcp-Name`) and per-request `params._meta["io.modelcontextprotocol/protocolVersion"]`
+ * against the JSON-RPC request body.
+ *
+ * Returns `-32020 HeaderMismatch` when `Mcp-Method` or `Mcp-Name` conflicts with the body,
+ * and `-32022 UnsupportedProtocolVersion` when an unsupported protocol version is requested.
+ */
+export declare function validateMcpHttpHeadersAndMeta(headers: McpHttpHeaderValidationInput, rpc: unknown): {
+    ok: true;
+    protocolVersion: string;
+} | {
+    ok: false;
+    id: unknown;
+    error: McpJsonRpcErrorObject;
+};
+/**
+ * Builds the canonical MCP 2026-07-28 `server/discover` response (SEP-2575 + SEP-2549).
+ * Includes both top-level `serverInfo`/`instructions` and `_meta["io.modelcontextprotocol/*"]`
+ * so both strict 2026-07-28 validators and dual-era clients succeed.
+ */
+export declare function buildMcpDiscoverResult(serverVersion: string): Record<string, unknown>;
+/**
+ * Canonical MCP Resource Templates (`resources/templates/list`) for parameterized
+ * governance, tool catalog, and skill inspection.
+ */
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+}
+export declare const MUXO_MCP_RESOURCE_TEMPLATES: McpResourceTemplate[];
+/**
+ * Evaluates MCP `completion/complete` requests for prompt arguments and resource templates.
+ */
+export declare function completeMcpArgument(params: Record<string, unknown> | undefined, toolSlugs?: string[]): {
+    values: string[];
+    total: number;
+    hasMore: boolean;
+};
+export interface McpToolSecurityScheme {
+    type: "noauth" | "oauth2";
+    scopes?: string[];
+}
+export interface McpToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    securitySchemes?: McpToolSecurityScheme[];
+    annotations: McpToolAnnotations;
+    _meta?: Record<string, unknown>;
+}
+export declare const MCP_TOOLS_OAUTH_SCOPE = "mcp:tools";
+/** Workspace-bound tools require an OAuth bearer token (or workspace API key). */
+export declare const DEFAULT_TOOL_SECURITY_SCHEMES: McpToolSecurityScheme[];
+/** Catalog discovery tools work anonymously and also accept OAuth. */
+export declare const PUBLIC_TOOL_SECURITY_SCHEMES: McpToolSecurityScheme[];
+export declare const PUBLIC_MCP_TOOL_NAMES: ReadonlySet<string>;
+export declare const MUXO_UI_WIDGET_URI = "ui://widget/muxo-card.html";
+export declare const MUXO_UI_MCP_APP_URI = "ui://widget/muxo-app.html";
+/**
+ * Tools whose results represent interactive user-facing milestones (catalog carousel,
+ * OAuth handoff, action plan review/edit, execution receipt, or workspace summary).
+ * Pure data/inspection helpers remain usable without forcing unnecessary widget remounts.
+ */
+export declare const UI_RENDERED_MCP_TOOL_NAMES: ReadonlySet<string>;
+export declare function mcpToolUiMeta(invoking: string, invoked: string, extra?: Record<string, unknown>): Record<string, unknown>;
+export interface OpenAiClientRequestMeta {
+    locale?: string;
+    userAgent?: string;
+    userLocation?: {
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+        longitude?: number;
+        latitude?: number;
+    };
+    subject?: string;
+    session?: string;
+    organization?: string;
+    widgetSessionId?: string;
+}
+/**
+ * Extracts optional OpenAI / MCP Apps client hints from JSON-RPC `params._meta`
+ * (`openai/locale`, `openai/userAgent`, `openai/userLocation`, `openai/subject`,
+ * `openai/session`, `openai/organization`, `openai/widgetSessionId`).
+ * These are best-effort hints and must never be used for authorization decisions.
+ */
+export declare function extractOpenAiClientMeta(params?: Record<string, unknown> | null): OpenAiClientRequestMeta;
+/**
+ * Enriches a tool descriptor for `tools/list` with both top-level `securitySchemes`
+ * and `_meta.securitySchemes` back-compat mirror per the OpenAI Plugin UI reference,
+ * as well as all four standard MCP tool annotations (`readOnlyHint`, `destructiveHint`,
+ * `idempotentHint`, `openWorldHint`).
+ */
+export declare function buildMcpToolDescriptor(tool: McpToolDefinition): McpToolDefinition;
+/**
+ * Builds the `_meta` object returned on `tools/call` results. Delivers widget-only
+ * metadata (`_meta`) without bloating the model-visible conversation transcript.
+ */
+export declare function buildMcpToolResultMeta(toolName: string, params?: Record<string, unknown> | null): Record<string, unknown>;
+/**
+ * Builds the `_meta` object for error tool results, including RFC 7235
+ * `_meta["mcp/www_authenticate"]` when an authentication challenge is required.
+ */
+export declare function buildMcpErrorResultMeta(err: unknown, baseUrl?: string): Record<string, unknown> | undefined;
+/** Stable per-workspace agent identity returned at agent signup on both runtimes. */
+export declare function workspaceAgentDid(workspaceId: string): string;
+/** JSON-RPC methods that anonymous MCP clients may call for discovery. */
+export declare const PUBLIC_MCP_METHODS: ReadonlySet<string>;
+/** True when a single JSON-RPC MCP request only needs public discovery access. */
+export declare function isPublicMcpRequest(rpc: unknown): boolean;
+export declare function securitySchemesForTool(name: string): McpToolSecurityScheme[];
+/** Maximum in-turn polling window for wait_for_connection and get_plan(wait_for_approval). */
+export declare const MAX_MCP_WAIT_SECONDS = 120;
+export declare const DEFAULT_MCP_WAIT_SECONDS = 15;
+export declare function clampWaitSeconds(raw: unknown, fallback?: number, max?: number): number;
+/** Matches explicit catalog slugs (e.g. 'app.github.create_issue') as opposed to natural-language requests. */
+export declare function looksLikeToolSlug(raw: string): boolean;
+/**
+ * Picks the live Composio search hit for a requested `app.<toolkit>.<action>` slug: an exact
+ * slug/upstream match, else a same-toolkit tool whose slug contains every action word. Returns
+ * null rather than an unrelated top search result.
+ */
+export declare function matchAppToolSlug<T extends {
+    slug: string;
+    upstreamSlug: string;
+    providerSlug: string;
+}>(requestedSlug: string, candidates: T[]): T | null;
+export declare const DEFAULT_MCP_SKILL_NAME = "muxo";
+/**
+ * SEP-2640 `skills/get` lookup. A `uri` takes precedence over `name`, and a miss returns
+ * `skill: undefined` so callers answer with JSON-RPC -32602 rather than a default skill.
+ */
+export declare function findMcpSkill<T extends {
+    uri: string;
+    name: string;
+}>(skills: readonly T[], params: {
+    uri?: unknown;
+    name?: unknown;
+}): {
+    skill: T | undefined;
+    requested: string;
+};
+export declare const APPROVED_PLAN_STATUSES: ReadonlySet<string>;
+export declare const GET_RUN_CONTEXT_ACTIONS: readonly ["inspect", "remember", "recall", "forget", "memory_graph", "set_guardrail", "reset_guardrails", "check_policy", "kill_switch", "governance_status", "scan_context", "list_workspaces", "switch_workspace", "onboard_team"];
+/** Error carrying a structured MCP/REST payload (merged into structuredContent / JSON body). */
+export declare class MuxoToolError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly payload: Record<string, unknown>;
+    constructor(message: string, options: {
+        code: string;
+        statusCode?: number;
+        payload?: Record<string, unknown>;
+    });
+}
+export declare function unknownToolError(slug: string): MuxoToolError;
+export interface ApprovalGatePlan {
+    id: string;
+    toolSlug: string;
+    riskLevel: string;
+    approvalStatus: string;
+}
+export declare function buildApprovalUrl(baseUrl: string, planId: string): string;
+export declare function buildApprovalHumanHandoff(baseUrl: string, plan: ApprovalGatePlan): HumanHandoff;
+export declare function buildOAuthHumanHandoff(params: {
+    providerSlug: string;
+    providerName?: string;
+    redirectUrl: string | null;
+    instructions?: string;
+}): HumanHandoff;
+/** Structured response returned when execute_<risk> is called on a plan still awaiting approval. */
+export declare function buildApprovalRequiredPayload(baseUrl: string, plan: ApprovalGatePlan): Record<string, unknown>;
+export declare function approvalRequiredError(baseUrl: string, plan: ApprovalGatePlan): MuxoToolError;
+export declare function errorPayloadFrom(err: unknown, fallback?: string): Record<string, unknown>;
+export interface OnboardTeamGuideInput {
+    baseUrl: string;
+    workspaceId: string;
+    workspaceName: string;
+    teamName?: string;
+    workspaces?: unknown[];
+}
+/**
+ * MCP onboard_team never mints credentials in-band; it returns the human handoff
+ * (Console / CLI / REST) that issues a Team API key so secrets stay out of agent transcripts.
+ */
+export declare function buildOnboardTeamGuide(input: OnboardTeamGuideInput): Record<string, unknown>;
+/**
+ * Concise server instructions (<512 chars) per OpenAI Plugin MCP Server specification:
+ * https://developers.openai.com/plugins/build/mcp-server
+ */
+export declare const MUXO_MCP_SERVER_INSTRUCTIONS = "Muxo governs SaaS actions (app.*), Instant tools (instant.*), Cloud Infrastructure (resource.*), Memory, and Guardrails. Workflow: 1) search_tools & inspect_tool. 2) plan_action to get a plan_*. 3) If authHandoff.required, show humanHandoff.url and call wait_for_connection. 4) If approvalStatus is pending_approval, send humanHandoff.url or call get_plan(wait_for_approval:true). 5) Execute via execute_<risk>. 6) Manage memory/guardrails via get_run_context.";
+export declare const MUXO_MCP_TOOLS: McpToolDefinition[];
+/**
+ * OpenAI Company Knowledge standard `search` and `fetch` tool definitions
+ * per https://developers.openai.com/plugins/build/mcp-server#company-knowledge-compatibility
+ */
+export declare const OPENAI_COMPANY_KNOWLEDGE_TOOLS: McpToolDefinition[];
+export interface McpNextToolCallHint {
+    tool: string;
+    input: Record<string, unknown>;
+    when: string;
+}
+export interface McpHarnessGuidance {
+    summary: string;
+    nextToolCalls: McpNextToolCallHint[];
+}
+/**
+ * Enriches any MCP tool output object with structured `llmGuidance` so agent harnesses
+ * (Claude Code, Cursor, Codex, OpenAI MCP, Windsurf) always know the exact next tool call.
+ */
+export declare function attachMcpHarnessGuidance<T>(toolName: string, toolArgs: Record<string, unknown>, output: T): T;
+export interface McpUiResourceDescriptor {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    _meta: Record<string, unknown>;
+}
+/**
+ * Canonical OpenAI Plugin UI (`text/html+skybridge`) & MCP Apps (`text/html;profile=mcp-app`)
+ * widget resource descriptors exposed by `resources/list` and `resources/read`.
+ * Follows:
+ * - https://developers.openai.com/plugins/reference
+ * - https://developers.openai.com/plugins/build/chatgpt-ui
+ * - https://developers.openai.com/plugins/concepts/ui-guidelines
+ */
+export declare const MUXO_UI_CSP_DOMAINS: readonly ["https://api.muxo.ai", "https://muxo.ai", "https://app.muxo.ai"];
+export declare const MUXO_UI_REDIRECT_DOMAINS: readonly ["https://api.muxo.ai", "https://muxo.ai", "https://app.muxo.ai", "https://connect.composio.dev", "https://backend.composio.dev"];
+export declare const MUXO_UI_RESOURCES: McpUiResourceDescriptor[];
+/**
+ * Renders the self-contained OpenAI Plugin UI / MCP App widget HTML (`ui://widget/muxo-card.html`).
+ * Strictly adheres to https://developers.openai.com/plugins/concepts/ui-guidelines:
+ * - System font stack (`-apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", system-ui, sans-serif`)
+ * - Light & dark mode CSS variables (`window.openai.theme` + `prefers-color-scheme`)
+ * - Brand accent (`#6366F1` light / `#818CF8` dark) only on primary buttons & badges (WCAG AA)
+ * - Monochromatic outlined SVG icons; no duplicate app logo header
+ * - Auto-fitting inline card with no nested scrollbars (`notifyIntrinsicHeight`), max 2 bottom CTAs
+ * - Inline 3–8 card carousel for `search_tools` catalog results
+ * - Inline editable parameter controls for `plan_action` before clicking Execute
+ * - Expand to fullscreen (`requestDisplayMode({ mode: "fullscreen" })`) for rich inspection
+ */
+export declare function renderMuxoUiWidgetHtml(baseUrl?: string): string;