@githits/mcp 0.10.0 → 0.11.0

package/README.md

@@ -9,11 +9,12 @@ This package exposes transport-neutral helpers for servers that want the GitHits
 - `createMcpServer(options)` creates an MCP server with GitHits tools registered.
 - `registerMcpTools(server, options)` registers GitHits tools on an existing MCP server.
 - `getMcpToolDescriptors()` returns static tool metadata without requiring concrete services.
-- `buildMcpInstructions(options?)` builds the GitHits MCP instruction block.
+- `buildMcpQuickStart(options?)` builds the guide returned by the read-only `quick_start` tool.
+- `buildMcpInstructions(options?)` is a deprecated compatibility alias for `buildMcpQuickStart()`.
 - `@githits/mcp/client` exports concrete GitHits service implementations, static token providers, URL/config helpers, request-header helpers, telemetry helpers, and registry helpers for remote MCP servers.
 - `@githits/mcp/smoke-test` exports reusable smoke assertions and `runMcpSmoke()` for remote MCP server validation.
 
-The package expects callers to provide service implementations through `McpToolServices` or a request-scoped `McpToolServicesProvider`. Servers can pass `traceTool` to `createMcpServer()` or `registerMcpTools()` to wrap public tool execution for instrumentation without receiving arguments or auth data.
+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.
 
 Only imports from `@githits/mcp`, `@githits/mcp/client`, `@githits/mcp/smoke-test`, 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.
 

package/dist/client.d.ts

@@ -136,8 +136,14 @@ interface TargetResolution {
 }
 type UnifiedSearchSource = "AUTO" | "DOCS" | "CODE" | "SYMBOL";
 type UnifiedSearchResultType = "DOCUMENTATION_PAGE" | "REPOSITORY_SYMBOL" | "REPOSITORY_CODE" | "REPOSITORY_DOC";
