@kontext-dev/js-sdk 0.1.0

package/dist/client/index.d.cts

@@ -0,0 +1,125 @@
+import { KontextMcp } from '../mcp/index.cjs';
+import { K as KontextStorage } from '../types-RIzHnRpk.cjs';
+import { KontextError } from '../errors.cjs';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * KontextClient — protocol-agnostic facade over KontextMcp.
+ *
+ * Hides all MCP internals (SEARCH_TOOLS, EXECUTE_TOOL, -32042) behind a
+ * clean, typed API. Advanced users can access the underlying KontextMcp
+ * via `client.mcp`.
+ *
+ * @example
+ * ```typescript
+ * import { createKontextClient } from '@kontext-dev/js-sdk';
+ *
+ * const client = createKontextClient({
+ *   clientId: 'your-client-id',
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   onAuthRequired: (url) => open(url.toString()),
+ * });
+ *
+ * await client.connect();
+ * const tools = await client.tools.list();
+ * const result = await client.tools.execute('github:repos', { query: 'mcp' });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+type ClientState = "idle" | "connecting" | "ready" | "needs_auth" | "failed";
+interface KontextClientConfig {
+    clientId: string;
+    redirectUri: string;
+    /**
+     * Full URL of the MCP server endpoint.
+     * When provided, the client connects directly to this URL.
+     *
+     * @example "https://my-server.com/mcp"
+     */
+    url?: string;
+    serverUrl?: string;
+    storage?: KontextStorage;
+    sessionKey?: string;
+    onAuthRequired: (url: URL) => string | URL | void | Promise<string | URL | void>;
+    onIntegrationRequired?: (url: string, info: {
+        id: string;
+        name?: string;
+    }) => void | Promise<void>;
+    onStateChange?: (state: ClientState) => void;
+}
+interface KontextTool {
+    id: string;
+    name: string;
+    description?: string;
+    inputSchema?: object;
+    server?: {
+        id: string;
+        name?: string;
+    };
+}
+interface IntegrationInfo {
+    id: string;
+    name: string;
+    connected: boolean;
+    connectUrl?: string;
+    reason?: string;
+}
+interface ToolResult {
+    content: string;
+    raw: unknown;
+}
+interface ConnectSessionResult {
+    connectUrl: string;
+    sessionId: string;
+    expiresAt: string;
+}
+interface KontextClient {
+    readonly state: ClientState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnectPageUrl(): Promise<ConnectSessionResult>;
+    readonly auth: {
+        signIn(): Promise<void>;
+        signOut(): Promise<void>;
+        handleCallback(url: string | URL): Promise<void>;
+        isCallback(url: string | URL): boolean;
+        readonly isAuthenticated: boolean;
+    };
+    readonly integrations: {
+        list(): Promise<IntegrationInfo[]>;
+    };
+    readonly tools: {
+        list(options?: {
+            limit?: number;
+        }): Promise<KontextTool[]>;
+        execute(toolId: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    };
+    on(event: "stateChange", handler: (state: ClientState) => void): () => void;
+    on(event: "error", handler: (error: KontextError) => void): () => void;
+    /**
+     * Advanced escape hatch to the raw MCP client.
+     *
+     * Note: In hybrid/orchestrator mode (`createKontextClient` called without
+     * `url`), this is the gateway MCP client only. Tools from direct internal
+     * integrations are exposed through `client.tools`, not through this property.
+     */
+    readonly mcp: KontextMcp;
+}
+declare function createSingleEndpointKontextClient(config: KontextClientConfig): KontextClient;
+/**
+ * Primary SDK client entrypoint.
+ *
+ * - `config.url` set: single-endpoint mode.
+ * - `config.url` omitted: hybrid orchestrated mode.
+ */
+declare function createKontextClient(config: KontextClientConfig & {
+    url: string;
+}): KontextClient;
+declare function createKontextClient(config: Omit<KontextClientConfig, "url"> & {
+    url?: undefined;
+}): KontextClient;
+
+export { type ClientState, type ConnectSessionResult, type IntegrationInfo, type KontextClient, type KontextClientConfig, type KontextTool, type ToolResult, createKontextClient, createSingleEndpointKontextClient };

package/dist/client/index.d.ts

@@ -0,0 +1,125 @@
+import { KontextMcp } from '../mcp/index.js';
+import { K as KontextStorage } from '../types-RIzHnRpk.js';
+import { KontextError } from '../errors.js';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * KontextClient — protocol-agnostic facade over KontextMcp.
+ *
+ * Hides all MCP internals (SEARCH_TOOLS, EXECUTE_TOOL, -32042) behind a
+ * clean, typed API. Advanced users can access the underlying KontextMcp
+ * via `client.mcp`.
+ *
+ * @example
+ * ```typescript
+ * import { createKontextClient } from '@kontext-dev/js-sdk';
+ *
+ * const client = createKontextClient({
+ *   clientId: 'your-client-id',
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   onAuthRequired: (url) => open(url.toString()),
+ * });
+ *
+ * await client.connect();
+ * const tools = await client.tools.list();
+ * const result = await client.tools.execute('github:repos', { query: 'mcp' });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+type ClientState = "idle" | "connecting" | "ready" | "needs_auth" | "failed";
+interface KontextClientConfig {
+    clientId: string;
+    redirectUri: string;
+    /**
+     * Full URL of the MCP server endpoint.
+     * When provided, the client connects directly to this URL.
+     *
+     * @example "https://my-server.com/mcp"
+     */
+    url?: string;
+    serverUrl?: string;
+    storage?: KontextStorage;
+    sessionKey?: string;
+    onAuthRequired: (url: URL) => string | URL | void | Promise<string | URL | void>;
+    onIntegrationRequired?: (url: string, info: {
+        id: string;
+        name?: string;
+    }) => void | Promise<void>;
+    onStateChange?: (state: ClientState) => void;
+}
+interface KontextTool {
+    id: string;
+    name: string;
+    description?: string;
+    inputSchema?: object;
+    server?: {
+        id: string;
+        name?: string;
+    };
+}
+interface IntegrationInfo {
+    id: string;
+    name: string;
+    connected: boolean;
+    connectUrl?: string;
+    reason?: string;
+}
+interface ToolResult {
+    content: string;
+    raw: unknown;
+}
+interface ConnectSessionResult {
+    connectUrl: string;
+    sessionId: string;
+    expiresAt: string;
+}
+interface KontextClient {
+    readonly state: ClientState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnectPageUrl(): Promise<ConnectSessionResult>;
+    readonly auth: {
+        signIn(): Promise<void>;
+        signOut(): Promise<void>;
+        handleCallback(url: string | URL): Promise<void>;
+        isCallback(url: string | URL): boolean;
+        readonly isAuthenticated: boolean;
+    };
+    readonly integrations: {
+        list(): Promise<IntegrationInfo[]>;
+    };
+    readonly tools: {
+        list(options?: {
+            limit?: number;
+        }): Promise<KontextTool[]>;
+        execute(toolId: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    };
+    on(event: "stateChange", handler: (state: ClientState) => void): () => void;
+    on(event: "error", handler: (error: KontextError) => void): () => void;
+    /**
+     * Advanced escape hatch to the raw MCP client.
+     *
+     * Note: In hybrid/orchestrator mode (`createKontextClient` called without
+     * `url`), this is the gateway MCP client only. Tools from direct internal
+     * integrations are exposed through `client.tools`, not through this property.
+     */
+    readonly mcp: KontextMcp;
+}
+declare function createSingleEndpointKontextClient(config: KontextClientConfig): KontextClient;
+/**
+ * Primary SDK client entrypoint.
+ *
+ * - `config.url` set: single-endpoint mode.
+ * - `config.url` omitted: hybrid orchestrated mode.
+ */
+declare function createKontextClient(config: KontextClientConfig & {
+    url: string;
+}): KontextClient;
+declare function createKontextClient(config: Omit<KontextClientConfig, "url"> & {
+    url?: undefined;
+}): KontextClient;
+
+export { type ClientState, type ConnectSessionResult, type IntegrationInfo, type KontextClient, type KontextClientConfig, type KontextTool, type ToolResult, createKontextClient, createSingleEndpointKontextClient };