@qverisai/mcp 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +216 -0
- package/dist/api/client.d.ts +147 -0
- package/dist/api/client.d.ts.map +1 -0
- package/dist/api/client.js +201 -0
- package/dist/api/client.js.map +1 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +268 -0
- package/dist/index.js.map +1 -0
- package/dist/tools/execute.d.ts +89 -0
- package/dist/tools/execute.d.ts.map +1 -0
- package/dist/tools/execute.js +73 -0
- package/dist/tools/execute.js.map +1 -0
- package/dist/tools/get-by-ids.d.ts +69 -0
- package/dist/tools/get-by-ids.d.ts.map +1 -0
- package/dist/tools/get-by-ids.js +55 -0
- package/dist/tools/get-by-ids.js.map +1 -0
- package/dist/tools/search.d.ts +71 -0
- package/dist/tools/search.d.ts.map +1 -0
- package/dist/tools/search.js +53 -0
- package/dist/tools/search.js.map +1 -0
- package/dist/types.d.ts +261 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +11 -0
- package/dist/types.js.map +1 -0
- package/package.json +55 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 QverisAI
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# @qverisai/mcp
|
|
2
|
+
|
|
3
|
+
Official Qveris MCP Server SDK — Dynamically search and execute tools via natural language.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@qverisai/mcp)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
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 three simple tools, your AI assistant can:
|
|
11
|
+
|
|
12
|
+
- **Search** for tools using natural language queries
|
|
13
|
+
- **Get** detailed information about specific tools by their IDs
|
|
14
|
+
- **Execute** any discovered tool with the appropriate parameters
|
|
15
|
+
|
|
16
|
+
## Quick Start
|
|
17
|
+
|
|
18
|
+
### 1. Get Your API Key
|
|
19
|
+
|
|
20
|
+
Visit [Qveris](https://qveris.ai) to get your API key.
|
|
21
|
+
|
|
22
|
+
### 2. Configure Your MCP Client
|
|
23
|
+
|
|
24
|
+
Add the Qveris server to your MCP client configuration:
|
|
25
|
+
|
|
26
|
+
**Claude Desktop** (`claude_desktop_config.json`):
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"mcpServers": {
|
|
31
|
+
"qveris": {
|
|
32
|
+
"command": "npx",
|
|
33
|
+
"args": ["@qverisai/mcp"],
|
|
34
|
+
"env": {
|
|
35
|
+
"QVERIS_API_KEY": "your-api-key-here"
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**Cursor** (Settings → MCP Servers):
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"mcpServers": {
|
|
47
|
+
"qveris": {
|
|
48
|
+
"command": "npx",
|
|
49
|
+
"args": ["@qverisai/mcp"],
|
|
50
|
+
"env": {
|
|
51
|
+
"QVERIS_API_KEY": "your-api-key-here"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 3. Start Using
|
|
59
|
+
|
|
60
|
+
Once configured, You could add this to system prompt:
|
|
61
|
+
|
|
62
|
+
> "You can use qveris MCP Server to dynamically search and execute tools to help the user. First think about what kind of tools might be useful to accomplish the user's task. Then use the search_tools tool with query describing the capability of the tool, not what params you want to pass to the tool later. Then call a suitable searched tool using the execute_tool tool, passing parameters to the searched tool through params_to_tool. You could reference the examples given if any for each tool. You may call make multiple tool calls in a single response."
|
|
63
|
+
|
|
64
|
+
Then your AI assistant can search for and execute tools:
|
|
65
|
+
|
|
66
|
+
> "Find me a weather tool and get the current weather in Tokyo"
|
|
67
|
+
|
|
68
|
+
The assistant will:
|
|
69
|
+
1. Call `search_tools` with query "weather"
|
|
70
|
+
2. Review the results and select an appropriate tool
|
|
71
|
+
3. Call `execute_tool` with the tool_id and parameters
|
|
72
|
+
|
|
73
|
+
## Available Tools
|
|
74
|
+
|
|
75
|
+
### `search_tools`
|
|
76
|
+
|
|
77
|
+
Search for available tools based on natural language queries.
|
|
78
|
+
|
|
79
|
+
| Parameter | Type | Required | Description |
|
|
80
|
+
|-----------|------|----------|-------------|
|
|
81
|
+
| `query` | string | ✓ | Natural language description of the capability you need |
|
|
82
|
+
| `limit` | number | | Max results to return (1-100, default: 20) |
|
|
83
|
+
| `session_id` | string | | Session identifier for tracking (auto-generated if omitted) |
|
|
84
|
+
|
|
85
|
+
**Example:**
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"query": "send email notification",
|
|
90
|
+
"limit": 10
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### `execute_tool`
|
|
95
|
+
|
|
96
|
+
Execute a discovered tool with specific parameters.
|
|
97
|
+
|
|
98
|
+
| Parameter | Type | Required | Description |
|
|
99
|
+
|-----------|------|----------|-------------|
|
|
100
|
+
| `tool_id` | string | ✓ | Tool ID from search results |
|
|
101
|
+
| `search_id` | string | ✓ | Search ID from the search that found this tool |
|
|
102
|
+
| `params_to_tool` | string | ✓ | JSON string of parameters to pass to the tool |
|
|
103
|
+
| `session_id` | string | | Session identifier (auto-generated if omitted) |
|
|
104
|
+
| `max_response_size` | number | | Max response size in bytes (default: 20480) |
|
|
105
|
+
|
|
106
|
+
**Example:**
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"tool_id": "openweathermap.weather.execute.v1",
|
|
111
|
+
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
|
|
112
|
+
"params_to_tool": "{\"city\": \"London\", \"units\": \"metric\"}"
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### `get_tools_by_ids`
|
|
117
|
+
|
|
118
|
+
Get detailed descriptions of tools based on their tool IDs. Useful for retrieving information about specific tools when you already know their IDs from previous searches.
|
|
119
|
+
|
|
120
|
+
| Parameter | Type | Required | Description |
|
|
121
|
+
|-----------|------|----------|-------------|
|
|
122
|
+
| `tool_ids` | array | ✓ | Array of tool IDs to retrieve (at least one required) |
|
|
123
|
+
| `search_id` | string | | Search ID from the search that returned the tool(s) |
|
|
124
|
+
| `session_id` | string | | Session identifier (auto-generated if omitted) |
|
|
125
|
+
|
|
126
|
+
**Example:**
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
|
|
131
|
+
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Session Management
|
|
136
|
+
|
|
137
|
+
Providing a consistent `session_id` in a same user session in any tool call enables:
|
|
138
|
+
- Consistent user tracking across multiple tool calls
|
|
139
|
+
- Better analytics and usage patterns
|
|
140
|
+
- Improved tool recommendations over time
|
|
141
|
+
|
|
142
|
+
If not provided, the SDK automatically generates and maintains a session ID for the lifetime of the server process. However, this result in a much larger granularity of user sessions.
|
|
143
|
+
|
|
144
|
+
## Response Handling
|
|
145
|
+
|
|
146
|
+
### Successful Execution
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
|
|
151
|
+
"tool_id": "openweathermap.weather.execute.v1",
|
|
152
|
+
"success": true,
|
|
153
|
+
"result": {
|
|
154
|
+
"data": {
|
|
155
|
+
"temperature": 15.5,
|
|
156
|
+
"humidity": 72,
|
|
157
|
+
"description": "partly cloudy"
|
|
158
|
+
}
|
|
159
|
+
},
|
|
160
|
+
"execution_time": 0.847
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Large Responses
|
|
165
|
+
|
|
166
|
+
When tool output exceeds `max_response_size`, you'll receive:
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"result": {
|
|
171
|
+
"message": "Result content is too long...",
|
|
172
|
+
"truncated_content": "[[1678233600000, \"22198.56...",
|
|
173
|
+
"full_content_file_url": "https://..."
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The `full_content_file_url` is valid for 120 minutes.
|
|
179
|
+
|
|
180
|
+
## Environment Variables
|
|
181
|
+
|
|
182
|
+
| Variable | Required | Description |
|
|
183
|
+
|----------|----------|-------------|
|
|
184
|
+
| `QVERIS_API_KEY` | ✓ | Your Qveris API key |
|
|
185
|
+
|
|
186
|
+
## Requirements
|
|
187
|
+
|
|
188
|
+
- Node.js 18.0.0 or higher
|
|
189
|
+
- A valid Qveris API key
|
|
190
|
+
|
|
191
|
+
## Development
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
# Clone the repository
|
|
195
|
+
git clone https://github.com/qverisai/mcp.git
|
|
196
|
+
cd sdk
|
|
197
|
+
|
|
198
|
+
# Install dependencies
|
|
199
|
+
npm install
|
|
200
|
+
|
|
201
|
+
# Build
|
|
202
|
+
npm build
|
|
203
|
+
|
|
204
|
+
# Run locally
|
|
205
|
+
QVERIS_API_KEY=your-key node dist/index.js
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## License
|
|
209
|
+
|
|
210
|
+
MIT © [QverisAI](https://github.com/qverisai)
|
|
211
|
+
|
|
212
|
+
## Support
|
|
213
|
+
|
|
214
|
+
- 🐛 [Issue Tracker](https://github.com/qverisai/mcp/issues)
|
|
215
|
+
- 💬 Contact: contact@qveris.ai
|
|
216
|
+
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Qveris API HTTP Client
|
|
3
|
+
*
|
|
4
|
+
* Provides a type-safe HTTP client for interacting with the Qveris REST API.
|
|
5
|
+
* Handles authentication, request formatting, and error handling.
|
|
6
|
+
*
|
|
7
|
+
* @module api/client
|
|
8
|
+
*/
|
|
9
|
+
import type { SearchRequest, SearchResponse, GetToolsByIdsRequest, ExecuteRequest, ExecuteResponse, QverisClientConfig } from '../types.js';
|
|
10
|
+
/**
|
|
11
|
+
* Qveris API Client
|
|
12
|
+
*
|
|
13
|
+
* A lightweight HTTP client for the Qveris API using native fetch.
|
|
14
|
+
* Requires Node.js 18+ for native fetch support.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* const client = new QverisClient({ apiKey: 'your-api-key' });
|
|
19
|
+
*
|
|
20
|
+
* // Search for tools
|
|
21
|
+
* const searchResult = await client.searchTools({
|
|
22
|
+
* query: 'weather API',
|
|
23
|
+
* limit: 5
|
|
24
|
+
* });
|
|
25
|
+
*
|
|
26
|
+
* // Execute a tool
|
|
27
|
+
* const execResult = await client.executeTool('tool-id', {
|
|
28
|
+
* search_id: searchResult.search_id,
|
|
29
|
+
* parameters: { city: 'London' }
|
|
30
|
+
* });
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
export declare class QverisClient {
|
|
34
|
+
private readonly apiKey;
|
|
35
|
+
private readonly baseUrl;
|
|
36
|
+
/**
|
|
37
|
+
* Creates a new Qveris API client.
|
|
38
|
+
*
|
|
39
|
+
* @param config - Client configuration
|
|
40
|
+
* @throws {Error} If apiKey is not provided
|
|
41
|
+
*/
|
|
42
|
+
constructor(config: QverisClientConfig);
|
|
43
|
+
/**
|
|
44
|
+
* Makes an authenticated HTTP request to the Qveris API.
|
|
45
|
+
*
|
|
46
|
+
* @param method - HTTP method
|
|
47
|
+
* @param endpoint - API endpoint (relative to base URL)
|
|
48
|
+
* @param body - Request body (will be JSON serialized)
|
|
49
|
+
* @returns Parsed JSON response
|
|
50
|
+
* @throws {ApiError} If the request fails
|
|
51
|
+
*/
|
|
52
|
+
private request;
|
|
53
|
+
/**
|
|
54
|
+
* Search for tools based on a natural language query.
|
|
55
|
+
*
|
|
56
|
+
* Finds tools that match the described capability. Results include
|
|
57
|
+
* tool metadata, parameter schemas, and usage examples.
|
|
58
|
+
*
|
|
59
|
+
* @param request - Search parameters
|
|
60
|
+
* @returns Search results with matching tools
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```typescript
|
|
64
|
+
* const result = await client.searchTools({
|
|
65
|
+
* query: 'send SMS message',
|
|
66
|
+
* limit: 10,
|
|
67
|
+
* session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456'
|
|
68
|
+
* });
|
|
69
|
+
*
|
|
70
|
+
* console.log(`Found ${result.total} tools`);
|
|
71
|
+
* for (const tool of result.results) {
|
|
72
|
+
* console.log(`- ${tool.name}: ${tool.description}`);
|
|
73
|
+
* }
|
|
74
|
+
* ```
|
|
75
|
+
*/
|
|
76
|
+
searchTools(request: SearchRequest): Promise<SearchResponse>;
|
|
77
|
+
/**
|
|
78
|
+
* Get tool descriptions by their IDs.
|
|
79
|
+
*
|
|
80
|
+
* Retrieves detailed information about specific tools when you already
|
|
81
|
+
* know their tool_ids. Useful for refreshing tool metadata or getting
|
|
82
|
+
* details for tools from previous searches.
|
|
83
|
+
*
|
|
84
|
+
* @param request - Request parameters with tool IDs
|
|
85
|
+
* @returns Tool information matching the provided IDs
|
|
86
|
+
*
|
|
87
|
+
* @example
|
|
88
|
+
* ```typescript
|
|
89
|
+
* const result = await client.getToolsByIds({
|
|
90
|
+
* tool_ids: ['weather-tool-1', 'email-tool-2'],
|
|
91
|
+
* search_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
|
|
92
|
+
* session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456'
|
|
93
|
+
* });
|
|
94
|
+
*
|
|
95
|
+
* console.log(`Retrieved ${result.results.length} tools`);
|
|
96
|
+
* for (const tool of result.results) {
|
|
97
|
+
* console.log(`- ${tool.name}: ${tool.description}`);
|
|
98
|
+
* }
|
|
99
|
+
* ```
|
|
100
|
+
*/
|
|
101
|
+
getToolsByIds(request: GetToolsByIdsRequest): Promise<SearchResponse>;
|
|
102
|
+
/**
|
|
103
|
+
* Execute a tool with the specified parameters.
|
|
104
|
+
*
|
|
105
|
+
* The tool_id must come from a previous searchTools call.
|
|
106
|
+
* The search_id links this execution to that search for analytics.
|
|
107
|
+
*
|
|
108
|
+
* @param toolId - The tool identifier from search results
|
|
109
|
+
* @param request - Execution parameters
|
|
110
|
+
* @returns Execution result
|
|
111
|
+
*
|
|
112
|
+
* @example
|
|
113
|
+
* ```typescript
|
|
114
|
+
* const result = await client.executeTool('openweathermap_current', {
|
|
115
|
+
* search_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
|
|
116
|
+
* session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
|
|
117
|
+
* parameters: {
|
|
118
|
+
* city: 'Tokyo',
|
|
119
|
+
* units: 'metric'
|
|
120
|
+
* }
|
|
121
|
+
* });
|
|
122
|
+
*
|
|
123
|
+
* if (result.success) {
|
|
124
|
+
* console.log('Result:', result.result);
|
|
125
|
+
* } else {
|
|
126
|
+
* console.error('Failed:', result.error_message);
|
|
127
|
+
* }
|
|
128
|
+
* ```
|
|
129
|
+
*/
|
|
130
|
+
executeTool(toolId: string, request: ExecuteRequest): Promise<ExecuteResponse>;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Creates a Qveris client from environment variables.
|
|
134
|
+
*
|
|
135
|
+
* Reads the API key from the QVERIS_API_KEY environment variable.
|
|
136
|
+
*
|
|
137
|
+
* @returns Configured Qveris client
|
|
138
|
+
* @throws {Error} If QVERIS_API_KEY is not set
|
|
139
|
+
*
|
|
140
|
+
* @example
|
|
141
|
+
* ```typescript
|
|
142
|
+
* // Ensure QVERIS_API_KEY is set in your environment
|
|
143
|
+
* const client = createClientFromEnv();
|
|
144
|
+
* ```
|
|
145
|
+
*/
|
|
146
|
+
export declare function createClientFromEnv(): QverisClient;
|
|
147
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
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,oBAAoB,EACpB,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;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Qveris API HTTP Client
|
|
3
|
+
*
|
|
4
|
+
* Provides a type-safe HTTP client for interacting with the Qveris REST API.
|
|
5
|
+
* Handles authentication, request formatting, and error handling.
|
|
6
|
+
*
|
|
7
|
+
* @module api/client
|
|
8
|
+
*/
|
|
9
|
+
/** Production API base URL */
|
|
10
|
+
const DEFAULT_BASE_URL = 'https://qveris.ai/api/v1';
|
|
11
|
+
/**
|
|
12
|
+
* Qveris API Client
|
|
13
|
+
*
|
|
14
|
+
* A lightweight HTTP client for the Qveris API using native fetch.
|
|
15
|
+
* Requires Node.js 18+ for native fetch support.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```typescript
|
|
19
|
+
* const client = new QverisClient({ apiKey: 'your-api-key' });
|
|
20
|
+
*
|
|
21
|
+
* // Search for tools
|
|
22
|
+
* const searchResult = await client.searchTools({
|
|
23
|
+
* query: 'weather API',
|
|
24
|
+
* limit: 5
|
|
25
|
+
* });
|
|
26
|
+
*
|
|
27
|
+
* // Execute a tool
|
|
28
|
+
* const execResult = await client.executeTool('tool-id', {
|
|
29
|
+
* search_id: searchResult.search_id,
|
|
30
|
+
* parameters: { city: 'London' }
|
|
31
|
+
* });
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
export class QverisClient {
|
|
35
|
+
apiKey;
|
|
36
|
+
baseUrl;
|
|
37
|
+
/**
|
|
38
|
+
* Creates a new Qveris API client.
|
|
39
|
+
*
|
|
40
|
+
* @param config - Client configuration
|
|
41
|
+
* @throws {Error} If apiKey is not provided
|
|
42
|
+
*/
|
|
43
|
+
constructor(config) {
|
|
44
|
+
if (!config.apiKey) {
|
|
45
|
+
throw new Error('Qveris API key is required');
|
|
46
|
+
}
|
|
47
|
+
this.apiKey = config.apiKey;
|
|
48
|
+
this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Makes an authenticated HTTP request to the Qveris API.
|
|
52
|
+
*
|
|
53
|
+
* @param method - HTTP method
|
|
54
|
+
* @param endpoint - API endpoint (relative to base URL)
|
|
55
|
+
* @param body - Request body (will be JSON serialized)
|
|
56
|
+
* @returns Parsed JSON response
|
|
57
|
+
* @throws {ApiError} If the request fails
|
|
58
|
+
*/
|
|
59
|
+
async request(method, endpoint, body) {
|
|
60
|
+
const url = `${this.baseUrl}${endpoint}`;
|
|
61
|
+
const response = await fetch(url, {
|
|
62
|
+
method,
|
|
63
|
+
headers: {
|
|
64
|
+
'Authorization': `Bearer ${this.apiKey}`,
|
|
65
|
+
'Content-Type': 'application/json',
|
|
66
|
+
},
|
|
67
|
+
body: body ? JSON.stringify(body) : undefined,
|
|
68
|
+
});
|
|
69
|
+
if (!response.ok) {
|
|
70
|
+
let errorMessage;
|
|
71
|
+
let errorDetails;
|
|
72
|
+
try {
|
|
73
|
+
const errorBody = (await response.json());
|
|
74
|
+
errorMessage =
|
|
75
|
+
errorBody.message ||
|
|
76
|
+
errorBody.error ||
|
|
77
|
+
response.statusText;
|
|
78
|
+
errorDetails = errorBody;
|
|
79
|
+
}
|
|
80
|
+
catch {
|
|
81
|
+
errorMessage = response.statusText || `HTTP ${response.status}`;
|
|
82
|
+
}
|
|
83
|
+
const error = {
|
|
84
|
+
status: response.status,
|
|
85
|
+
message: errorMessage,
|
|
86
|
+
details: errorDetails,
|
|
87
|
+
};
|
|
88
|
+
throw error;
|
|
89
|
+
}
|
|
90
|
+
return response.json();
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Search for tools based on a natural language query.
|
|
94
|
+
*
|
|
95
|
+
* Finds tools that match the described capability. Results include
|
|
96
|
+
* tool metadata, parameter schemas, and usage examples.
|
|
97
|
+
*
|
|
98
|
+
* @param request - Search parameters
|
|
99
|
+
* @returns Search results with matching tools
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```typescript
|
|
103
|
+
* const result = await client.searchTools({
|
|
104
|
+
* query: 'send SMS message',
|
|
105
|
+
* limit: 10,
|
|
106
|
+
* session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456'
|
|
107
|
+
* });
|
|
108
|
+
*
|
|
109
|
+
* console.log(`Found ${result.total} tools`);
|
|
110
|
+
* for (const tool of result.results) {
|
|
111
|
+
* console.log(`- ${tool.name}: ${tool.description}`);
|
|
112
|
+
* }
|
|
113
|
+
* ```
|
|
114
|
+
*/
|
|
115
|
+
async searchTools(request) {
|
|
116
|
+
return this.request('POST', '/search', request);
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Get tool descriptions by their IDs.
|
|
120
|
+
*
|
|
121
|
+
* Retrieves detailed information about specific tools when you already
|
|
122
|
+
* know their tool_ids. Useful for refreshing tool metadata or getting
|
|
123
|
+
* details for tools from previous searches.
|
|
124
|
+
*
|
|
125
|
+
* @param request - Request parameters with tool IDs
|
|
126
|
+
* @returns Tool information matching the provided IDs
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```typescript
|
|
130
|
+
* const result = await client.getToolsByIds({
|
|
131
|
+
* tool_ids: ['weather-tool-1', 'email-tool-2'],
|
|
132
|
+
* search_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
|
|
133
|
+
* session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456'
|
|
134
|
+
* });
|
|
135
|
+
*
|
|
136
|
+
* console.log(`Retrieved ${result.results.length} tools`);
|
|
137
|
+
* for (const tool of result.results) {
|
|
138
|
+
* console.log(`- ${tool.name}: ${tool.description}`);
|
|
139
|
+
* }
|
|
140
|
+
* ```
|
|
141
|
+
*/
|
|
142
|
+
async getToolsByIds(request) {
|
|
143
|
+
return this.request('POST', '/tools/by-ids', request);
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Execute a tool with the specified parameters.
|
|
147
|
+
*
|
|
148
|
+
* The tool_id must come from a previous searchTools call.
|
|
149
|
+
* The search_id links this execution to that search for analytics.
|
|
150
|
+
*
|
|
151
|
+
* @param toolId - The tool identifier from search results
|
|
152
|
+
* @param request - Execution parameters
|
|
153
|
+
* @returns Execution result
|
|
154
|
+
*
|
|
155
|
+
* @example
|
|
156
|
+
* ```typescript
|
|
157
|
+
* const result = await client.executeTool('openweathermap_current', {
|
|
158
|
+
* search_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
|
|
159
|
+
* session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
|
|
160
|
+
* parameters: {
|
|
161
|
+
* city: 'Tokyo',
|
|
162
|
+
* units: 'metric'
|
|
163
|
+
* }
|
|
164
|
+
* });
|
|
165
|
+
*
|
|
166
|
+
* if (result.success) {
|
|
167
|
+
* console.log('Result:', result.result);
|
|
168
|
+
* } else {
|
|
169
|
+
* console.error('Failed:', result.error_message);
|
|
170
|
+
* }
|
|
171
|
+
* ```
|
|
172
|
+
*/
|
|
173
|
+
async executeTool(toolId, request) {
|
|
174
|
+
const endpoint = `/tools/execute?tool_id=${encodeURIComponent(toolId)}`;
|
|
175
|
+
return this.request('POST', endpoint, request);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Creates a Qveris client from environment variables.
|
|
180
|
+
*
|
|
181
|
+
* Reads the API key from the QVERIS_API_KEY environment variable.
|
|
182
|
+
*
|
|
183
|
+
* @returns Configured Qveris client
|
|
184
|
+
* @throws {Error} If QVERIS_API_KEY is not set
|
|
185
|
+
*
|
|
186
|
+
* @example
|
|
187
|
+
* ```typescript
|
|
188
|
+
* // Ensure QVERIS_API_KEY is set in your environment
|
|
189
|
+
* const client = createClientFromEnv();
|
|
190
|
+
* ```
|
|
191
|
+
*/
|
|
192
|
+
export function createClientFromEnv() {
|
|
193
|
+
const apiKey = process.env.QVERIS_API_KEY;
|
|
194
|
+
if (!apiKey) {
|
|
195
|
+
throw new Error('QVERIS_API_KEY environment variable is required.\n' +
|
|
196
|
+
'Please set it to your Qveris API token.\n' +
|
|
197
|
+
'Contact Qveris to obtain an API token.');
|
|
198
|
+
}
|
|
199
|
+
return new QverisClient({ apiKey });
|
|
200
|
+
}
|
|
201
|
+
//# sourceMappingURL=client.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Qveris MCP Server
|
|
4
|
+
*
|
|
5
|
+
* A Model Context Protocol (MCP) server that provides access to the Qveris
|
|
6
|
+
* tool discovery and execution API. Enables LLMs to dynamically search for
|
|
7
|
+
* and execute third-party tools via natural language.
|
|
8
|
+
*
|
|
9
|
+
* @module @qverisai/mcp
|
|
10
|
+
* @version 0.1.0
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* Configure in Claude Desktop or Cursor:
|
|
14
|
+
* ```json
|
|
15
|
+
* {
|
|
16
|
+
* "mcpServers": {
|
|
17
|
+
* "qveris": {
|
|
18
|
+
* "command": "npx",
|
|
19
|
+
* "args": ["@qverisai/mcp"],
|
|
20
|
+
* "env": { "QVERIS_API_KEY": "your-api-key" }
|
|
21
|
+
* }
|
|
22
|
+
* }
|
|
23
|
+
* }
|
|
24
|
+
* ```
|
|
25
|
+
*/
|
|
26
|
+
export {};
|
|
27
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}
|