@githits/mcp 0.17.0 → 0.18.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
@@ -1622,7 +1622,41 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
1622
1622
  private normalisePackageDocsList;
1623
1623
  readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
1624
1624
  private executeReadPackageDoc;
1625
- private normalisePackageDocResult;
1625
+ }
1626
+ interface ReadParams {
1627
+ target: string;
1628
+ path?: string;
1629
+ startLine?: number;
1630
+ endLine?: number;
1631
+ waitTimeoutMs?: number;
1632
+ }
1633
+ interface ReadCodeResult {
1634
+ source: "code";
1635
+ result: ReadFileResult;
1636
+ }
1637
+ interface ReadDocsResult {
1638
+ source: "docs";
1639
+ result: PackageDocResult;
1640
+ }
1641
+ type ReadResult = ReadCodeResult | ReadDocsResult;
1642
+ interface ReadService {
1643
+ read(params: ReadParams): Promise<ReadResult>;
1644
+ }
1645
+ interface ReadServiceRuntime {
1646
+ clientHeaders?: ClientHeaderBuilder;
1647
+ userAgent?: string;
1648
+ clientVersion?: string;
1649
+ diagnostics?: ServiceDiagnostics;
1650
+ }
1651
+ /** Client for the backend's compact documentation/code read union. */
1652
+ declare class ReadServiceImpl implements ReadService {
1653
+ private readonly endpointUrl;
1654
+ private readonly tokenProvider;
1655
+ private readonly fetchFn;
1656
+ private readonly runtime;
1657
+ constructor(endpointUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: ReadServiceRuntime);
1658
+ read(params: ReadParams): Promise<ReadResult>;
1659
+ private executeRead;
1626
1660
  }
1627
1661
  /**
1628
1662
  * Factory function type for creating GitHitsService instances.
@@ -1648,4 +1682,4 @@ declare class RefreshingGitHitsService implements GitHitsService {
1648
1682
  */
1649
1683
  private withTokenRefresh;
1650
1684
  }
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 };
1685
+ 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-1cwgg1hh.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: {
@@ -1307,6 +1307,25 @@ interface PackageIntelligenceService {
1307
1307
  listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
1308
1308
  readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
1309
1309
  }
1310
+ interface ReadParams {
1311
+ target: string;
1312
+ path?: string;
1313
+ startLine?: number;
1314
+ endLine?: number;
1315
+ waitTimeoutMs?: number;
1316
+ }
1317
+ interface ReadCodeResult {
1318
+ source: "code";
1319
+ result: ReadFileResult;
1320
+ }
1321
+ interface ReadDocsResult {
1322
+ source: "docs";
1323
+ result: PackageDocResult;
1324
+ }
1325
+ type ReadResult = ReadCodeResult | ReadDocsResult;
1326
+ interface ReadService {
1327
+ read(params: ReadParams): Promise<ReadResult>;
1328
+ }
1310
1329
  /**
1311
1330
  * Services required to construct the MCP tool surface.
1312
1331
  *
@@ -1317,6 +1336,7 @@ interface McpToolServices {
1317
1336
  githitsService: GitHitsService;
1318
1337
  codeNavigationService: CodeNavigationService;
1319
1338
  packageIntelligenceService: PackageIntelligenceService;
1339
+ readService: ReadService;
1320
1340
  }
1321
1341
  interface McpServerMetadata {
1322
1342
  name: string;
@@ -1345,7 +1365,7 @@ interface CreateMcpServerOptions<TExtra = unknown> {
1345
1365
  instructionOptions?: Parameters<typeof buildMcpQuickStart>[0];
1346
1366
  traceTool?: McpToolExecutionHook;
1347
1367
  }
1348
- interface McpToolDescriptor<TSchema extends ZodRawShape2 = ZodRawShape2> {
1368
+ interface McpToolDescriptor<TSchema extends ZodRawShape = ZodRawShape> {
1349
1369
  name: string;
1350
1370
  description: string;
1351
1371
  schema: TSchema;