convez.ai
MCP Server
koalyptus

ls-apis

koalyptus/ls-apis

Ver no GitHub
InicialPluginScore · de 0 a 100

Public API Discovery for Humans & Agents

Instalação

$npx convez-ai koalyptus/ls-apis

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 dias
Versão
v0.0.34
Issues abertas
0
Contribuidores
4

README

A tradução para o português deste README ainda está na fila.

ls-apis

Public APIs Discovery for Humans & Agents

A curated collection of 4,000+ public APIs with a powerful CLI search tool. Discover, filter, and explore APIs by category, authentication type.

Features

  • Comprehensive Dataset - 4,000+ APIs aggregated from multiple sources
  • Smart Search - Filter by query, category, authentication type
  • Colored Output - Syntax-highlighted results (use --no-color to disable)
  • Multiple Output Formats - Text or JSON output
  • MCP Server - AI-friendly API search via Model Context Protocol
  • Extensible Architecture - Pluggable fetchers for adding new API sources
  • TypeScript - Fully typed for better developer experience

Installation

git clone https://github.com/koalyptus/ls-apis.git
cd ls-apis
npm install

Quick Start

npm install -g @ls-apis/cli
ls-apis -q weather

Via npm link (local development)

npm link --workspace=@ls-apis/cli
ls-apis -q weather

Usage

CLI Search

# Search by keyword
npm run ls-apis -- -q weather

# Filter by category
npm run ls-apis -- -c weather

# Filter by authentication type
npm run ls-apis -- -a apiKey

# Combine filters
npm run ls-apis -- -q weather -c data -a oauth

# Limit results
npm run ls-apis -- -q weather -l 10

# Output as JSON
npm run ls-apis -- -q weather -o json

# Sort by name
npm run ls-apis -- -q weather -s name

# List all categories
npm run ls-apis -- categories

# List categories sorted by count
npm run ls-apis -- categories --sort count

# List categories as JSON
npm run ls-apis -- categories --output json

Commands

CommandDescription
categoriesList all API categories with counts
providersList all data providers
configShow config settings and file path
qaRun QA checks (terminal summary)
# Run QA via CLI
npm run ls-apis -- qa

# Save QA report to custom path
npm run ls-apis -- qa -f ./my-report.json

QA Options

FlagAliasDescription
--sort-sSort by: name (default), count
--output-oOutput format: text (default), json

Providers Options

FlagAliasDescription
--sort-sSort by: name (default), count
--output-oOutput format: text (default), json

Options

FlagAliasDescription
--query-qSearch query (filters name, description)
--category-cFilter by category
--auth-aFilter by auth type (apiKey, OAuth, no)
--limit-lMax results to show (default: 20)
--output-oOutput format: text or json (default: text)
--sort-sSort results: name, category, auth
--no-colorDisable colors in output
--help-hShow help
--version-VShow version

Note: Colors are enabled by default. Use --no-color or set NO_COLOR=1 environment variable to disable.

Configuration File

A config file is automatically created at ~/.ls-apis on first run. You can edit it to set personal defaults. CLI flags always override config values.

Location: ~/.ls-apis (your home directory)

{
  "limit": 10,
  "descriptionMaxLength": 150,
  "colors": true
}
KeyDefaultDescription
limit20Default max results
descriptionMaxLength250Max chars before truncation
colorstrueEnable terminal colors

The config file is plain JSON. Edit it manually to customize defaults, or delete it to regenerate with built-in values.

Example Output

Found 2 APIs:
  Weather API
    Description: Get real-time weather data for any location...
    Link: https://api.weather.example.com
    Auth: apiKey
    Categories: weather, data
    Sources: apis-guru

  Weather2 API
    Description: Comprehensive weather forecasting service...
    Link: https://api.weather2.example.com
    Auth: OAuth
    Categories: weather, forecast
    Sources: publicapis-dev

MCP Server

ls-apis includes an MCP server for AI assistants to search and discover public APIs via natural language.

Tools

ToolDescription
search-apisSearch public APIs by query, category, auth type, and limit
list-categoriesList all API categories with API counts
list-providersList all data providers with API counts

Resources

URIDescription
apis://dataFull aggregated API dataset (JSON)
apis://categoriesAll API categories with counts (JSON)
apis://providersAll data providers with counts (JSON)
apis://statsDataset summary statistics (JSON)

Setup

npm install

Configuration

VS Code / GitHub Copilot

Create .vscode/mcp.json in your project root:

VS Code will ask for permission on first run — this is standard for project-local MCP servers. Approve once and it won't prompt again.

{
  "servers": {
    "ls-apis": {
      "command": "npx",
      "args": ["tsx", "packages/mcp-server/src/index.ts"],
      "cwd": "/path/to/ls-apis"
    }
  }
}

Switch Copilot Chat to Agent mode to use MCP tools.

Claude Desktop

Edit claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "ls-apis": {
      "command": "npx",
      "args": ["tsx", "packages/mcp-server/src/index.ts"],
      "cwd": "/path/to/ls-apis"
    }
  }
}

Cursor

Create .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "ls-apis": {
      "command": "npx",
      "args": ["tsx", "packages/mcp-server/src/index.ts"],
      "cwd": "/path/to/ls-apis"
    }
  }
}

Verification

After configuring, the client should discover the tools and resources listed above. You can also test via CLI:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npm run mcp

Project Structure

See AGENTS.md for the full project layout. The repo is a monorepo with four packages under packages/:

  • aggregator — fetches, normalizes, deduplicates API data from upstream sources
  • cli — command-line search tool published as ls-apis
  • shared — types, config, search logic, paths consumed by all packages
  • mcp-server — MCP server for AI-friendly API queries (stdio transport)

Scripts

# Install dependencies
npm install

# Run all tests with coverage
npm test

# Run specific package tests
npm run test:aggregator
npm run test:cli
npm run test:shared
npm run test:mcp

# Typecheck all workspaces
npm run typecheck

# Lint & format
npm run lint
npm run format

# Run aggregator (generates data/apis.json in CLI package)
npm run aggregate

# Run QA checks on aggregated data
npm run qa

# Run CLI directly
npm run ls-apis -- -q <query>

# Run MCP server (stdio transport for AI clients)
npm run mcp

# Build CLI to dist/ (tsc + ESM import fix)
npm run build --workspace=@ls-apis/cli

CLI Build and Publish Notes

  • The published CLI entrypoint is packages/cli/dist/index.js.
  • packages/cli/src/ contains TypeScript sources.
  • packages/cli build script runs:
    • tsc to compile TS into dist/
    • tsc-esm-fix --target dist to add .js extensions required by Node ESM runtime
  • prepack in the CLI package runs the build before packaging, so npm publish includes ready-to-run JavaScript.

Data Schema

The packages/cli/data/apis.json file contains metadata and aggregated API data with the following structure:

interface DataFile {
  timestamp: string; // ISO 8601 UTC timestamp of processing
  providers: Provider[]; // Data source providers
  apis: ApiEntry[]; // Aggregated API entries
}

interface Provider {
  name: string; // Provider identifier (e.g., 'apis-guru')
  url: string; // Data source URL
}

interface ApiEntry {
  name: string;
  description?: string;
  link: string;
  auth?: string; // apiKey, OAuth, etc.
  cors?: string;
  categories: string[];
  openapiSpec?: string; // OpenAPI spec URL if available
  sources: string[]; // Which fetchers found this API
}

Adding a New API Source

  1. Create a new fetcher in packages/aggregator/src/sources/:

    touch packages/aggregator/src/sources/mysource.fetcher.ts
    
  2. Implement the SourceFetcher interface:

    import type { SourceFetcher, ApiEntry } from '../types';
    
    export const mysourceFetcher: SourceFetcher = {
      name: 'mysource',
      fetchApis: async (): Promise<ApiEntry[]> => {
        // Fetch and normalize APIs from your source
        return [
          /* ApiEntry items */
        ];
      },
    };
    
  3. Run the aggregator to fetch and update:

    npm run aggregate
    

Fetchers are auto-loaded via loadAllFetchers() in sources/index.ts.

Testing

Tests use Vitest with v8 coverage:

# Run all tests
npm test

# Run specific package tests
npm run test:aggregator
npm run test:cli
npm run test:shared
npm run test:mcp

# Watch mode
cd packages/cli && npm run test:watch

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Ver o original no GitHub

Bom para

Relacionados