@githits/mcp 0.4.15 → 0.5.1

package/README.md

@@ -11,9 +11,10 @@ This package exposes transport-neutral helpers for servers that want the GitHits
 - `getMcpToolDescriptors()` returns static tool metadata without requiring concrete services.
 - `buildMcpInstructions(options?)` builds the GitHits MCP instruction block.
 - `@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`.
+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.
 
-Only imports from `@githits/mcp`, `@githits/mcp/client`, 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`, 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

@@ -103,6 +103,7 @@ interface TargetResolutionIdentity {
 	commitSha?: string;
 }
 type AvailableRef = AvailableVersion;
+type SuggestedRef = AvailableVersion;
 interface TargetResolution {
 	requested?: TargetResolutionIdentity;
 	resolvedRequested?: TargetResolutionIdentity;
@@ -112,6 +113,7 @@ interface TargetResolution {
 	indexingRef?: string;
 	availableVersions: AvailableVersion[];
 	availableRefs: AvailableRef[];
+	suggestedRefs?: SuggestedRef[];
 }
 type UnifiedSearchSource = "AUTO" | "DOCS" | "CODE" | "SYMBOL";
 type UnifiedSearchResultType = "DOCUMENTATION_PAGE" | "REPOSITORY_SYMBOL" | "REPOSITORY_CODE" | "REPOSITORY_DOC";
@@ -207,6 +209,7 @@ interface UnifiedSearchProgressTarget {
 	targetResolution?: TargetResolution;
 	availableVersions?: AvailableVersion[];
 	availableRefs?: AvailableRef[];
+	suggestedRefs?: SuggestedRef[];
 }
 interface UnifiedSearchRequestedTarget {
 	registry?: CodeNavigationRegistry;
@@ -543,6 +546,8 @@ declare class GitHitsServiceImpl implements GitHitsService {
 interface PackageSummaryParams {
 	registry: PkgseerRegistry;
 	packageName: string;
+	/** Include verbose/json-only fields such as recent advisories and changes. */
+	includeVerboseFields?: boolean;
 }
 interface PackageIdentity {
 	name: string;
@@ -645,6 +650,10 @@ interface PackageDependenciesParams {
 	version?: string;
 	/** Optional. Backend returns a full transitive graph when true. */
 	includeTransitive?: boolean;
+	/** Include transitive aggregate/detail fields beyond the dependency graph. */
+	includeTransitiveDetails?: boolean;
+	/** Include dependency group metadata. */
+	includeGroups?: boolean;
 	/**
 	* Optional transitive-traversal depth (1–10). Omit for the backend
 	* default (full graph) — note the CLI applies a 3-deep guardrail but
@@ -669,19 +678,158 @@ interface PackageUpgradeDependencyProbeParams {
 	includeDependencyChanges?: boolean;
 	includeGroups?: boolean;
 }
+interface PackageUpgradeReviewPackageParams {
+	registry: PkgseerRegistry;
+	name: string;
+	currentVersion: string;
+	targetVersion: string;
+}
+interface PackageUpgradeReviewParams {
+	packages: PackageUpgradeReviewPackageParams[];
+	includeTransitiveSecurity: boolean;
+	includeDependencyIssues: boolean;
+	changelogLimit: number;
+	minSeverity?: number;
+}
+interface PackageUpgradeAdvisorySummary {
+	id?: string;
+	aliases: string[];
+	summary?: string;
+	severity?: number;
+	severityLabel?: string;
+	fixedIn: string[];
+	isMalicious?: boolean;
+}
+interface PackageUpgradeVersionVulnerabilitySummary {
+	version: string;
+	publishedAt?: string;
+	deprecated?: boolean;
+	deprecationReason?: string;
+	affectedCount: number;
+	nonAffectingCount: number;
+	allCount: number;
+	lastModifiedAt?: string;
+	advisories: PackageUpgradeAdvisorySummary[];
+}
+interface PackageUpgradeTransitiveVulnerablePackage {
+	id: string;
+	registry: string;
+	name: string;
+	versions: string[];
+	affectedCount: number;
+	maxSeverityScore?: number;
+	maxSeverityLabel?: string;
+	advisoryIds: string[];
+}
+interface PackageUpgradeTransitivePackagePage {
+	entries: PackageUpgradeTransitiveVulnerablePackage[];
+	totalCount: number;
+	truncated: boolean;
+}
+interface PackageUpgradeTransitiveSecurity {
+	currentAffected: number;
+	targetAffected: number;
+	introducedPackages: string[];
+	fixedPackages: string[];
+	introducedPackageDetails: PackageUpgradeTransitivePackagePage;
+	fixedPackageDetails: PackageUpgradeTransitivePackagePage;
+	stillAffectedPackageDetails: PackageUpgradeTransitivePackagePage;
+}
+interface PackageUpgradeSecurity {
+	current?: PackageUpgradeVersionVulnerabilitySummary;
+	target?: PackageUpgradeVersionVulnerabilitySummary;
+	added: PackageUpgradeAdvisorySummary[];
+	removed: PackageUpgradeAdvisorySummary[];
+	notAddressed: PackageUpgradeAdvisorySummary[];
+	fixed: PackageUpgradeAdvisorySummary[];
+	introduced: PackageUpgradeAdvisorySummary[];
+	unchanged: PackageUpgradeAdvisorySummary[];
+	transitive?: PackageUpgradeTransitiveSecurity;
+}
+interface PackageUpgradeChangelogEntry {
+	version?: string;
+	publishedAt?: string;
+	htmlUrl?: string;
+	body?: string;
+	bodyPreview?: string;
+	headline?: string;
+	signals: string[];
+}
+interface PackageUpgradeChangelog {
+	source?: string;
+	fallback?: string;
+	entries: PackageUpgradeChangelogEntry[];
+	sampledEntries: PackageUpgradeChangelogEntry[];
+	keywordEntries: PackageUpgradeChangelogEntry[];
+	totalKeywordEntries: number;
+	totalEntries: number;
+	totalEntriesWithBodies: number;
+	truncated: boolean;
+	hasReleaseNoteBodies: boolean;
+	breakingSignals: string[];
+	migrationSignals: string[];
+}
+interface PackageUpgradeCompatibility {
+	peerDependencyChanges: string[];
+	notes: string[];
+}
+interface PackageUpgradeDependencyChangeItem {
+	name: string;
+	registry?: string;
+	version?: string;
+	fromVersions: string[];
+	toVersions: string[];
+	constraint?: string;
+	type?: string;
+}
+interface PackageUpgradeDependencyChangeGroup {
+	added: PackageUpgradeDependencyChangeItem[];
+	removed: PackageUpgradeDependencyChangeItem[];
+	changed: PackageUpgradeDependencyChangeItem[];
+}
+interface PackageUpgradeDependencyChanges {
+	direct: PackageUpgradeDependencyChangeGroup;
+	transitive: PackageUpgradeDependencyChangeGroup;
+}
+interface PackageUpgradeDependencyIssues {
+	currentTotal: number;
+	targetTotal: number;
+	introducedDeprecated: string[];
+	introducedDuplicates: string[];
+	introducedConflicts: string[];
+	introducedOutdated: string[];
+}
+interface PackageUpgradeReview {
+	registry: string;
+	name: string;
+	currentVersion: string;
+	targetVersion: string;
+	latestVersion?: string;
+	versionDelta: string;
+	security: PackageUpgradeSecurity;
+	changelog: PackageUpgradeChangelog;
+	compatibility?: PackageUpgradeCompatibility;
+	dependencyChanges?: PackageUpgradeDependencyChanges;
+	dependencyIssues?: PackageUpgradeDependencyIssues;
+	unknowns: string[];
+}
+interface PackageUpgradeReviewResponse {
+	summary: {
+		total: number;
+		withUnknowns: number;
+		withAddedAdvisories: number;
+		withBreakingSignals: number;
+		withDirectDependencyChanges: number;
+		withTransitiveVulnerabilityAdditions: number;
+	};
+	reviews: PackageUpgradeReview[];
+}
 interface DirectDependency {
 	name: string;
 	versionConstraint?: string;
 	type?: string;
 }
 /**
-* Opaque GenericJSON passthrough. The `package_dependencies` tool
-* migrated to typed fields (`dependencyGraph`, `dependencyConflicts`,
-* `circularDependencyCycles`, `environmentMarkers`); this type is
-* retained for the one remaining passthrough — `ChangelogEntryDetail.metadata`.
-*/
-type UntypedGenericJSON = unknown;
-/**
 * Node in a typed dependency graph. Mirrors `DependencyGraphNode`.
 * `registry` is a lowercase string: `"npm"`, `"pypi"`, …, or
 * `"synthetic"` for manifest / project root nodes. `version` is null
@@ -912,6 +1060,8 @@ interface PackageChangelogParams {
 	toVersion?: string;
 	/** Latest-mode cap (1–50). Rejected client-side when `fromVersion` is set. */
 	limit?: number;
+	/** Include raw markdown bodies in entries. Defaults to true. */
+	includeBodies?: boolean;
 }
 /**
 * Package-info echo from the changelog response. Mirrors
@@ -926,20 +1076,13 @@ interface ChangelogPackageInfo {
 	toVersion?: string;
 	limit?: number;
 }
-/**
-* Full changelog entry as observed on the wire. The envelope builder
-* projects this into the lean response shape; `metadata` is dropped
-* from the envelope because its source-specific opaque structure
-* isn't worth the token cost today. Revisit via agent feedback.
-*/
+/** Full changelog entry as observed on the wire. */
 interface ChangelogEntryDetail {
 	version?: string;
 	normalizedVersion?: string;
 	body?: string;
 	htmlUrl?: string;
 	publishedAt?: string;
-	/** TODO(backend): surface when shape is documented. */
-	metadata?: UntypedGenericJSON;
 }
 interface ChangelogReport {
 	/** Echo of addressing + filter as the backend saw it. */
@@ -1019,6 +1162,7 @@ interface PackageIntelligenceService {
 	packageVulnerabilities(params: PackageVulnerabilitiesParams): Promise<VulnerabilityReport>;
 	packageDependencies(params: PackageDependenciesParams): Promise<DependencyReport>;
 	packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams): Promise<DependencyReport>;
+	packageUpgradeReview(params: PackageUpgradeReviewParams): Promise<PackageUpgradeReviewResponse>;
 	packageChangelog(params: PackageChangelogParams): Promise<ChangelogReport>;
 	listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
 	readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
@@ -1045,6 +1189,8 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
 	private normaliseVulnerabilityReport;
 	packageDependencies(params: PackageDependenciesParams): Promise<DependencyReport>;
 	packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams): Promise<DependencyReport>;
+	packageUpgradeReview(params: PackageUpgradeReviewParams): Promise<PackageUpgradeReviewResponse>;
+	private executePackageUpgradeReview;
 	private executePackageUpgradeDependencyProbe;
 	private executePackageDependencies;
 	private normaliseDependencyReport;

package/dist/client.js

@@ -1 +1 @@
-import{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-95wchh8v.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};
+import{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-s6vw5w26.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};

package/dist/index.d.ts

@@ -78,6 +78,7 @@ interface TargetResolutionIdentity {
 	commitSha?: string;
 }
 type AvailableRef = AvailableVersion;
+type SuggestedRef = AvailableVersion;
 interface TargetResolution {
 	requested?: TargetResolutionIdentity;
 	resolvedRequested?: TargetResolutionIdentity;
@@ -87,6 +88,7 @@ interface TargetResolution {
 	indexingRef?: string;
 	availableVersions: AvailableVersion[];
 	availableRefs: AvailableRef[];
+	suggestedRefs?: SuggestedRef[];
 }
 type UnifiedSearchSource = "AUTO" | "DOCS" | "CODE" | "SYMBOL";
 type UnifiedSearchResultType = "DOCUMENTATION_PAGE" | "REPOSITORY_SYMBOL" | "REPOSITORY_CODE" | "REPOSITORY_DOC";
@@ -182,6 +184,7 @@ interface UnifiedSearchProgressTarget {
 	targetResolution?: TargetResolution;
 	availableVersions?: AvailableVersion[];
 	availableRefs?: AvailableRef[];
+	suggestedRefs?: SuggestedRef[];
 }
 interface UnifiedSearchRequestedTarget {
 	registry?: CodeNavigationRegistry;
@@ -428,6 +431,8 @@ interface GitHitsService {
 interface PackageSummaryParams {
 	registry: PkgseerRegistry;
 	packageName: string;
+	/** Include verbose/json-only fields such as recent advisories and changes. */
+	includeVerboseFields?: boolean;
 }
 interface PackageIdentity {
 	name: string;
@@ -530,6 +535,10 @@ interface PackageDependenciesParams {
 	version?: string;
 	/** Optional. Backend returns a full transitive graph when true. */
 	includeTransitive?: boolean;
+	/** Include transitive aggregate/detail fields beyond the dependency graph. */
+	includeTransitiveDetails?: boolean;
+	/** Include dependency group metadata. */
+	includeGroups?: boolean;
 	/**
 	* Optional transitive-traversal depth (1–10). Omit for the backend
 	* default (full graph) — note the CLI applies a 3-deep guardrail but
@@ -554,19 +563,158 @@ interface PackageUpgradeDependencyProbeParams {
 	includeDependencyChanges?: boolean;
 	includeGroups?: boolean;
 }
+interface PackageUpgradeReviewPackageParams {
+	registry: PkgseerRegistry;
+	name: string;
+	currentVersion: string;
+	targetVersion: string;
+}
+interface PackageUpgradeReviewParams {
+	packages: PackageUpgradeReviewPackageParams[];
+	includeTransitiveSecurity: boolean;
+	includeDependencyIssues: boolean;
+	changelogLimit: number;
+	minSeverity?: number;
+}
+interface PackageUpgradeAdvisorySummary {
+	id?: string;
+	aliases: string[];
+	summary?: string;
+	severity?: number;
+	severityLabel?: string;
+	fixedIn: string[];
+	isMalicious?: boolean;
+}
+interface PackageUpgradeVersionVulnerabilitySummary {
+	version: string;
+	publishedAt?: string;
+	deprecated?: boolean;
+	deprecationReason?: string;
+	affectedCount: number;
+	nonAffectingCount: number;
+	allCount: number;
+	lastModifiedAt?: string;
+	advisories: PackageUpgradeAdvisorySummary[];
+}
+interface PackageUpgradeTransitiveVulnerablePackage {
+	id: string;
+	registry: string;
+	name: string;
+	versions: string[];
+	affectedCount: number;
+	maxSeverityScore?: number;
+	maxSeverityLabel?: string;
+	advisoryIds: string[];
+}
+interface PackageUpgradeTransitivePackagePage {
+	entries: PackageUpgradeTransitiveVulnerablePackage[];
+	totalCount: number;
+	truncated: boolean;
+}
+interface PackageUpgradeTransitiveSecurity {
+	currentAffected: number;
+	targetAffected: number;
+	introducedPackages: string[];
+	fixedPackages: string[];
+	introducedPackageDetails: PackageUpgradeTransitivePackagePage;
+	fixedPackageDetails: PackageUpgradeTransitivePackagePage;
+	stillAffectedPackageDetails: PackageUpgradeTransitivePackagePage;
+}
+interface PackageUpgradeSecurity {
+	current?: PackageUpgradeVersionVulnerabilitySummary;
+	target?: PackageUpgradeVersionVulnerabilitySummary;
+	added: PackageUpgradeAdvisorySummary[];
+	removed: PackageUpgradeAdvisorySummary[];
+	notAddressed: PackageUpgradeAdvisorySummary[];
+	fixed: PackageUpgradeAdvisorySummary[];
+	introduced: PackageUpgradeAdvisorySummary[];
+	unchanged: PackageUpgradeAdvisorySummary[];
+	transitive?: PackageUpgradeTransitiveSecurity;
+}
+interface PackageUpgradeChangelogEntry {
+	version?: string;
+	publishedAt?: string;
+	htmlUrl?: string;
+	body?: string;
+	bodyPreview?: string;
+	headline?: string;
+	signals: string[];
+}
+interface PackageUpgradeChangelog {
+	source?: string;
+	fallback?: string;
+	entries: PackageUpgradeChangelogEntry[];
+	sampledEntries: PackageUpgradeChangelogEntry[];
+	keywordEntries: PackageUpgradeChangelogEntry[];
+	totalKeywordEntries: number;
+	totalEntries: number;
+	totalEntriesWithBodies: number;
+	truncated: boolean;
+	hasReleaseNoteBodies: boolean;
+	breakingSignals: string[];
+	migrationSignals: string[];
+}
+interface PackageUpgradeCompatibility {
+	peerDependencyChanges: string[];
+	notes: string[];
+}
+interface PackageUpgradeDependencyChangeItem {
+	name: string;
+	registry?: string;
+	version?: string;
+	fromVersions: string[];
+	toVersions: string[];
+	constraint?: string;
+	type?: string;
+}
+interface PackageUpgradeDependencyChangeGroup {
+	added: PackageUpgradeDependencyChangeItem[];
+	removed: PackageUpgradeDependencyChangeItem[];
+	changed: PackageUpgradeDependencyChangeItem[];
+}
+interface PackageUpgradeDependencyChanges {
+	direct: PackageUpgradeDependencyChangeGroup;
+	transitive: PackageUpgradeDependencyChangeGroup;
+}
+interface PackageUpgradeDependencyIssues {
+	currentTotal: number;
+	targetTotal: number;
+	introducedDeprecated: string[];
+	introducedDuplicates: string[];
+	introducedConflicts: string[];
+	introducedOutdated: string[];
+}
+interface PackageUpgradeReview {
+	registry: string;
+	name: string;
+	currentVersion: string;
+	targetVersion: string;
+	latestVersion?: string;
+	versionDelta: string;
+	security: PackageUpgradeSecurity;
+	changelog: PackageUpgradeChangelog;
+	compatibility?: PackageUpgradeCompatibility;
+	dependencyChanges?: PackageUpgradeDependencyChanges;
+	dependencyIssues?: PackageUpgradeDependencyIssues;
+	unknowns: string[];
+}
+interface PackageUpgradeReviewResponse {
+	summary: {
+		total: number;
+		withUnknowns: number;
+		withAddedAdvisories: number;
+		withBreakingSignals: number;
+		withDirectDependencyChanges: number;
+		withTransitiveVulnerabilityAdditions: number;
+	};
+	reviews: PackageUpgradeReview[];
+}
 interface DirectDependency {
 	name: string;
 	versionConstraint?: string;
 	type?: string;
 }
 /**
-* Opaque GenericJSON passthrough. The `package_dependencies` tool
-* migrated to typed fields (`dependencyGraph`, `dependencyConflicts`,
-* `circularDependencyCycles`, `environmentMarkers`); this type is
-* retained for the one remaining passthrough — `ChangelogEntryDetail.metadata`.
-*/
-type UntypedGenericJSON = unknown;
-/**
 * Node in a typed dependency graph. Mirrors `DependencyGraphNode`.
 * `registry` is a lowercase string: `"npm"`, `"pypi"`, …, or
 * `"synthetic"` for manifest / project root nodes. `version` is null
@@ -797,6 +945,8 @@ interface PackageChangelogParams {
 	toVersion?: string;
 	/** Latest-mode cap (1–50). Rejected client-side when `fromVersion` is set. */
 	limit?: number;
+	/** Include raw markdown bodies in entries. Defaults to true. */
+	includeBodies?: boolean;
 }
 /**
 * Package-info echo from the changelog response. Mirrors
@@ -811,20 +961,13 @@ interface ChangelogPackageInfo {
 	toVersion?: string;
 	limit?: number;
 }
-/**
-* Full changelog entry as observed on the wire. The envelope builder
-* projects this into the lean response shape; `metadata` is dropped
-* from the envelope because its source-specific opaque structure
-* isn't worth the token cost today. Revisit via agent feedback.
-*/
+/** Full changelog entry as observed on the wire. */
 interface ChangelogEntryDetail {
 	version?: string;
 	normalizedVersion?: string;
 	body?: string;
 	htmlUrl?: string;
 	publishedAt?: string;
-	/** TODO(backend): surface when shape is documented. */
-	metadata?: UntypedGenericJSON;
 }
 interface ChangelogReport {
 	/** Echo of addressing + filter as the backend saw it. */
@@ -904,12 +1047,23 @@ interface PackageIntelligenceService {
 	packageVulnerabilities(params: PackageVulnerabilitiesParams): Promise<VulnerabilityReport>;
 	packageDependencies(params: PackageDependenciesParams): Promise<DependencyReport>;
 	packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams): Promise<DependencyReport>;
+	packageUpgradeReview(params: PackageUpgradeReviewParams): Promise<PackageUpgradeReviewResponse>;
 	packageChangelog(params: PackageChangelogParams): Promise<ChangelogReport>;
 	listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
 	readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
 }
 import { z } from "zod";
 /**
+* Standard result type for all MCP tools
+*/
+type ToolResult = {
+	content: Array<{
+		type: "text";
+		text: string;
+	}>;
+	isError?: boolean;
+};
+/**
 * Zod raw shape type (what MCP SDK expects)
 */
 type ZodRawShape = {
@@ -939,12 +1093,15 @@ interface McpRequestContext<TExtra = unknown> {
 	extra: TExtra | undefined;
 }
 type McpToolServicesProvider<TExtra = unknown> = McpToolServices | ((context: McpRequestContext<TExtra>) => McpToolServices | Promise<McpToolServices>);
+/** Wraps one public MCP tool call without receiving arguments or auth data. */
+type McpToolExecutionHook = (toolName: string, runHandler: () => Promise<ToolResult>) => ToolResult | Promise<ToolResult>;
 interface CreateMcpServerOptions<TExtra = unknown> {
 	metadata: McpServerMetadata;
 	services: McpToolServicesProvider<TExtra>;
 	authAction?: McpAuthAction;
 	instructions?: string;
 	instructionOptions?: Parameters<typeof buildMcpInstructions>[0];
+	traceTool?: McpToolExecutionHook;
 }
 interface McpToolDescriptor<TSchema extends ZodRawShape = ZodRawShape> {
 	name: string;
@@ -956,9 +1113,10 @@ declare function getMcpToolDescriptors(): McpToolDescriptor[];
 declare function registerMcpTools<TExtra = unknown>(server: McpServer, options: {
 	authAction?: McpAuthAction;
 	services: McpToolServicesProvider<TExtra>;
+	traceTool?: McpToolExecutionHook;
 }): void;
 /**
 * 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, McpToolDescriptor, McpServerMetadata, McpRequestContext, McpAuthActionContext, McpAuthAction, CreateMcpServerOptions, BuildMcpInstructionsOptions };
+export { registerMcpTools, getMcpToolDescriptors, createMcpServer, buildMcpInstructions, McpToolServicesProvider, McpToolServices, McpToolExecutionHook, McpToolDescriptor, McpServerMetadata, McpRequestContext, McpAuthActionContext, McpAuthAction, CreateMcpServerOptions, BuildMcpInstructionsOptions };