@githits/mcp 0.15.0 → 0.16.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,35 +22,6 @@ 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
- /**
54
25
  * Registry taxonomy shared by code-navigation and package-intelligence
55
26
  * services. Single source of truth for:
56
27
  *
@@ -91,6 +62,35 @@ declare function toPkgseerRegistry(registry: PkgseerRegistryArg): PkgseerRegistr
91
62
  */
92
63
  declare function toPkgseerRegistryLowercase(registry: PkgseerRegistry): PkgseerRegistryArg;
93
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>;
91
+ }
92
+ declare function createStaticTokenProvider(token: string): TokenProvider;
93
+ /**
94
94
  * Back-compat alias — the canonical registry union now lives in
95
95
  * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
96
96
  * consumers of `CodeNavigationRegistry` compile unchanged.
@@ -165,7 +165,7 @@ type KnownUnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "C
165
165
  * response.
166
166
  */
167
167
  type UnifiedSearchSessionStatus = KnownUnifiedSearchSessionStatus | (string & {});
168
- type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "PROVISIONAL" | "STALE" | "FAILED" | "MISSING" | string;
168
+ type CodeIndexState = "CURRENT" | "INDEXED" | "PENDING" | "INDEXING" | "PROVISIONAL" | "STALE" | "FAILED" | "MISSING" | string;
169
169
  /** Coverage state of the selected published documentation corpus. */
170
170
  type DocCoverageState = "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | string;
171
171
  /**
@@ -804,7 +804,7 @@ declare class CodeNavigationServiceImpl implements CodeNavigationService, CodeDi
804
804
  *
805
805
  * Three separate URLs are needed:
806
806
  * - MCP URL: For OAuth discovery (.well-known endpoints) and auth flow
807
- * - API URL: For REST API calls (search, languages, feedbacks)
807
+ * - API URL: For REST API calls (search and languages)
808
808
  * - Code navigation URL: For indexed package/source calls
809
809
  */
810
810
  declare const DEFAULT_MCP_URL = "https://mcp.githits.com";
@@ -816,7 +816,7 @@ declare const DEFAULT_CODE_NAV_URL = "https://pkgseer.dev";
816
816
  */
817
817
  declare function getMcpUrl(): string;
818
818
  /**
819
- * Get the REST API base URL (for search, languages, feedbacks).
819
+ * Get the REST API base URL (for search and languages).
820
820
  * Override with GITHITS_API_URL environment variable.
821
821
  */
822
822
  declare function getApiUrl(): string;
