api2mcp 0.3.2 → 0.4.0

package/dist/index.d.mts

@@ -9,6 +9,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * API 请求头配置
  */
 type ApiHeaders = Record<string, string>;
+/**
+ * 工作模式
+ */
+type Mode = 'default' | 'ondemand';
 /**
  * 单个 API 源配置
  */
@@ -23,6 +27,8 @@ interface ApiSourceConfig {
     headers?: ApiHeaders;
     /** 工具名前缀 */
     toolPrefix?: string;
+    /** 工作模式：default（默认）或 ondemand（按需） */
+    mode?: Mode;
 }
 /**
  * 完整配置
@@ -41,6 +47,7 @@ declare const CliArgsSchema: z.ZodObject<{
     headers: z.ZodOptional<z.ZodString>;
     prefix: z.ZodOptional<z.ZodString>;
     debug: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<["default", "ondemand"]>>;
 }, "strip", z.ZodTypeAny, {
     debug?: boolean | undefined;
     url?: string | undefined;
@@ -48,6 +55,7 @@ declare const CliArgsSchema: z.ZodObject<{
     timeout?: number | undefined;
     headers?: string | undefined;
     prefix?: string | undefined;
+    mode?: "default" | "ondemand" | undefined;
 }, {
     debug?: boolean | undefined;
     url?: string | undefined;
@@ -55,6 +63,7 @@ declare const CliArgsSchema: z.ZodObject<{
     timeout?: number | undefined;
     headers?: string | undefined;
     prefix?: string | undefined;
+    mode?: "default" | "ondemand" | undefined;
 }>;
 type CliArgs = z.infer<typeof CliArgsSchema>;
 /**
@@ -290,6 +299,208 @@ declare function parseOpenApi(source: string): Promise<ParsedOpenApiDoc>;
  */
 declare function getBaseUrl(doc: ParsedOpenApiDoc, overrideUrl?: string): string | undefined;
 
