@githits/mcp 0.22.0 → 0.24.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/dist/client.d.ts CHANGED
@@ -22,6 +22,35 @@ interface CreateClientHeaderBuilderOptions {
22
22
  */
23
23
  declare function createClientHeaderBuilder(options: CreateClientHeaderBuilderOptions): ClientHeaderBuilder;
24
24
  /**
25
+ * Host-supplied diagnostics for transport-neutral service clients.
26
+ *
27
+ * Implementations may record operation timings or debug events in whatever
28
+ * way is appropriate for their host. Core does not provide a default and
29
+ * remains silent when diagnostics are omitted. Core callers gate every debug
30
+ * event through `isEnabled(area)`; when it returns `false`, the corresponding
31
+ * debug call is suppressed entirely. Returning `true` is therefore both a log
32
+ * filter and a content-disclosure decision for the host.
33
+ *
34
+ * In particular, the `code-nav-wire` area may carry the exact GraphQL document
35
+ * and request variables, including caller query text, so it requires separate
36
+ * explicit opt-in. The `code-nav` and `pkg-graphql` schema-mismatch paths may
37
+ * carry raw backend error text, and an enabled area may select that raw error
38
+ * content instead of the sanitized message. These areas are not PII-safe;
39
+ * hosts own their privacy and retention policy for any enabled diagnostics.
40
+ */
41
+ interface ServiceDiagnostics {
42
+ withOperation<T>(name: string, operation: () => Promise<T>): Promise<T>;
43
+ isEnabled(area: string): boolean;
44
+ debug(area: string, event: Record<string, unknown>): void;
45
+ }
46
+ interface TokenProvider {
47
+ /** Get a valid token, refreshing proactively or reactively as needed. */
48
+ getToken(): Promise<string | undefined>;
49
+ /** Force a refresh, usually after an authentication failure. */
50
+ forceRefresh(): Promise<string | undefined>;
51
+ }
52
+ declare function createStaticTokenProvider(token: string): TokenProvider;
53
+ /**
25
54
  * Registry taxonomy shared by code-navigation and package-intelligence
26
55
  * services. Single source of truth for:
27
56
  *
@@ -61,35 +90,14 @@ declare function toPkgseerRegistry(registry: PkgseerRegistryArg): PkgseerRegistr
61
90
  * lowering a response field for user display.
62
91
  */
63
92
  declare function toPkgseerRegistryLowercase(registry: PkgseerRegistry): PkgseerRegistryArg;
64
- /**
65
- * Host-supplied diagnostics for transport-neutral service clients.
66
- *
67
- * Implementations may record operation timings or debug events in whatever
68
- * way is appropriate for their host. Core does not provide a default and
69
- * remains silent when diagnostics are omitted. Core callers gate every debug
70
- * event through `isEnabled(area)`; when it returns `false`, the corresponding
71
- * debug call is suppressed entirely. Returning `true` is therefore both a log
72
- * filter and a content-disclosure decision for the host.
73
- *
74
- * In particular, the `code-nav-wire` area may carry the exact GraphQL document
75
- * and request variables, including caller query text, so it requires separate
76
- * explicit opt-in. The `code-nav` and `pkg-graphql` schema-mismatch paths may
77
- * carry raw backend error text, and an enabled area may select that raw error
78
- * content instead of the sanitized message. These areas are not PII-safe;
79
- * hosts own their privacy and retention policy for any enabled diagnostics.
80
- */
81
- interface ServiceDiagnostics {
82
- withOperation<T>(name: string, operation: () => Promise<T>): Promise<T>;
83
- isEnabled(area: string): boolean;
84
- debug(area: string, event: Record<string, unknown>): void;
85
- }
86
- interface TokenProvider {
87
- /** Get a valid token, refreshing proactively or reactively as needed. */
88
- getToken(): Promise<string | undefined>;
89
- /** Force a refresh, usually after an authentication failure. */
90
- forceRefresh(): Promise<string | undefined>;
93
+ /** A backend-selected address for a code or documentation read. */
94
+ interface ReadTarget {
95
+ target: string;
96
+ path?: string;
97
+ selector?: string;
98
+ startLine?: number;
99
+ endLine?: number;
91
100
  }
92
- declare function createStaticTokenProvider(token: string): TokenProvider;
93
101
  /**
94
102
  * Back-compat alias — the canonical registry union now lives in
95
103
  * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
@@ -204,8 +212,6 @@ interface UnifiedSearchParams {
204
212
  interface UnifiedSearchReadOptions {
205
213
  /** Cancel the discovery request when its caller stops waiting. */
206
214
  signal?: AbortSignal;
207
- /** Omit compatibility navigation source when the caller renders only matched evidence. */
208
- omitFocusedSource?: boolean;
209
215
  }
210
216
  interface UnifiedSearchEvidenceRange {
211
217
  startLine: number;
@@ -296,6 +302,7 @@ interface UnifiedSearchDocumentationPreview {
296
302
  highlights: Array<readonly [number, number]>;
297
303
  }
298
304
  interface UnifiedSearchRepositoryEvidence {
305
+ /** Legacy input shape; discovery queries no longer select this field. */
299
306
  focusedSource?: UnifiedSearchFocusedSource | null;
300
307
  semanticContext: UnifiedSearchSemanticContext | null;
301
308
  /** Complete positive-term field list; null means unknown, not no matches. */
@@ -307,7 +314,7 @@ interface UnifiedSearchLocator {
307
314
  packageName?: string;
308
315
  version?: string;
309
316
  pageId?: string;
310
- /** Preferred docs_read target; absent on legacy discovery results. */
317
+ /** Emitted documentation locator accepted by unified read; absent on legacy results. */
311
318
  docsReadTarget?: string;
312
319
  sourceKind?: string;
313
320
  sourceUrl?: string;
@@ -330,10 +337,13 @@ interface UnifiedSearchLocator {
330
337
  language?: string;
331
338
  }
332
339
  interface UnifiedSearchHit {
340
+ /** Backend-selected action; absent only for older custom providers. */
341
+ readTarget?: ReadTarget | null;
333
342
  id: string;
334
343
  resultType: UnifiedSearchResultType;
335
344
  targetLabel: string;
336
345
  title?: string;
346
+ /** Legacy input shape; discovery queries no longer select this field. */
337
347
  summary?: string;
338
348
  score?: number;
339
349
  highlights?: {
@@ -523,6 +533,8 @@ interface ReadFileParams {
523
533
  waitTimeoutMs?: number;
524
534
  }
525
535
  interface ReadFileResult {
536
+ /** Served action selected by unified read; legacy readers may omit it. */
537
+ readTarget?: ReadTarget | null;
526
538
  filePath?: string;
527
539
  language?: string;
528
540
  totalLines?: number;
@@ -828,24 +840,24 @@ declare class CodeNavigationServiceImpl implements CodeNavigationService, CodeDi
828
840
  */
829
841
  declare const DEFAULT_MCP_URL = "https://mcp.githits.com";
830
842
  declare const DEFAULT_API_URL = "https://api.githits.com";
831
- declare const DEFAULT_CODE_NAV_URL = "https://pkgseer.dev";
843
+ declare const DEFAULT_CODE_NAV_URL = "https://oss.githits.dev";
832
844
  /**
833
845
  * Get the MCP server base URL (for OAuth discovery).
834
846
  * Override with GITHITS_MCP_URL environment variable.
847
+ * @param env Supplies GITHITS_ENV and URL overrides; defaults to process.env.
835
848
  */
836
- declare function getMcpUrl(): string;
849
+ declare function getMcpUrl(env?: Record<string, string | undefined>): string;
837
850
  /**
838
851
  * Get the REST API base URL (for search).
839
852
  * Override with GITHITS_API_URL environment variable.
853
+ * @param env Supplies GITHITS_ENV and URL overrides; defaults to process.env.
840
854
  */
841
- declare function getApiUrl(): string;
855
+ declare function getApiUrl(env?: Record<string, string | undefined>): string;
842
856
  /**
843
- * Get the code-navigation backend URL. `GITHITS_CODE_NAV_URL` is the
844
- * supported override; a legacy env var is also accepted for local
845
- * development parity with older environments but is not publicly
846
- * documented.
857
+ * Get the OSS package/source backend URL from the preset or GITHITS_CODE_NAV_URL.
858
+ * @param env Supplies GITHITS_ENV and URL overrides; defaults to process.env.
847
859
  */
848
- declare function getCodeNavigationUrl(): string;
860
+ declare function getCodeNavigationUrl(env?: Record<string, string | undefined>): string;
849
861
  /**
850
862
  * Get API token from environment variable (for CI/automation).
851
863
  */
@@ -892,6 +904,163 @@ declare class GitHitsServiceImpl implements GitHitsService {
892
904
  private request;
893
905
  private createError;
894
906
  }
907
+ type ListFileIntent = "PRODUCTION" | "TEST" | "BENCHMARK" | "EXAMPLE" | "GENERATED" | "FIXTURE" | "BUILD" | "VENDOR";
908
+ interface ListParams {
909
+ target: string;
910
+ paths?: string[];
911
+ recursive?: boolean;
912
+ fileTypes?: string[];
913
+ languages?: string[];
914
+ intents?: ListFileIntent[];
915
+ limit?: number;
916
+ after?: string;
917
+ waitTimeoutMs?: number;
918
+ includeDetailedFields: boolean;
919
+ /** Select exact read actions for compact site text; detailed fields always include them. */
920
+ includeReadActions?: boolean;
921
+ }
922
+ type ListInventoryKind = "SOURCE" | "SITE";
923
+ type ListEntryKind = "FILE" | "PAGE" | "DIRECTORY";
924
+ type ListSiteWaitOutcome = "COMPLETED" | "DISCARDED" | "CANCELLED" | "TIMEOUT";
925
+ interface ListReadAction {
926
+ target: string;
927
+ path: string | null;
928
+ }
929
+ interface ListBrowseAction {
930
+ target: string;
931
+ paths: string[] | null;
932
+ }
933
+ type ListAction = ListReadAction | ListBrowseAction;
934
+ interface ListEntry {
935
+ kind: ListEntryKind;
936
+ path: string;
937
+ title?: string | null;
938
+ language?: string | null;
939
+ fileType?: string | null;
940
+ intent?: string | null;
941
+ byteSize?: number | null;
942
+ lineCount?: number | null;
943
+ contentHash?: string | null;
944
+ read?: ListReadAction | null;
945
+ browse?: ListBrowseAction | null;
946
+ }
947
+ interface ListAvailableVersion {
948
+ version: string | null;
949
+ ref: string;
950
+ }
951
+ interface ListResolution {
952
+ requestedVersion: string | null;
953
+ requestedRef: string | null;
954
+ resolvedRef: string | null;
955
+ commitSha: string | null;
956
+ }
957
+ interface ListTargetIdentity {
958
+ kind: string | null;
959
+ registry: string | null;
960
+ packageName: string | null;
961
+ version: string | null;
962
+ repoUrl: string | null;
963
+ gitRef: string | null;
964
+ commitSha: string | null;
965
+ }
966
+ interface ListTargetResolution {
967
+ requested: ListTargetIdentity | null;
968
+ resolvedRequested: ListTargetIdentity | null;
969
+ served: ListTargetIdentity | null;
970
+ freshness: string | null;
971
+ freshnessReason: string | null;
972
+ indexingRef: string | null;
973
+ availableVersions: ListAvailableVersion[] | null;
974
+ availableRefs: ListAvailableVersion[] | null;
975
+ suggestedRefs: ListAvailableVersion[] | null;
976
+ }
977
+ interface ListIndexingEstimate {
978
+ lowerSeconds: number | null;
979
+ upperSeconds: number | null;
980
+ elapsedSeconds: number | null;
981
+ sampleCount: number | null;
982
+ source: string | null;
983
+ }
984
+ interface ListSiteJob {
985
+ mode: string | null;
986
+ state: string;
987
+ }
988
+ interface ListSiteWait {
989
+ mode: string | null;
990
+ outcome: ListSiteWaitOutcome;
991
+ }
992
+ interface ListSitePreparation {
993
+ selected: number;
994
+ enqueued: number;
995
+ activeJobs: ListSiteJob[];
996
+ awaited: ListSiteWait[];
997
+ }
998
+ interface ListResult {
999
+ inventoryKind: ListInventoryKind;
1000
+ requestedTarget: string;
1001
+ canonicalTarget: string | null;
1002
+ entries: ListEntry[];
1003
+ hasMore: boolean;
1004
+ nextCursor: string | null;
1005
+ indexedVersion: string | null;
1006
+ resolution?: ListResolution | null;
1007
+ targetResolution?: ListTargetResolution | null;
1008
+ codeIndexState: string | null;
1009
+ indexingStatus: string | null;
1010
+ indexingRef: string | null;
1011
+ availableVersions?: ListAvailableVersion[] | null;
1012
+ indexingEstimate?: ListIndexingEstimate | null;
1013
+ inventoryState: "AVAILABLE" | "EMPTY" | null;
1014
+ crawlStatus: "IDLE" | "RUNNING" | "COMPLETE" | "FAILED" | null;
1015
+ coverageState: "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | null;
1016
+ coverageReason: string | null;
1017
+ preparation: ListSitePreparation | null;
1018
+ }
1019
+ interface ListService {
1020
+ list(params: ListParams): Promise<ListResult>;
1021
+ }
1022
+ interface ListServiceRuntime {
1023
+ clientHeaders?: ClientHeaderBuilder;
1024
+ userAgent?: string;
1025
+ clientVersion?: string;
1026
+ diagnostics?: ServiceDiagnostics;
1027
+ }
1028
+ declare class ListAccessError extends Error {
1029
+ constructor(message: string);
1030
+ }
1031
+ declare class ListGraphQLError extends Error {
1032
+ readonly code?: string | undefined;
1033
+ readonly retryable?: boolean | undefined;
1034
+ readonly repoUrl?: string | undefined;
1035
+ readonly commitSha?: string | undefined;
1036
+ readonly indexingRef?: string | undefined;
1037
+ readonly hint?: string | undefined;
1038
+ constructor(message: string, code?: string | undefined, retryable?: boolean | undefined, repoUrl?: string | undefined, commitSha?: string | undefined, indexingRef?: string | undefined, hint?: string | undefined);
1039
+ }
1040
+ declare class ListBackendError extends Error {
1041
+ readonly status?: number | undefined;
1042
+ readonly graphqlCode?: string | undefined;
1043
+ readonly retryable?: boolean | undefined;
1044
+ constructor(message: string, status?: number | undefined, graphqlCode?: string | undefined, retryable?: boolean | undefined);
1045
+ }
1046
+ declare class ListNetworkError extends Error {
1047
+ constructor(message: string, options?: {
1048
+ cause?: unknown;
1049
+ });
1050
+ }
1051
+ declare class MalformedListResponseError extends Error {
1052
+ constructor(message?: string);
1053
+ }
1054
+ /** Client for the backend's unified package, repository, and site inventory. */
1055
+ declare class ListServiceImpl implements ListService {
1056
+ private readonly endpointUrl;
1057
+ private readonly tokenProvider;
1058
+ private readonly fetchFn;
1059
+ private readonly runtime;
1060
+ constructor(endpointUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: ListServiceRuntime);
1061
+ list(params: ListParams): Promise<ListResult>;
1062
+ private executeList;
1063
+ }
895
1064
  interface PackageSummaryParams {
896
1065
  registry: PkgseerRegistry;
897
1066
  packageName: string;
@@ -1547,6 +1716,8 @@ interface PackageDocContentRange {
1547
1716
  anchor?: string;
1548
1717
  }
1549
1718
  interface PackageDocResult {
1719
+ /** Enclosing served selection; legacy readers may omit it. */
1720
+ readTarget?: ReadTarget;
1550
1721
  registry?: string;
1551
1722
  packageName?: string;
1552
1723
  version?: string;
@@ -1699,4 +1870,4 @@ declare class RefreshingGitHitsService implements GitHitsService {
1699
1870
  */
1700
1871
  private withTokenRefresh;
1701
1872
  }
1702
- export { AgentInfo, 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, GitHitsService, GitHitsServiceImpl, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, RefreshingGitHitsService, ServiceDiagnostics, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
1873
+ export { AgentInfo, 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, GitHitsService, GitHitsServiceImpl, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedListResponseError, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, ServiceDiagnostics, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
package/dist/client.js CHANGED
@@ -1 +1 @@
1
- import{DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,PackageIntelligenceServiceImpl2,CodeDiffError2,CodeNavigationServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,createStaticTokenProvider2,createClientHeaderBuilder2}from"./shared/chunk-dc5q5dw3.js";export{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,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
1
+ import{DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,PackageIntelligenceServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,createStaticTokenProvider2,createClientHeaderBuilder2}from"./shared/chunk-1tvgyfva.js";export{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,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
package/dist/index.d.ts CHANGED
@@ -75,6 +75,14 @@ declare const registryMap: {
75
75
  readonly swift: "SWIFT";
76
76
  };
77
77
  type PkgseerRegistry = (typeof registryMap)[keyof typeof registryMap];
78
+ /** A backend-selected address for a code or documentation read. */
79
+ interface ReadTarget {
80
+ target: string;
81
+ path?: string;
82
+ selector?: string;
83
+ startLine?: number;
84
+ endLine?: number;
85
+ }
78
86
  /**
79
87
  * Back-compat alias — the canonical registry union now lives in
80
88
  * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
@@ -189,8 +197,6 @@ interface UnifiedSearchParams {
189
197
  interface UnifiedSearchReadOptions {
190
198
  /** Cancel the discovery request when its caller stops waiting. */
191
199
  signal?: AbortSignal;
192
- /** Omit compatibility navigation source when the caller renders only matched evidence. */
193
- omitFocusedSource?: boolean;
194
200
  }
195
201
  interface UnifiedSearchEvidenceRange {
196
202
  startLine: number;
@@ -281,6 +287,7 @@ interface UnifiedSearchDocumentationPreview {
281
287
  highlights: Array<readonly [number, number]>;
282
288
  }
283
289
  interface UnifiedSearchRepositoryEvidence {
290
+ /** Legacy input shape; discovery queries no longer select this field. */
284
291
  focusedSource?: UnifiedSearchFocusedSource | null;
285
292
  semanticContext: UnifiedSearchSemanticContext | null;
286
293
  /** Complete positive-term field list; null means unknown, not no matches. */
@@ -292,7 +299,7 @@ interface UnifiedSearchLocator {
292
299
  packageName?: string;
293
300
  version?: string;
294
301
  pageId?: string;
295
- /** Preferred docs_read target; absent on legacy discovery results. */
302
+ /** Emitted documentation locator accepted by unified read; absent on legacy results. */
296
303
  docsReadTarget?: string;
297
304
  sourceKind?: string;
298
305
  sourceUrl?: string;
@@ -315,10 +322,13 @@ interface UnifiedSearchLocator {
315
322
  language?: string;
316
323
  }
317
324
  interface UnifiedSearchHit {
325
+ /** Backend-selected action; absent only for older custom providers. */
326
+ readTarget?: ReadTarget | null;
318
327
  id: string;
319
328
  resultType: UnifiedSearchResultType;
320
329
  targetLabel: string;
321
330
  title?: string;
331
+ /** Legacy input shape; discovery queries no longer select this field. */
322
332
  summary?: string;
323
333
  score?: number;
324
334
  highlights?: {
@@ -508,6 +518,8 @@ interface ReadFileParams {
508
518
  waitTimeoutMs?: number;
509
519
  }
510
520
  interface ReadFileResult {
521
+ /** Served action selected by unified read; legacy readers may omit it. */
522
+ readTarget?: ReadTarget | null;
511
523
  filePath?: string;
512
524
  language?: string;
513
525
  totalLines?: number;
@@ -622,6 +634,120 @@ interface GitHitsService {
622
634
  /** Search for code examples. Returns markdown-formatted result. */
623
635
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
624
636
  }
637
+ type ListFileIntent = "PRODUCTION" | "TEST" | "BENCHMARK" | "EXAMPLE" | "GENERATED" | "FIXTURE" | "BUILD" | "VENDOR";
638
+ interface ListParams {
639
+ target: string;
640
+ paths?: string[];
641
+ recursive?: boolean;
642
+ fileTypes?: string[];
643
+ languages?: string[];
644
+ intents?: ListFileIntent[];
645
+ limit?: number;
646
+ after?: string;
647
+ waitTimeoutMs?: number;
648
+ includeDetailedFields: boolean;
649
+ /** Select exact read actions for compact site text; detailed fields always include them. */
650
+ includeReadActions?: boolean;
651
+ }
652
+ type ListInventoryKind = "SOURCE" | "SITE";
653
+ type ListEntryKind = "FILE" | "PAGE" | "DIRECTORY";
654
+ type ListSiteWaitOutcome = "COMPLETED" | "DISCARDED" | "CANCELLED" | "TIMEOUT";
655
+ interface ListReadAction {
656
+ target: string;
657
+ path: string | null;
658
+ }
659
+ interface ListBrowseAction {
660
+ target: string;
661
+ paths: string[] | null;
662
+ }
663
+ interface ListEntry {
664
+ kind: ListEntryKind;
665
+ path: string;
666
+ title?: string | null;
667
+ language?: string | null;
668
+ fileType?: string | null;
669
+ intent?: string | null;
670
+ byteSize?: number | null;
671
+ lineCount?: number | null;
672
+ contentHash?: string | null;
673
+ read?: ListReadAction | null;
674
+ browse?: ListBrowseAction | null;
675
+ }
676
+ interface ListAvailableVersion {
677
+ version: string | null;
678
+ ref: string;
679
+ }
680
+ interface ListResolution {
681
+ requestedVersion: string | null;
682
+ requestedRef: string | null;
683
+ resolvedRef: string | null;
684
+ commitSha: string | null;
685
+ }
686
+ interface ListTargetIdentity {
687
+ kind: string | null;
688
+ registry: string | null;
689
+ packageName: string | null;
690
+ version: string | null;
691
+ repoUrl: string | null;
692
+ gitRef: string | null;
693
+ commitSha: string | null;
694
+ }
695
+ interface ListTargetResolution {
696
+ requested: ListTargetIdentity | null;
697
+ resolvedRequested: ListTargetIdentity | null;
698
+ served: ListTargetIdentity | null;
699
+ freshness: string | null;
700
+ freshnessReason: string | null;
701
+ indexingRef: string | null;
702
+ availableVersions: ListAvailableVersion[] | null;
703
+ availableRefs: ListAvailableVersion[] | null;
704
+ suggestedRefs: ListAvailableVersion[] | null;
705
+ }
706
+ interface ListIndexingEstimate {
707
+ lowerSeconds: number | null;
708
+ upperSeconds: number | null;
709
+ elapsedSeconds: number | null;
710
+ sampleCount: number | null;
711
+ source: string | null;
712
+ }
713
+ interface ListSiteJob {
714
+ mode: string | null;
715
+ state: string;
716
+ }
717
+ interface ListSiteWait {
718
+ mode: string | null;
719
+ outcome: ListSiteWaitOutcome;
720
+ }
721
+ interface ListSitePreparation {
722
+ selected: number;
723
+ enqueued: number;
724
+ activeJobs: ListSiteJob[];
725
+ awaited: ListSiteWait[];
726
+ }
727
+ interface ListResult {
728
+ inventoryKind: ListInventoryKind;
729
+ requestedTarget: string;
730
+ canonicalTarget: string | null;
731
+ entries: ListEntry[];
732
+ hasMore: boolean;
733
+ nextCursor: string | null;
734
+ indexedVersion: string | null;
735
+ resolution?: ListResolution | null;
736
+ targetResolution?: ListTargetResolution | null;
737
+ codeIndexState: string | null;
738
+ indexingStatus: string | null;
739
+ indexingRef: string | null;
740
+ availableVersions?: ListAvailableVersion[] | null;
741
+ indexingEstimate?: ListIndexingEstimate | null;
742
+ inventoryState: "AVAILABLE" | "EMPTY" | null;
743
+ crawlStatus: "IDLE" | "RUNNING" | "COMPLETE" | "FAILED" | null;
744
+ coverageState: "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | null;
745
+ coverageReason: string | null;
746
+ preparation: ListSitePreparation | null;
747
+ }
748
+ interface ListService {
749
+ list(params: ListParams): Promise<ListResult>;
750
+ }
625
751
  interface PackageSummaryParams {
626
752
  registry: PkgseerRegistry;
627
753
  packageName: string;
@@ -1277,6 +1403,8 @@ interface PackageDocContentRange {
1277
1403
  anchor?: string;
1278
1404
  }
1279
1405
  interface PackageDocResult {
1406
+ /** Enclosing served selection; legacy readers may omit it. */
1407
+ readTarget?: ReadTarget;
1280
1408
  registry?: string;
1281
1409
  packageName?: string;
1282
1410
  version?: string;
@@ -1355,6 +1483,7 @@ interface McpToolServices {
1355
1483
  githitsService: GitHitsService;
1356
1484
  codeNavigationService: CodeNavigationService;
1357
1485
  packageIntelligenceService: PackageIntelligenceService;
1486
+ listService: ListService;
1358
1487
  readService: ReadService;
1359
1488
  }
1360
1489
  interface McpServerMetadata {