npm package: @orbitalmcp/sdk
Description: OrbitalMCP Agent SDK - Connect to any MCP server with 2 lines of code
Author: OrbitalMCP
Latest version: 1.0.1

# @orbitalmcp/sdk

> Connect to any MCP server with 2 lines of code

OrbitalMCP Agent SDK provides a simple, unified API for discovering and connecting to any Model Context Protocol (MCP) server. No configuration needed - just import and use.

## Features

- 🔍 **Auto-Discovery**: Find MCP servers by capability, category, or name
- 🚀 **Universal Gateway**: Invoke any MCP server via HTTP (no local installation)
- 🎯 **Simple API**: 2-line integration for AI agents
- 📦 **567+ Servers**: Access to entire OrbitalMCP registry
- ⚡ **Parallel Execution**: Batch requests to multiple servers
- 🔒 **Type-Safe**: Full TypeScript support
- 🌐 **Cross-Platform**: Works in Node.js and browsers

## Installation

```bash
npm install @orbitalmcp/sdk
```

## Quick Start

### Simple 2-Line Integration

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Discover and invoke in one call
const result = await client.discover("github", "search_repos", {
  query: "mcp",
});

console.log(result);
```

### Direct Server Invocation

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Invoke a known server
const result = await client.invoke("Airbnb", "airbnb_search", {
  location: "New York",
  checkin: "2025-11-01",
  checkout: "2025-11-05",
});

console.log(result);
```

## API Reference

### OrbitalClient

The main unified client that combines registry discovery and gateway invocation.

#### Constructor

```typescript
new OrbitalClient(options?: ClientOptions)
```

Options:

- `registryUrl?: string` - Custom registry URL (default: OrbitalMCP public registry)
- `gatewayUrl?: string` - Custom gateway URL (default: OrbitalMCP public gateway)
- `timeout?: number` - Request timeout in ms (default: 30000)
- `apiKey?: string` - API key for authenticated requests

#### Methods

##### discover(query, tool, args, options?)

Discover and invoke a tool in one call. Automatically finds a server matching the query and invokes the tool.

```javascript
const result = await client.discover("github", "search_repos", {
  query: "mcp",
});
```

##### invoke(server, tool, args, options?)

Invoke a tool on a known server.

```javascript
const result = await client.invoke("Airbnb", "airbnb_search", {
  location: "San Francisco",
});
```

##### search(filters)

Search for servers with filters.

```javascript
const servers = await client.search({
  category: "ai",
  capability: "search",
  limit: 10,
});
```

Filters:

- `capability?: string` - Filter by capability (e.g., 'search', 'read', 'write')
- `category?: string` - Filter by category (e.g., 'ai', 'database', 'productivity')
- `q?: string` - Text search query
- `tag?: string` - Filter by tag
- `sort?: 'rating' | 'installs' | 'name' | 'created' | 'stars'`
- `order?: 'asc' | 'desc'`
- `limit?: number` - Max results
- `offset?: number` - Pagination offset

##### getServer(identifier)

Get details about a specific server.

```javascript
const server = await client.getServer("Airbnb");
console.log(server.tools); // List all available tools
```

##### listTools(server)

List available tools for a server.

```javascript
const tools = await client.listTools("Airbnb");
// [{ name: 'airbnb_search', description: '...', arguments: {...} }]
```

##### findByCapability(capability)

Find servers by capability.

```javascript
const servers = await client.findByCapability("search");
```

##### findByCategory(category)

Find servers by category.

```javascript
const servers = await client.findByCategory("ai");
```

##### batch(requests, options?)

Invoke multiple tools in parallel.

```javascript
const results = await client.batch([
  {
    server: "Airbnb",
    tool: "airbnb_search",
    arguments: { location: "NYC" },
  },
  {
    server: "GitHub",
    tool: "search_repos",
    arguments: { query: "mcp" },
  },
]);
```

##### getCapabilities()

Get all available capabilities in the registry.

```javascript
const capabilities = await client.getCapabilities();
// ['read', 'write', 'search', 'update', 'delete', 'analyze', 'execute']
```

##### getCategories()

Get all categories with server counts.

```javascript
const categories = await client.getCategories();
// [{ category: 'ai', count: '164' }, { category: 'development', count: '92' }, ...]
```

##### getStats()

Get registry statistics.

```javascript
const stats = await client.getStats();
// { total_servers: 567, total_capabilities: 7, ... }
```

### RegistryClient

Low-level client for registry discovery (automatically used by OrbitalClient).

```javascript
import { RegistryClient } from "@orbitalmcp/sdk";

const registry = new RegistryClient();
const servers = await registry.search({ category: "ai" });
```

### GatewayClient

Low-level client for gateway invocation (automatically used by OrbitalClient).

```javascript
import { GatewayClient } from "@orbitalmcp/sdk";

const gateway = new GatewayClient();
const result = await gateway.invoke("Airbnb", "airbnb_search", {
  location: "New York",
});
```

## Examples

### AI Agent Integration

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// AI agent needs to search GitHub
async function handleUserRequest(userQuery) {
  if (userQuery.includes("search github")) {
    const result = await client.discover("github", "search_repos", {
      query: extractQuery(userQuery),
    });

    return formatResponse(result);
  }
}
```

### Multi-Server Search

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Search multiple travel sites in parallel
const results = await client.batch([
  { server: "Airbnb", tool: "airbnb_search", arguments: { location: "Paris" } },
  { server: "Hotels", tool: "search_hotels", arguments: { city: "Paris" } },
  {
    server: "Flights",
    tool: "search_flights",
    arguments: { destination: "Paris" },
  },
]);

// Combine and present results
```

### Dynamic Server Discovery

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Find all servers that can search
const searchServers = await client.findByCapability("search");

console.log(`Found ${searchServers.length} servers with search capability`);

// Use the first one
const result = await client.invoke(
  searchServers[0].name,
  searchServers[0].tools[0].name,
  { query: "example" }
);
```

### Category Browsing

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Get all AI servers
const aiServers = await client.findByCategory("ai");

// Get all database servers
const dbServers = await client.findByCategory("database");

// Get all productivity servers
const productivityServers = await client.findByCategory("productivity");
```

## TypeScript Support

Full TypeScript definitions included:

```typescript
import { OrbitalClient, McpServer, InvokeResult } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

const server: McpServer = await client.getServer("Airbnb");
const result: InvokeResult = await client.invoke("Airbnb", "airbnb_search", {
  location: "Tokyo",
});
```

## Advanced Configuration

### Custom Registry/Gateway URLs

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient({
  registryUrl: "https://custom-registry.example.com/api/registry/v1",
  gatewayUrl: "https://custom-gateway.example.com/api/gateway",
  timeout: 60000, // 60 seconds
  apiKey: "your-api-key",
});
```

### Authentication

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient({ apiKey: "your-api-key" });

// API key is automatically included in all requests
const result = await client.invoke("SecureServer", "protected_tool", {});
```

### Error Handling

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

try {
  const result = await client.invoke("Airbnb", "airbnb_search", {
    location: "New York",
  });

  if (result.success) {
    console.log("Success:", result.result);
  }
} catch (error) {
  console.error("Failed to invoke tool:", error.message);
}
```

## Architecture

OrbitalMCP SDK consists of three main components:

1. **Registry Client**: Discovers MCP servers from the OrbitalMCP registry (567+ servers)
2. **Gateway Client**: Invokes tools on any MCP server via HTTP
3. **Unified Client**: High-level API combining discovery and invocation

```
┌─────────────┐
│  Your App   │
└──────┬──────┘
       │
       │ @orbitalmcp/sdk
       │
┌──────▼──────────────────────────┐
│     OrbitalClient               │
│  ┌──────────┐   ┌─────────────┐│
│  │ Registry │   │   Gateway   ││
│  │  Client  │   │   Client    ││
│  └────┬─────┘   └──────┬──────┘│
└───────┼────────────────┼───────┘
        │                │
        │                │
┌───────▼──────┐  ┌──────▼───────┐
│   Registry   │  │   Gateway    │
│   Service    │  │   Service    │
│ (567 servers)│  │ (Universal   │
│              │  │  Proxy)      │
└──────────────┘  └──────────────┘
```

## Browser Support

The SDK works in browsers with a bundler (Webpack, Vite, etc.):

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Works in browser - all calls go through HTTP gateway
const result = await client.invoke("Airbnb", "airbnb_search", {
  location: "London",
});
```

## License

MIT

## AI Agent Integration

OrbitalMCP SDK enables seamless integration with popular AI agents and development tools.

### Claude Desktop Integration

Add OrbitalMCP to Claude Desktop using the MCP server bridge:

1. **Setup the bridge server:**

```bash
npm install @orbitalmcp/sdk
# Copy orbitalmcp-mcp-server.js from sdk/examples/
```

2. **Configure Claude Desktop (`claude_desktop_config.json`):**

```json
{
  "mcpServers": {
    "orbitalmcp": {
      "command": "node",
      "args": ["/path/to/orbitalmcp-mcp-server.js"]
    }
  }
}
```

3. **Claude can now access 567+ MCP servers:**

```
"Hey Claude, search GitHub for MCP servers"
"Hey Claude, find Airbnb listings in Paris"
"Hey Claude, search Linear for issues"
```

### GPT Actions Integration

Configure GPT Actions with the OrbitalMCP OpenAPI spec:

1. **Upload the API specification:**

   - Go to OpenAI's GPT Actions configuration
   - Upload `gpt-actions-openapi.yaml` from this package
   - Set authentication headers if needed

2. **GPT can now invoke any MCP server:**

```
"Search for GitHub repos about MCP"
"Find Airbnb listings in Tokyo"
"Query Git operations on a repository"
```

### Custom Agent Integration

Use the SDK directly in your agent code:

```javascript
import { OrbitalClient } from "@orbitalmcp/sdk";

class MyAgent {
  constructor() {
    this.mcpClient = new OrbitalClient();
  }

  async searchKnowledge(query) {
    // Search across multiple MCP servers
    return await this.mcpClient.discover("github", "search_repos", { query });
  }

  async getTravelInfo(location) {
    // Parallel search multiple travel APIs
    return await this.mcpClient.batch([
      { server: "Airbnb", tool: "airbnb_search", arguments: { location } },
      {
        server: "Hotels",
        tool: "search_hotels",
        arguments: { city: location },
      },
    ]);
  }
}
```

## Links

- [OrbitalMCP Website](https://www.orbitalmcp.com)
- [API Documentation](https://docs.orbitalmcp.com)
- [Registry Browser](https://www.orbitalmcp.com/registry)
- [Examples](https://github.com/orbitalmcp/orbitalmcp/tree/main/sdk/examples)
- [Integration Guides](https://docs.orbitalmcp.com/integration)
- [GitHub](https://github.com/orbitalmcp/orbitalmcp)

## Support

- Email: support@orbitalmcp.com