import type { CallToolResult } from '@modelcontextprotocol/server';
import type { ScapiSchemaDocument } from '@salesforce/b2c-tooling-sdk/scapi';
import type { z, ZodRawShape } from 'zod';
import type { Toolset } from './constants.js';
/**
 * Result returned from MCP tool execution.
 * Matches the MCP SDK's CallToolResult type.
 */
export type ToolResult = CallToolResult;
/** Protocol input stays separate from model-supplied tool arguments. */
export interface ToolContext {
    signal?: AbortSignal;
    requestState?: unknown;
    inputResponses?: Record<string, unknown>;
    supportsElicitation?: boolean;
    /** Legacy elicitation keeps the originating request open between handler entries. */
    keepCancellation?: boolean;
    /** Record content returned to the client; sent as CONTENT_READ telemetry when the call succeeds. */
    recordContentRead?: (read: ContentRead) => void;
}
/** Identifies a skill file, doc, or schema returned to the client. Never includes queries. */
export interface ContentRead {
    contentType: 'doc' | 'schema' | 'skill';
    /** Skill entry ID (`mcp/b2c-mcp-cip`), doc ID, or schema ID. */
    contentId: string;
    /** Skill file URI. */
    contentUri?: string;
    /** Doc category. */
    category?: string;
    /** Requested skill section. */
    section?: string;
    /** Paging offset; nonzero for continuation reads. */
    offset?: number;
}
/** Effects of advertised operations; annotations are derived at registration. */
export interface ToolEffects {
    effect: 'destructive' | 'read' | 'write';
    /** Repeating the same arguments causes no additional effects, even if results differ. */
    idempotent: boolean;
    /** Interacts with external entities rather than only a bounded local domain. */
    openWorld: boolean;
}
/**
 * Configuration for an MCP tool.
 */
export interface McpToolConfig<T extends ZodRawShape = ZodRawShape> extends ToolEffects {
    /** Tool name (used in MCP protocol) */
    name: string;
    /** Human-readable description */
    description: string;
    /** Optional display title and object-root result schema. */
    title?: string;
    outputSchema?: ZodRawShape;
    /** Zod schema for input validation */
    inputSchema: T;
    /** Toolsets this tool belongs to */
    toolsets: Toolset[];
    /**
     * Load this tool's schema at session start instead of behind client tool search.
     * Reserve for the few entry points nearly every session uses; each costs context upfront.
     */
    alwaysLoad?: boolean;
    /**
     * Extra words Claude Code's tool search matches (synonyms, task phrasing) without sending them to the model.
     * Put vocabulary here when only search needs it; descriptions are paid for in every listing.
     */
    searchHint?: string;
}
/**
 * MCP Tool definition with handler.
 */
export interface McpTool<T extends ZodRawShape = ZodRawShape> extends McpToolConfig<T> {
    /** Handler function that executes the tool */
    handler: (args: z.infer<z.ZodObject<T>>, context?: ToolContext) => Promise<ToolResult>;
}
/**
 * Startup flags passed to the MCP server.
 */
export interface StartupFlags {
    /** Comma-separated list of toolsets to enable */
    toolsets?: string[];
    /** Specific individual tools to enable */
    tools?: string[];
    /** Path to config file (dw.json format) */
    configPath?: string;
    /** Default project directory for configuration and project operations. */
    projectDirectory?: string;
    /**
     * Comma-separated allowlist of documentation categories the docs tools may
     * expose (from `--docs-topics` / `SFCC_DOCS_TOPICS`). Bounds the whole docs
     * corpus at startup; unset means all categories.
     */
    docsTopics?: string;
    /**
     * Developer-supplied SCAPI contracts loaded from `--scapi-schemas` / `SFCC_SCAPI_SCHEMAS`.
     * They replace bundled and live contracts with the same id in scapi_search and scapi_execute.
     */
    scapiSchemas?: readonly ScapiSchemaDocument[];
}