Proposal: Generate an API catalog with CLI and MCP lookup interfaces

Motivation

While exploring es-toolkit/fp, I found its composable API useful and started thinking about how the existing reference material could be made easier to query.

In a few cases, locating the exact function for a task involved bringing a broader portion of the documentation into context than the eventual answer required. A compact, structured lookup layer could help developers and coding agents move more directly from an intent to the relevant function, entry point, and import path.

es-toolkit already provides extensive reference documentation, Agent Skills, and llms.txt. I would like to explore whether the same information could be generated into a shared API catalog and reused through CLI and MCP interfaces.

Proposal

Generate a compact, release-aligned API catalog from information already maintained in the repository, then expose the same lookup behavior through:

• a CLI for developers, scripts, and terminal-based agents
• a read-only MCP server for MCP-compatible agent environments

The catalog would be generated and validated during CI or the package build rather than maintained as a separate documentation source.

Architecture

flowchart LR
    API["TypeScript API / JSDoc"] --> Generator["Catalog generator"]
    Exports["Package exports"] --> Generator
    Docs["Reference documentation"] --> Generator
    Aliases["Optional reviewed aliases"] -.-> Generator

    Generator --> Catalog["Versioned API catalog"]
    Catalog --> Search["Shared lookup and search logic"]

    Search --> CLI["CLI"]
    Search --> MCP["MCP server"]
    Search -. optional integration .-> Skills["Existing Agent Skills"]

The catalog and search implementation would be shared so that the existing Skills, CLI users, and MCP clients can use consistent API information and ranking behavior.

Catalog generation

The generator could start from the public entry points declared in package.json, inspect their exported TypeScript symbols, and resolve the corresponding declarations and reference documents.

The repository already uses @deno/doc under .scripts/docs to extract public API information, so an initial implementation could reuse or extend that pipeline.

Each field would have a deterministic source:

• TypeScript API and JSDoc for names, signatures, parameters, and declaration paths
• package exports for entry points and import paths
• reference documentation for summaries and documentation URLs
• package.json for the package version
• a generator-owned constant for the catalog schema version
• an optional reviewed overlay for aliases

For example, a generated record for the fp variant of chunk could look like this:

{
  "id": "es-toolkit/fp#chunk",
  "schemaVersion": 1,
  "packageVersion": "<generated from package.json>",
  "name": "chunk",
  "entryPoints": ["es-toolkit/fp"],
  "importPath": "es-toolkit/fp",
  "category": "array",
  "signature": "chunk<T>(size: number): (array: readonly T[]) => T[][]",
  "summary": "Creates a function that splits an array into sub-arrays of a given length.",
  "parameters": ["size"],
  "docsUrl": "https://es-toolkit.dev/fp/reference/chunk.html",
  "aliases": ["group", "batch"]
}

All fields except aliases could be generated from existing repository data. The aliases above are illustrative and would only be added after review.

Because the same function name may have different signatures or behavior across the main, fp, and compatibility entry points, each record should represent a specific public API variant.

The generator could validate records against package exports and produce stably ordered output during CI.

Deterministic search

The catalog would retain canonical fields instead of maintaining a separate generated keyword list.

The search implementation could apply the same deterministic tokenization and lightweight normalization to both catalog fields and user queries, then use fixed field-specific weights.

For the chunk record above, search signals could be derived mechanically:

name         → chunk
entry point  → fp
category     → array
summary      → split, array, sub-array, length
parameters   → size
aliases      → group, batch

The following query:

split an array into fixed-size groups

could be normalized to:

split, array, fixed, size, group

This produces matches such as:

split → summary
array → summary
size  → parameter
group → alias

Name and reviewed alias matches could receive more weight than summary, parameter, category, or entry-point matches.

Even without the illustrative group alias, the generated fields would still provide matches for split, array, and size. Whether those signals rank chunk above other candidates would be verified against the complete catalog.

This is deterministic lexical retrieval rather than semantic inference. The same catalog, query, filters, and scoring constants would always produce the same ordering.

Optional aliases would only be added when common user vocabulary is absent from the canonical API and documentation, and representative search tests show that the alias improves discovery.

A small set of query-to-expected-result tests could keep ranking behavior predictable as the catalog evolves.

CLI and MCP interfaces

The CLI could support ranked discovery and exact lookup:

es-toolkit search "split an array into fixed-size groups" --entry fp --json
es-toolkit show chunk --entry fp --json

The command and package names are illustrative.

A small MCP server could initially expose the same operations as two read-only tools:

search_functions(query, entryPoint?, limit?)
get_function(name, entryPoint?)

Search would return a bounded list of brief candidates, while exact lookup would return the selected catalog entry.

The MCP interface would make the same versioned lookup available as discoverable, typed tools in environments where a shell CLI is not the natural integration path. It would remain a thin adapter over the same catalog and search implementation used by the CLI.

Repository integration

The generator could reuse or extend the existing .scripts/docs tooling. Lookup and ranking logic should remain independent from CLI argument handling and MCP transport code so that both interfaces share the same behavior.

The CLI and MCP server could be distributed from the same package or executable. Whether they should be included in the main es-toolkit package or provided as a separate workspace package could be decided after a small proof of concept.

The existing Agent Skills would remain the higher-level experience for function selection, es-toolkit/fp, compatibility, and migration guidance. Where useful, they could reuse the generated lookup interface.

If maintainers find this direction useful, I would be glad to help define the initial schema or build a small proof of concept for the generator, deterministic search implementation, CLI, and MCP adapter.

References

• Astryx issue #2306 — comparison of CLI, MCP, and retrieval approaches for coding agents
• Astryx CLI: Finding things with astryx search — an example of a deterministic lookup interface backed by documentation metadata