@qverisai/mcp 0.1.2

package/dist/tools/search.js

@@ -0,0 +1,53 @@
+/**
+ * search_tools MCP Tool Implementation
+ *
+ * Searches for available tools based on natural language queries.
+ * Returns relevant tools that can help accomplish tasks.
+ *
+ * @module tools/search
+ */
+/**
+ * JSON Schema for the search_tools tool input.
+ * Used by MCP to validate and document the tool parameters.
+ */
+export const searchToolsSchema = {
+    type: 'object',
+    properties: {
+        query: {
+            type: 'string',
+            description: 'The search query describing the general capability of the tool. ' +
+                'Describe what you want to accomplish, not specific params you want to pass to the tool later. ' +
+                'Example: "weather forecast API", "send email", "stock prices"',
+        },
+        limit: {
+            type: 'number',
+            description: 'Maximum number of results to return (1-100)',
+            default: 20,
+            minimum: 1,
+            maximum: 100,
+        },
+        session_id: {
+            type: 'string',
+            description: 'Session identifier for tracking user sessions. ' +
+                'If not provided, an auto-generated session ID will be used.',
+        },
+    },
+    required: ['query'],
+};
+/**
+ * Executes the search_tools operation.
+ *
+ * @param client - Initialized Qveris API client
+ * @param input - Search parameters
+ * @param defaultSessionId - Fallback session ID if not provided in input
+ * @returns Search results with matching tools
+ */
+export async function executeSearchTools(client, input, defaultSessionId) {
+    const response = await client.searchTools({
+        query: input.query,
+        limit: input.limit ?? 20,
+        session_id: input.session_id ?? defaultSessionId,
+    });
+    return response;
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkCH;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,QAAiB;IACvB,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,kEAAkE;gBAClE,gGAAgG;gBAChG,+DAA+D;SAClE;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,6CAA6C;YAC1D,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,GAAG;SACb;QACD,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,iDAAiD;gBACjD,6DAA6D;SAChE;KACF;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAoB,EACpB,KAAuB,EACvB,gBAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;QACxC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,gBAAgB;KACjD,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Qveris API Type Definitions
+ *
+ * This module contains TypeScript types that match the Qveris API v0.1.6 schema.
+ * All types are fully documented for IDE autocompletion and developer experience.
+ *
+ * @module types
+ * @see {@link https://qveris.ai/api/v1} Qveris API Base URL
+ */
+/**
+ * Request body for the Search Tools API.
+ *
+ * @example
+ * ```typescript
+ * const request: SearchRequest = {
+ *   query: "weather forecast API",
+ *   limit: 10,
+ *   session_id: "abcd1234-ab12-ab12-ab12-abcdef123456"
+ * };
+ * ```
+ */
+export interface SearchRequest {
+    /**
+     * Natural language search query describing the tool capability you need.
+     * @example "weather forecast API"
+     * @example "send email notification"
+     */
+    query: string;
+    /**
+     * Maximum number of results to return.
+     * @default 20
+     * @minimum 1
+     * @maximum 100
+     */
+    limit?: number;
+    /**
+     * Session identifier for tracking user sessions.
+     * Same ID corresponds to the same user session.
+     */
+    session_id?: string;
+}
+/**
+ * Parameter definition for a tool.
+ * Describes a single input parameter that a tool accepts.
+ */
+export interface ToolParameter {
+    /** Parameter name (used as key in the parameters object) */
+    name: string;
+    /** Data type of the parameter */
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    /** Whether this parameter must be provided */
+    required: boolean;
+    /** Human-readable description of what this parameter does */
+    description: string;
+    /** If present, restricts valid values to this list */
+    enum?: string[];
+}
+/**
+ * Example usage for a tool, showing sample parameters.
+ */
+export interface ToolExamples {
+    /** Sample parameter values demonstrating typical usage */
+    sample_parameters?: Record<string, unknown>;
+}
+/**
+ * Information about a tool returned from search results.
+ * Contains everything needed to understand and execute the tool.
+ */
+export interface ToolInfo {
+    /** Unique identifier for the tool (used in execute_tool) */
+    tool_id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Detailed description of what the tool does */
+    description: string;
+    /** Name of the organization/service providing this tool */
+    provider_name?: string;
+    /** Description of the provider */
+    provider_description?: string;
+    /**
+     * Geographic availability of the tool.
+     * - "global" - Available worldwide
+     * - "US|CA" - Whitelist: only available in US and Canada
+     * - "!CN|RU" - Blacklist: not available in China and Russia
+     */
+    region?: string;
+    /** Average response latency in milliseconds */
+    avg_latency_ms?: number;
+    /** List of parameters the tool accepts */
+    params?: ToolParameter[];
+    /** Usage examples with sample parameters */
+    examples?: ToolExamples;
+}
+/**
+ * Performance statistics for a search operation.
+ */
+export interface SearchStats {
+    /** Total time to complete the search in milliseconds */
+    search_time_ms: number;
+}
+/**
+ * Response from the Search Tools API.
+ */
+export interface SearchResponse {
+    /** The original search query */
+    query?: string;
+    /**
+     * Unique identifier for this search.
+     * Required when calling execute_tool for any tool from these results.
+     */
+    search_id: string;
+    /** Total number of results returned */
+    total?: number;
+    /** Array of matching tools */
+    results: ToolInfo[];
+    /** Search performance statistics */
+    stats?: SearchStats;
+}
+/**
+ * Request body for the Get Tools by IDs API.
+ *
+ * @example
+ * ```typescript
+ * const request: GetToolsByIdsRequest = {
+ *   tool_ids: ["tool-1", "tool-2"],
+ *   search_id: "search-123",
+ *   session_id: "abcd1234-ab12-ab12-ab12-abcdef123456"
+ * };
+ * ```
+ */
+export interface GetToolsByIdsRequest {
+    /**
+     * Array of tool IDs to retrieve information for.
+     */
+    tool_ids: string[];
+    /**
+     * The search_id from the search that returned the tool(s).
+     * Optional but recommended for analytics and billing.
+     */
+    search_id?: string;
+    /**
+     * Session identifier for tracking user sessions.
+     * Same ID corresponds to the same user session.
+     */
+    session_id?: string;
+}
+/**
+ * Request body for the Execute Tool API.
+ *
+ * @example
+ * ```typescript
+ * const request: ExecuteRequest = {
+ *   search_id: "abcd1234-ab12-ab12-ab12-abcdef123456",
+ *   session_id: "abcd1234-ab12-ab12-ab12-abcdef123456",
+ *   parameters: { city: "London", units: "metric" },
+ *   max_response_size: 20480
+ * };
+ * ```
+ */
+export interface ExecuteRequest {
+    /**
+     * The search_id from the search that returned this tool.
+     * Links the execution to the original search for analytics.
+     */
+    search_id: string;
+    /**
+     * Session identifier for tracking user sessions.
+     * Same ID corresponds to the same user session.
+     */
+    session_id?: string;
+    /**
+     * Key-value pairs of parameters to pass to the tool.
+     * Must match the parameter schema from the tool's definition.
+     */
+    parameters: Record<string, unknown>;
+    /**
+     * Maximum size of response data in bytes.
+     * If the tool generates data longer than this, it will be truncated
+     * and a download URL will be provided for the full content.
+     * @default 20480 (20KB)
+     * @minimum -1 (-1 means no limit)
+     */
+    max_response_size?: number;
+}
+/**
+ * Result data when the response fits within max_response_size.
+ */
+export interface ExecuteResultData {
+    /** The actual result data from the tool execution */
+    data: unknown;
+}
+/**
+ * Result data when the response exceeds max_response_size.
+ * Provides truncated content and a URL to download the full result.
+ */
+export interface ExecuteResultTruncated {
+    /** Explanation message about the truncation */
+    message: string;
+    /**
+     * URL to download the complete result file.
+     * Valid for 120 minutes.
+     */
+    full_content_file_url: string;
+    /**
+     * The initial portion of the response (max_response_size bytes).
+     * Useful for previewing the data structure.
+     */
+    truncated_content: string;
+}
+/**
+ * Union type for execution results (either full data or truncated).
+ */
+export type ExecuteResult = ExecuteResultData | ExecuteResultTruncated;
+/**
+ * Response from the Execute Tool API.
+ */
+export interface ExecuteResponse {
+    /** Unique identifier for this execution record */
+    execution_id: string;
+    /** The tool that was executed */
+    tool_id: string;
+    /** The parameters that were passed to the tool */
+    parameters: Record<string, unknown>;
+    /**
+     * The execution result.
+     * Contains either `data` (if within size limit) or truncation info.
+     */
+    result?: ExecuteResult;
+    /** Whether the execution completed successfully */
+    success: boolean;
+    /**
+     * Error message if execution failed.
+     * Common reasons: insufficient balance, quota exceeded, invalid parameters.
+     */
+    error_message?: string | null;
+    /** Execution duration in seconds */
+    execution_time?: number;
+    /** Timestamp of execution (ISO 8601 format) */
+    created_at: string;
+}
+/**
+ * Configuration options for the Qveris API client.
+ */
+export interface QverisClientConfig {
+    /** API authentication token */
+    apiKey: string;
+    /** Base URL for the API (defaults to production) */
+    baseUrl?: string;
+}
+/**
+ * Error response from the Qveris API.
+ */
+export interface ApiError {
+    /** HTTP status code */
+    status: number;
+    /** Error message */
+    message: string;
+    /** Original error details if available */
+    details?: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Qveris API Type Definitions
+ *
+ * This module contains TypeScript types that match the Qveris API v0.1.6 schema.
+ * All types are fully documented for IDE autocompletion and developer experience.
+ *
+ * @module types
+ * @see {@link https://qveris.ai/api/v1} Qveris API Base URL
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@qverisai/mcp",
+  "version": "0.1.2",
+  "description": "Official Qveris AI MCP Server SDK - Search and execute tools via natural language",
+  "keywords": [
+    "qveris",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "tools",
+    "sdk"
+  ],
+  "author": "QverisAI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/qverisai/mcp"
+  },
+  "homepage": "https://github.com/qverisai/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/qverisai/mcp/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "qveris-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "uuid": "^11.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}