get_kibana_api_detail

Instructions

Implementation Reference

• src/base-tools.ts:295-326 (handler)

  Handler for 'get_kibana_api_detail': builds API index, finds endpoint by method/path, resolves OpenAPI refs for parameters/body/responses, returns detailed JSON or error if not found.

  async ({ method, path }): Promise<ToolResponse> => {
    await buildApiIndex();
    const endpoint = apiEndpointIndex.find(
      e => e.method === method.toUpperCase() && e.path === path
    );
    if (!endpoint) {
      return {
        content: [
          {
            type: "text",
            text: `API endpoint not found: ${method} ${path}`
          }
        ],
        isError: true
      };
    }
    // Recursively resolve parameters, requestBody, and responses references
    const detailed = {
      ...endpoint,
      parameters: resolveRef(endpoint.parameters, openApiDoc),
      requestBody: resolveRef(endpoint.requestBody, openApiDoc),
      responses: resolveRef(endpoint.responses, openApiDoc)
    };
    return {
      content: [
        {
          type: "text",
          text: `API endpoint details: ${JSON.stringify(detailed, null, 2)}`
        }
      ]
    };
  }

• src/base-tools.ts:291-294 (schema)

  Input schema using Zod: requires 'method' (string) and 'path' (string) parameters.

  z.object({
    method: z.string().describe("HTTP method, e.g. GET, POST, PUT, DELETE"),
    path: z.string().describe("API path, e.g. /api/actions/connector_types")
  }),

• src/base-tools.ts:288-327 (registration)

  Tool registration call in registerBaseTools function, specifying name, description, schema, and inline handler.

  server.tool(
    "get_kibana_api_detail",
    `Get details for a specific Kibana API endpoint`,
    z.object({
      method: z.string().describe("HTTP method, e.g. GET, POST, PUT, DELETE"),
      path: z.string().describe("API path, e.g. /api/actions/connector_types")
    }),
    async ({ method, path }): Promise<ToolResponse> => {
      await buildApiIndex();
      const endpoint = apiEndpointIndex.find(
        e => e.method === method.toUpperCase() && e.path === path
      );
      if (!endpoint) {
        return {
          content: [
            {
              type: "text",
              text: `API endpoint not found: ${method} ${path}`
            }
          ],
          isError: true
        };
      }
      // Recursively resolve parameters, requestBody, and responses references
      const detailed = {
        ...endpoint,
        parameters: resolveRef(endpoint.parameters, openApiDoc),
        requestBody: resolveRef(endpoint.requestBody, openApiDoc),
        responses: resolveRef(endpoint.responses, openApiDoc)
      };
      return {
        content: [
          {
            type: "text",
            text: `API endpoint details: ${JSON.stringify(detailed, null, 2)}`
          }
        ]
      };
    }
  );

• src/base-tools.ts:107-129 (helper)

  Recursive helper to resolve $ref references in OpenAPI objects, preventing circular refs, used in the tool handler for parameters, requestBody, responses.

  function resolveRef(obj: any, doc: any, seen = new Set()): any {
    if (!obj || typeof obj !== 'object') return obj;
    if (Array.isArray(obj)) return obj.map(item => resolveRef(item, doc, seen));
    if (obj.$ref) {
      const ref = obj.$ref;
      if (seen.has(ref)) return { circularRef: ref };
      seen.add(ref);
  
      const parts = ref.replace(/^#\//, '').split('/');
      let target = doc;
      for (const p of parts) {
        if (target && typeof target === 'object') target = target[p];
        else return { invalidRef: ref };
      }
      return resolveRef(target, doc, seen);
    }
  
    const result: any = {};
    for (const k of Object.keys(obj)) {
      result[k] = resolveRef(obj[k], doc, seen);
    }
    return result;
  }

• src/base-tools.ts:32-93 (helper)

  Builds the global apiEndpointIndex by parsing kibana-openapi-source.yaml file, populating endpoints list, called by the tool handler.

  async function buildApiIndex(): Promise<void> {
    if (isIndexBuilt) return;
    
    // Enhanced path resolution for both compiled JS and direct TS execution
    const possiblePaths = [
      // Environment variable takes highest priority
      process.env.KIBANA_OPENAPI_YAML_PATH,
      // Current working directory
      path.join(process.cwd(), 'kibana-openapi-source.yaml'),
      // Relative to the source file
      path.join(__dirname, 'kibana-openapi-source.yaml'),
      // One level up from source file (for ts-node execution)
      path.resolve(__dirname, '..', 'kibana-openapi-source.yaml'),
      // dist directory for compiled JS
      path.join(process.cwd(), 'dist', 'src', 'kibana-openapi-source.yaml')
    ].filter((p): p is string => typeof p === 'string' && p.length > 0);
  
    for (const p of possiblePaths) {
      if (fs.existsSync(p)) {
        YAML_FILE_PATH = p;
        console.warn(`Using YAML file from: ${p}`);
        break;
      }
    }
  
    if (!YAML_FILE_PATH) {
      console.error('Could not find kibana-openapi-source.yaml file');
      isIndexBuilt = true;
      return;
    }
  
    try {
      const yamlContent = fs.readFileSync(YAML_FILE_PATH, 'utf8');
      openApiDoc = yaml.load(yamlContent);
      
      if (!openApiDoc || !openApiDoc.paths) {
        throw new Error('Invalid YAML file structure: missing paths');
      }
  
      for (const [pathStr, pathObj] of Object.entries(openApiDoc.paths)) {
        for (const [method, methodObj] of Object.entries(pathObj as Record<string, any>)) {
          if (["get", "post", "put", "delete", "patch"].includes(method)) {
            apiEndpointIndex.push({
              path: pathStr as string,
              method: method.toUpperCase(),
              description: (methodObj as any).description,
              summary: (methodObj as any).summary,
              parameters: (methodObj as any).parameters,
              requestBody: (methodObj as any).requestBody,
              responses: (methodObj as any).responses,
              deprecated: (methodObj as any).deprecated,
              tags: (methodObj as any).tags
            });
          }
        }
      }
      isIndexBuilt = true;
    } catch (error) {
      console.error('Error loading or parsing YAML file:', error);
      throw error;
    }
  }