@mcp-marketplace/client-sdk

TypeScript SDK for accessing the MCP (Model Context Protocol) App Marketplace API. Works in both browser and Node.js environments.

Installation

npm install @mcp-marketplace/client-sdk

Quick Start

import { createMarketplaceClient } from '@mcp-marketplace/client-sdk';

const client = createMarketplaceClient({
  baseUrl: 'https://marketplace.example.com',
  apiKey: 'your-api-key', // optional
  getUserId: () => 'user-123' // optional
});

// List all apps
const apps = await client.listApps();

Configuration

Basic Configuration

import { MarketplaceClient } from '@mcp-marketplace/client-sdk';

const client = new MarketplaceClient({
  baseUrl: 'https://marketplace.example.com',
  apiKey: 'your-api-key', // optional
  token: 'bearer-token', // optional, alternative to apiKey
  timeout: 30000, // optional, default: 30000ms
  getUserId: () => 'user-id' // optional, default: 'dev'
});

Environment Variables

You can also create a client from environment variables:

import { createMarketplaceClientFromEnv } from '@mcp-marketplace/client-sdk';

const client = createMarketplaceClientFromEnv(
  () => 'user-id' // optional getUserId function
);

Environment variables:

• MARKETPLACE_URL - Base URL for the marketplace API
• MARKETPLACE_API_KEY - API key for authentication
• MARKETPLACE_TOKEN - Bearer token for authentication

API Methods

listApps(filters?)

List all available apps with optional filters.

const apps = await client.listApps({
  search: 'weather',
  category: 'tools',
  visibility: 'global' // or 'private'
});

Parameters:

• filters? - Optional filters object:
  • search?: string - Search query
  • category?: string - Filter by category
  • visibility?: 'private' | 'global' - Filter by visibility

Returns: Promise<MCPApp[]>

getApp(appId)

Get detailed information about a specific app.

const app = await client.getApp('app-id');

Parameters:

• appId: string - The app ID

Returns: Promise<MCPApp>

searchApps(query, filters?)

Search apps by query string.

const results = await client.searchApps('weather', {
  category: 'tools'
});

Parameters:

• query: string - Search query
• filters? - Optional filters (same as listApps)

Returns: Promise<MCPApp[]>

downloadApp(appId, version?)

Download app package as a Blob.

const blob = await client.downloadApp('app-id');
// or with version
const blob = await client.downloadApp('app-id', '1.0.0');

Parameters:

• appId: string - The app ID
• version?: string - Optional version string

Returns: Promise<Blob>

getAppManifest(appId)

Get app manifest JSON.

const manifest = await client.getAppManifest('app-id');

Parameters:

• appId: string - The app ID

Returns: Promise<AppManifest>

uploadApp(file, visibility)

Upload app package (for developers).

const file = new File([...], 'app.zip');
const app = await client.uploadApp(file, 'global');

Parameters:

• file: File | Blob | Buffer - The app package file
• visibility: 'private' | 'global' - App visibility

Returns: Promise<MCPApp>

getAppHealth(appId)

Check health status of external API app.

const health = await client.getAppHealth('app-id');
// { healthy: true, latency: 123 }

Parameters:

• appId: string - The app ID

Returns: Promise<HealthStatus>

deleteApp(appId)

Delete an app (only if user owns it).

await client.deleteApp('app-id');

Parameters:

• appId: string - The app ID

Returns: Promise<void>

addAppToAccount(appId)

Add app to user's account (for use in chat UI). Only works for external API apps that can run in browser.

const result = await client.addAppToAccount('app-id');
// { success: true, message: '...', server?: {...} }

Parameters:

• appId: string - The app ID

Returns: Promise<{ success: boolean; message: string; server?: any }>

Browser Usage

The SDK works seamlessly in browser environments:

import { createMarketplaceClient } from '@mcp-marketplace/client-sdk';

const client = createMarketplaceClient({
  baseUrl: window.MARKETPLACE_URL || 'https://marketplace.example.com',
  getUserId: () => getCurrentUserId()
});

const apps = await client.listApps();

Node.js Usage

The SDK also works in Node.js environments:

import { createMarketplaceClient } from '@mcp-marketplace/client-sdk';
import { readFileSync } from 'fs';

const client = createMarketplaceClient({
  baseUrl: process.env.MARKETPLACE_URL || 'https://marketplace.example.com',
  apiKey: process.env.MARKETPLACE_API_KEY
});

// Upload from Node.js
const buffer = readFileSync('app.zip');
const app = await client.uploadApp(buffer, 'global');

Error Handling

All methods throw errors on failure:

try {
  const app = await client.getApp('invalid-id');
} catch (error) {
  console.error('Failed to fetch app:', error.message);
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All types are exported from @mcp-marketplace/types:

import type { MCPApp, AppManifest } from '@mcp-marketplace/client-sdk';
// or
import type { MCPApp, AppManifest } from '@mcp-marketplace/types';

License

MIT License

Repository

• GitHub: https://github.com/ggange/mcp-marketplace
• npm: @mcp-marketplace/client-sdk