@githits/mcp 0.32.0 → 0.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -157,6 +157,8 @@ boundary is authenticated and reached.
157
157
 
158
158
  The package expects callers to provide service implementations through `McpToolServices` or a request-scoped `McpToolServicesProvider`. `McpToolServices.readService` is required for the advertised compact `read` tool; remote hosts should construct the `ReadServiceImpl` instance per request with that request's endpoint, token, headers, fetch function, and diagnostics. GitHits does not populate MCP initialize instructions because hosts expose them inconsistently; `quick_start` owns shared guidance instead. Callers may still pass their own `instructions` explicitly. Use `quickStartOptions` to configure the guide. Servers can pass `traceTool` to `createMcpServer()` or `registerMcpTools()` to wrap public tool execution for instrumentation without receiving arguments or auth data.
159
159
 
160
+ Servers can pass an optional `progress` hook to `createMcpServer()` or `registerMcpTools()` to forward live status for `research` and `get_example`. It is used only when the client sends a progress token (including `0`); updates become `notifications/progress` and stop before the tool returns. `RelayReceiver` is the bundled hook: it receives GitHits operation progress over one shared WebSocket, authorized either by the caller's own GitHits token (`{ kind: "caller", getToken }`) or by a service credential supplied at runtime (`{ kind: "service", serviceId, key }`). The package ships no credentials. Progress is best effort: if it is unavailable or rejected, the tool runs unchanged, resending a rejected request once without progress, and the final result is always authoritative. Call `close()` on shutdown.
161
+
160
162
  Network-backed tools forward the MCP request's abort signal to their service call as an optional trailing `ServiceRequestOptions` argument (`{ signal }`), so a cancelled call or closed connection aborts the backend request. The bundled service implementations behind these tools honor it; custom service implementations should forward `options?.signal` to their own requests. Calls without a signal keep their single-argument shape.
161
163
 
162
164
  Only imports from `@githits/mcp`, `@githits/mcp/client`, `@githits/mcp/smoke-test`, `@githits/mcp/tools`, and `@githits/mcp/package.json` are public. The workspace alias `@githits/mcp/internal` is not exported, is not supported for external consumers, and must not be used by remote MCP server implementations.
package/dist/client.d.ts CHANGED
@@ -28,6 +28,20 @@ interface CreateClientHeaderBuilderOptions {
28
28
  */
29
29
  declare function createClientHeaderBuilder(options: CreateClientHeaderBuilderOptions): ClientHeaderBuilder;
30
30
  /**
31
+ * Optional per-call progress correlation for backend requests.
32
+ *
33
+ * Progress is best effort: the HTTP result stays authoritative. The backend
34
+ * validates progress headers before admission, accounting and execution, so a
35
+ * rejection carrying `X-GitHits-Progress-Error` means nothing ran and the same
36
+ * request is safe to resend once without the progress headers.
37
+ */
38
+ interface ProgressRequest {
39
+ /** Correlation headers merged after client headers and before auth. */
40
+ readonly headers: Readonly<Record<string, string>>;
41
+ /** Reports a pre-execution progress rejection; the call is then resent without progress. */
42
+ rejected(code: string): void;
43
+ }
44
+ /**
31
45
  * Host-supplied diagnostics for transport-neutral service clients.
32
46
  *
33
47
  * Implementations may record operation timings or debug events in whatever
@@ -72,6 +86,8 @@ type AgenticAskRequest = AgenticAskQuestion & AgenticAskSubject & {
72
86
  };
73
87
  interface AgenticAskRequestOptions {
74
88
  signal?: AbortSignal;
89
+ /** Optional best-effort progress correlation; never changes the result. */
90
+ progress?: ProgressRequest;
75
91
  }
76
92
  /** Expected backend envelope; successful JSON is deliberately not runtime-validated. */
