@qverisai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 QverisAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @qverisai/sdk
+
+Official Qveris MCP Server SDK — Dynamically search and execute tools via natural language.
+
+[![npm version](https://img.shields.io/npm/v/@qverisai/sdk.svg)](https://www.npmjs.com/package/@qverisai/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables LLMs to discover and execute third-party tools through the Qveris API. With just two simple tools, your AI assistant can:
+
+- **Search** for tools using natural language queries
+- **Execute** any discovered tool with the appropriate parameters
+
+## Installation
+
+```bash
+# Using npx (recommended for MCP)
+npx @qverisai/sdk
+
+# Or install globally
+npm add -g @qverisai/sdk
+```
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Visit [Qveris](https://qveris.ai) to get your API key.
+
+### 2. Configure Your MCP Client
+
+Add the Qveris server to your MCP client configuration:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "qveris": {
+      "command": "npx",
+      "args": ["@qverisai/sdk"],
+      "env": {
+        "QVERIS_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (Settings → MCP Servers):
+
+```json
+{
+  "mcpServers": {
+    "qveris": {
+      "command": "npx",
+      "args": ["@qverisai/sdk"],
+      "env": {
+        "QVERIS_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 3. Start Using
+
+Once configured, your AI assistant can search for and execute tools:
+
+> "Find me a weather API and get the current weather in Tokyo"
+
+The assistant will:
+1. Call `search_tools` with query "weather API"
+2. Review the results and select an appropriate tool
+3. Call `execute_tool` with the tool_id and parameters
+
+## Available Tools
+
+### `search_tools`
+
+Search for available tools based on natural language queries.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | ✓ | Natural language description of the capability you need |
+| `limit` | number | | Max results to return (1-100, default: 20) |
+| `session_id` | string | | Session identifier for tracking (auto-generated if omitted) |
+
+**Example:**
+
+```json
+{
+  "query": "send email notification",
+  "limit": 5
+}
+```
+
+### `execute_tool`
+
+Execute a discovered tool with specific parameters.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tool_id` | string | ✓ | Tool ID from search results |
+| `search_id` | string | ✓ | Search ID from the search that found this tool |
+| `params_to_tool` | string | ✓ | JSON string of parameters to pass to the tool |
+| `session_id` | string | | Session identifier (auto-generated if omitted) |
+| `max_data_size` | number | | Max response size in bytes (default: 20480) |
+
+**Example:**
+
+```json
+{
+  "tool_id": "openweathermap_current_weather",
+  "search_id": "abc123",
+  "params_to_tool": "{\"city\": \"London\", \"units\": \"metric\"}"
+}
+```
+
+## Session Management
+
+The SDK automatically generates and maintains a session ID for the lifetime of the server process. This enables:
+
+- Consistent user tracking across multiple tool calls
+- Better analytics and usage patterns
+- Improved tool recommendations over time
+
+You can override the session ID by providing `session_id` in any tool call.
+
+## Response Handling
+
+### Successful Execution
+
+```json
+{
+  "execution_id": "exec-123",
+  "tool_id": "openweathermap_current_weather",
+  "success": true,
+  "result": {
+    "data": {
+      "temperature": 15.5,
+      "humidity": 72,
+      "description": "partly cloudy"
+    }
+  },
+  "execution_time": 0.847
+}
+```
+
+### Large Responses
+
+When tool output exceeds `max_data_size`, you'll receive:
+
+```json
+{
+  "result": {
+    "message": "Result content is too long...",
+    "truncated_content": "[[1678233600000, \"22198.56...",
+    "full_content_file_url": "https://..."
+  }
+}
+```
+
+The `full_content_file_url` is valid for 120 minutes.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `QVERIS_API_KEY` | ✓ | Your Qveris API authentication token |
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- A valid Qveris API key
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/qverisai/sdk.git
+cd sdk
+
+# Install dependencies
+npm install
+
+# Build
+npm build
+
+# Run locally
+QVERIS_API_KEY=your-key node dist/index.js
+```
+
+## License
+
+MIT © [QverisAI](https://github.com/qverisai)
+
+## Support
+
+- 📖 [API Documentation](https://qveris.ai/docs)
+- 🐛 [Issue Tracker](https://github.com/qverisai/sdk/issues)
+- 💬 Contact: contact@qveris.ai
+

package/dist/api/client.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Qveris API HTTP Client
+ *
+ * Provides a type-safe HTTP client for interacting with the Qveris REST API.
+ * Handles authentication, request formatting, and error handling.
+ *
+ * @module api/client
+ */
+import type { SearchRequest, SearchResponse, ExecuteRequest, ExecuteResponse, QverisClientConfig } from '../types.js';
+/**
+ * Qveris API Client
+ *
+ * A lightweight HTTP client for the Qveris API using native fetch.
+ * Requires Node.js 18+ for native fetch support.
+ *
+ * @example
+ * ```typescript
+ * const client = new QverisClient({ apiKey: 'your-api-key' });
+ *
+ * // Search for tools
+ * const searchResult = await client.searchTools({
+ *   query: 'weather API',
+ *   limit: 5
+ * });
+ *
+ * // Execute a tool
+ * const execResult = await client.executeTool('tool-id', {
+ *   search_id: searchResult.search_id,
+ *   parameters: { city: 'London' }
+ * });
+ * ```
+ */
+export declare class QverisClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    /**
+     * Creates a new Qveris API client.
+     *
+     * @param config - Client configuration
+     * @throws {Error} If apiKey is not provided
+     */
+    constructor(config: QverisClientConfig);
+    /**
+     * Makes an authenticated HTTP request to the Qveris API.
+     *
+     * @param method - HTTP method
+     * @param endpoint - API endpoint (relative to base URL)
+     * @param body - Request body (will be JSON serialized)
+     * @returns Parsed JSON response
+     * @throws {ApiError} If the request fails
+     */
+    private request;
+    /**
+     * Search for tools based on a natural language query.
+     *
+     * Finds tools that match the described capability. Results include
+     * tool metadata, parameter schemas, and usage examples.
+     *
+     * @param request - Search parameters
+     * @returns Search results with matching tools
+     *
+     * @example
+     * ```typescript
+     * const result = await client.searchTools({
+     *   query: 'send SMS message',
+     *   limit: 10,
+     *   session_id: 'user-123'
+     * });
+     *
+     * console.log(`Found ${result.total} tools`);
+     * for (const tool of result.results) {
+     *   console.log(`- ${tool.name}: ${tool.description}`);
+     * }
+     * ```
+     */
+    searchTools(request: SearchRequest): Promise<SearchResponse>;
+    /**
+     * Execute a tool with the specified parameters.
+     *
+     * The tool_id must come from a previous searchTools call.
+     * The search_id links this execution to that search for analytics.
+     *
+     * @param toolId - The tool identifier from search results
+     * @param request - Execution parameters
+     * @returns Execution result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.executeTool('openweathermap_current', {
+     *   search_id: 'search-abc123',
+     *   session_id: 'user-123',
+     *   parameters: {
+     *     city: 'Tokyo',
+     *     units: 'metric'
+     *   }
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Result:', result.result);
+     * } else {
+     *   console.error('Failed:', result.error_message);
+     * }
+     * ```
+     */
+    executeTool(toolId: string, request: ExecuteRequest): Promise<ExecuteResponse>;
+}
+/**
+ * Creates a Qveris client from environment variables.
+ *
+ * Reads the API key from the QVERIS_API_KEY environment variable.
+ *
+ * @returns Configured Qveris client
+ * @throws {Error} If QVERIS_API_KEY is not set
+ *
+ * @example
+ * ```typescript
+ * // Ensure QVERIS_API_KEY is set in your environment
+ * const client = createClientFromEnv();
+ * ```
+ */
+export declare function createClientFromEnv(): QverisClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;OAKG;gBACS,MAAM,EAAE,kBAAkB;IAQtC;;;;;;;;OAQG;YACW,OAAO;IA2CrB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;CAI5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,CAYlD"}

package/dist/api/client.js

@@ -0,0 +1,174 @@
+/**
+ * Qveris API HTTP Client
+ *
+ * Provides a type-safe HTTP client for interacting with the Qveris REST API.
+ * Handles authentication, request formatting, and error handling.
+ *
+ * @module api/client
+ */
+/** Production API base URL */
+const DEFAULT_BASE_URL = 'https://qveris.ai/api/v1';
+/**
+ * Qveris API Client
+ *
+ * A lightweight HTTP client for the Qveris API using native fetch.
+ * Requires Node.js 18+ for native fetch support.
+ *
+ * @example
+ * ```typescript
+ * const client = new QverisClient({ apiKey: 'your-api-key' });
+ *
+ * // Search for tools
+ * const searchResult = await client.searchTools({
+ *   query: 'weather API',
+ *   limit: 5
+ * });
+ *
+ * // Execute a tool
+ * const execResult = await client.executeTool('tool-id', {
+ *   search_id: searchResult.search_id,
+ *   parameters: { city: 'London' }
+ * });
+ * ```
+ */
+export class QverisClient {
+    apiKey;
+    baseUrl;
+    /**
+     * Creates a new Qveris API client.
+     *
+     * @param config - Client configuration
+     * @throws {Error} If apiKey is not provided
+     */
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('Qveris API key is required');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    }
+    /**
+     * Makes an authenticated HTTP request to the Qveris API.
+     *
+     * @param method - HTTP method
+     * @param endpoint - API endpoint (relative to base URL)
+     * @param body - Request body (will be JSON serialized)
+     * @returns Parsed JSON response
+     * @throws {ApiError} If the request fails
+     */
+    async request(method, endpoint, body) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            let errorMessage;
+            let errorDetails;
+            try {
+                const errorBody = (await response.json());
+                errorMessage =
+                    errorBody.message ||
+                        errorBody.error ||
+                        response.statusText;
+                errorDetails = errorBody;
+            }
+            catch {
+                errorMessage = response.statusText || `HTTP ${response.status}`;
+            }
+            const error = {
+                status: response.status,
+                message: errorMessage,
+                details: errorDetails,
+            };
+            throw error;
+        }
+        return response.json();
+    }
+    /**
+     * Search for tools based on a natural language query.
+     *
+     * Finds tools that match the described capability. Results include
+     * tool metadata, parameter schemas, and usage examples.
+     *
+     * @param request - Search parameters
+     * @returns Search results with matching tools
+     *
+     * @example
+     * ```typescript
+     * const result = await client.searchTools({
+     *   query: 'send SMS message',
+     *   limit: 10,
+     *   session_id: 'user-123'
+     * });
+     *
+     * console.log(`Found ${result.total} tools`);
+     * for (const tool of result.results) {
+     *   console.log(`- ${tool.name}: ${tool.description}`);
+     * }
+     * ```
+     */
+    async searchTools(request) {
+        return this.request('POST', '/search', request);
+    }
+    /**
+     * Execute a tool with the specified parameters.
+     *
+     * The tool_id must come from a previous searchTools call.
+     * The search_id links this execution to that search for analytics.
+     *
+     * @param toolId - The tool identifier from search results
+     * @param request - Execution parameters
+     * @returns Execution result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.executeTool('openweathermap_current', {
+     *   search_id: 'search-abc123',
+     *   session_id: 'user-123',
+     *   parameters: {
+     *     city: 'Tokyo',
+     *     units: 'metric'
+     *   }
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Result:', result.result);
+     * } else {
+     *   console.error('Failed:', result.error_message);
+     * }
+     * ```
+     */
+    async executeTool(toolId, request) {
+        const endpoint = `/tools/execute?tool_id=${encodeURIComponent(toolId)}`;
+        return this.request('POST', endpoint, request);
+    }
+}
+/**
+ * Creates a Qveris client from environment variables.
+ *
+ * Reads the API key from the QVERIS_API_KEY environment variable.
+ *
+ * @returns Configured Qveris client
+ * @throws {Error} If QVERIS_API_KEY is not set
+ *
+ * @example
+ * ```typescript
+ * // Ensure QVERIS_API_KEY is set in your environment
+ * const client = createClientFromEnv();
+ * ```
+ */
+export function createClientFromEnv() {
+    const apiKey = process.env.QVERIS_API_KEY;
+    if (!apiKey) {
+        throw new Error('QVERIS_API_KEY environment variable is required.\n' +
+            'Please set it to your Qveris API token.\n' +
+            'Contact Qveris to obtain an API token.');
+    }
+    return new QverisClient({ apiKey });
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,8BAA8B;AAC9B,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAS;IACf,OAAO,CAAS;IAEjC;;;;;OAKG;IACH,YAAY,MAA0B;QACpC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,OAAO,CACnB,MAAsB,EACtB,QAAgB,EAChB,IAAc;QAEd,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC;QAEzC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM;YACN,OAAO,EAAE;gBACP,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;gBACxC,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SAC9C,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,IAAI,YAAoB,CAAC;YACzB,IAAI,YAAqB,CAAC;YAE1B,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA4B,CAAC;gBACrE,YAAY;oBACT,SAAS,CAAC,OAAkB;wBAC5B,SAAS,CAAC,KAAgB;wBAC3B,QAAQ,CAAC,UAAU,CAAC;gBACtB,YAAY,GAAG,SAAS,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY,GAAG,QAAQ,CAAC,UAAU,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;YAClE,CAAC;YAED,MAAM,KAAK,GAAa;gBACtB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,OAAO,EAAE,YAAY;gBACrB,OAAO,EAAE,YAAY;aACtB,CAAC;YAEF,MAAM,KAAK,CAAC;QACd,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,WAAW,CAAC,OAAsB;QACtC,OAAO,IAAI,CAAC,OAAO,CAAiB,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,WAAW,CACf,MAAc,EACd,OAAuB;QAEvB,MAAM,QAAQ,GAAG,0BAA0B,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QACxE,OAAO,IAAI,CAAC,OAAO,CAAkB,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAE1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,oDAAoD;YACpD,2CAA2C;YAC3C,wCAAwC,CACzC,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Qveris MCP Server
+ *
+ * A Model Context Protocol (MCP) server that provides access to the Qveris
+ * tool discovery and execution API. Enables LLMs to dynamically search for
+ * and execute third-party tools via natural language.
+ *
+ * @module @qverisai/sdk
+ * @version 0.1.0
+ *
+ * @example
+ * Configure in Claude Desktop or Cursor:
+ * ```json
+ * {
+ *   "mcpServers": {
+ *     "qveris": {
+ *       "command": "npx",
+ *       "args": ["@qverisai/sdk"],
+ *       "env": { "QVERIS_API_KEY": "your-api-key" }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}