@githits/mcp 0.11.0 → 0.11.1

package/README.md

@@ -4,6 +4,13 @@ Reusable MCP server APIs and tool registrations for GitHits.
 
 This package exposes transport-neutral helpers for servers that want the GitHits MCP tool surface without the local `githits` CLI startup, auth storage, or Commander wiring.
 
+> **Browser boundary:** only the selected `@githits/mcp/tools` resolved runtime
+> graph is browser-safe. Installing `@githits/mcp` still installs its MCP SDK
+> and other Node-oriented dependencies; the package root and
+> `@githits/mcp/client` remain Node entries. The `/tools` entry does not provide
+> filesystem access, authentication implementation or storage, configuration
+> discovery, or any other host behavior.
+
 ## API
 
 - `createMcpServer(options)` creates an MCP server with GitHits tools registered.
@@ -11,11 +18,83 @@ This package exposes transport-neutral helpers for servers that want the GitHits
 - `getMcpToolDescriptors()` returns static tool metadata without requiring concrete services.
 - `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/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.
+- 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.
 - `@githits/mcp/smoke-test` exports reusable smoke assertions and `runMcpSmoke()` for remote MCP server validation.
+- `@githits/mcp/tools` exports the browser-callable `get_example` factory and
+  its structural service contract, plus `toCallableTool()` and the stable
+  callable result/schema types. It also exports the neutral
+  `AuthenticationError`, `ApiRateLimitError`, `FetchTimeoutError`, and
+  `TermsAcceptanceRequiredError` constructors used by the callable error
+  boundary.
+
+## Browser-callable `@githits/mcp/tools`
+
+The `/tools` entry is a small frontend-facing surface. Inject a service with
+only the `search(params, options?)` method, create the existing `get_example`
+definition, and adapt it to a plain callable object:
+
+```ts
+import {
+  createGetExampleTool,
+  toCallableTool,
+  type GetExampleRequestOptions,
+  type GetExampleSearchParams,
+  type GetExampleService,
+} from "@githits/mcp/tools";
+
+// Supplied by the application; it owns transport, authentication, and CORS.
+declare function searchExamples(
+  params: GetExampleSearchParams,
+  options?: GetExampleRequestOptions,
+): Promise<string>;
+
+const service: GetExampleService = {
+  search: (params, options) => searchExamples(params, options),
+};
+
+const tool = toCallableTool(createGetExampleTool(service));
+```
+
+`toCallableTool()` wraps the tool's Zod object schema, emits input-mode JSON
+Schema, and validates/defaults input before calling the service. The omitted
+`format` field remains optional in the schema and defaults to `"text-v1"`.
+Unknown object properties follow the normal Zod object behavior. Successful
+and structured error results are returned as the serializable `ToolResult`
+shape. If the caller supplies an `AbortSignal`, it is forwarded unchanged to
+the service; caller cancellation rejects the execution rather than becoming an
+error result.
+
+An injected browser service should throw one of the exported neutral error
+constructors when it wants `get_example` to return a structured
+`AUTH_REQUIRED`, `RATE_LIMITED`, `TIMEOUT`, or `TERMS_ACCEPTANCE_REQUIRED`
+`ToolResult`. This is an explicit thrown-error contract, not automatic HTTP
+response classification. Callable authentication remediation is host-neutral:
+`Authenticate with GitHits, then retry.` Terms errors use the canonical
+`acceptanceUrl` action. Other errors remain `UNKNOWN`.
+
+A frontend can add a small registration adapter for its WebMCP host API. The
+adapter owns the host-specific registration call and passes its signal through;
+the callable surface is not a generic protocol-conversion layer:
+
+```ts
+document.modelContext.registerTool({
+  name: tool.name,
+  description: tool.description,
+  inputSchema: tool.inputSchema,
+  annotations: tool.annotations,
+  execute: (input, options) =>
+    tool.execute(input, { signal: options?.signal }),
+});
+```
+
+The frontend owns `document.modelContext`, authentication and login UI, its
+response-to-error conversion, request transport, CORS policy, and any
+user-facing recovery. The injected service decides how the app-owned backend
+boundary is authenticated and reached.
 
 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.
+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.
 
 Remote MCP servers should provide request-scoped services through `createMcpServer()` and keep transport, auth/session handling, deployment config, and observability outside this package.

package/dist/client.d.ts

@@ -61,6 +61,28 @@ interface CreateClientHeaderBuilderOptions {
 * relying on module-level CLI state.
 */
 declare function createClientHeaderBuilder(options: CreateClientHeaderBuilderOptions): ClientHeaderBuilder;
+/**
+* Host-supplied diagnostics for transport-neutral service clients.
+*
+* Implementations may record operation timings or debug events in whatever
+* way is appropriate for their host. Core does not provide a default and
+* remains silent when diagnostics are omitted. Core callers gate every debug
+* event through `isEnabled(area)`; when it returns `false`, the corresponding
+* debug call is suppressed entirely. Returning `true` is therefore both a log
+* filter and a content-disclosure decision for the host.
+*
+* In particular, the `code-nav-wire` area may carry the exact GraphQL document
+* and request variables, including caller query text, so it requires separate
+* explicit opt-in. The `code-nav` and `pkg-graphql` schema-mismatch paths may
+* carry raw backend error text, and an enabled area may select that raw error
+* content instead of the sanitized message. These areas are not PII-safe;
+* hosts own their privacy and retention policy for any enabled diagnostics.
+*/
+interface ServiceDiagnostics {
+	withOperation<T>(name: string, operation: () => Promise<T>): Promise<T>;
+	isEnabled(area: string): boolean;
+	debug(area: string, event: Record<string, unknown>): void;
+}
 interface TokenProvider {
 	/** Get a valid token, refreshing proactively or reactively as needed. */
 	getToken(): Promise<string | undefined>;
@@ -637,6 +659,7 @@ declare class CodeNavigationServiceImpl implements CodeNavigationService, CodeDi
 		clientHeaders?: ClientHeaderBuilder;
 		userAgent?: string;
 		clientVersion?: string;
+		diagnostics?: ServiceDiagnostics;
 	});
 	private postGraphqlWithTargetResolutionFallback;
 	search(params: UnifiedSearchParams): Promise<UnifiedSearchOutcome>;
@@ -717,6 +740,10 @@ interface SearchParams {
 	licenseMode?: "strict" | "yolo" | "custom";
 	includeExplanation?: boolean;
 }
+/** Optional browser-standard controls for a GitHits service request. */
+interface GitHitsServiceRequestOptions {
+	signal?: AbortSignal;
+}
 /**
 * Parameters for feedback API call.
 *
@@ -743,13 +770,14 @@ interface GitHitsServiceRuntimeOptions {
 	clientHeaders?: ClientHeaderBuilder;
 	userAgent?: string;
 	exampleRequestTimeoutMs?: number;
+	diagnostics?: ServiceDiagnostics;
 }
 /**
 * Service interface for GitHits REST API.
 */
 interface GitHitsService {
 	/** Search for code examples. Returns markdown-formatted result. */
-	search(params: SearchParams): Promise<string>;
+	search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
 	/** Get all supported languages. */
 	getLanguages(): Promise<Language[]>;
 	/** Search supported languages using backend-ranked matching. */
@@ -767,7 +795,7 @@ declare class GitHitsServiceImpl implements GitHitsService {
 	private readonly fetchTimeoutMs;
 	private readonly runtime;
 	constructor(apiUrl: string, token: string, fetchFn?: typeof fetch | undefined, fetchTimeoutMs?: number | undefined, runtime?: GitHitsServiceRuntimeOptions);
-	search(params: SearchParams): Promise<string>;
+	search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
 	getLanguages(): Promise<Language[]>;
 	searchLanguages(query: string, limit?: number): Promise<Language[]>;
 	submitFeedback(params: FeedbackParams): Promise<FeedbackResult>;
@@ -1410,6 +1438,7 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
 		clientHeaders?: ClientHeaderBuilder;
 		userAgent?: string;
 		clientVersion?: string;
+		diagnostics?: ServiceDiagnostics;
 	});
 	packageSummary(params: PackageSummaryParams): Promise<PackageSummary>;
 	private executePackageSummary;
@@ -1456,7 +1485,7 @@ declare class RefreshingGitHitsService implements GitHitsService {
 	private readonly serviceFactory;
 	private readonly runtime;
 	constructor(apiUrl: string, tokenProvider: TokenProvider, serviceFactory?: ServiceFactory | undefined, runtime?: GitHitsServiceRuntimeOptions);
-	search(params: SearchParams): Promise<string>;
+	search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
 	getLanguages(): Promise<Language[]>;
 	searchLanguages(query: string, limit?: number): Promise<Language[]>;
 	submitFeedback(params: FeedbackParams): Promise<FeedbackResult>;
@@ -1466,15 +1495,4 @@ declare class RefreshingGitHitsService implements GitHitsService {
 	*/
 	private withTokenRefresh;
 }
-type TelemetryAttributeValue = string | number | boolean;
-interface TelemetryAttributes {
-	[key: string]: TelemetryAttributeValue | undefined;
-}
-interface TelemetrySpanHandle {
-	id: number;
-}
-declare function withTelemetrySpan<T>(name: string, operation: () => Promise<T>, attributes?: TelemetryAttributes): 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 { 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 };
+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 };

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-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};
+import{CodeDiffError,CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,toPkgseerRegistry,toPkgseerRegistryLowercase}from"./shared/chunk-mjxp4hpz.js";import"./shared/chunk-51x6tx02.js";export{CodeDiffError,CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,toPkgseerRegistry,toPkgseerRegistryLowercase};

package/dist/index.d.ts

@@ -451,6 +451,10 @@ interface SearchParams {
 	licenseMode?: "strict" | "yolo" | "custom";
 	includeExplanation?: boolean;
 }
+/** Optional browser-standard controls for a GitHits service request. */
+interface GitHitsServiceRequestOptions {
+	signal?: AbortSignal;
+}
 /**
 * Parameters for feedback API call.
 *
@@ -478,7 +482,7 @@ interface FeedbackResult {
 */
 interface GitHitsService {
 	/** Search for code examples. Returns markdown-formatted result. */
-	search(params: SearchParams): Promise<string>;
+	search(params: SearchParams, options?: GitHitsServiceRequestOptions): Promise<string>;
 	/** Get all supported languages. */
 	getLanguages(): Promise<Language[]>;
 	/** Search supported languages using backend-ranked matching. */
@@ -1110,14 +1114,31 @@ interface PackageIntelligenceService {
 	listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
 	readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
 }
-import { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 /** Annotation fields required by OpenAI's MCP marketplace validation. */
-interface CompleteToolAnnotations extends ToolAnnotations {
+interface CompleteToolAnnotations {
+	title?: string;
 	readOnlyHint: boolean;
+	idempotentHint?: boolean;
 	openWorldHint: boolean;
 	destructiveHint: boolean;
 }
+interface McpAuthActionContext {
+	authSource: unknown;
+	defaultAction: string;
+}
+type McpAuthAction = string | ((context: McpAuthActionContext) => string);
+/** Host-selected message and action for terms-acceptance failures. */
+interface ToolTermsRemediation {
+	message: string;
+	action: string;
+}
+/** Host-provided execution state shared by MCP and direct tool callers. */
+interface ToolExecutionContext {
+	authAction?: McpAuthAction;
+	termsRemediation?: ToolTermsRemediation;
+	signal?: AbortSignal;
+}
 /**
 * Standard result type for all MCP tools
 */
@@ -1134,11 +1155,6 @@ type ToolResult = {
 type ZodRawShape2 = {
 	[k: string]: z.ZodTypeAny;
 };
-interface McpAuthActionContext {
-	authSource: unknown;
-	defaultAction: string;
-}
-type McpAuthAction = string | ((context: McpAuthActionContext) => string);
 /**
 * Services required to construct the MCP tool surface.
 *
@@ -1168,6 +1184,7 @@ interface CreateMcpServerOptions<TExtra = unknown> {
 	metadata: McpServerMetadata;
 	services: McpToolServicesProvider<TExtra>;
 	authAction?: McpAuthAction;
+	termsRemediation?: ToolTermsRemediation;
 	/** Optional caller-owned MCP instructions. GitHits does not provide defaults. */
 	instructions?: string;
 	/** Controls the guide returned by `quick_start`. */
@@ -1185,6 +1202,7 @@ interface McpToolDescriptor<TSchema extends ZodRawShape2 = ZodRawShape2> {
 declare function getMcpToolDescriptors(): McpToolDescriptor[];
 declare function registerMcpTools<TExtra = unknown>(server: McpServer, options: {
 	authAction?: McpAuthAction;
+	termsRemediation?: ToolTermsRemediation;
 	services: McpToolServicesProvider<TExtra>;
 	traceTool?: McpToolExecutionHook;
 }): void;
@@ -1192,4 +1210,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, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };
+export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, ToolExecutionContext, ToolTermsRemediation, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };