apifable

Instructions

Implementation Reference

• src/tools/get-schema.ts:5-20 (handler)

  The core handler function that implements get_schema tool logic. Looks up a schema by name from the parsed spec, returns error with suggestions if not found, or returns the schema with resolved $refs.

  export function getSchema(spec: ParsedSpec, name: string) {
    const schema = spec.schemas[name]
  
    if (schema === undefined) {
      const suggestions = findSimilarNames(name, Object.keys(spec.schemas))
      return {
        isError: true,
        message: buildNotFoundMessage(`Schema '${name}' not found.`, suggestions),
      }
    }
  
    return {
      name,
      schema: resolveRefs(schema, spec.rawSpec),
    }
  }

• src/index.ts:168-184 (registration)

  Registration of the get_schema tool with the MCP server. Defines the tool name, description, input schema (name parameter), and handler that wraps getSchema function.

  server.registerTool(
    'get_schema',
    {
      description: 'Get a specific schema from components/schemas by name. Supported internal component $refs are resolved inline. Use get_types to convert schemas to TypeScript type declarations.',
      inputSchema: {
        name: z.string().describe('Schema name (e.g. User, CreateOrderRequest)'),
      },
    },
    ({ name }) => {
      const result = getSchema(spec, name)
      const isError = 'isError' in result && result.isError === true
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        isError,
      }
    },
  )

• src/spec/ref-resolver.ts:3-5 (helper)

  Helper function that resolves internal component $refs inline. Used by getSchema to expand references in the returned schema.

  export function resolveRefs(value: unknown, rawSpec: OpenAPIObject, visited: Set<string> = new Set()): unknown {
    return resolveRefsInternal(value, rawSpec, visited, false)
  }

• src/tools/suggestions.ts:3-41 (helper)

  Helper function used to provide fuzzy search suggestions when a schema name is not found. Uses substring matching first, then falls back to MiniSearch for fuzzy matching.

  export function findSimilarNames(input: string, candidates: string[], limit = 5): string[] {
    const normalizedInput = input.trim().toLowerCase()
    if (!normalizedInput) return []
  
    const uniqueCandidates = [...new Set(candidates)]
  
    const substringMatches = uniqueCandidates
      .filter(candidate => {
        const normalizedCandidate = candidate.toLowerCase()
        return normalizedCandidate.includes(normalizedInput) || normalizedInput.includes(normalizedCandidate)
      })
      .sort((a, b) => {
        const aStarts = a.toLowerCase().startsWith(normalizedInput) ? 0 : 1
        const bStarts = b.toLowerCase().startsWith(normalizedInput) ? 0 : 1
        if (aStarts !== bStarts) return aStarts - bStarts
        if (a.length !== b.length) return a.length - b.length
        return a.localeCompare(b)
      })
  
    if (substringMatches.length > 0) {
      return substringMatches.slice(0, limit)
    }
  
    const ms = new MiniSearch({
      fields: ['name'],
      idField: 'name',
    })
  
    ms.addAll(uniqueCandidates.map(name => ({ name })))
  
    return ms
      .search(input, {
        fuzzy: 0.2,
        prefix: true,
        boost: { name: 2 },
      })
      .map(result => result.id as string)
      .slice(0, limit)
  }