@githits/mcp 0.25.1 → 0.27.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/index.d.ts CHANGED
@@ -19,47 +19,6 @@ 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
- import { z } from "zod";
23
- /** Annotation fields required by OpenAI's MCP marketplace validation. */
24
- interface CompleteToolAnnotations {
25
- title?: string;
26
- readOnlyHint: boolean;
27
- idempotentHint?: boolean;
28
- openWorldHint: boolean;
29
- destructiveHint: boolean;
30
- }
31
- interface McpAuthActionContext {
32
- authSource: unknown;
33
- defaultAction: string;
34
- }
35
- type McpAuthAction = string | ((context: McpAuthActionContext) => string);
36
- /** Host-selected message and action for terms-acceptance failures. */
37
- interface ToolTermsRemediation {
38
- message: string;
39
- action: string;
40
- }
41
- /** Host-provided execution state shared by MCP and direct tool callers. */
42
- interface ToolExecutionContext {
43
- authAction?: McpAuthAction;
44
- termsRemediation?: ToolTermsRemediation;
45
- signal?: AbortSignal;
46
- }
47
- /**
48
- * Standard result type for all MCP tools
49
- */
50
- type ToolResult = {
51
- content: Array<{
52
- type: "text";
53
- text: string;
54
- }>;
55
- isError?: boolean;
56
- };
57
- /**
58
- * Zod raw shape type (what MCP SDK expects)
59
- */
60
- type ZodRawShape = {
61
- [k: string]: z.ZodTypeAny;
62
- };
63
22
  declare const registryMap: {
64
23
  readonly npm: "NPM";
65
24
  readonly pypi: "PYPI";
@@ -75,6 +34,22 @@ declare const registryMap: {
75
34
  readonly swift: "SWIFT";
76
35
  };
77
36
  type PkgseerRegistry = (typeof registryMap)[keyof typeof registryMap];
37
+ interface IndexingDurationEstimate {
38
+ lowerSeconds?: number;
39
+ upperSeconds?: number;
40
+ elapsedSeconds?: number;
41
+ sampleCount?: number;
42
+ source?: string;
43
+ }
44
+ /** Pending preparation evidence; total execution seconds, never a search ETA. */
45
+ interface DiscoveryIndexingEstimate {
46
+ kind: "REPOSITORY" | "DOCUMENTATION";
47
+ targets: string[];
48
+ repositoryUrl?: string;
49
+ commitSha?: string;
50
+ estimate?: IndexingDurationEstimate;
51
+ unavailableReason?: "NO_HISTORY" | "UNSUPPORTED_WORK";
52
+ }
78
53
  /** A backend-selected address for a code or documentation read. */
79
54
  interface ReadTarget {
80
55
  target: string;
@@ -134,6 +109,8 @@ interface TargetResolutionIdentity {
134
109
  repoUrl?: string;
135
110
  gitRef?: string;
136
111
  commitSha?: string;
112
+ /** Verified UTC committer time for this exact repository commit, not freshness. */
113
+ committedAt?: string;
137
114
  site?: string;
138
115
  }
139
116
  type AvailableRef = AvailableVersion;
@@ -418,15 +395,6 @@ interface UnifiedSearchResult {
418
395
  sourceStatus: UnifiedSearchSourceStatus[];
419
396
  evidenceNotice?: string;
420
397
  }
421
- /** Pending preparation evidence; total execution seconds, never a search ETA. */
422
- interface DiscoveryIndexingEstimate {
423
- kind: "REPOSITORY" | "DOCUMENTATION";
424
- targets: string[];
425
- repositoryUrl?: string;
426
- commitSha?: string;
427
- estimate?: IndexingDurationEstimate;
428
- unavailableReason?: "NO_HISTORY" | "UNSUPPORTED_WORK";
429
- }
430
398
  interface UnifiedSearchProgress {
431
399
  searchRef: string;
432
400
  status: UnifiedSearchSessionStatus;
@@ -465,13 +433,6 @@ interface AvailableVersion {
465
433
  version?: string;
466
434
  ref: string;
467
435
  }
468
- interface IndexingDurationEstimate {
469
- lowerSeconds?: number;
470
- upperSeconds?: number;
471
- elapsedSeconds?: number;
472
- sampleCount?: number;
473
- source?: string;
474
- }
475
436
  /**
476
437
  * Input for {@link CodeNavigationService.listFiles}.
477
438
  */
@@ -499,6 +460,7 @@ interface RepoFileEntry {
499
460
  byteSize?: number;
500
461
  }
501
462
  interface ListFilesResult {
463
+ indexingEstimates?: DiscoveryIndexingEstimate[];
502
464
  files: RepoFileEntry[];
503
465
  total: number;
504
466
  hasMore: boolean;
@@ -518,6 +480,7 @@ interface ReadFileParams {
518
480
  waitTimeoutMs?: number;
519
481
  }
520
482
  interface ReadFileResult {
483
+ indexingEstimates?: DiscoveryIndexingEstimate[];
521
484
  /** Served action selected by unified read; legacy readers may omit it. */
522
485
  readTarget?: ReadTarget | null;
523
486
  filePath?: string;
@@ -530,11 +493,128 @@ interface ReadFileResult {
530
493
  targetResolution?: TargetResolution;
531
494
  availableVersions?: AvailableVersion[];
532
495
  }
496
+ /**
497
+ * A package-addressing target for a repository-wide CodeDiff. Version
498
+ * resolution belongs to the comparison endpoints, so this target
499
+ * intentionally has no version field. Package addressing resolves repository
500
+ * identity and commits; it does not narrow raw file results to a package path.
501
+ * Target selection uses own-key presence; a `repoUrl` key rejects this shape
502
+ * even when its value is `undefined`.
503
+ */
504
+ interface CodeDiffPackageTarget {
505
+ registry: CodeNavigationRegistry;
506
+ packageName: string;
507
+ }
508
+ /**
509
+ * A public repository target for CodeDiff. Ref resolution belongs to the
510
+ * comparison endpoints, so this target intentionally has no gitRef field.
511
+ * Target selection uses own-key presence; a `registry` or `packageName` key
512
+ * rejects this shape even when its value is `undefined`.
513
+ */
514
+ interface CodeDiffRepositoryTarget {
515
+ repoUrl: string;
516
+ }
517
+ type CodeDiffTarget = CodeDiffPackageTarget | CodeDiffRepositoryTarget;
518
+ type CodeDiffMode = "inventory" | "stats" | "patches";
519
+ interface CodeDiffOptions {
520
+ maxFiles?: number;
521
+ maxPatchBytes?: number;
522
+ pathPrefix?: string;
523
+ pathGlob?: string;
524
+ }
525
+ interface CodeDiffParams {
526
+ target: CodeDiffTarget;
527
+ from: string;
528
+ to: string;
529
+ mode: CodeDiffMode;
530
+ options?: CodeDiffOptions;
531
+ }
532
+ type CodeDiffRefKind = "SHA" | "TAG" | "BRANCH" | "HEAD" | "UNKNOWN";
533
+ type CodeDiffVersionSource = "REGISTRY" | "GIT_HEAD" | "TAG" | "RELEASE";
534
+ /**
535
+ * Effective raw inventory scope. Current successful backends return
536
+ * `REPOSITORY`; `PACKAGE` and `UNKNOWN` remain accepted for compatibility with
537
+ * legacy responses.
538
+ */
539
+ type RawCodeDiffScopeStatus = "PACKAGE" | "REPOSITORY" | "UNKNOWN";
540
+ type RawCodeDiffFileStatus = "ADDED" | "DELETED" | "MODIFIED";
541
+ type RawCodeDiffPathEncoding = "UTF8" | "BYTE_ESCAPED";
542
+ type RawCodeDiffFileContentStatus = "NOT_REQUESTED" | "STATS" | "PATCH" | "BINARY" | "METADATA_ONLY" | "OMITTED" | "UNAVAILABLE";
543
+ type RawCodeDiffContentCoverage = "NOT_REQUESTED" | "COMPLETE" | "PARTIAL" | "FAILED";
533
544
  type ContentModification = "INVISIBLE_CONTROLS_STRIPPED" | "HTML_COMMENTS_STRIPPED" | "IMAGES_REPLACED" | "UNSAFE_LINKS_NEUTRALIZED";
545
+ interface CodeDiffPackageInfo {
546
+ registry: CodeNavigationRegistry;
547
+ name: string;
548
+ repoUrl: string;
549
+ }
550
+ interface CodeDiffRefResolution {
551
+ requested: string;
552
+ resolvedVersion?: string;
553
+ ref: string;
554
+ commitSha: string;
555
+ refKind: CodeDiffRefKind;
556
+ versionSource?: CodeDiffVersionSource;
557
+ }
558
+ interface RawCodeDiffSummary {
559
+ filesChanged: number;
560
+ added: number;
561
+ deleted: number;
562
+ modified: number;
563
+ modeChanged: number;
564
+ typeChanged: number;
565
+ inventoryComplete: boolean;
566
+ unprojectableFiles: number;
567
+ }
568
+ interface RawCodeDiffScope {
569
+ /** Scope of returned paths and counts, independent of addressing form. */
570
+ status: RawCodeDiffScopeStatus;
571
+ /** Legacy package-scope metadata; absent from current repository results. */
572
+ fromSubpath?: string;
573
+ /** Legacy package-scope metadata; absent from current repository results. */
574
+ toSubpath?: string;
575
+ /** Caller-supplied repository-relative filter, not verified package scope. */
576
+ pathPrefix?: string;
577
+ /** Caller-supplied repository-relative filter, not verified package scope. */
578
+ pathGlob?: string;
579
+ }
580
+ interface RawCodeDiffContentFailure {
581
+ code: string;
582
+ retryable: boolean;
583
+ retryAfterMs?: number;
584
+ stage?: string;
585
+ limitKind?: string;
586
+ }
534
587
  interface ContentSafety {
535
588
  filtered: boolean;
536
589
  modifications: ContentModification[];
537
590
  }
591
+ interface RawCodeDiffFile {
592
+ path: string;
593
+ pathEncoding: RawCodeDiffPathEncoding;
594
+ status: RawCodeDiffFileStatus;
595
+ modeChanged: boolean;
596
+ typeChanged: boolean;
597
+ additions?: number;
598
+ deletions?: number;
599
+ patch?: string;
600
+ contentStatus: RawCodeDiffFileContentStatus;
601
+ contentOmissionReason?: string;
602
+ contentSafety: ContentSafety;
603
+ }
604
+ interface RawCodeDiff {
605
+ summary: RawCodeDiffSummary;
606
+ scope: RawCodeDiffScope;
607
+ contentCoverage: RawCodeDiffContentCoverage;
608
+ contentFailure?: RawCodeDiffContentFailure;
609
+ files: RawCodeDiffFile[];
610
+ hasMoreFiles: boolean;
611
+ }
612
+ interface CodeDiffResult {
613
+ package?: CodeDiffPackageInfo;
614
+ fromResolution: CodeDiffRefResolution;
615
+ toResolution: CodeDiffRefResolution;
616
+ raw: RawCodeDiff;
617
+ }
538
618
  type GrepRepoPatternType = "LITERAL" | "REGEX";
539
619
  type GrepPathSelectorKind = "EXACT" | "PREFIX" | "GLOB";
540
620
  interface GrepRepoPathSelector {
@@ -592,6 +672,7 @@ interface GrepRepoMatch {
592
672
  type GrepRouteTaken = "SINGLE_FILE" | "CONTENT_INDEX";
593
673
  type GrepTruncatedReason = "NONE" | "MAX_MATCHES" | "MAX_MATCHES_PER_FILE" | "DEADLINE";
594
674
  interface GrepRepoResult {
675
+ indexingEstimates?: DiscoveryIndexingEstimate[];
595
676
  matches: GrepRepoMatch[];
596
677
  nextCursor?: string;
597
678
  hasMore: boolean;
@@ -614,6 +695,10 @@ interface CodeNavigationService {
614
695
  readFile(params: ReadFileParams): Promise<ReadFileResult>;
615
696
  grepRepo(params: GrepRepoParams): Promise<GrepRepoResult>;
616
697
  }
698
+ /** Additive client capability for the unpromoted CodeDiff surface. */
699
+ interface CodeDiffService {
700
+ codeDiff(params: CodeDiffParams): Promise<CodeDiffResult>;
701
+ }
617
702
  /**
618
703
  * Parameters for search API call.
619
704
  */
@@ -749,6 +834,7 @@ interface GrepUnavailableTarget {
749
834
  suggestedSiteTargets: string[] | null;
750
835
  }
751
836
  interface GrepResult {
837
+ indexingEstimates?: DiscoveryIndexingEstimate[];
752
838
  hits: GrepHit[];
753
839
  targets: GrepTargetStatus[];
754
840
  unavailableTargets: GrepUnavailableTarget[];
@@ -771,12 +857,13 @@ interface ListParams {
771
857
  after?: string;
772
858
  waitTimeoutMs?: number;
773
859
  includeDetailedFields: boolean;
860
+ includeTargetProvenance?: boolean;
774
861
  /** Select exact read actions for compact site text; detailed fields always include them. */
775
862
  includeReadActions?: boolean;
776
863
  }
777
864
  type ListInventoryKind = "SOURCE" | "SITE";
778
865
  type ListEntryKind = "FILE" | "PAGE" | "DIRECTORY";
779
- type ListSiteWaitOutcome = "COMPLETED" | "DISCARDED" | "CANCELLED" | "TIMEOUT";
866
+ type ListSiteWaitOutcome = "COMPLETED" | "DISCARDED" | "CANCELLED" | "TIMEOUT" | "FAILED" | "SUPERSEDED";
780
867
  interface ListReadAction {
781
868
  target: string;
782
869
  path: string | null;
@@ -809,13 +896,14 @@ interface ListResolution {
809
896
  commitSha: string | null;
810
897
  }
811
898
  interface ListTargetIdentity {
812
- kind: string | null;
813
- registry: string | null;
814
- packageName: string | null;
815
- version: string | null;
816
- repoUrl: string | null;
899
+ kind?: string | null;
900
+ registry?: string | null;
901
+ packageName?: string | null;
902
+ version?: string | null;
903
+ repoUrl?: string | null;
817
904
  gitRef: string | null;
818
- commitSha: string | null;
905
+ commitSha?: string | null;
906
+ committedAt?: string | null;
819
907
  }
820
908
  interface ListTargetResolution {
821
909
  requested: ListTargetIdentity | null;
@@ -823,10 +911,10 @@ interface ListTargetResolution {
823
911
  served: ListTargetIdentity | null;
824
912
  freshness: string | null;
825
913
  freshnessReason: string | null;
826
- indexingRef: string | null;
827
- availableVersions: ListAvailableVersion[] | null;
828
- availableRefs: ListAvailableVersion[] | null;
829
- suggestedRefs: ListAvailableVersion[] | null;
914
+ indexingRef?: string | null;
915
+ availableVersions?: ListAvailableVersion[] | null;
916
+ availableRefs?: ListAvailableVersion[] | null;
917
+ suggestedRefs?: ListAvailableVersion[] | null;
830
918
  }
831
919
  interface ListIndexingEstimate {
832
920
  lowerSeconds: number | null;
@@ -850,6 +938,7 @@ interface ListSitePreparation {
850
938
  awaited: ListSiteWait[];
851
939
  }
852
940
  interface ListResult {
941
+ indexingEstimates?: DiscoveryIndexingEstimate[];
853
942
  inventoryKind: ListInventoryKind;
854
943
  requestedTarget: string;
855
944
  canonicalTarget: string | null;
@@ -1486,6 +1575,7 @@ interface PackageDocsPageInfo {
1486
1575
  totalCount?: number;
1487
1576
  }
1488
1577
  interface PackageDocsList {
1578
+ indexingEstimates?: DiscoveryIndexingEstimate[];
1489
1579
  registry?: string;
1490
1580
  packageName?: string;
1491
1581
  version?: string;
@@ -1598,6 +1688,123 @@ type ReadResult = ReadCodeResult | ReadDocsResult | ReadSymbolResolutionResult;
1598
1688
  interface ReadService {
1599
1689
  read(params: ReadParams): Promise<ReadResult>;
1600
1690
  }
1691
+ type ResolveTargetKind = "PACKAGE" | "REPOSITORY" | "SITE";
1692
+ type KnownLatestVersionMaliciousStatus = "NOT_APPLICABLE" | "CLEAR" | "AFFECTED" | "UNKNOWN";
1693
+ /**
1694
+ * Backend-owned malicious-content decision for the displayed latest version.
1695
+ * Future values remain readable and are interpreted conservatively by clients.
1696
+ */
1697
+ type LatestVersionMaliciousStatus = KnownLatestVersionMaliciousStatus | (string & {});
1698
+ type KnownMaliciousAdvisoryClassificationReason = "AFFECTED_VERSION_RANGE_MATCH" | "MISSING_DISPLAYED_VERSION" | "INVALID_DISPLAYED_VERSION" | "MISSING_AFFECTED_RANGES" | "EMPTY_AFFECTED_RANGES" | "INVALID_AFFECTED_RANGE";
1699
+ type MaliciousAdvisoryClassificationReason = KnownMaliciousAdvisoryClassificationReason | (string & {});
1700
+ interface ResolveTargetLatestVersionMaliciousAdvisory {
1701
+ osvId: string;
1702
+ classificationReasons: MaliciousAdvisoryClassificationReason[];
1703
+ }
1704
+ interface ResolveTargetLatestVersionMaliciousEvidence {
1705
+ advisories: ResolveTargetLatestVersionMaliciousAdvisory[];
1706
+ totalCount: number;
1707
+ truncated: boolean;
1708
+ }
1709
+ interface ResolveTargetParams {
1710
+ name: string;
1711
+ query?: string;
1712
+ registries?: PkgseerRegistry[];
1713
+ preferredKinds?: ResolveTargetKind[];
1714
+ intentHints?: string[];
1715
+ limit: number;
1716
+ includeDetailedFields: boolean;
1717
+ includeNameSimilarity: boolean;
1718
+ }
1719
+ interface ResolveTargetReference {
1720
+ kind: string;
1721
+ canonicalKey: string;
1722
+ confidence: string;
1723
+ }
1724
+ interface ResolveTargetMatch {
1725
+ confidence: string;
1726
+ nameSimilarity?: number;
1727
+ matchedAliases?: string[];
1728
+ matchTier?: number;
1729
+ score?: number;
1730
+ }
1731
+ interface ResolveTargetTarget {
1732
+ kind: string;
1733
+ canonicalKey: string;
1734
+ displayName?: string;
1735
+ description?: string;
1736
+ registry?: string;
1737
+ packageName?: string;
1738
+ latestVersion?: string;
1739
+ latestVersionMaliciousStatus: LatestVersionMaliciousStatus;
1740
+ latestVersionMaliciousEvidence?: ResolveTargetLatestVersionMaliciousEvidence;
1741
+ repositoryUrl?: string;
1742
+ repositoryOwner?: string;
1743
+ repositoryName?: string;
1744
+ stars?: number;
1745
+ downloadsLastMonth?: number;
1746
+ downloadsTotal?: number;
1747
+ documentationUrl?: string;
1748
+ docsAvailable: boolean;
1749
+ codeAvailable: boolean;
1750
+ groupKey?: string;
1751
+ match?: ResolveTargetMatch;
1752
+ docsPageCount?: number;
1753
+ codeFileCount?: number;
1754
+ license?: string;
1755
+ }
1756
+ interface ResolveTargetResult {
1757
+ best?: ResolveTargetReference;
1758
+ protectedMatches: ResolveTargetReference[];
1759
+ targets: ResolveTargetTarget[];
1760
+ targetsTruncated: boolean;
1761
+ ambiguous: boolean;
1762
+ ambiguousReason: string;
1763
+ }
1764
+ interface ResolveTargetService {
1765
+ resolveTarget(params: ResolveTargetParams): Promise<ResolveTargetResult>;
1766
+ }
1767
+ import { z as z3 } from "zod";
1768
+ /** Annotation fields required by OpenAI's MCP marketplace validation. */
1769
+ interface CompleteToolAnnotations {
1770
+ title?: string;
1771
+ readOnlyHint: boolean;
1772
+ idempotentHint?: boolean;
1773
+ openWorldHint: boolean;
1774
+ destructiveHint: boolean;
1775
+ }
1776
+ interface McpAuthActionContext {
1777
+ authSource: unknown;
1778
+ defaultAction: string;
1779
+ }
1780
+ type McpAuthAction = string | ((context: McpAuthActionContext) => string);
1781
+ /** Host-selected message and action for terms-acceptance failures. */
1782
+ interface ToolTermsRemediation {
1783
+ message: string;
1784
+ action: string;
1785
+ }
1786
+ /** Host-provided execution state shared by MCP and direct tool callers. */
1787
+ interface ToolExecutionContext {
1788
+ authAction?: McpAuthAction;
1789
+ termsRemediation?: ToolTermsRemediation;
1790
+ signal?: AbortSignal;
1791
+ }
1792
+ /**
1793
+ * Standard result type for all MCP tools
1794
+ */
1795
+ type ToolResult = {
1796
+ content: Array<{
1797
+ type: "text";
1798
+ text: string;
1799
+ }>;
1800
+ isError?: boolean;
1801
+ };
1802
+ /**
1803
+ * Zod raw shape type (what MCP SDK expects)
1804
+ */
1805
+ type ZodRawShape = {
1806
+ [k: string]: z3.ZodTypeAny;
1807
+ };
1601
1808
  /**
1602
1809
  * Services required to construct the MCP tool surface.
1603
1810
  *
@@ -1606,11 +1813,12 @@ interface ReadService {
1606
1813
  */
1607
1814
  interface McpToolServices {
1608
1815
  githitsService: GitHitsService;
1609
- codeNavigationService: CodeNavigationService;
1816
+ codeNavigationService: CodeNavigationService & CodeDiffService;
1610
1817
  packageIntelligenceService: PackageIntelligenceService;
1611
1818
  listService: ListService;
1612
1819
  readService: ReadService;
1613
1820
  grepService: GrepService;
1821
+ resolveTargetService: ResolveTargetService;
1614
1822
  }
1615
1823
  interface McpServerMetadata {
1616
1824
  name: string;