@githits/mcp 0.10.1 → 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

@@ -1285,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;
@@ -1323,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";

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-nxdqknc9.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};
+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: {
@@ -987,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;
@@ -1025,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";
@@ -1161,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> {
@@ -1181,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 { BuildMcpInstructionsOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, buildMcpInstructions, createMcpServer, getMcpToolDescriptors, registerMcpTools };
+export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };