@a1st/mcp-registry-client

TypeScript client for the official MCP Registry API.

Installation

npm install @a1st/mcp-registry-client

Quick Start

import { McpRegistryClient } from '@a1st/mcp-registry-client';

const client = new McpRegistryClient();

// Search for servers
const results = await client.search('playwright');
console.log(results.servers);

API

new McpRegistryClient(options?)

Create a new client instance.

const client = new McpRegistryClient({
  baseUrl: 'https://registry.modelcontextprotocol.io', // default
  fetch: customFetch, // optional custom fetch implementation
});

client.search(query, options?)

Search for servers by name. Returns latest versions by default.

const results = await client.search('github');
// { servers: [...], metadata: { count: 5, nextCursor: '...' } }

client.list(options?)

List servers with optional filtering and pagination.

const results = await client.list({
  limit: 10,
  version: 'latest',
  updatedSince: '2024-01-01T00:00:00Z',
});

client.getServer(name, version?)

Get a specific server by name. Defaults to latest version.

const server = await client.getServer('io.github.anthropics/mcp-server-github');
console.log(server.server.name);        // 'io.github.anthropics/mcp-server-github'
console.log(server.server.description); // 'GitHub API integration'
console.log(server.server.packages);    // Package configurations

client.getServerVersions(name)

Get all versions of a server.

const versions = await client.getServerVersions('io.github.anthropics/mcp-server-github');
for (const entry of versions.servers ?? []) {
  console.log(entry.server.version);
}

client.listAll(options?)

Async generator that handles pagination automatically.

for await (const server of client.listAll({ version: 'latest' })) {
  console.log(server.server.name);
}

Types

The package exports full TypeScript types for the MCP Registry API:

import type {
  ServerJSON,           // Server configuration
  ServerResponse,       // Server + registry metadata
  ServerListResponse,   // Paginated list response
  Package,              // Package configuration (npm, pypi, etc.)
  Transport,            // Transport config (stdio, http, sse)
  ListServersOptions,   // Options for list/search
} from '@a1st/mcp-registry-client';

Error Handling

The client throws McpRegistryError for API errors:

import { McpRegistryClient, McpRegistryError } from '@a1st/mcp-registry-client';

try {
  await client.getServer('nonexistent/server');
} catch (error) {
  if (error instanceof McpRegistryError) {
    console.log(error.status);   // HTTP status code
    console.log(error.message);  // Error message
    console.log(error.response); // Full error response (if available)
  }
}

Usage in aix

This package is used by the aix CLI to power aix search and aix add mcp commands. When you run:

aix search playwright
aix add mcp github

The CLI uses this client to query the MCP Registry and fetch server configurations.

License

MIT