@yoctotta/kaman-gateway-client

Base SDK for building Kaman Data Gateway clients that bridge local data sources to the Kaman platform.

Installation

npm install @yoctotta/kaman-gateway-client

Overview

This package provides two core abstractions:

• DataProvider - Abstract base class you extend to expose a local data source (e.g., Tally, QuickBooks, a database). Implement listResources(), readResource(), and getMetadata(), and optionally listTools() / callTool().
• GatewayClient - Connects your provider to the Kaman Data Gateway server over WebSocket (Socket.IO). Handles registration, heartbeats, automatic reconnection with exponential backoff, and routing incoming MCP requests to your provider.

Quick Start

import { GatewayClient, DataProvider, Resource, ResourceReadResult } from '@yoctotta/kaman-gateway-client';

class MyProvider extends DataProvider {
  async listResources() {
    return {
      resources: [
        { uri: 'my://data/users', name: 'Users', mimeType: 'application/json' },
      ],
    };
  }

  async readResource(uri: string, cursor?: string): Promise<ResourceReadResult> {
    return { contents: { data: [{ id: 1, name: 'Alice' }], mimeType: 'application/json' } };
  }

  async getMetadata(uri: string) {
    return { resourceType: 'table', schema: { columns: [{ name: 'id', type: 'number', nullable: false }] } };
  }
}

const client = new GatewayClient(new MyProvider(), {
  gatewayUrl: 'https://gateway.example.com',
  gatewayKey: 'your-pairing-key',
});

await client.connect();

DataProvider Methods

| Method | Required | Description | |--------|----------|-------------| | listResources() | Yes | Return all available resources with URIs, names, and metadata | | readResource(uri, cursor?) | Yes | Read data from a resource. Support pagination via cursor | | getMetadata(uri) | Yes | Return schema and metadata for a resource | | listTools() | No | Expose callable tools in Kaman func-table format | | callTool(name, args) | No | Execute a tool by name |

GatewayClientOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | gatewayUrl | string | required | Gateway server URL | | gatewayKey | string | required | Pairing key from Kaman Marketplace | | reconnect | boolean | true | Auto-reconnect on disconnect | | reconnectMaxRetries | number | 10 | Max reconnection attempts | | heartbeatInterval | number | 30000 | Heartbeat interval in ms |

Existing Clients

• @yoctotta/kaman-gateway-client-tally - Tally ERP
• @yoctotta/kaman-gateway-client-localsys - Local filesystem

License

MIT