mcp-usage-control-mcp 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import type { ServerContext } from '@modelcontextprotocol/server';
+import { type Principal, type UsageControl, type UsageLease, type UsageLeaseResumeState } from 'mcp-usage-control';
+type MaybePromise<T> = T | Promise<T>;
+export interface ProtectToolOptions<TArgs, TResult> {
+    control: UsageControl;
+    tool: string;
+    /**
+     * Set to true when the MCP tool has no input schema.
+     *
+     * The SDK's TypeScript callback type is `(ctx)` for no-input tools, while
+     * some server dispatch paths invoke the callback at runtime as `({}, ctx)`.
+     * An empty object is indistinguishable from valid args for an empty input
+     * schema, so this adapter requires an explicit mode instead of guessing.
+     */
+    noInput?: boolean;
+    principal(ctx: ServerContext): MaybePromise<Principal>;
+    operationId(args: TArgs, ctx: ServerContext): MaybePromise<string>;
+    /** Disable only when the application renews the lease itself. Defaults to true. */
+    leaseHeartbeat?: boolean;
+    /**
+     * Best-effort notification that automatic lease renewal became acknowledgement-ambiguous,
+     * or that a later renewal confirmed the lease again. The callback is advisory only: it
+     * never changes authoritative accounting state and callback failures are ignored.
+     */
+    onLeaseRenewalState?(event: LeaseRenewalStateEvent): MaybePromise<void>;
+    successUnits?(input: {
+        result: TResult;
+        args: TArgs;
+        ctx: ServerContext;
+        lease: UsageLease;
+    }): MaybePromise<number>;
+    toolErrorUnits?(input: {
+        result: TResult;
+        args: TArgs;
+        ctx: ServerContext;
+        lease: UsageLease;
+    }): MaybePromise<number>;
+    errorUnits?(input: {
+        error: unknown;
+        args: TArgs;
+        ctx: ServerContext;
+        lease: UsageLease;
+    }): MaybePromise<number>;
+}
+export type LeaseRenewalStateEvent = {
+    status: 'uncertain';
+    lease: UsageLease;
+    error: unknown;
+} | {
+    status: 'confirmed';
+    lease: UsageLease;
+};
+export type NoInputProtectToolOptions<TResult> = ProtectToolOptions<undefined, TResult> & {
+    noInput: true;
+};
+export type InputProtectToolOptions<TArgs, TResult> = ProtectToolOptions<TArgs, TResult> & {
+    noInput?: false;
+};
+export type NoInputProtectedToolHandler<TResult> = (ctx: ServerContext) => Promise<TResult>;
+export type InputProtectedToolHandler<TArgs, TResult> = (args: TArgs, ctx: ServerContext) => Promise<TResult>;
+/** Decoded payload expected from the SDK requestState verification hook. */
+export interface McpUsageRequestStatePayload {
+    mcpUsageControl: 1;
+    flowId: string;
+}
+/**
+ * Binding checked atomically before a suspended flow is consumed.
+ * The args hash prevents a retry from changing the original tool arguments.
+ */
+export interface McpUsageFlowBinding {
+    principalId: string;
+    tenantId?: string;
+    tool: string;
+    argsHash: string;
+}
+/** Serializable trusted server-side state for one suspended MCP usage flow. */
+export interface McpUsageFlowRecord {
+    flowId: string;
+    binding: McpUsageFlowBinding;
+    lease: UsageLeaseResumeState;
+    /** First handler entry is round 0; the first retry is round 1. */
+    round: number;
+    expiresAt: number;
+    /** Original handler-authored requestState, retained server-side rather than trusted from the client. */
+    applicationRequestState?: string;
+}
+/**
+ * Server-side suspended-flow storage.
+ *
+ * `consume()` MUST atomically compare `binding`, reject expired state using the
+ * store's authoritative time domain, and remove the flow only when it matches
+ * and remains valid. A mismatched or expired caller must receive undefined
+ * without consuming a legitimate live flow. A successfully returned record is
+ * authoritative proof that suspended-flow expiry passed; callers MUST NOT
+ * reinterpret that result using an unrelated application-host clock. This
+ * one-time consume prevents concurrent retry re-entry.
+ */
+export interface McpUsageFlowStore {
+    suspend(record: McpUsageFlowRecord): MaybePromise<void>;
+    consume(flowId: string, binding: McpUsageFlowBinding): MaybePromise<McpUsageFlowRecord | undefined>;
+}
+/**
+ * Process-local flow store for tests and single-process servers.
+ *
+ * Instantiate it outside a `createMcpHandler` per-request factory. Distributed
+ * or horizontally scaled servers should provide a durable store with atomic
+ * compare-and-consume semantics instead.
+ */
+export declare class MemoryMcpUsageFlowStore implements McpUsageFlowStore {
+    private readonly flows;
+    suspend(record: McpUsageFlowRecord): void;
+    consume(flowId: string, binding: McpUsageFlowBinding): McpUsageFlowRecord | undefined;
+    private pruneExpired;
+}
+export interface McpUsageRequestStateMinter {
+    /**
+     * Mint an integrity-protected requestState value for the client round-trip.
+     * Use the same codec whose `verify` hook is configured on the MCP server.
+     */
+    mint(payload: McpUsageRequestStatePayload, ctx: ServerContext): MaybePromise<string>;
+}
+export interface McpUsageFlowContext {
+    /** First handler entry is 0; each successful resume increments it by one. */
+    readonly round: number;
+    /** Stable logical operation ID from the first round. */
+    readonly operationId: string;
+    /**
+     * Handler-authored requestState captured from the prior input_required result.
+     * It came from trusted server-side flow storage; the wrapper-owned wire
+     * requestState is not exposed here.
+     */
+    readonly applicationRequestState?: string;
+}
+export interface ProtectMultiRoundToolOptions<TArgs, TResult> extends ProtectToolOptions<TArgs, TResult> {
+    flowStore: McpUsageFlowStore;
+    requestState: McpUsageRequestStateMinter;
+    /** Explicit human/input suspension lease duration. Required to avoid an accidental unbounded hold. */
+    suspendTtlMs: number;
+    /** Maximum number of resumed rounds. Defaults to 8. */
+    maxRounds?: number;
+    /** Test/custom ID generator. Defaults to a cryptographically random ID. */
+    flowId?: () => MaybePromise<string>;
+}
+export type NoInputProtectMultiRoundToolOptions<TResult> = ProtectMultiRoundToolOptions<undefined, TResult> & {
+    noInput: true;
+};
+export type InputProtectMultiRoundToolOptions<TArgs, TResult> = ProtectMultiRoundToolOptions<TArgs, TResult> & {
+    noInput?: false;
+};
+export declare class UsageSettlementError extends Error {
+    readonly settlementError: unknown;
+    readonly executionError?: unknown | undefined;
+    constructor(message: string, settlementError: unknown, executionError?: unknown | undefined);
+}
+export declare class UsageClassificationError extends Error {
+    readonly classificationError: unknown;
+    readonly executionError?: unknown | undefined;
+    constructor(message: string, classificationError: unknown, executionError?: unknown | undefined);
+}
+export declare class UnsupportedMcpUsageFlowError extends Error {
+    constructor(message: string);
+}
+export declare class McpUsageResumeError extends Error {
+    constructor(message: string);
+}
+export declare class McpUsageRoundsExceededError extends Error {
+    constructor(message: string);
+}
+/** No-input-schema overload. `noInput: true` is required. */
+export declare function protectTool<TResult>(options: NoInputProtectToolOptions<TResult>, handler: (args: undefined, ctx: ServerContext) => MaybePromise<TResult>): NoInputProtectedToolHandler<TResult>;
+/** Input-schema overload. `noInput` must be omitted or false. */
+export declare function protectTool<TArgs, TResult>(options: InputProtectToolOptions<TArgs, TResult>, handler: (args: TArgs, ctx: ServerContext) => MaybePromise<TResult>): InputProtectedToolHandler<TArgs, TResult>;
+/** No-input-schema multi-round overload. */
+export declare function protectMultiRoundTool<TResult>(options: NoInputProtectMultiRoundToolOptions<TResult>, handler: (args: undefined, ctx: ServerContext, flow: McpUsageFlowContext) => MaybePromise<TResult>): NoInputProtectedToolHandler<TResult>;
+/** Input-schema multi-round overload. */
+export declare function protectMultiRoundTool<TArgs, TResult>(options: InputProtectMultiRoundToolOptions<TArgs, TResult>, handler: (args: TArgs, ctx: ServerContext, flow: McpUsageFlowContext) => MaybePromise<TResult>): InputProtectedToolHandler<TArgs, TResult>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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