api2mcp 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * 配置类型定义
+ */
+
+/**
+ * API 请求头配置
+ */
+type ApiHeaders = Record<string, string>;
+/**
+ * 单个 API 源配置
+ */
+interface ApiSourceConfig {
+    /** OpenAPI 文档 URL 或本地文件路径 */
+    openapiUrl: string;
+    /** API 基础 URL（可选，默认从 OpenAPI 文档中提取） */
+    baseUrl?: string;
+    /** 请求超时时间（毫秒） */
+    timeout?: number;
+    /** 自定义请求头 */
+    headers?: ApiHeaders;
+    /** 工具名前缀 */
+    toolPrefix?: string;
+}
+/**
+ * 完整配置
+ */
+interface Config extends ApiSourceConfig {
+    /** 调试模式 */
+    debug: boolean;
+}
+/**
+ * CLI 参数 Schema
+ */
+declare const CliArgsSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    headers: z.ZodOptional<z.ZodString>;
+    prefix: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    debug?: boolean | undefined;
+    url?: string | undefined;
+    baseUrl?: string | undefined;
+    timeout?: number | undefined;
+    headers?: string | undefined;
+    prefix?: string | undefined;
+}, {
+    debug?: boolean | undefined;
+    url?: string | undefined;
+    baseUrl?: string | undefined;
+    timeout?: number | undefined;
+    headers?: string | undefined;
+    prefix?: string | undefined;
+}>;
+type CliArgs = z.infer<typeof CliArgsSchema>;
+/**
+ * 环境变量配置
+ */
+interface EnvConfig {
+    OPENAPI_URL?: string;
+    API_BASE_URL?: string;
+    API_TIMEOUT?: string;
+    API_HEADERS?: string;
+    DEBUG?: string;
+}
+
+/**
+ * 配置加载器
+ * 优先级: CLI 参数 > 环境变量 > 配置文件
+ */
+
+/**
+ * 加载配置
+ * 优先级: CLI 参数 > 环境变量 > 配置文件
+ */
+declare function loadConfig(cliArgs?: CliArgs, env?: EnvConfig): Config;
+
+/**
+ * OpenAPI 类型定义
+ */
+/**
+ * OpenAPI 参数位置
+ */
+type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
+/**
+ * OpenAPI 参数
+ */
+interface OpenApiParameter {
+    name: string;
+    in: ParameterLocation;
+    required?: boolean;
+    description?: string;
+    schema?: OpenApiSchema;
+    deprecated?: boolean;
+}
+/**
+ * OpenAPI Schema
+ */
+interface OpenApiSchema {
+    type?: string;
+    format?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    const?: unknown;
+    items?: OpenApiSchema;
+    properties?: Record<string, OpenApiSchema>;
+    additionalProperties?: boolean | OpenApiSchema;
+    required?: string[];
+    oneOf?: OpenApiSchema[];
+    anyOf?: OpenApiSchema[];
+    allOf?: OpenApiSchema[];
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: boolean | number;
+    exclusiveMaximum?: boolean | number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    nullable?: boolean;
+    deprecated?: boolean;
+    example?: unknown;
+    $ref?: string;
+}
+/**
+ * OpenAPI 请求体
+ */
+interface OpenApiRequestBody {
+    description?: string;
+    required?: boolean;
+    content: Record<string, {
+        schema?: OpenApiSchema;
+        example?: unknown;
+        examples?: Record<string, unknown>;
+    }>;
+}
+/**
+ * OpenAPI 响应
+ */
+interface OpenApiResponse {
+    description?: string;
+    content?: Record<string, {
+        schema?: OpenApiSchema;
+        example?: unknown;
+    }>;
+}
+/**
+ * OpenAPI 操作
+ */
+interface OpenApiOperation {
+    /** HTTP 方法 */
+    method: string;
+    /** API 路径 */
+    path: string;
+    /** 操作 ID */
+    operationId?: string;
+    /** 摘要 */
+    summary?: string;
+    /** 详细描述 */
+    description?: string;
+    /** 标签 */
+    tags?: string[];
+    /** 参数列表 */
+    parameters?: OpenApiParameter[];
+    /** 请求体 */
+    requestBody?: OpenApiRequestBody;
+    /** 响应 */
+    responses?: Record<string, OpenApiResponse>;
+    /** 是否废弃 */
+    deprecated?: boolean;
+}
+/**
+ * OpenAPI 文档信息
+ */
+interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+}
+/**
+ * OpenAPI 服务器
+ */
+interface OpenApiServer {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        enum?: string[];
+        description?: string;
+    }>;
+}
+/**
+ * 解析后的 OpenAPI 文档
+ */
+interface ParsedOpenApiDoc {
+    openapi: string;
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    operations: OpenApiOperation[];
+    components?: {
+        schemas?: Record<string, OpenApiSchema>;
+        parameters?: Record<string, OpenApiParameter>;
+        requestBodies?: Record<string, OpenApiRequestBody>;
+        responses?: Record<string, OpenApiResponse>;
+    };
+}
+
+/**
+ * OpenAPI Schema 到 Zod Schema 转换器
+ */
+
+/**
+ * Schema 引用解析函数类型
+ */
+type RefResolver = (ref: string) => OpenApiSchema | undefined;
+/**
+ * 将 OpenAPI Schema 转换为 Zod Schema
+ */
+declare function convertSchema(schema: OpenApiSchema | undefined, refResolver?: RefResolver): z.ZodType;
+/**
+ * 创建引用解析器
+ */
+declare function createRefResolver(components: Record<string, OpenApiSchema> | undefined): RefResolver;
+
+/**
+ * MCP 工具生成器
+ */
+
+/**
+ * 生成的工具定义
+ */
+interface GeneratedTool {
+    /** 工具名称 */
+    name: string;
+    /** 工具描述 */
+    description: string;
+    /** 输入参数 Schema */
+    inputSchema: z.ZodObject<z.ZodRawShape>;
+    /** 原始操作定义 */
+    operation: OpenApiOperation;
+}
+/**
+ * 从 OpenAPI 操作生成 MCP 工具
+ */
+declare function generateTool(operation: OpenApiOperation, components?: Record<string, OpenApiSchema>, toolPrefix?: string): GeneratedTool;
+/**
+ * 批量生成工具
+ */
+declare function generateTools(operations: OpenApiOperation[], components?: Record<string, OpenApiSchema>, toolPrefix?: string): GeneratedTool[];
+
+/**
+ * HTTP 客户端
+ */
+
+/**
+ * HTTP 响应
+ */
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+/**
+ * 执行 HTTP 请求
+ */
+declare function executeRequest(operation: OpenApiOperation, input: Record<string, unknown>, config: Config): Promise<HttpResponse>;
+/**
+ * 格式化响应为字符串
+ */
+declare function formatResponse(response: HttpResponse): string;
+
+/**
+ * OpenAPI 解析器
+ */
+
+/**
+ * 解析 OpenAPI 文档
+ */
+declare function parseOpenApi(source: string): Promise<ParsedOpenApiDoc>;
+/**
+ * 获取基础 URL
+ */
+declare function getBaseUrl(doc: ParsedOpenApiDoc, overrideUrl?: string): string;
+
+/**
+ * MCP 服务器
+ */
+
+/**
+ * 创建并启动 MCP 服务器
+ */
+declare function createServer(config: Config): Promise<McpServer>;
+/**
+ * 启动服务器（使用 stdio 传输）
+ */
+declare function startServer(config: Config): Promise<void>;
+
+/**
+ * MCP 工具管理器
+ */
+
+/**
+ * 工具管理器
+ */
+declare class ToolManager {
+    private tools;
+    private config;
+    private server;
+    constructor(server: McpServer, config: Config);
+    /**
+     * 注册工具
+     */
+    registerTool(tool: GeneratedTool): void;
+    /**
+     * 批量注册工具
+     */
+    registerTools(tools: GeneratedTool[]): void;
+    /**
+     * 执行工具
+     */
+    private executeTool;
+    /**
+     * 获取所有已注册的工具名称
+     */
+    getToolNames(): string[];
+    /**
+     * 获取工具数量
+     */
+    getToolCount(): number;
+}
+
+/**
+ * 错误类定义
+ */
+declare class Api2McpError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+declare class ConfigurationError extends Api2McpError {
+    constructor(message: string, cause?: Error);
+}
+declare class OpenApiParseError extends Api2McpError {
+    constructor(message: string, cause?: Error);
+}
+declare class ToolExecutionError extends Api2McpError {
+    readonly toolName: string;
+    constructor(message: string, toolName: string, cause?: Error);
+}
+declare class HttpError extends Api2McpError {
+    readonly statusCode: number;
+    readonly responseBody?: string | undefined;
+    constructor(message: string, statusCode: number, responseBody?: string | undefined, cause?: Error);
+}
+
+/**
+ * 简单日志工具
+ * 所有日志输出到 stderr，避免干扰 MCP stdio 协议
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    setLevel: (level: LogLevel) => void;
+}
+declare const logger: Logger;
+
+export { Api2McpError, type ApiHeaders, type ApiSourceConfig, type Config, ConfigurationError, type GeneratedTool, HttpError, type HttpResponse, type OpenApiOperation, type OpenApiParameter, OpenApiParseError, type OpenApiSchema, type ParsedOpenApiDoc, ToolExecutionError, ToolManager, convertSchema, createRefResolver, createServer, executeRequest, formatResponse, generateTool, generateTools, getBaseUrl, loadConfig, logger, parseOpenApi, startServer };