@githits/mcp 0.17.1 → 0.19.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 CHANGED
@@ -25,7 +25,7 @@ update and deployment rather than through a parallel implementation.
25
25
  - `getMcpToolDescriptors()` returns static tool metadata without requiring concrete services.
26
26
  - `buildMcpQuickStart(options?)` builds the guide returned by the read-only `quick_start` tool.
27
27
  - `buildMcpInstructions(options?)` is a deprecated compatibility alias for `buildMcpQuickStart()`.
28
- - `@githits/mcp/client` exports concrete GitHits service implementations, static token providers, URL/config helpers, request-header helpers, the `ServiceDiagnostics` type, and registry helpers for remote MCP servers. Service clients are silent by default; hosts that need operation spans or debug events inject a `ServiceDiagnostics` implementation through their runtime options. Hosts must explicitly opt into sensitive diagnostic areas and own the resulting privacy and retention policy.
28
+ - `@githits/mcp/client` exports GitHits service types and implementations, including `ReadService` and `ReadServiceImpl`, static token providers, URL/config helpers, request-header helpers, the `ServiceDiagnostics` type, and registry helpers for remote MCP servers. Service clients are silent by default; hosts that need operation spans or debug events inject a `ServiceDiagnostics` implementation through their runtime options. Hosts must explicitly opt into sensitive diagnostic areas and own the resulting privacy and retention policy.
29
29
  - The former module-global telemetry lifecycle helpers (`startTelemetrySpan`, `endTelemetrySpan`, `flushTelemetry`, and `withTelemetrySpan`) are not exported from `@githits/mcp/client`. Remote hosts own diagnostics lifecycle and destinations through injection.
30
30
  - `@githits/mcp/smoke-test` exports reusable smoke assertions and `runMcpSmoke()` for remote MCP server validation.
31
31
  - `@githits/mcp/tools` exports the browser-callable `get_example` factory and
@@ -100,7 +100,7 @@ response-to-error conversion, request transport, CORS policy, and any
100
100
  user-facing recovery. The injected service decides how the app-owned backend
101
101
  boundary is authenticated and reached.
102
102
 
103
- The package expects callers to provide service implementations through `McpToolServices` or a request-scoped `McpToolServicesProvider`. 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.
103
+ 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.
104
104
 
105
105
  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.
106
106
 
package/dist/client.d.ts CHANGED
@@ -823,7 +823,7 @@ declare class CodeNavigationServiceImpl implements CodeNavigationService, CodeDi
823
823
  *
824
824
  * Three separate URLs are needed:
825
825
  * - MCP URL: For OAuth discovery (.well-known endpoints) and auth flow
826
- * - API URL: For REST API calls (search and languages)
826
+ * - API URL: For REST API calls (search)
827
827
  * - Code navigation URL: For indexed package/source calls
828
828
  */
829
829
  declare const DEFAULT_MCP_URL = "https://mcp.githits.com";
@@ -835,7 +835,7 @@ declare const DEFAULT_CODE_NAV_URL = "https://pkgseer.dev";
835
835
  */
836
836
  declare function getMcpUrl(): string;
837
837
  /**
838
- * Get the REST API base URL (for search and languages).
838
+ * Get the REST API base URL (for search).
839
839
  * Override with GITHITS_API_URL environment variable.
840
840
  */
841
841
  declare function getApiUrl(): string;
@@ -851,16 +851,6 @@ declare function getCodeNavigationUrl(): string;
851
851
  */
852
852
  declare function getEnvApiToken(): string | undefined;
853
853
  /**
854
- * Language data from the API.
855
- */
856
- interface Language {
857
- id: string;
858
- name: string;
859
- display_name: string;
860
- aliases: string[];
861
- search_priority?: number;
862
- }
863
- /**
864
854
  * Parameters for search API call.
865
855
  */
866
856
  interface SearchParams {
@@ -885,10 +875,6 @@ interface GitHitsServiceRuntimeOptions {
885
875
  interface GitHitsService {
886
876
  /** Search for code examples. Returns markdown-formatted result. */
887
877
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
888
- /** Get all supported languages. */
889
- getLanguages(): Promise<Language[]>;
890
- /** Search supported languages using backend-ranked matching. */
891
- searchLanguages(query: string, limit?: number): Promise<Language[]>;
892
878
  }
893
879
  /**
894
880
  * Production implementation of GitHitsService.
@@ -901,12 +887,9 @@ declare class GitHitsServiceImpl implements GitHitsService {
901
887
  private readonly runtime;
902
888
  constructor(apiUrl: string, token: string, fetchFn?: typeof fetch | undefined, fetchTimeoutMs?: number | undefined, runtime?: GitHitsServiceRuntimeOptions);
903
889
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
904
- getLanguages(): Promise<Language[]>;
905
- searchLanguages(query: string, limit?: number): Promise<Language[]>;
906
890
  private headers;
907
891
  private fetchOptions;
908
892
  private request;
909
- private parseLanguages;
910
893
  private createError;
911
894
  }
912
895
  interface PackageSummaryParams {
@@ -1622,7 +1605,41 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
1622
1605
  private normalisePackageDocsList;
1623
1606
  readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
1624
1607
  private executeReadPackageDoc;
1625
- private normalisePackageDocResult;
1608
+ }
1609
+ interface ReadParams {
1610
+ target: string;
1611
+ path?: string;
1612
+ startLine?: number;
1613
+ endLine?: number;
1614
+ waitTimeoutMs?: number;
1615
+ }
1616
+ interface ReadCodeResult {
1617
+ source: "code";
1618
+ result: ReadFileResult;
1619
+ }
1620
+ interface ReadDocsResult {
1621
+ source: "docs";
1622
+ result: PackageDocResult;
1623
+ }
1624
+ type ReadResult = ReadCodeResult | ReadDocsResult;
1625
+ interface ReadService {
1626
+ read(params: ReadParams): Promise<ReadResult>;
1627
+ }
1628
+ interface ReadServiceRuntime {
1629
+ clientHeaders?: ClientHeaderBuilder;
1630
+ userAgent?: string;
1631
+ clientVersion?: string;
1632
+ diagnostics?: ServiceDiagnostics;
1633
+ }
1634
+ /** Client for the backend's compact documentation/code read union. */
1635
+ declare class ReadServiceImpl implements ReadService {
1636
+ private readonly endpointUrl;
1637
+ private readonly tokenProvider;
1638
+ private readonly fetchFn;
1639
+ private readonly runtime;
1640
+ constructor(endpointUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: ReadServiceRuntime);
1641
+ read(params: ReadParams): Promise<ReadResult>;
1642
+ private executeRead;
1626
1643
  }
1627
1644
  /**
1628
1645
  * Factory function type for creating GitHitsService instances.
@@ -1640,12 +1657,10 @@ declare class RefreshingGitHitsService implements GitHitsService {
1640
1657
  private readonly runtime;
1641
1658
  constructor(apiUrl: string, tokenProvider: TokenProvider, serviceFactory?: ServiceFactory | undefined, runtime?: GitHitsServiceRuntimeOptions);
1642
1659
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
1643
- getLanguages(): Promise<Language[]>;
1644
- searchLanguages(query: string, limit?: number): Promise<Language[]>;
1645
1660
  /**
1646
1661
  * Execute an operation with a fresh token.
1647
1662
  * On AuthenticationError, force-refresh and retry once.
1648
1663
  */
1649
1664
  private withTokenRefresh;
1650
1665
  }
1651
- export { AgentInfo, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, 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, RefreshingGitHitsService, ServiceDiagnostics, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
1666
+ export { AgentInfo, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, 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, 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,PackageIntelligenceServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,RefreshingGitHitsService2,createStaticTokenProvider2,createClientHeaderBuilder2}from"./shared/chunk-nsq99b9j.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,ReadServiceImpl2,RefreshingGitHitsService2,createStaticTokenProvider2,createClientHeaderBuilder2}from"./shared/chunk-d30a8smh.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};
package/dist/index.d.ts CHANGED
@@ -57,7 +57,7 @@ type ToolResult = {
57
57
  /**
58
58
  * Zod raw shape type (what MCP SDK expects)
59
59
  */
60
- type ZodRawShape2 = {
60
+ type ZodRawShape = {
61
61
  [k: string]: z.ZodTypeAny;
62
62
  };
63
63
  declare const registryMap: {
@@ -603,16 +603,6 @@ interface CodeNavigationService {
603
603
  grepRepo(params: GrepRepoParams): Promise<GrepRepoResult>;
604
604
  }
605
605
  /**
606
- * Language data from the API.
607
- */
608
- interface Language {
609
- id: string;
610
- name: string;
611
- display_name: string;
612
- aliases: string[];
613
- search_priority?: number;
614
- }
615
- /**
616
606
  * Parameters for search API call.
617
607
  */
618
608
  interface SearchParams {
@@ -631,10 +621,6 @@ interface GitHitsServiceRequestOptions {
631
621
  interface GitHitsService {
632
622
  /** Search for code examples. Returns markdown-formatted result. */
633
623
  search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
634
- /** Get all supported languages. */
635
- getLanguages(): Promise<Language[]>;
636
- /** Search supported languages using backend-ranked matching. */
637
- searchLanguages(query: string, limit?: number): Promise<Language[]>;
638
624
  }
639
625
  interface PackageSummaryParams {
640
626
  registry: PkgseerRegistry;
@@ -1307,6 +1293,25 @@ interface PackageIntelligenceService {
1307
1293
  listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
1308
1294
  readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
1309
1295
  }
1296
+ interface ReadParams {
1297
+ target: string;
1298
+ path?: string;
1299
+ startLine?: number;
1300
+ endLine?: number;
1301
+ waitTimeoutMs?: number;
1302
+ }
1303
+ interface ReadCodeResult {
1304
+ source: "code";
1305
+ result: ReadFileResult;
1306
+ }
1307
+ interface ReadDocsResult {
1308
+ source: "docs";
1309
+ result: PackageDocResult;
1310
+ }
1311
+ type ReadResult = ReadCodeResult | ReadDocsResult;
1312
+ interface ReadService {
1313
+ read(params: ReadParams): Promise<ReadResult>;
1314
+ }
1310
1315
  /**
1311
1316
  * Services required to construct the MCP tool surface.
1312
1317
  *
@@ -1317,6 +1322,7 @@ interface McpToolServices {
1317
1322
  githitsService: GitHitsService;
1318
1323
  codeNavigationService: CodeNavigationService;
1319
1324
  packageIntelligenceService: PackageIntelligenceService;
1325
+ readService: ReadService;
1320
1326
  }
1321
1327
  interface McpServerMetadata {
1322
1328
  name: string;
@@ -1345,7 +1351,7 @@ interface CreateMcpServerOptions<TExtra = unknown> {
1345
1351
  instructionOptions?: Parameters<typeof buildMcpQuickStart>[0];
1346
1352
  traceTool?: McpToolExecutionHook;
1347
1353
  }
1348
- interface McpToolDescriptor<TSchema extends ZodRawShape2 = ZodRawShape2> {
1354
+ interface McpToolDescriptor<TSchema extends ZodRawShape = ZodRawShape> {
1349
1355
  name: string;
1350
1356
  description: string;
1351
1357
  schema: TSchema;