/**
 * MCP Server Factory — creates an McpServer instance with all protocol tools
 * registered from the existing tool registry. Each tool invocation resolves
 * auth from the HTTP request, builds a ResolvedToolContext, and delegates
 * to the raw tool handler.
 */
import { McpServer, fromJsonSchema } from '@modelcontextprotocol/server';
import type { JsonSchemaType } from '@modelcontextprotocol/server';
import type { McpAuthResolver } from '../shared/interfaces/auth.interface.js';
import type { ToolDeps, ResolvedToolContext, RawToolDefinition } from '../shared/agent/tool.helpers.js';
import type { ToolRegistryDeps } from '../runtime/foreground/composition/tool.registry.js';
import type { McpAuthorizationObserver, McpCapabilityPolicyOptions } from './mcp.authorization-policy.js';
/**
 * Static registration metadata for one MCP tool — schema conversion artifacts
 * that depend only on registry-shaping feature flags, not on per-request
 * database scope.
 */
type McpToolRegistrationMetadata = Pick<RawToolDefinition, 'name' | 'description' | 'schema'> & {
    jsonSchema: JsonSchemaType;
    inputSchema: ReturnType<typeof fromJsonSchema>;
};
/**
 * Builds a cache key from registry-shaping dependency booleans.
 * When a feature flag changes the tool set, the cache key changes so
 * the cached metadata set is automatically invalidated.
 */
export declare function getMcpToolMetadataCacheKey(deps: Pick<ToolDeps, 'chatSession' | 'agentDatabase' | 'agentDispatcher' | 'questionerEnqueue'>): string;
/**
 * Clears the metadata cache. Used in tests to ensure fresh state between cases.
 */
export declare function clearMcpToolMetadataCacheForTests(): void;
/**
 * Returns cached (or builds and caches) static MCP tool registration metadata.
 * The first call per cache key runs the full registry creation + schema
 * conversion; subsequent calls return the cached metadata array for the same
 * registry-shaping dependency profile.
 *
 * Does NOT store tool handlers — those remain request-scoped because they
 * capture per-request userDb/systemDb.
 */
export declare function getCachedMcpToolMetadata(deps: ToolRegistryDeps): readonly McpToolRegistrationMetadata[];
/**
 * Runtime/auth failures are converted into structured MCP `isError` tool
 * results for the caller. Reporting them as application exceptions produces
 * Sentry noise for expected client failures and policy-enforced timeouts.
 */
export declare function shouldReportMcpToolError(err: unknown): boolean;
/**
 * Strips internal `_`-prefixed keys from `data` and promotes `isError`
 * from the inner `success: false` signal to the MCP envelope level.
 * Fail-open: if JSON parsing throws, returns the original text with isError: false.
 */
export declare function sanitizeMcpResult(text: string): {
    text: string;
    isError: boolean;
};
/**
 * Factory for creating per-request scoped database instances.
 * Injected from the controller/handler layer to keep the protocol layer
 * free of direct adapter imports.
 */
export interface ScopedDepsFactory {
    /** Creates scoped userDb and systemDb for the given user and allowed network IDs. */
    create(userId: string, allowedNetworkIds: string[]): Pick<ToolDeps, 'userDb' | 'systemDb'>;
}
/**
 * Promotes a network-scoped agent's bound network into the resolved tool
 * context as the implicit chat scope. Every tool derives its focused network
 * from the `scopeType`/`scopeId` envelope; without this step scoped API-key
 * calls would still resolve an unscoped/global view.
 *
 * No-op when there is no scope, or when an explicit scope is already set
 * (a user-driven network-scoped chat must keep precedence over the agent
 * binding — which would be a strict subset anyway, since the API key cannot
 * reach beyond its bound network).
 */
export declare const applyNetworkScopeToContext: (context: ResolvedToolContext, networkScopeId: string | null | undefined) => void;
export { ONBOARDING_ALLOWED } from './mcp.authorization-policy.js';
/**
 * Builds the onboarding gate message for MCP callers.  Condensed from the
 * chat orchestrator's flow (chat.prompt.ts buildOnboarding) into a
 * 6-step tool-error guide suited for non-interactive MCP clients.
 */
export declare function buildMcpOnboardingMessage(ctx: ResolvedToolContext): string;
export declare const MCP_INSTRUCTIONS: string;
/**
 * Extracts a Bearer token from an HTTP Authorization header.
 */
export declare function extractBearerToken(req: Request): string | undefined;
export declare function createMcpServer(deps: ToolRegistryDeps, authResolver: McpAuthResolver, scopedDepsFactory: ScopedDepsFactory, policyOptions?: McpCapabilityPolicyOptions, authorizationObserver?: McpAuthorizationObserver): McpServer;