api2mcp 0.3.2 → 0.4.0-beta.0

package/dist/index.js

@@ -31,14 +31,27 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Api2McpError: () => Api2McpError,
+  ApiRegistry: () => ApiRegistry,
   ConfigurationError: () => ConfigurationError,
   HttpError: () => HttpError,
   OpenApiParseError: () => OpenApiParseError,
   ToolExecutionError: () => ToolExecutionError,
   ToolManager: () => ToolManager,
+  apiDetailSchema: () => apiDetailSchema,
+  apiDetailTool: () => apiDetailTool,
+  apiExecuteSchema: () => apiExecuteSchema,
+  apiExecuteTool: () => apiExecuteTool,
+  apiListSchema: () => apiListSchema,
+  apiListTool: () => apiListTool,
+  apiSearchSchema: () => apiSearchSchema,
+  apiSearchTool: () => apiSearchTool,
   convertSchema: () => convertSchema,
   createRefResolver: () => createRefResolver,
   createServer: () => createServer,
+  executeApiDetail: () => executeApiDetail,
+  executeApiExecute: () => executeApiExecute,
+  executeApiList: () => executeApiList,
+  executeApiSearch: () => executeApiSearch,
   executeRequest: () => executeRequest,
   formatResponse: () => formatResponse,
   generateTool: () => generateTool,