77
93
  interface AgenticAskResponse {
@@ -969,6 +985,8 @@ interface SearchParams {
969
985
  /** Optional browser-standard controls for a GitHits service request. */
970
986
  interface GitHitsServiceRequestOptions {
971
987
  signal?: AbortSignal;
988
+ /** Optional best-effort progress correlation; never changes the result. */
989
+ progress?: ProgressRequest;
972
990
  }
973
991
  interface GitHitsServiceRuntimeOptions {
974
992
  clientHeaders?: ClientHeaderBuilder;
@@ -1336,6 +1354,12 @@ interface PackageSummaryParams {
1336
1354
  /** Include verbose/json-only fields such as recent advisories and changes. */
1337
1355
  includeVerboseFields?: boolean;
1338
1356
  }
1357
+ /** Logical artifact repository that supplied validated release metadata. */
1358
+ interface RegistryRepository {
1359
+ id: string;
1360
+ name: string;
1361
+ url: string;
1362
+ }
1339
1363
  interface PackageIdentity {
1340
1364
  name: string;
1341
1365
  registry?: string;
@@ -1350,6 +1374,7 @@ interface PackageIdentity {
1350
1374
  versionCount?: number;
1351
1375
  downloadsRefreshedAt?: string;
1352
1376
  githubRepository?: GithubRepository;
1377
+ registryRepository?: RegistryRepository;
1353
1378
  }
1354
1379
  interface GithubRepository {
1355
1380
  stargazersCount?: number;
@@ -1406,6 +1431,7 @@ interface PackageVersionIdentity {
1406
1431
  publishedAt?: string;
1407
1432
  deprecated?: boolean;
1408
1433
  deprecationReason?: string;
1434
+ registryRepository?: RegistryRepository;
1409
1435
  }
1410
1436
  interface VulnerabilityDetail {
1411
1437
  osvId?: string;
@@ -2323,4 +2349,4 @@ declare class ResolveTargetServiceImpl implements ResolveTargetService {
2323
2349
  resolveTarget(params: ResolveTargetParams, options?: ServiceRequestOptions): Promise<ResolveTargetResult>;
2324
2350
  private executeResolveTarget;
2325
2351
  }
2326
- export { AGENTIC_ASK_REQUEST_TIMEOUT_MS, AgentInfo, AgenticAskRateLimitScope, AgenticAskRequest, AgenticAskRequestOptions, AgenticAskResponse, AgenticAskService, AgenticAskServiceImpl, AgenticAskServiceRuntimeOptions, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, CodeSymbolCandidate, CodeSymbolResolution, CodeSymbolSuggestion, ContentModification, ContentSafety, DEFAULT_API_URL, DEFAULT_CODE_NAV_URL, DEFAULT_MCP_URL, DiscoveryIndexingEstimate, GitHitsService, GitHitsServiceImpl, GrepAccessError, GrepBackendError, GrepContentSafety, GrepCorpus, GrepFileIssue, GrepGraphQLError, GrepHit, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepReadAction, GrepReadiness, GrepRepositoryHit, GrepResult, GrepService, GrepServiceImpl, GrepSiteHit, GrepTarget, GrepTargetStatus, GrepTraversal, GrepUnavailableTarget, IndexingDurationEstimate, KnownLatestVersionMaliciousStatus, KnownMaliciousAdvisoryClassificationReason, LatestVersionMaliciousStatus, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedGrepResponseError, MalformedListResponseError, MaliciousAdvisoryClassificationReason, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, ServiceRequestOptions, SessionIdConfigError, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
2352
+ export { AGENTIC_ASK_REQUEST_TIMEOUT_MS, AgentInfo, AgenticAskRateLimitScope, AgenticAskRequest, AgenticAskRequestOptions, AgenticAskResponse, AgenticAskService, AgenticAskServiceImpl, AgenticAskServiceRuntimeOptions, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, CodeSymbolCandidate, CodeSymbolResolution, CodeSymbolSuggestion, ContentModification, ContentSafety, DEFAULT_API_URL, DEFAULT_CODE_NAV_URL, DEFAULT_MCP_URL, DiscoveryIndexingEstimate, GitHitsService, GitHitsServiceImpl, GrepAccessError, GrepBackendError, GrepContentSafety, GrepCorpus, GrepFileIssue, GrepGraphQLError, GrepHit, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepReadAction, GrepReadiness, GrepRepositoryHit, GrepResult, GrepService, GrepServiceImpl, GrepSiteHit, GrepTarget, GrepTargetStatus, GrepTraversal, GrepUnavailableTarget, IndexingDurationEstimate, KnownLatestVersionMaliciousStatus, KnownMaliciousAdvisoryClassificationReason, LatestVersionMaliciousStatus, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedGrepResponseError, MalformedListResponseError, MaliciousAdvisoryClassificationReason, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, RegistryRepository, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, ServiceRequestOptions, SessionIdConfigError, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
package/dist/client.js CHANGED
@@ -1 +1 @@
1
- import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-a1w4dxpc.js";import{DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,AGENTIC_ASK_REQUEST_TIMEOUT_MS2,AgenticAskServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2}from"./shared/chunk-j6q0y6f2.js";export{AGENTIC_ASK_REQUEST_TIMEOUT_MS2 as AGENTIC_ASK_REQUEST_TIMEOUT_MS,AgenticAskServiceImpl2 as AgenticAskServiceImpl,CodeDiffError2 as CodeDiffError,CodeNavigationServiceImpl2 as CodeNavigationServiceImpl,DEFAULT_API_URL2 as DEFAULT_API_URL,DEFAULT_CODE_NAV_URL2 as DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL2 as DEFAULT_MCP_URL,GitHitsServiceImpl2 as GitHitsServiceImpl,GrepAccessError2 as GrepAccessError,GrepBackendError2 as GrepBackendError,GrepGraphQLError2 as GrepGraphQLError,GrepNetworkError2 as GrepNetworkError,GrepServiceImpl2 as GrepServiceImpl,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedGrepResponseError2 as MalformedGrepResponseError,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,ResolveTargetServiceImpl2 as ResolveTargetServiceImpl,SessionIdConfigError2 as SessionIdConfigError,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getEnvSessionId2 as getEnvSessionId,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
1
+ import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-jemh0eym.js";import{DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,AGENTIC_ASK_REQUEST_TIMEOUT_MS2,AgenticAskServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2}from"./shared/chunk-1bad2znr.js";export{AGENTIC_ASK_REQUEST_TIMEOUT_MS2 as AGENTIC_ASK_REQUEST_TIMEOUT_MS,AgenticAskServiceImpl2 as AgenticAskServiceImpl,CodeDiffError2 as CodeDiffError,CodeNavigationServiceImpl2 as CodeNavigationServiceImpl,DEFAULT_API_URL2 as DEFAULT_API_URL,DEFAULT_CODE_NAV_URL2 as DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL2 as DEFAULT_MCP_URL,GitHitsServiceImpl2 as GitHitsServiceImpl,GrepAccessError2 as GrepAccessError,GrepBackendError2 as GrepBackendError,GrepGraphQLError2 as GrepGraphQLError,GrepNetworkError2 as GrepNetworkError,GrepServiceImpl2 as GrepServiceImpl,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedGrepResponseError2 as MalformedGrepResponseError,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,ResolveTargetServiceImpl2 as ResolveTargetServiceImpl,SessionIdConfigError2 as SessionIdConfigError,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getEnvSessionId2 as getEnvSessionId,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
package/dist/index.d.ts CHANGED
@@ -19,6 +19,20 @@ declare function buildMcpQuickStart(options?: BuildMcpQuickStartOptions): string
19
19
  */
20
20
  declare function buildMcpInstructions(options?: BuildMcpInstructionsOptions): string;
21
21
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
22
+ /**
23
+ * Optional per-call progress correlation for backend requests.
24
+ *
25
+ * Progress is best effort: the HTTP result stays authoritative. The backend
26
+ * validates progress headers before admission, accounting and execution, so a
27
+ * rejection carrying `X-GitHits-Progress-Error` means nothing ran and the same
28
+ * request is safe to resend once without the progress headers.
29
+ */
30
+ interface ProgressRequest {
31
+ /** Correlation headers merged after client headers and before auth. */
32
+ readonly headers: Readonly<Record<string, string>>;
33
+ /** Reports a pre-execution progress rejection; the call is then resent without progress. */
34
+ rejected(code: string): void;
35
+ }
22
36
  interface AgenticAskQuestion {
23
37
  question: string;
24
38
  }
@@ -34,6 +48,8 @@ type AgenticAskRequest = AgenticAskQuestion & AgenticAskSubject & {
34
48
  };
35
49
  interface AgenticAskRequestOptions {
36
50
  signal?: AbortSignal;
51
+ /** Optional best-effort progress correlation; never changes the result. */
52
+ progress?: ProgressRequest;
37
53
  }
38
54
  /** Expected backend envelope; successful JSON is deliberately not runtime-validated. */
39
55
  interface AgenticAskResponse {
@@ -750,6 +766,8 @@ interface SearchParams {
750
766
  /** Optional browser-standard controls for a GitHits service request. */
751
767
  interface GitHitsServiceRequestOptions {
752
768
  signal?: AbortSignal;
769
+ /** Optional best-effort progress correlation; never changes the result. */
770
+ progress?: ProgressRequest;
753
771
  }
754
772
  /**
755
773
  * Service interface for GitHits REST API.
@@ -1007,6 +1025,12 @@ interface PackageSummaryParams {
1007
1025
  /** Include verbose/json-only fields such as recent advisories and changes. */
1008
1026
  includeVerboseFields?: boolean;
1009
1027
  }
1028
+ /** Logical artifact repository that supplied validated release metadata. */
1029
+ interface RegistryRepository {
1030
+ id: string;
1031
+ name: string;
1032
+ url: string;
1033
+ }
1010
1034
  interface PackageIdentity {
1011
1035
  name: string;
1012
1036
  registry?: string;
@@ -1021,6 +1045,7 @@ interface PackageIdentity {
1021
1045
  versionCount?: number;
1022
1046
  downloadsRefreshedAt?: string;
1023
1047
  githubRepository?: GithubRepository;
1048
+ registryRepository?: RegistryRepository;
1024
1049
  }
1025
1050
  interface GithubRepository {
1026
1051
  stargazersCount?: number;
@@ -1077,6 +1102,7 @@ interface PackageVersionIdentity {
1077
1102
  publishedAt?: string;
1078
1103
  deprecated?: boolean;
1079
1104
  deprecationReason?: string;
1105
+ registryRepository?: RegistryRepository;
1080
1106
  }
1081
1107
  interface VulnerabilityDetail {
1082
1108
  osvId?: string;
@@ -1898,6 +1924,128 @@ interface ResolveTargetResult {
1898
1924
  interface ResolveTargetService {
1899
1925
  resolveTarget(params: ResolveTargetParams, options?: ServiceRequestOptions): Promise<ResolveTargetResult>;
1900
1926
  }
1927
+ /** One MCP progress update derived from a backend progress event. */
1928
+ interface McpProgressUpdate {
1929
+ /** Strictly increasing per operation; suitable for MCP `progress`. */
1930
+ progress: number;
1931
+ /** Fixed, server-allowlisted status text. */
1932
+ message: string;
1933
+ }
1934
+ /** One correlated backend call; `end()` stops delivery before the result returns. */
1935
+ interface McpProgressOperation extends ProgressRequest {
1936
+ end(): void;
1937
+ }
1938
+ /**
1939
+ * Optional, credential-free progress source for long-running tools.
1940
+ *
1941
+ * `begin` returns `undefined` whenever progress is unavailable; tools then run
1942
+ * exactly as without a hook. The HTTP result is always authoritative.
1943
+ */
1944
+ interface McpProgressHook {
1945
+ begin(notify: (update: McpProgressUpdate) => void): Promise<McpProgressOperation | undefined>;
1946
+ }
1947
+ /**
1948
+ * How the receiver authenticates relay setup.
1949
+ *
1950
+ * - `caller`: the caller's own GitHits token (local MCP); progress reaches only
1951
+ * that caller's receiver.
1952
+ * - `service`: a trusted service credential for a server that multiplexes
1953
+ * many callers over one socket. The credential is supplied at runtime and
1954
+ * never ships in this package.
1955
+ */
1956
+ type RelayAuth = {
1957
+ kind: "caller";
1958
+ getToken: () => Promise<string | undefined>;
1959
+ } | {
1960
+ kind: "service";
1961
+ serviceId: string;
1962
+ key: string;
1963
+ };
1964
+ /** The subset of a WebSocket the receiver uses; `ws` and WHATWG sockets fit. */
1965
+ interface RelaySocket {
1966
+ onopen: (() => void) | null;
1967
+ onmessage: ((event: {
1968
+ data: unknown;
1969
+ }) => void) | null;
1970
+ onclose: (() => void) | null;
1971
+ onerror: (() => void) | null;
1972
+ close(): void;
1973
+ }
1974
+ interface RelayReceiverOptions {
1975
+ apiUrl: string;
1976
+ auth: RelayAuth;
1977
+ fetchFn?: typeof fetch;
1978
+ createSocket?: (url: string) => RelaySocket;
1979
+ /** Extra headers for relay setup requests, such as client attribution. */
1980
+ clientHeaders?: () => Record<string, string>;
1981
+ /** Longest a call waits for an existing relay's socket before proceeding. */
1982
+ connectWaitMs?: number;
1983
+ /**
1984
+ * Longest a call waits while the first relay is minted and its socket opens.
1985
+ * Minting takes about a second, so a shorter wait would skip progress for the
1986
+ * first call of every process.
1987
+ */
1988
+ firstConnectWaitMs?: number;
1989
+ /** Close an unused socket after this long. */
1990
+ idleCloseMs?: number;
1991
+ /** First reconnect delay; doubles per attempt up to 30 s. */
1992
+ reconnectBaseMs?: number;
1993
+ /** Earliest renewal after a mint, even for short-lived receive URLs. */
1994
+ minRenewDelayMs?: number;
1995
+ now?: () => number;
1996
+ createId?: () => string;
1997
+ }
1998
+ /**
1999
+ * Receives backend operation progress over one shared WebSocket and routes it
2000
+ * to the MCP call that supplied each operation ID.
2001
+ *
2002
+ * Every failure degrades to "no progress": relay setup errors back off, socket
2003
+ * drops reconnect in the background, and late or unknown events are dropped.
2004
+ */
2005
+ declare class RelayReceiver implements McpProgressHook {
2006
+ private readonly options;
2007
+ private readonly fetchFn;
2008
+ private readonly createSocket;
2009
+ private readonly connectWaitMs;
2010
+ private readonly firstConnectWaitMs;
2011
+ private readonly idleCloseMs;
2012
+ private readonly reconnectBaseMs;
2013
+ private readonly minRenewDelayMs;
2014
+ private readonly now;
2015
+ private readonly createId;
2016
+ private readonly routes;
2017
+ private relay;
2018
+ private socket;
2019
+ private connecting;
2020
+ private unavailableUntil;
2021
+ private reconnectAttempts;
2022
+ private renewTimer;
2023
+ private reconnectTimer;
2024
+ private idleTimer;
2025
+ private closed;
2026
+ constructor(options: RelayReceiverOptions);
2027
+ begin(notify: (update: McpProgressUpdate) => void): Promise<McpProgressOperation | undefined>;
2028
+ /** Stops all timers and closes the socket; later calls get no progress. */
2029
+ close(): void;
2030
+ private ensureConnected;
2031
+ private connect;
2032
+ /** Resolves once the socket opens or fails; an open socket replaces the old one. */
2033
+ private openSocket;
2034
+ /** A socket that cannot open (e.g. a proxy blocking WebSockets) backs off. */
2035
+ private socketFailed;
2036
+ private deliver;
2037
+ private setup;
2038
+ private authHeaders;
2039
+ private serviceHeaders;
2040
+ private scheduleRenewal;
2041
+ /** Mint a fresh receive URL for the same relay while the old socket stays up. */
2042
+ private ensureFresh;
2043
+ private scheduleReconnect;
2044
+ private scheduleIdleClose;
2045
+ private closeSocket;
2046
+ private detach;
2047
+ private clearTimer;
2048
+ }
1901
2049
  import { z as z3 } from "zod";
1902
2050
  /** Annotation fields required by OpenAI's MCP marketplace validation. */
1903
2051
  interface CompleteToolAnnotations {
@@ -1917,11 +2065,22 @@ interface ToolTermsRemediation {
1917
2065
  message: string;
1918
2066
  action: string;
1919
2067
  }
2068
+ /** One correlated backend call; `end()` must run before the tool returns. */
2069
+ interface ToolProgressOperation extends ProgressRequest {
2070
+ end(): void;
2071
+ }
2072
+ /** Progress already bound to the current MCP request's progress token. */
2073
+ interface ToolProgress {
2074
+ /** Returns `undefined` when progress is unavailable; run without it then. */
2075
+ begin(): Promise<ToolProgressOperation | undefined>;
2076
+ }
1920
2077
  /** Host-provided execution state shared by MCP and direct tool callers. */
1921
2078
  interface ToolExecutionContext {
1922
2079
  authAction?: McpAuthAction;
1923
2080
  termsRemediation?: ToolTermsRemediation;
1924
2081
  signal?: AbortSignal;
2082
+ /** Present only when the host enabled progress and the client asked for it. */
2083
+ progress?: ToolProgress;
1925
2084
  }
1926
2085
  /**
1927
2086
  * Standard result type for all MCP tools
@@ -1982,6 +2141,8 @@ interface CreateMcpServerOptions<TExtra = unknown> {
1982
2141
  /** @deprecated Use `quickStartOptions`. */
1983
2142
  instructionOptions?: Parameters<typeof buildMcpQuickStart>[0];
1984
2143
  traceTool?: McpToolExecutionHook;
2144
+ /** Optional progress source; used only when the client sends a progress token. */
2145
+ progress?: McpProgressHook;
1985
2146
  }
1986
2147
  interface McpToolDescriptor<TSchema extends ZodRawShape = ZodRawShape> {
1987
2148
  name: string;
@@ -1995,9 +2156,10 @@ declare function registerMcpTools<TExtra = unknown>(server: McpServer, options:
1995
2156
  termsRemediation?: ToolTermsRemediation;
1996
2157
  services: McpToolServicesProvider<TExtra>;
1997
2158
  traceTool?: McpToolExecutionHook;
2159
+ progress?: McpProgressHook;
1998
2160
  }): void;
1999
2161
  /**
2000
2162
  * Creates the transport-neutral MCP server with injected services.
2001
2163
  */
2002
2164
  declare function createMcpServer<TExtra = unknown>(options: CreateMcpServerOptions<TExtra>): McpServer;
2003
- export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, ToolExecutionContext, ToolTermsRemediation, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };
2165
+ export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpProgressHook, McpProgressOperation, McpProgressUpdate, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, RelayAuth, RelayReceiver, RelayReceiverOptions, RelaySocket, ToolExecutionContext, ToolTermsRemediation, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };