@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 +2 -0
- package/dist/client.d.ts +27 -1
- package/dist/client.js +1 -1
- package/dist/index.d.ts +163 -1
- package/dist/index.js +22 -17
- package/dist/shared/{chunk-j6q0y6f2.js → chunk-1bad2znr.js} +13 -4
- package/dist/shared/chunk-hmvv1js7.js +31 -0
- package/dist/shared/{chunk-a1w4dxpc.js → chunk-jemh0eym.js} +1 -1
- package/dist/tools.d.ts +130 -101
- package/dist/tools.js +1 -1
- package/package.json +2 -1
- package/dist/shared/chunk-9qbcj09a.js +0 -31
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-
|
|
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 };
|