+/**
+ * Registry 类型定义
+ */
+
+/**
+ * API 条目 - 存储在 Registry 中的 API 信息
+ */
+interface ApiEntry {
+    /** 唯一标识符（通常是 operationId 或生成的 ID） */
+    id: string;
+    /** 工具名称（带前缀） */
+    name: string;
+    /** HTTP 方法 */
+    method: string;
+    /** API 路径 */
+    path: string;
+    /** 简短描述 */
+    summary?: string;
+    /** 详细描述 */
+    description?: string;
+    /** 标签 */
+    tags?: string[];
+    /** 是否废弃 */
+    deprecated?: boolean;
+    /** 原始 OpenAPI 操作定义 */
+    operation: OpenApiOperation;
+    /** 组件 Schema（用于参数解析） */
+    components?: Record<string, OpenApiSchema>;
+}
+/**
+ * 搜索选项
+ */
+interface SearchOptions {
+    /** 搜索关键词 */
+    query: string;
+    /** 搜索范围：name、summary、description、path */
+    searchIn?: ('name' | 'summary' | 'description' | 'path')[];
+    /** 最大返回数量 */
+    limit?: number;
+}
+/**
+ * 列表选项
+ */
+interface ListOptions {
+    /** 页码（从 1 开始） */
+    page?: number;
+    /** 每页数量 */
+    pageSize?: number;
+    /** 按标签过滤 */
+    tag?: string;
+}
+/**
+ * 搜索结果项
+ */
+interface SearchResultItem {
+    /** API ID */
+    id: string;
+    /** 工具名称 */
+    name: string;
+    /** HTTP 方法 */
+    method: string;
+    /** API 路径 */
+    path: string;
+    /** 简短描述 */
+    summary?: string;
+    /** 匹配字段 */
+    matchedFields: string[];
+    /** 匹配度分数（0-1） */
+    score: number;
+}
+/**
+ * 列表结果项
+ */
+interface ListItem {
+    /** API ID */
+    id: string;
+    /** 工具名称 */
+    name: string;
+    /** HTTP 方法 */
+    method: string;
+    /** API 路径 */
+    path: string;
+    /** 简短描述 */
+    summary?: string;
+    /** 标签 */
+    tags?: string[];
+    /** 是否废弃 */
+    deprecated?: boolean;
+}
+/**
+ * 分页列表结果
+ */
+interface ListResult {
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+    /** 总数量 */
+    total: number;
+    /** 总页数 */
+    totalPages: number;
+    /** API 列表 */
+    items: ListItem[];
+}
+/**
+ * API 详情
+ */
+interface ApiDetail extends ApiEntry {
+    /** 参数 Schema（JSON Schema 格式） */
+    parameterSchema?: Record<string, unknown>;
+    /** 请求体 Schema（JSON Schema 格式） */
+    requestBodySchema?: Record<string, unknown>;
+    /** 响应 Schema */
+    responseSchemas?: Record<string, {
+        description?: string;
+        schema?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Registry 统计信息
+ */
+interface RegistryStats {
+    /** API 总数 */
+    totalApis: number;
+    /** 标签列表 */
+    tags: string[];
+    /** 按方法统计 */
+    byMethod: Record<string, number>;
+    /** 按标签统计 */
+    byTag: Record<string, number>;
+}
+
+/**
+ * API 注册表
+ * 用于存储、搜索和管理 API
+ */
+
+/**
+ * API 注册表实现
+ */
+declare class ApiRegistry {
+    private apis;
+    private nameIndex;
+    private tagIndex;
+    /**
+     * 注册 API
+     */
+    register(entry: ApiEntry): void;
+    /**
+     * 批量注册 API
+     */
+    registerAll(entries: ApiEntry[]): void;
+    /**
+     * 获取单个 API
+     */
+    get(id: string): ApiEntry | undefined;
+    /**
+     * 通过名称获取 API
+     */
+    getByName(name: string): ApiEntry | undefined;
+    /**
+     * 检查 API 是否存在
+     */
+    has(id: string): boolean;
+    /**
+     * 搜索 API
+     */
+    search(options: SearchOptions): SearchResultItem[];
+    /**
+     * 分页列出 API
+     */
+    list(options?: ListOptions): ListResult;
+    /**
+     * 获取所有标签
+     */
+    getTags(): string[];
+    /**
+     * 获取 API 详情
+     */
+    getDetail(id: string): ApiDetail | undefined;
+    /**
+     * 获取统计信息
+     */
+    getStats(): RegistryStats;
+    /**
+     * 获取 API 数量
+     */
+    get size(): number;
+    /**
+     * 构建参数 Schema
+     */
+    private buildParameterSchema;
+    /**
+     * 构建请求体 Schema
+     */
+    private buildRequestBodySchema;
+    /**
+     * 构建响应 Schema
+     */
+    private buildResponseSchemas;
+}
+
 /**
  * MCP 服务器
  */
@@ -323,10 +534,27 @@ declare class ToolManager {
      * 批量注册工具
      */
     registerTools(tools: GeneratedTool[]): void;
+    /**
+     * 获取工具
+     */
+    getTool(name: string): GeneratedTool | undefined;
+    /**
+     * 通过 operationId 获取工具
+     */
+    getToolByOperationId(operationId: string): GeneratedTool | undefined;
     /**
      * 执行工具
      */
     private executeTool;
+    /**
+     * 通过 operation 直接执行（用于 ondemand 模式）
+     */
+    executeByOperation(operation: OpenApiOperation, args: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>;
     /**
      * 获取所有已注册的工具名称
      */
@@ -335,8 +563,188 @@ declare class ToolManager {
      * 获取工具数量
      */
     getToolCount(): number;
+    /**
+     * 获取配置
+     */
+    getConfig(): Config;
 }
 
+/**
+ * api_detail 工具
+ * 获取 API 详情
+ */
+
+/**
+ * 输入参数 Schema
+ */
+declare const apiDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+type ApiDetailInput = z.infer<typeof apiDetailSchema>;
+/**
+ * 工具定义
+ */
+declare const apiDetailTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+    }, {
+        id: string;
+    }>;
+};
+/**
+ * 执行 api_detail 工具
+ */
+declare function executeApiDetail(registry: ApiRegistry, input: ApiDetailInput): string;
+
+/**
+ * api_execute 工具
+ * 直接执行 API 调用
+ */
+
+/**
+ * 输入参数 Schema
+ */
+declare const apiExecuteSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    _baseUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    operationId: string;
+    _baseUrl?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}, {
+    operationId: string;
+    _baseUrl?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}>;
+type ApiExecuteInput = z.infer<typeof apiExecuteSchema>;
+/**
+ * 工具定义
+ */
+declare const apiExecuteTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        operationId: z.ZodString;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        _baseUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        operationId: string;
+        _baseUrl?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }, {
+        operationId: string;
+        _baseUrl?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }>;
+};
+/**
+ * 执行 api_execute 工具
+ */
+declare function executeApiExecute(registry: ApiRegistry, config: Config, input: ApiExecuteInput): Promise<string>;
+
+/**
+ * api_list 工具
+ * 分页浏览所有 API
+ */
+
+/**
+ * 输入参数 Schema
+ */
+declare const apiListSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+    tag: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    pageSize: number;
+    tag?: string | undefined;
+}, {
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    tag?: string | undefined;
+}>;
+type ApiListInput = z.infer<typeof apiListSchema>;
+/**
+ * 工具定义
+ */
+declare const apiListTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        page: z.ZodDefault<z.ZodNumber>;
+        pageSize: z.ZodDefault<z.ZodNumber>;
+        tag: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        page: number;
+        pageSize: number;
+        tag?: string | undefined;
+    }, {
+        page?: number | undefined;
+        pageSize?: number | undefined;
+        tag?: string | undefined;
+    }>;
+};
+/**
+ * 执行 api_list 工具
+ */
+declare function executeApiList(registry: ApiRegistry, input: ApiListInput): string;
+
+/**
+ * api_search 工具
+ * 模糊搜索 API
+ */
+
+/**
+ * 输入参数 Schema
+ */
+declare const apiSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    searchIn: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<["name", "summary", "description", "path"]>, "many">>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    searchIn: ("path" | "description" | "name" | "summary")[];
+    limit: number;
+}, {
+    query: string;
+    searchIn?: ("path" | "description" | "name" | "summary")[] | undefined;
+    limit?: number | undefined;
+}>;
+type ApiSearchInput = z.infer<typeof apiSearchSchema>;
+/**
+ * 工具定义
+ */
+declare const apiSearchTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        query: z.ZodString;
+        searchIn: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<["name", "summary", "description", "path"]>, "many">>>;
+        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+        searchIn: ("path" | "description" | "name" | "summary")[];
+        limit: number;
+    }, {
+        query: string;
+        searchIn?: ("path" | "description" | "name" | "summary")[] | undefined;
+        limit?: number | undefined;
+    }>;
+};
+/**
+ * 执行 api_search 工具
+ */
+declare function executeApiSearch(registry: ApiRegistry, input: ApiSearchInput): string;
+
 /**
  * 错误类定义
  */
@@ -375,4 +783,4 @@ interface Logger {
 }
 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 };
+export { Api2McpError, type ApiDetail, type ApiDetailInput, type ApiEntry, type ApiExecuteInput, type ApiHeaders, type ApiListInput, ApiRegistry, type ApiSearchInput, type ApiSourceConfig, type Config, ConfigurationError, type GeneratedTool, HttpError, type HttpResponse, type ListItem, type ListOptions, type ListResult, type Mode, type OpenApiOperation, type OpenApiParameter, OpenApiParseError, type OpenApiSchema, type ParsedOpenApiDoc, type RegistryStats, type SearchOptions, type SearchResultItem, ToolExecutionError, ToolManager, apiDetailSchema, apiDetailTool, apiExecuteSchema, apiExecuteTool, apiListSchema, apiListTool, apiSearchSchema, apiSearchTool, convertSchema, createRefResolver, createServer, executeApiDetail, executeApiExecute, executeApiList, executeApiSearch, executeRequest, formatResponse, generateTool, generateTools, getBaseUrl, loadConfig, logger, parseOpenApi, startServer };