@@ -854,28 +854,6 @@ interface SearchParams {
854
854
  interface GitHitsServiceRequestOptions {
855
855
  signal?: AbortSignal;
856
856
  }
857
- /**
858
- * Parameters for feedback API call.
859
- *
860
- * Feedback can target an example, a solution, or the current CLI/MCP
861
- * session. When neither `exampleId` nor `solutionId` is present, the
862
- * backend uses the `x-githits-session-id` header from injected client headers
863
- * to create generic session feedback.
864
- */
865
- interface FeedbackParams {
866
- exampleId?: string;
867
- solutionId?: string;
868
- accepted: boolean;
869
- feedbackText?: string;
870
- toolName?: string;
871
- }
872
- /**
873
- * Feedback response from the API.
874
- */
875
- interface FeedbackResult {
876
- success: boolean;
877
- message: string;
878
- }
879
857
  interface GitHitsServiceRuntimeOptions {
880
858
  clientHeaders?: ClientHeaderBuilder;
881
859
  userAgent?: string;
@@ -892,8 +870,6 @@ interface GitHitsService {
892
870
  getLanguages(): Promise<Language[]>;
893
871
  /** Search supported languages using backend-ranked matching. */
894
872
  searchLanguages(query: string, limit?: number): Promise<Language[]>;
895
- /** Submit feedback on a result or the current GitHits session. */
896
- submitFeedback(params: FeedbackParams): Promise<FeedbackResult>;
897
873
  }
898
874
  /**
899
875
  * Production implementation of GitHitsService.
@@ -908,7 +884,6 @@ declare class GitHitsServiceImpl implements GitHitsService {
908
884
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
909
885
  getLanguages(): Promise<Language[]>;
910
886
  searchLanguages(query: string, limit?: number): Promise<Language[]>;
911
- submitFeedback(params: FeedbackParams): Promise<FeedbackResult>;
912
887
  private headers;
913
888
  private fetchOptions;
914
889
  private request;
@@ -1529,6 +1504,8 @@ interface PackageDocsList {
1529
1504
  packageName?: string;
1530
1505
  version?: string;
1531
1506
  stale?: boolean;
1507
+ /** Backend-owned repository documentation lifecycle state. */
1508
+ codeIndexState?: CodeIndexState;
1532
1509
  pages: PackageDocPageSummary[];
1533
1510
  pageInfo?: PackageDocsPageInfo;
1534
1511
  }
@@ -1633,7 +1610,6 @@ declare class RefreshingGitHitsService implements GitHitsService {
1633
1610
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
1634
1611
  getLanguages(): Promise<Language[]>;
1635
1612
  searchLanguages(query: string, limit?: number): Promise<Language[]>;
1636
- submitFeedback(params: FeedbackParams): Promise<FeedbackResult>;
1637
1613
  /**
1638
1614
  * Execute an operation with a fresh token.
1639
1615
  * On AuthenticationError, force-refresh and retry once.
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,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2,RefreshingGitHitsService2,createStaticTokenProvider2,createClientHeaderBuilder2}from"./shared/chunk-vkwpw51c.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,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,PackageIntelligenceServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,RefreshingGitHitsService2,createStaticTokenProvider2,createClientHeaderBuilder2}from"./shared/chunk-kpjbjs3v.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,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
@@ -23,6 +23,47 @@ declare function buildMcpQuickStart(options?: BuildMcpQuickStartOptions): string
23
23
  */
24
24
  declare function buildMcpInstructions(options?: BuildMcpInstructionsOptions): string;
25
25
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
26
+ import { z } from "zod";
27
+ /** Annotation fields required by OpenAI's MCP marketplace validation. */
28
+ interface CompleteToolAnnotations {
29
+ title?: string;
30
+ readOnlyHint: boolean;
31
+ idempotentHint?: boolean;
32
+ openWorldHint: boolean;
33
+ destructiveHint: boolean;
34
+ }
35
+ interface McpAuthActionContext {
36
+ authSource: unknown;
37
+ defaultAction: string;
38
+ }
39
+ type McpAuthAction = string | ((context: McpAuthActionContext) => string);
40
+ /** Host-selected message and action for terms-acceptance failures. */
41
+ interface ToolTermsRemediation {
42
+ message: string;
43
+ action: string;
44
+ }
45
+ /** Host-provided execution state shared by MCP and direct tool callers. */
46
+ interface ToolExecutionContext {
47
+ authAction?: McpAuthAction;
48
+ termsRemediation?: ToolTermsRemediation;
49
+ signal?: AbortSignal;
50
+ }
51
+ /**
52
+ * Standard result type for all MCP tools
53
+ */
54
+ type ToolResult = {
55
+ content: Array<{
56
+ type: "text";
57
+ text: string;
58
+ }>;
59
+ isError?: boolean;
60
+ };
61
+ /**
62
+ * Zod raw shape type (what MCP SDK expects)
63
+ */
64
+ type ZodRawShape2 = {
65
+ [k: string]: z.ZodTypeAny;
66
+ };
26
67
  declare const registryMap: {
27
68
  readonly npm: "NPM";
28
69
  readonly pypi: "PYPI";
@@ -113,7 +154,7 @@ type KnownUnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "C
113
154
  * response.
114
155
  */
115
156
  type UnifiedSearchSessionStatus = KnownUnifiedSearchSessionStatus | (string & {});
116
- type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "PROVISIONAL" | "STALE" | "FAILED" | "MISSING" | string;
157
+ type CodeIndexState = "CURRENT" | "INDEXED" | "PENDING" | "INDEXING" | "PROVISIONAL" | "STALE" | "FAILED" | "MISSING" | string;
117
158
  /** Coverage state of the selected published documentation corpus. */
118
159
  type DocCoverageState = "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | string;
119
160
  /**
@@ -570,28 +611,6 @@ interface GitHitsServiceRequestOptions {
570
611
  signal?: AbortSignal;
571
612
  }
572
613
  /**
573
- * Parameters for feedback API call.
574
- *
575
- * Feedback can target an example, a solution, or the current CLI/MCP
576
- * session. When neither `exampleId` nor `solutionId` is present, the
577
- * backend uses the `x-githits-session-id` header from injected client headers
578
- * to create generic session feedback.
579
- */
580
- interface FeedbackParams {
581
- exampleId?: string;
582
- solutionId?: string;
583
- accepted: boolean;
584
- feedbackText?: string;
585
- toolName?: string;
586
- }
587
- /**
588
- * Feedback response from the API.
589
- */
590
- interface FeedbackResult {
591
- success: boolean;
592
- message: string;
593
- }
594
- /**
595
614
  * Service interface for GitHits REST API.
596
615
  */
597
616
  interface GitHitsService {
@@ -601,8 +620,6 @@ interface GitHitsService {
601
620
  getLanguages(): Promise<Language[]>;
602
621
  /** Search supported languages using backend-ranked matching. */
603
622
  searchLanguages(query: string, limit?: number): Promise<Language[]>;
604
- /** Submit feedback on a result or the current GitHits session. */
605
- submitFeedback(params: FeedbackParams): Promise<FeedbackResult>;
606
623
  }
607
624
  interface PackageSummaryParams {
608
625
  registry: PkgseerRegistry;
@@ -1218,6 +1235,8 @@ interface PackageDocsList {
1218
1235
  packageName?: string;
1219
1236
  version?: string;
1220
1237
  stale?: boolean;
1238
+ /** Backend-owned repository documentation lifecycle state. */
1239
+ codeIndexState?: CodeIndexState;
1221
1240
  pages: PackageDocPageSummary[];
1222
1241
  pageInfo?: PackageDocsPageInfo;
1223
1242
  }
@@ -1260,47 +1279,6 @@ interface PackageIntelligenceService {
1260
1279
  listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
1261
1280
  readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
1262
1281
  }
1263
- import { z } from "zod";
1264
- /** Annotation fields required by OpenAI's MCP marketplace validation. */
1265
- interface CompleteToolAnnotations {
1266
- title?: string;
1267
- readOnlyHint: boolean;
1268
- idempotentHint?: boolean;
1269
- openWorldHint: boolean;
1270
- destructiveHint: boolean;
1271
- }
1272
- interface McpAuthActionContext {
1273
- authSource: unknown;
1274
- defaultAction: string;
1275
- }
1276
- type McpAuthAction = string | ((context: McpAuthActionContext) => string);
1277
- /** Host-selected message and action for terms-acceptance failures. */
1278
- interface ToolTermsRemediation {
1279
- message: string;
1280
- action: string;
1281
- }
1282
- /** Host-provided execution state shared by MCP and direct tool callers. */
1283
- interface ToolExecutionContext {
1284
- authAction?: McpAuthAction;
1285
- termsRemediation?: ToolTermsRemediation;
1286
- signal?: AbortSignal;
1287
- }
1288
- /**
1289
- * Standard result type for all MCP tools
1290
- */
1291
- type ToolResult = {
1292
- content: Array<{
1293
- type: "text";
1294
- text: string;
1295
- }>;
1296
- isError?: boolean;
1297
- };
1298
- /**
1299
- * Zod raw shape type (what MCP SDK expects)
1300
- */
1301
- type ZodRawShape2 = {
1302
- [k: string]: z.ZodTypeAny;
1303
- };
1304
1282
  /**
1305
1283
  * Services required to construct the MCP tool surface.
1306
1284
  *