@githits/mcp 0.23.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
@@ -329,6 +337,8 @@ interface UnifiedSearchLocator {
329
337
  language?: string;
330
338
  }
331
339
  interface UnifiedSearchHit {
340
+ /** Backend-selected action; absent only for older custom providers. */
341
+ readTarget?: ReadTarget | null;
332
342
  id: string;
333
343
  resultType: UnifiedSearchResultType;
334
344
  targetLabel: string;
@@ -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;
@@ -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-a5wp03h1.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
@@ -314,6 +322,8 @@ interface UnifiedSearchLocator {
314
322
  language?: string;
315
323
  }
316
324
  interface UnifiedSearchHit {
325
+ /** Backend-selected action; absent only for older custom providers. */
326
+ readTarget?: ReadTarget | null;
317
327
  id: string;
318
328
  resultType: UnifiedSearchResultType;
319
329
  targetLabel: string;
@@ -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 {