/**
* Progress notification service for MCP tools.
*
* Provides a lightweight abstraction over MCP's stable `notifications/progress`
* mechanism. Tool functions accept an optional `ProgressReporter` to emit
* per-step progress without depending on the full `RequestHandlerExtra` type.
*/
export interface ProgressReporter {
/** Report that step `current` of `total` is done, with an optional status message. */
report(current: number, total: number, message?: string): Promise<void>;
/** Whether the client actually requested progress (sent a progressToken). */
readonly enabled: boolean;
}
/**
* Creates a `ProgressReporter` from an MCP tool handler's `extra` parameter.
*
* If the client did not include a `progressToken` in `_meta`, the returned
* reporter is a no-op (`.enabled === false`), so callers can always call
* `progress.report()` unconditionally.
*
* @param progressToken Value of `extra._meta?.progressToken`
* @param sendNotification Value of `extra.sendNotification` — typed loosely to
* avoid coupling to SDK's strict discriminated union. At runtime the SDK
* accepts any valid JSON-RPC notification including `notifications/progress`.
*/
export function createProgressReporter(
progressToken: string | number | undefined,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
sendNotification: (notification: any) => Promise<void>
): ProgressReporter {
if (progressToken === undefined) {
return {
enabled: false,
report: async () => {},
};
}
return {
enabled: true,
report: async (current: number, total: number, message?: string) => {
try {
await sendNotification({
method: 'notifications/progress',
params: {
progressToken,
progress: current,
total,
...(message !== undefined ? { message } : {}),
},
});
} catch {
// Swallow notification errors (e.g., client disconnected).
// Progress is best-effort — tool execution should continue regardless.
}
},
};
}