@@ -186,7 +199,8 @@ function loadFromFile(workingDir = process.cwd()) {
           timeout: parsed.timeout,
           headers: parsed.headers,
           toolPrefix: parsed.toolPrefix,
-          debug: parsed.debug
+          debug: parsed.debug,
+          mode: parsed.mode
         };
       } catch (error) {
         throw new ConfigurationError(
@@ -217,6 +231,9 @@ function loadFromCli(args) {
   if (args.debug !== void 0) {
     config.debug = args.debug;
   }
+  if (args.mode) {
+    config.mode = args.mode;
+  }
   return config;
 }
 function mergeConfigs(...configs) {
@@ -231,6 +248,7 @@ function mergeConfigs(...configs) {
     if (config.headers !== void 0) merged.headers = config.headers;
     if (config.toolPrefix !== void 0) merged.toolPrefix = config.toolPrefix;
     if (config.debug !== void 0) merged.debug = config.debug;
+    if (config.mode !== void 0) merged.mode = config.mode;
   }
   if (merged.timeout === void 0) {
     merged.timeout = DEFAULT_TIMEOUT;
@@ -255,6 +273,7 @@ function loadConfig(cliArgs = {}, env = process.env) {
     baseUrl: config.baseUrl,
     timeout: config.timeout,
     toolPrefix: config.toolPrefix,
+    mode: config.mode,
     debug: config.debug
   });
   return config;
@@ -903,10 +922,572 @@ function getBaseUrl(doc, overrideUrl) {
   return void 0;
 }
 
+// src/registry/api-registry.ts
+var DEFAULT_PAGE_SIZE = 20;
+var DEFAULT_SEARCH_LIMIT = 50;
+var ApiRegistry = class {
+  apis = /* @__PURE__ */ new Map();
+  nameIndex = /* @__PURE__ */ new Map();
+  // name -> id
+  tagIndex = /* @__PURE__ */ new Map();
+  // tag -> set of ids
+  /**
+   * 注册 API
+   */
+  register(entry) {
+    if (this.apis.has(entry.id)) {
+      logger.warn(`API already registered: ${entry.id}, overwriting`);
+    }
+    this.apis.set(entry.id, entry);
+    this.nameIndex.set(entry.name, entry.id);
+    if (entry.tags) {
+      for (const tag of entry.tags) {
+        if (!this.tagIndex.has(tag)) {
+          this.tagIndex.set(tag, /* @__PURE__ */ new Set());
+        }
+        this.tagIndex.get(tag)?.add(entry.id);
+      }
+    }
+    logger.debug(`Registered API: ${entry.id}`);
+  }
+  /**
+   * 批量注册 API
+   */
+  registerAll(entries) {
+    for (const entry of entries) {
+      this.register(entry);
+    }
+    logger.info(`Registered ${entries.length} APIs in registry`);
+  }
+  /**
+   * 获取单个 API
+   */
+  get(id) {
+    return this.apis.get(id);
+  }
+  /**
+   * 通过名称获取 API
+   */
+  getByName(name) {
+    const id = this.nameIndex.get(name);
+    return id ? this.apis.get(id) : void 0;
+  }
+  /**
+   * 检查 API 是否存在
+   */
+  has(id) {
+    return this.apis.has(id);
+  }
+  /**
+   * 搜索 API
+   */
+  search(options) {
+    const {
+      query,
+      searchIn = ["name", "summary", "description", "path"],
+      limit = DEFAULT_SEARCH_LIMIT
+    } = options;
+    const normalizedQuery = query.toLowerCase().trim();
+    const results = [];
+    for (const entry of this.apis.values()) {
+      const matchedFields = [];
+      let score = 0;
+      if (searchIn.includes("name") && entry.name) {
+        const nameLower = entry.name.toLowerCase();
+        if (nameLower.includes(normalizedQuery)) {
+          matchedFields.push("name");
+          score += nameLower === normalizedQuery ? 1 : 0.8;
+        }
+      }
+      if (searchIn.includes("summary") && entry.summary) {
+        const summaryLower = entry.summary.toLowerCase();
+        if (summaryLower.includes(normalizedQuery)) {
+          matchedFields.push("summary");
+          score += 0.6;
+        }
+      }
+      if (searchIn.includes("description") && entry.description) {
+        const descLower = entry.description.toLowerCase();
+        if (descLower.includes(normalizedQuery)) {
+          matchedFields.push("description");
+          score += 0.4;
+        }
+      }
+      if (searchIn.includes("path") && entry.path) {
+        const pathLower = entry.path.toLowerCase();
+        if (pathLower.includes(normalizedQuery)) {
+          matchedFields.push("path");
+          score += 0.5;
+        }
+      }
+      if (matchedFields.length > 0) {
+        results.push({
+          id: entry.id,
+          name: entry.name,
+          method: entry.method,
+          path: entry.path,
+          summary: entry.summary,
+          matchedFields,
+          score: Math.min(score, 1)
+        });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+  }
+  /**
+   * 分页列出 API
+   */
+  list(options = {}) {
+    const { page = 1, pageSize = DEFAULT_PAGE_SIZE, tag } = options;
+    let entries;
+    if (tag) {
+      const ids = this.tagIndex.get(tag);
+      entries = ids ? Array.from(ids).map((id) => this.apis.get(id)).filter((entry) => entry !== void 0) : [];
+    } else {
+      entries = Array.from(this.apis.values());
+    }
+    const total = entries.length;
+    const totalPages = Math.ceil(total / pageSize);
+    const startIndex = (page - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    const pageEntries = entries.slice(startIndex, endIndex);
+    const items = pageEntries.map((entry) => ({
+      id: entry.id,
+      name: entry.name,
+      method: entry.method,
+      path: entry.path,
+      summary: entry.summary,
+      tags: entry.tags,
+      deprecated: entry.deprecated
+    }));
+    return {
+      page,
+      pageSize,
+      total,
+      totalPages,
+      items
+    };
+  }
+  /**
+   * 获取所有标签
+   */
+  getTags() {
+    return Array.from(this.tagIndex.keys()).sort();
+  }
+  /**
+   * 获取 API 详情
+   */
+  getDetail(id) {
+    const entry = this.apis.get(id);
+    if (!entry) {
+      return void 0;
+    }
+    return {
+      ...entry,
+      parameterSchema: this.buildParameterSchema(entry),
+      requestBodySchema: this.buildRequestBodySchema(entry),
+      responseSchemas: this.buildResponseSchemas(entry)
+    };
+  }
+  /**
+   * 获取统计信息
+   */
+  getStats() {
+    const byMethod = {};
+    const byTag = {};
+    for (const entry of this.apis.values()) {
+      const method = entry.method.toUpperCase();
+      byMethod[method] = (byMethod[method] || 0) + 1;
+      if (entry.tags) {
+        for (const tag of entry.tags) {
+          byTag[tag] = (byTag[tag] || 0) + 1;
+        }
+      }
+    }
+    return {
+      totalApis: this.apis.size,
+      tags: this.getTags(),
+      byMethod,
+      byTag
+    };
+  }
+  /**
+   * 获取 API 数量
+   */
+  get size() {
+    return this.apis.size;
+  }
+  /**
+   * 构建参数 Schema
+   */
+  buildParameterSchema(entry) {
+    const { operation } = entry;
+    if (!operation.parameters || operation.parameters.length === 0) {
+      return void 0;
+    }
+    const properties = {};
+    const required = [];
+    for (const param of operation.parameters) {
+      const paramName = param.name;
+      properties[paramName] = {
+        ...param.schema,
+        description: param.description,
+        in: param.in
+      };
+      if (param.required) {
+        required.push(paramName);
+      }
+    }
+    return {
+      type: "object",
+      properties,
+      required: required.length > 0 ? required : void 0
+    };
+  }
+  /**
+   * 构建请求体 Schema
+   */
+  buildRequestBodySchema(entry) {
+    const { operation } = entry;
+    if (!operation.requestBody) {
+      return void 0;
+    }
+    const jsonContent = operation.requestBody.content["application/json"];
+    if (!jsonContent?.schema) {
+      return void 0;
+    }
+    return {
+      ...jsonContent.schema,
+      description: operation.requestBody.description,
+      required: operation.requestBody.required
+    };
+  }
+  /**
+   * 构建响应 Schema
+   */
+  buildResponseSchemas(entry) {
+    const { operation } = entry;
+    if (!operation.responses) {
+      return void 0;
+    }
+    const schemas = {};
+    for (const [status, response] of Object.entries(operation.responses)) {
+      const jsonContent = response.content?.["application/json"];
+      schemas[status] = {
+        description: response.description,
+        schema: jsonContent?.schema
+      };
+    }
+    return schemas;
+  }
+};
+
 // src/server/index.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
+// src/tools/discovery/api-detail.ts
+var import_zod3 = require("zod");
+var apiDetailSchema = import_zod3.z.object({
+  id: import_zod3.z.string().min(1).describe("API ID\uFF08operationId \u6216\u5DE5\u5177\u540D\u79F0\uFF09")
+});
+var apiDetailTool = {
+  name: "api_detail",
+  description: `\u83B7\u53D6 API \u7684\u8BE6\u7EC6\u4FE1\u606F\u3002
+
+\u4F7F\u7528\u573A\u666F\uFF1A
+- \u67E5\u770B\u67D0\u4E2A API \u7684\u5B8C\u6574\u53C2\u6570\u5B9A\u4E49
+- \u4E86\u89E3\u8BF7\u6C42\u4F53\u548C\u54CD\u5E94\u7684\u7ED3\u6784
+- \u5728\u8C03\u7528 API \u524D\u4E86\u89E3\u9700\u8981\u54EA\u4E9B\u53C2\u6570
+
+\u8FD4\u56DE\u5185\u5BB9\u5305\u62EC\uFF1A
+- API \u57FA\u672C\u4FE1\u606F\uFF08\u65B9\u6CD5\u3001\u8DEF\u5F84\u3001\u63CF\u8FF0\uFF09
+- \u53C2\u6570 Schema\uFF08\u8DEF\u5F84\u53C2\u6570\u3001\u67E5\u8BE2\u53C2\u6570\u3001\u5934\u53C2\u6570\uFF09
+- \u8BF7\u6C42\u4F53 Schema
+- \u54CD\u5E94 Schema`,
+  inputSchema: apiDetailSchema
+};
+function formatSchema(schema, indent = 0) {
+  if (!schema) return "\u65E0";
+  const spaces = "  ".repeat(indent);
+  const lines = [];
+  if (schema.type) {
+    lines.push(`${spaces}\u7C7B\u578B: ${schema.type}`);
+  }
+  if (schema.description) {
+    lines.push(`${spaces}\u63CF\u8FF0: ${schema.description}`);
+  }
+  if (schema.properties) {
+    lines.push(`${spaces}\u5C5E\u6027:`);
+    const props = schema.properties;
+    const required = schema.required || [];
+    for (const [name, prop] of Object.entries(props)) {
+      const isRequired = required.includes(name);
+      const reqTag = isRequired ? " (\u5FC5\u586B)" : " (\u53EF\u9009)";
+      const propType = prop.type || "unknown";
+      const propDesc = prop.description ? ` - ${prop.description}` : "";
+      lines.push(`${spaces}  - ${name}${reqTag}: ${propType}${propDesc}`);
+      if (prop.properties) {
+        lines.push(formatSchema(prop, indent + 2));
+      }
+    }
+  }
+  if (schema.enum) {
+    lines.push(`${spaces}\u679A\u4E3E\u503C: ${schema.enum.join(", ")}`);
+  }
+  if (schema.example !== void 0) {
+    lines.push(`${spaces}\u793A\u4F8B: ${JSON.stringify(schema.example)}`);
+  }
+  return lines.join("\n");
+}
+function executeApiDetail(registry, input) {
+  const { id } = input;
+  logger.debug(`Executing api_detail: id=${id}`);
+  const detail = registry.getDetail(id);
+  if (!detail) {
+    const byName = registry.getByName(id);
+    if (byName) {
+      return executeApiDetail(registry, { id: byName.id });
+    }
+    return `\u9519\u8BEF: \u627E\u4E0D\u5230 API "${id}"
+
+\u8BF7\u4F7F\u7528 api_search \u641C\u7D22\u53EF\u7528\u7684 API\u3002`;
+  }
+  const lines = [];
+  lines.push(`## API: ${detail.name}`);
+  lines.push("");
+  const methodBadge = `[${detail.method.toUpperCase()}]`;
+  const deprecatedTag = detail.deprecated ? " \u26A0\uFE0F \u5DF2\u5E9F\u5F03" : "";
+  lines.push(`**${methodBadge}** \`${detail.path}\`${deprecatedTag}`);
+  lines.push("");
+  if (detail.summary) {
+    lines.push(`**\u6458\u8981**: ${detail.summary}`);
+    lines.push("");
+  }
+  if (detail.description) {
+    lines.push(`**\u63CF\u8FF0**: ${detail.description}`);
+    lines.push("");
+  }
+  if (detail.tags && detail.tags.length > 0) {
+    lines.push(`**\u6807\u7B7E**: ${detail.tags.map((t) => `\`${t}\``).join(", ")}`);
+    lines.push("");
+  }
+  lines.push("### \u53C2\u6570");
+  lines.push("");
+  if (detail.parameterSchema) {
+    lines.push(formatSchema(detail.parameterSchema));
+  } else {
+    lines.push("\u65E0\u53C2\u6570");
+  }
+  lines.push("");
+  if (detail.requestBodySchema) {
+    lines.push("### \u8BF7\u6C42\u4F53");
+    lines.push("");
+    lines.push(formatSchema(detail.requestBodySchema));
+    lines.push("");
+  }
+  if (detail.responseSchemas && Object.keys(detail.responseSchemas).length > 0) {
+    lines.push("### \u54CD\u5E94");
+    lines.push("");
+    for (const [status, resp] of Object.entries(detail.responseSchemas)) {
+      lines.push(`#### \u72B6\u6001\u7801: ${status}`);
+      if (resp.description) {
+        lines.push(`${resp.description}`);
+      }
+      if (resp.schema) {
+        lines.push(formatSchema(resp.schema, 1));
+      }
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push("### \u8C03\u7528\u65B9\u5F0F");
+  lines.push("");
+  lines.push("\u4F7F\u7528 api_execute \u5DE5\u5177\u8C03\u7528\u6B64 API:");
+  lines.push("```");
+  lines.push(`api_execute(operationId="${detail.id}", parameters={...})`);
+  lines.push("```");
+  return lines.join("\n");
+}
+
+// src/tools/discovery/api-execute.ts
+var import_zod4 = require("zod");
+var apiExecuteSchema = import_zod4.z.object({
+  operationId: import_zod4.z.string().min(1).describe("API ID\uFF08operationId \u6216\u5DE5\u5177\u540D\u79F0\uFF09"),
+  parameters: import_zod4.z.record(import_zod4.z.unknown()).optional().describe("API \u53C2\u6570\uFF08\u8DEF\u5F84\u53C2\u6570\u3001\u67E5\u8BE2\u53C2\u6570\u3001\u8BF7\u6C42\u4F53\u7B49\uFF09"),
+  _baseUrl: import_zod4.z.string().url().optional().describe("API base URL\uFF08\u53EF\u9009\uFF0C\u8986\u76D6\u9ED8\u8BA4\u914D\u7F6E\uFF09")
+});
+var apiExecuteTool = {
+  name: "api_execute",
+  description: `\u6267\u884C API \u8C03\u7528\u3002
+
+\u4F7F\u7528\u573A\u666F\uFF1A
+- \u76F4\u63A5\u8C03\u7528\u5DF2\u77E5\u7684 API
+- \u4F7F\u7528 api_search \u6216 api_list \u627E\u5230 API \u540E\u6267\u884C\u8C03\u7528
+
+\u4F7F\u7528\u6B65\u9AA4\uFF1A
+1. \u5148\u4F7F\u7528 api_search \u6216 api_list \u627E\u5230\u9700\u8981\u7684 API
+2. \u4F7F\u7528 api_detail \u67E5\u770B\u53C2\u6570\u8981\u6C42
+3. \u4F7F\u7528 api_execute \u6267\u884C\u8C03\u7528
+
+\u53C2\u6570\u8BF4\u660E\uFF1A
+- operationId: API \u7684\u552F\u4E00\u6807\u8BC6\u7B26
+- parameters: \u5305\u542B\u8DEF\u5F84\u53C2\u6570\u3001\u67E5\u8BE2\u53C2\u6570\u3001\u8BF7\u6C42\u4F53\u7B49
+  - \u8DEF\u5F84\u53C2\u6570: URL \u8DEF\u5F84\u4E2D\u7684\u53C2\u6570 (\u5982 /users/{id} \u4E2D\u7684 id)
+  - \u67E5\u8BE2\u53C2\u6570: URL \u95EE\u53F7\u540E\u7684\u53C2\u6570
+  - body: \u8BF7\u6C42\u4F53\uFF08JSON \u5BF9\u8C61\uFF09`,
+  inputSchema: apiExecuteSchema
+};
+async function executeApiExecute(registry, config, input) {
+  const { operationId, parameters = {}, _baseUrl } = input;
+  logger.debug(`Executing api_execute: operationId=${operationId}`);
+  let apiEntry = registry.get(operationId);
+  if (!apiEntry) {
+    apiEntry = registry.getByName(operationId);
+  }
+  if (!apiEntry) {
+    return `\u9519\u8BEF: \u627E\u4E0D\u5230 API "${operationId}"
+
+\u8BF7\u4F7F\u7528 api_search \u641C\u7D22\u53EF\u7528\u7684 API\u3002`;
+  }
+  if (apiEntry.deprecated) {
+    logger.warn(`API ${operationId} is deprecated`);
+  }
+  try {
+    const executionConfig = {
+      ...config,
+      baseUrl: _baseUrl || config.baseUrl
+    };
+    if (!executionConfig.baseUrl) {
+      return `\u9519\u8BEF: \u6CA1\u6709\u914D\u7F6E base URL
+
+\u8BF7\u901A\u8FC7\u4EE5\u4E0B\u65B9\u5F0F\u4E4B\u4E00\u63D0\u4F9B base URL:
+1. \u5728\u914D\u7F6E\u6587\u4EF6\u4E2D\u8BBE\u7F6E baseUrl
+2. \u542F\u52A8\u65F6\u4F7F\u7528 --base-url \u53C2\u6570
+3. \u8C03\u7528\u65F6\u63D0\u4F9B _baseUrl \u53C2\u6570`;
+    }
+    logger.info(`Executing API: ${apiEntry.method} ${apiEntry.path}`);
+    const response = await executeRequest(apiEntry.operation, parameters, executionConfig);
+    const formattedResponse = formatResponse(response);
+    return formattedResponse;
+  } catch (error) {
+    const errorMessage = error instanceof ToolExecutionError ? `\u9519\u8BEF: ${error.message}` : `\u9519\u8BEF: ${error instanceof Error ? error.message : "\u672A\u77E5\u9519\u8BEF"}`;
+    logger.error(`API execution failed: ${operationId}`, error);
+    return errorMessage;
+  }
+}
+
+// src/tools/discovery/api-list.ts
+var import_zod5 = require("zod");
+var apiListSchema = import_zod5.z.object({
+  page: import_zod5.z.number().int().min(1).default(1).describe("\u9875\u7801\uFF08\u4ECE 1 \u5F00\u59CB\uFF09"),
+  pageSize: import_zod5.z.number().int().min(1).max(100).default(20).describe("\u6BCF\u9875\u6570\u91CF\uFF081-100\uFF09"),
+  tag: import_zod5.z.string().optional().describe("\u6309\u6807\u7B7E\u8FC7\u6EE4")
+});
+var apiListTool = {
+  name: "api_list",
+  description: `\u5206\u9875\u6D4F\u89C8\u6240\u6709\u53EF\u7528\u7684 API\u3002
+
+\u4F7F\u7528\u573A\u666F\uFF1A
+- \u67E5\u770B\u6709\u54EA\u4E9B API \u53EF\u7528
+- \u6309\u6807\u7B7E\u8FC7\u6EE4 API
+- \u6D4F\u89C8 API \u5217\u8868\u4EE5\u627E\u5230\u9700\u8981\u7684\u63A5\u53E3
+
+\u8FD4\u56DE\u5185\u5BB9\u5305\u62EC\uFF1AAPI ID\u3001\u540D\u79F0\u3001HTTP \u65B9\u6CD5\u3001\u8DEF\u5F84\u3001\u6458\u8981\u3001\u6807\u7B7E\u7B49\u3002`,
+  inputSchema: apiListSchema
+};
+function executeApiList(registry, input) {
+  const { page, pageSize, tag } = input;
+  logger.debug(`Executing api_list: page=${page}, pageSize=${pageSize}, tag=${tag}`);
+  const result = registry.list({ page, pageSize, tag });
+  const lines = [];
+  lines.push(`## API \u5217\u8868 (${result.total} \u4E2A API)`);
+  lines.push(`\u9875\u7801: ${result.page}/${result.totalPages}`);
+  if (tag) {
+    lines.push(`\u6807\u7B7E\u8FC7\u6EE4: ${tag}`);
+  }
+  lines.push("");
+  if (result.items.length === 0) {
+    lines.push("\u6CA1\u6709\u627E\u5230\u5339\u914D\u7684 API\u3002");
+    return lines.join("\n");
+  }
+  for (const item of result.items) {
+    const methodBadge = `[${item.method.toUpperCase().padEnd(6)}]`;
+    const deprecatedTag = item.deprecated ? " [\u5DF2\u5E9F\u5F03]" : "";
+    const tags = item.tags ? ` (${item.tags.join(", ")})` : "";
+    lines.push(`### ${item.id}`);
+    lines.push(`${methodBadge} ${item.path}${deprecatedTag}${tags}`);
+    if (item.summary) {
+      lines.push(`${item.summary}`);
+    }
+    lines.push("");
+  }
+  if (result.totalPages > 1) {
+    lines.push("---");
+    if (result.page < result.totalPages) {
+      lines.push(`\u4F7F\u7528 page=${result.page + 1} \u67E5\u770B\u4E0B\u4E00\u9875`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/tools/discovery/api-search.ts
+var import_zod6 = require("zod");
+var apiSearchSchema = import_zod6.z.object({
+  query: import_zod6.z.string().min(1).describe("\u641C\u7D22\u5173\u952E\u8BCD"),
+  searchIn: import_zod6.z.array(import_zod6.z.enum(["name", "summary", "description", "path"])).optional().default(["name", "summary", "description", "path"]).describe("\u641C\u7D22\u8303\u56F4\uFF08\u9ED8\u8BA4\u641C\u7D22\u6240\u6709\u5B57\u6BB5\uFF09"),
+  limit: import_zod6.z.number().int().min(1).max(100).optional().default(20).describe("\u6700\u5927\u8FD4\u56DE\u6570\u91CF\uFF081-100\uFF09")
+});
+var apiSearchTool = {
+  name: "api_search",
+  description: `\u641C\u7D22 API\u3002
+
+\u4F7F\u7528\u573A\u666F\uFF1A
+- \u6839\u636E\u5173\u952E\u8BCD\u5FEB\u901F\u627E\u5230\u76F8\u5173 API
+- \u641C\u7D22\u7279\u5B9A\u529F\u80FD\u6216\u8D44\u6E90\u7684\u63A5\u53E3
+- \u67E5\u627E\u5305\u542B\u7279\u5B9A\u8DEF\u5F84\u6BB5\u7684 API
+
+\u641C\u7D22\u8303\u56F4\u5305\u62EC\uFF1AAPI \u540D\u79F0\u3001\u6458\u8981\u3001\u63CF\u8FF0\u3001\u8DEF\u5F84\u3002
+\u7ED3\u679C\u6309\u5339\u914D\u5EA6\u6392\u5E8F\uFF0C\u6700\u5339\u914D\u7684\u6392\u5728\u524D\u9762\u3002`,
+  inputSchema: apiSearchSchema
+};
+function executeApiSearch(registry, input) {
+  const { query, searchIn, limit } = input;
+  logger.debug(
+    `Executing api_search: query="${query}", searchIn=${searchIn?.join(",")}, limit=${limit}`
+  );
+  const results = registry.search({ query, searchIn, limit });
+  const lines = [];
+  lines.push(`## \u641C\u7D22\u7ED3\u679C: "${query}"`);
+  lines.push(`\u627E\u5230 ${results.length} \u4E2A\u5339\u914D\u7684 API`);
+  lines.push("");
+  if (results.length === 0) {
+    lines.push("\u6CA1\u6709\u627E\u5230\u5339\u914D\u7684 API\u3002");
+    lines.push("");
+    lines.push("\u5EFA\u8BAE\uFF1A");
+    lines.push("- \u5C1D\u8BD5\u4F7F\u7528\u4E0D\u540C\u7684\u5173\u952E\u8BCD");
+    lines.push("- \u68C0\u67E5\u62FC\u5199\u662F\u5426\u6B63\u786E");
+    lines.push("- \u4F7F\u7528\u66F4\u901A\u7528\u7684\u641C\u7D22\u8BCD");
+    return lines.join("\n");
+  }
+  for (const item of results) {
+    const methodBadge = `[${item.method.toUpperCase().padEnd(6)}]`;
+    const matchInfo = `\u5339\u914D\u5B57\u6BB5: ${item.matchedFields.join(", ")}`;
+    lines.push(`### ${item.id}`);
+    lines.push(`${methodBadge} ${item.path}`);
+    if (item.summary) {
+      lines.push(`${item.summary}`);
+    }
+    lines.push(`_${matchInfo}_ (\u76F8\u5173\u5EA6: ${Math.round(item.score * 100)}%)`);
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("\u4F7F\u7528 api_detail <id> \u67E5\u770B API \u8BE6\u60C5");
+  lines.push("\u4F7F\u7528 api_execute <id> <parameters> \u6267\u884C API");
+  return lines.join("\n");
+}
+
 // src/server/tool-manager.ts
 var ToolManager = class {
   tools = /* @__PURE__ */ new Map();
@@ -943,6 +1524,23 @@ var ToolManager = class {
     }
     logger.info(`Registered ${tools.length} tools`);
   }
+  /**
+   * 获取工具
+   */
+  getTool(name) {
+    return this.tools.get(name);
+  }
+  /**
+   * 通过 operationId 获取工具
+   */
+  getToolByOperationId(operationId) {
+    for (const tool of this.tools.values()) {
+      if (tool.operation.operationId === operationId) {
+        return tool;
+      }
+    }
+    return void 0;
+  }
   /**
    * 执行工具
    */
@@ -988,6 +1586,40 @@ var ToolManager = class {
       };
     }
   }
+  /**
+   * 通过 operation 直接执行（用于 ondemand 模式）
+   */
+  async executeByOperation(operation, args) {
+    try {
+      logger.debug(`Executing operation: ${operation.operationId || operation.path}`, args);
+      const { _baseUrl, ...restArgs } = args;
+      const executionConfig = {
+        ...this.config,
+        baseUrl: typeof _baseUrl === "string" ? _baseUrl : this.config.baseUrl
+      };
+      const response = await executeRequest(operation, restArgs, executionConfig);
+      const formattedResponse = formatResponse(response);
+      return {
+        content: [
+          {
+            type: "text",
+            text: formattedResponse
+          }
+        ]
+      };
+    } catch (error) {
+      const errorMessage = error instanceof ToolExecutionError ? `Error: ${error.message}` : `Error: ${error instanceof Error ? error.message : "Unknown error"}`;
+      logger.error(`Operation execution failed: ${operation.operationId || operation.path}`, error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: errorMessage
+          }
+        ]
+      };
+    }
+  }
   /**
    * 获取所有已注册的工具名称
    */
@@ -1000,11 +1632,80 @@ var ToolManager = class {
   getToolCount() {
     return this.tools.size;
   }
+  /**
+   * 获取配置
+   */
+  getConfig() {
+    return this.config;
+  }
 };
 
 // src/server/index.ts
+function createRegistry(operations, components) {
+  const registry = new ApiRegistry();
+  for (const tool of operations) {
+    const entry = {
+      id: tool.operation.operationId || tool.name,
+      name: tool.name,
+      method: tool.operation.method,
+      path: tool.operation.path,
+      summary: tool.operation.summary,
+      description: tool.operation.description,
+      tags: tool.operation.tags,
+      deprecated: tool.operation.deprecated,
+      operation: tool.operation,
+      components
+    };
+    registry.register(entry);
+  }
+  return registry;
+}
+function registerOndemandTools(server, registry, config) {
+  server.tool(
+    apiListTool.name,
+    apiListTool.description,
+    apiListSchema.shape,
+    async (args) => {
+      const result = executeApiList(registry, args);
+      return { content: [{ type: "text", text: result }] };
+    }
+  );
+  server.tool(
+    apiSearchTool.name,
+    apiSearchTool.description,
+    apiSearchSchema.shape,
+    async (args) => {
+      const result = executeApiSearch(registry, args);
+      return { content: [{ type: "text", text: result }] };
+    }
+  );
+  server.tool(
+    apiDetailTool.name,
+    apiDetailTool.description,
+    apiDetailSchema.shape,
+    async (args) => {
+      const result = executeApiDetail(registry, args);
+      return { content: [{ type: "text", text: result }] };
+    }
+  );
+  server.tool(
+    apiExecuteTool.name,
+    apiExecuteTool.description,
+    apiExecuteSchema.shape,
+    async (args) => {
+      const result = await executeApiExecute(
+        registry,
+        config,
+        args
+      );
+      return { content: [{ type: "text", text: result }] };
+    }
+  );
+  logger.info("Registered 4 discovery tools (ondemand mode)");
+}
 async function createServer(config) {
   logger.info("Creating MCP server...");
+  logger.info(`Mode: ${config.mode || "default"}`);
   const server = new import_mcp.McpServer({
     name: "api2mcp",
     version: "0.1.0"
@@ -1020,9 +1721,17 @@ async function createServer(config) {
     openApiDoc.components?.schemas,
     config.toolPrefix
   );
-  const toolManager = new ToolManager(server, effectiveConfig);
-  toolManager.registerTools(tools);
-  logger.info(`Server ready with ${toolManager.getToolCount()} tools`);
+  if (config.mode === "ondemand") {
+    const registry = createRegistry(tools, openApiDoc.components?.schemas);
+    registerOndemandTools(server, registry, effectiveConfig);
+    const stats = registry.getStats();
+    logger.info(`Server ready with ${stats.totalApis} APIs in registry`);
+    logger.info(`Tags: ${stats.tags.slice(0, 5).join(", ")}${stats.tags.length > 5 ? "..." : ""}`);
+  } else {
+    const toolManager = new ToolManager(server, effectiveConfig);
+    toolManager.registerTools(tools);
+    logger.info(`Server ready with ${toolManager.getToolCount()} tools`);
+  }
   return server;
 }
 async function startServer(config) {
@@ -1034,14 +1743,27 @@ async function startServer(config) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Api2McpError,
+  ApiRegistry,
   ConfigurationError,
   HttpError,
   OpenApiParseError,
   ToolExecutionError,
   ToolManager,
+  apiDetailSchema,
+  apiDetailTool,
+  apiExecuteSchema,
+  apiExecuteTool,
+  apiListSchema,
+  apiListTool,
+  apiSearchSchema,
+  apiSearchTool,
   convertSchema,
   createRefResolver,
   createServer,
+  executeApiDetail,
+  executeApiExecute,
+  executeApiList,
+  executeApiSearch,
   executeRequest,
   formatResponse,
   generateTool,