-type UnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "COMPLETED" | "TIMEOUT" | "FAILED";
-type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "STALE" | "FAILED" | "MISSING" | string;
+type KnownUnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "COMPLETED" | "DEFERRED" | "TIMEOUT" | "FAILED";
+/**
+* Backend-owned search-session status. Known values have explicit client
+* behavior; future values remain readable instead of invalidating the whole
+* response.
+*/
+type UnifiedSearchSessionStatus = KnownUnifiedSearchSessionStatus | (string & {});
+type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "PROVISIONAL" | "STALE" | "FAILED" | "MISSING" | string;
 /** Coverage state of the selected published documentation corpus. */
 type DocCoverageState = "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | string;
 /**
@@ -240,7 +246,7 @@ interface UnifiedSearchSourceStatus {
 }
 type UnifiedSearchDocumentationContributorKind = "REPOSITORY_DOCS" | "DOCPACK";
 type UnifiedSearchDocumentationContributorState = "SEARCHED" | "READY" | "PENDING" | "UNAVAILABLE";
-type UnifiedSearchDocumentationFreshness = "CURRENT" | "STALE";
+type UnifiedSearchDocumentationFreshness = "CURRENT" | "PROVISIONAL" | "STALE";
 /** One physical documentation corpus disclosed for a DOCS source row. */
 interface UnifiedSearchDocumentationContributor {
 	kind: UnifiedSearchDocumentationContributorKind;
@@ -1279,8 +1285,8 @@ interface PackageChangelogParams {
 	/** Branch or tag for CHANGELOG.md fetching. Ignored for GH Releases. */
 	gitRef?: string;
 	/**
-	* Start of version range. When set, the backend returns every entry
-	* between `fromVersion` and `toVersion` (or latest); `limit` is
+	* Exclusive start of version range. When set, the backend returns every
+	* entry after `fromVersion` through `toVersion` (or latest); `limit` is
 	* rejected client-side in this mode.
 	*/
 	fromVersion?: string;
@@ -1317,7 +1323,7 @@ interface ChangelogReport {
 	package?: ChangelogPackageInfo;
 	/** `"releases"` | `"changelog_file"` | `"hexdocs"` when resolved; absent for package versions with no changelog entry. */
 	source?: string;
-	/** Entries, newest-first. Empty array = resolved source but nothing in range. */
+	/** Entries in backend/source order. Empty array = resolved source but nothing in range. */
 	entries: ChangelogEntryDetail[];
 }
 type PackageDocSourceKind = "CRAWLED" | "REPOSITORY";
@@ -1471,4 +1477,4 @@ declare function withTelemetrySpan<T>(name: string, operation: () => Promise<T>,
 declare function startTelemetrySpan(name: string, attributes?: TelemetryAttributes): TelemetrySpanHandle | undefined;
 declare function endTelemetrySpan(handle: TelemetrySpanHandle | undefined, attributes?: TelemetryAttributes): void;
 declare function flushTelemetry(exitCode?: number): void;
-export { withTelemetrySpan, toPkgseerRegistryLowercase, toPkgseerRegistry, startTelemetrySpan, getMcpUrl, getEnvApiToken, getCodeNavigationUrl, getApiUrl, flushTelemetry, endTelemetrySpan, createStaticTokenProvider, createClientHeaderBuilder, TokenProvider, RefreshingGitHitsService, RawCodeDiffSummary, RawCodeDiffScopeStatus, RawCodeDiffScope, RawCodeDiffPathEncoding, RawCodeDiffFileStatus, RawCodeDiffFileContentStatus, RawCodeDiffFile, RawCodeDiffContentFailure, RawCodeDiffContentCoverage, RawCodeDiff, PackageIntelligenceServiceImpl, PackageIntelligenceService, PKGSEER_REGISTRY_LIST, GitHitsServiceImpl, GitHitsService, DEFAULT_MCP_URL, DEFAULT_CODE_NAV_URL, DEFAULT_API_URL, ContentSafety, ContentModification, CodeNavigationServiceImpl, CodeNavigationService, CodeDiffVersionSource, CodeDiffTarget, CodeDiffService, CodeDiffResult, CodeDiffRepositoryTarget, CodeDiffRefResolution, CodeDiffRefKind, CodeDiffPartialResult, CodeDiffParams, CodeDiffPackageTarget, CodeDiffPackageInfo, CodeDiffOptions, CodeDiffMode, CodeDiffErrorRef, CodeDiffErrorDetails, CodeDiffError, AgentInfo };
+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, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, endTelemetrySpan, flushTelemetry, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getMcpUrl, startTelemetrySpan, toPkgseerRegistry, toPkgseerRegistryLowercase, withTelemetrySpan };

package/dist/client.js

@@ -1 +1 @@
-import{CodeDiffError,CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,endTelemetrySpan,flushTelemetry,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,startTelemetrySpan,toPkgseerRegistry,toPkgseerRegistryLowercase,withTelemetrySpan}from"./shared/chunk-qawyzgzx.js";export{withTelemetrySpan,toPkgseerRegistryLowercase,toPkgseerRegistry,startTelemetrySpan,getMcpUrl,getEnvApiToken,getCodeNavigationUrl,getApiUrl,flushTelemetry,endTelemetrySpan,createStaticTokenProvider,createClientHeaderBuilder,RefreshingGitHitsService,PackageIntelligenceServiceImpl,PKGSEER_REGISTRY_LIST,GitHitsServiceImpl,DEFAULT_MCP_URL,DEFAULT_CODE_NAV_URL,DEFAULT_API_URL,CodeNavigationServiceImpl,CodeDiffError};
+import{CodeDiffError,CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,endTelemetrySpan,flushTelemetry,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,startTelemetrySpan,toPkgseerRegistry,toPkgseerRegistryLowercase,withTelemetrySpan}from"./shared/chunk-7xsjs2xx.js";export{CodeDiffError,CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,endTelemetrySpan,flushTelemetry,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,startTelemetrySpan,toPkgseerRegistry,toPkgseerRegistryLowercase,withTelemetrySpan};

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 /**
-* Build the server-level instructions string for the current session.
+* Build the detailed guide returned by `quick_start`.
 *
 * Emits the core block plus the package/code-tools section.
 * Mirrors `getMcpToolDefinitions` so the instructions stay aligned
 * with the registered tool surface.
 */
-interface BuildMcpInstructionsOptions {
+interface BuildMcpQuickStartOptions {
 	/**
 	* Include the external-content posture (shared guardrail block).
 	* Defaults to `true` — production always wants it. The eval mock
@@ -14,6 +14,13 @@ interface BuildMcpInstructionsOptions {
 	*/
 	includeExternalContentPosture?: boolean;
 }
+/** @deprecated Use `BuildMcpQuickStartOptions`; retained for API compatibility. */
+type BuildMcpInstructionsOptions = BuildMcpQuickStartOptions;
+declare function buildMcpQuickStart(options?: BuildMcpQuickStartOptions): string;
+/**
+* @deprecated Use `buildMcpQuickStart`. GitHits no longer publishes MCP
+* initialize instructions because clients expose them inconsistently.
+*/
 declare function buildMcpInstructions(options?: BuildMcpInstructionsOptions): string;
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 declare const registryMap: {
@@ -99,8 +106,14 @@ interface TargetResolution {
 }
 type UnifiedSearchSource = "AUTO" | "DOCS" | "CODE" | "SYMBOL";
 type UnifiedSearchResultType = "DOCUMENTATION_PAGE" | "REPOSITORY_SYMBOL" | "REPOSITORY_CODE" | "REPOSITORY_DOC";
-type UnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "COMPLETED" | "TIMEOUT" | "FAILED";
-type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "STALE" | "FAILED" | "MISSING" | string;
+type KnownUnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "COMPLETED" | "DEFERRED" | "TIMEOUT" | "FAILED";
+/**
+* Backend-owned search-session status. Known values have explicit client
+* behavior; future values remain readable instead of invalidating the whole
+* response.
+*/
+type UnifiedSearchSessionStatus = KnownUnifiedSearchSessionStatus | (string & {});
+type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "PROVISIONAL" | "STALE" | "FAILED" | "MISSING" | string;
 /** Coverage state of the selected published documentation corpus. */
 type DocCoverageState = "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | string;
 /**
@@ -203,7 +216,7 @@ interface UnifiedSearchSourceStatus {
 }
 type UnifiedSearchDocumentationContributorKind = "REPOSITORY_DOCS" | "DOCPACK";
 type UnifiedSearchDocumentationContributorState = "SEARCHED" | "READY" | "PENDING" | "UNAVAILABLE";
-type UnifiedSearchDocumentationFreshness = "CURRENT" | "STALE";
+type UnifiedSearchDocumentationFreshness = "CURRENT" | "PROVISIONAL" | "STALE";
 /** One physical documentation corpus disclosed for a DOCS source row. */
 interface UnifiedSearchDocumentationContributor {
 	kind: UnifiedSearchDocumentationContributorKind;
@@ -981,8 +994,8 @@ interface PackageChangelogParams {
 	/** Branch or tag for CHANGELOG.md fetching. Ignored for GH Releases. */
 	gitRef?: string;
 	/**
-	* Start of version range. When set, the backend returns every entry
-	* between `fromVersion` and `toVersion` (or latest); `limit` is
+	* Exclusive start of version range. When set, the backend returns every
+	* entry after `fromVersion` through `toVersion` (or latest); `limit` is
 	* rejected client-side in this mode.
 	*/
 	fromVersion?: string;
@@ -1019,7 +1032,7 @@ interface ChangelogReport {
 	package?: ChangelogPackageInfo;
 	/** `"releases"` | `"changelog_file"` | `"hexdocs"` when resolved; absent for package versions with no changelog entry. */
 	source?: string;
-	/** Entries, newest-first. Empty array = resolved source but nothing in range. */
+	/** Entries in backend/source order. Empty array = resolved source but nothing in range. */
 	entries: ChangelogEntryDetail[];
 }
 type PackageDocSourceKind = "CRAWLED" | "REPOSITORY";
@@ -1155,8 +1168,12 @@ interface CreateMcpServerOptions<TExtra = unknown> {
 	metadata: McpServerMetadata;
 	services: McpToolServicesProvider<TExtra>;
 	authAction?: McpAuthAction;
+	/** Optional caller-owned MCP instructions. GitHits does not provide defaults. */
 	instructions?: string;
-	instructionOptions?: Parameters<typeof buildMcpInstructions>[0];
+	/** Controls the guide returned by `quick_start`. */
+	quickStartOptions?: Parameters<typeof buildMcpQuickStart>[0];
+	/** @deprecated Use `quickStartOptions`. */
+	instructionOptions?: Parameters<typeof buildMcpQuickStart>[0];
 	traceTool?: McpToolExecutionHook;
 }
 interface McpToolDescriptor<TSchema extends ZodRawShape2 = ZodRawShape2> {
@@ -1175,4 +1192,4 @@ declare function registerMcpTools<TExtra = unknown>(server: McpServer, options:
 * Creates the transport-neutral MCP server with injected services.
 */
 declare function createMcpServer<TExtra = unknown>(options: CreateMcpServerOptions<TExtra>): McpServer;
-export { registerMcpTools, getMcpToolDescriptors, createMcpServer, buildMcpInstructions, McpToolServicesProvider, McpToolServices, McpToolExecutionHook, McpToolDescriptor, McpServerMetadata, McpRequestContext, McpAuthActionContext, McpAuthAction, CreateMcpServerOptions, BuildMcpInstructionsOptions };
+export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };