@qverisai/mcp 0.7.5 → 0.9.0
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/CHANGELOG.md +145 -0
- package/README.md +297 -236
- package/dist/api/client.d.ts +9 -0
- package/dist/api/client.d.ts.map +1 -1
- package/dist/api/client.js +113 -76
- package/dist/api/client.js.map +1 -1
- package/dist/http.d.ts +99 -0
- package/dist/http.d.ts.map +1 -0
- package/dist/http.js +564 -0
- package/dist/http.js.map +1 -0
- package/dist/index.d.ts +107 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +176 -60
- package/dist/index.js.map +1 -1
- package/dist/output-schemas.d.ts +12 -0
- package/dist/output-schemas.d.ts.map +1 -0
- package/dist/output-schemas.js +61 -0
- package/dist/output-schemas.js.map +1 -0
- package/dist/retry.d.ts +42 -0
- package/dist/retry.d.ts.map +1 -0
- package/dist/retry.js +69 -0
- package/dist/retry.js.map +1 -0
- package/dist/server-card.d.ts +85 -0
- package/dist/server-card.d.ts.map +1 -0
- package/dist/server-card.js +87 -0
- package/dist/server-card.js.map +1 -0
- package/dist/tools/audit-utils.d.ts.map +1 -1
- package/dist/tools/audit-utils.js +11 -16
- package/dist/tools/audit-utils.js.map +1 -1
- package/dist/tools/credits-ledger.d.ts +1 -2
- package/dist/tools/credits-ledger.d.ts.map +1 -1
- package/dist/tools/credits-ledger.js.map +1 -1
- package/dist/tools/execute.d.ts.map +1 -1
- package/dist/tools/execute.js.map +1 -1
- package/dist/tools/get-by-ids.d.ts.map +1 -1
- package/dist/tools/get-by-ids.js +1 -2
- package/dist/tools/get-by-ids.js.map +1 -1
- package/dist/tools/usage-history.d.ts +1 -2
- package/dist/tools/usage-history.d.ts.map +1 -1
- package/dist/tools/usage-history.js.map +1 -1
- package/dist/types.d.ts +6 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +70 -59
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
# @qverisai/mcp
|
|
2
|
-
|
|
3
|
-
Official QVeris MCP Server — 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
|
-
|
|
1
|
+
# @qverisai/mcp
|
|
2
|
+
|
|
3
|
+
Official QVeris MCP Server — 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
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 a small set of tools, your AI assistant can:
|
|
11
11
|
|
|
12
12
|
- **Discover** tools using natural language queries
|
|
@@ -14,13 +14,13 @@ This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.
|
|
|
14
14
|
- **Call** any discovered tool with the appropriate parameters
|
|
15
15
|
- **Audit usage** with context-safe summaries or precise filtered records
|
|
16
16
|
- **Review credits ledger** without dumping full account history into context
|
|
17
|
-
|
|
18
|
-
## Quick Start
|
|
19
|
-
|
|
20
|
-
### 1. Get Your API Key
|
|
21
|
-
|
|
22
|
-
Visit [QVeris](https://qveris.ai) (Global) or [QVeris](https://qveris.cn) (China) to get your API key.
|
|
23
|
-
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
### 1. Get Your API Key
|
|
21
|
+
|
|
22
|
+
Visit [QVeris](https://qveris.ai) (Global) or [QVeris](https://qveris.cn) (China) to get your API key.
|
|
23
|
+
|
|
24
24
|
### 2. Configure Your MCP Client
|
|
25
25
|
|
|
26
26
|
Use the QVeris CLI to generate config without hand-editing JSON. Placeholder output intentionally fails API key validation until you replace it or use `--include-key`:
|
|
@@ -43,112 +43,112 @@ qveris mcp validate --target cursor --probe
|
|
|
43
43
|
Add the QVeris server to your MCP client configuration:
|
|
44
44
|
|
|
45
45
|
**Claude Desktop** (`claude_desktop_config.json`):
|
|
46
|
-
|
|
47
|
-
```json
|
|
48
|
-
{
|
|
49
|
-
"mcpServers": {
|
|
50
|
-
"qveris": {
|
|
51
|
-
"command": "npx",
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"mcpServers": {
|
|
50
|
+
"qveris": {
|
|
51
|
+
"command": "npx",
|
|
52
52
|
"args": ["-y", "@qverisai/mcp"],
|
|
53
|
-
"env": {
|
|
54
|
-
"QVERIS_API_KEY": "your-api-key-here"
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
**Cursor** (Settings → MCP Servers):
|
|
62
|
-
|
|
63
|
-
```json
|
|
64
|
-
{
|
|
65
|
-
"mcpServers": {
|
|
66
|
-
"qveris": {
|
|
67
|
-
"command": "npx",
|
|
53
|
+
"env": {
|
|
54
|
+
"QVERIS_API_KEY": "your-api-key-here"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**Cursor** (Settings → MCP Servers):
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"qveris": {
|
|
67
|
+
"command": "npx",
|
|
68
68
|
"args": ["-y", "@qverisai/mcp"],
|
|
69
|
-
"env": {
|
|
70
|
-
"QVERIS_API_KEY": "your-api-key-here"
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
### 3. Start Using
|
|
78
|
-
|
|
79
|
-
Once configured, You could add this to system prompt:
|
|
80
|
-
|
|
81
|
-
> "You can use qveris MCP Server to dynamically discover and call tools to help the user. First think about what kind of tools might be useful to accomplish the user's task. Then use the discover tool with a query describing the capability of the tool, not what params you want to pass to the tool later. Then call a suitable tool using the call tool, passing parameters through params_to_tool. You could reference the examples given if any for each tool. You may make multiple tool calls in a single response."
|
|
82
|
-
|
|
83
|
-
Then your AI assistant can discover and call tools:
|
|
84
|
-
|
|
85
|
-
> "Find me a weather tool and get the current weather in Tokyo"
|
|
86
|
-
|
|
87
|
-
The assistant will:
|
|
88
|
-
1. Call `discover` with query "weather"
|
|
89
|
-
2. Optionally call `inspect` to review tool details
|
|
69
|
+
"env": {
|
|
70
|
+
"QVERIS_API_KEY": "your-api-key-here"
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### 3. Start Using
|
|
78
|
+
|
|
79
|
+
Once configured, You could add this to system prompt:
|
|
80
|
+
|
|
81
|
+
> "You can use qveris MCP Server to dynamically discover and call tools to help the user. First think about what kind of tools might be useful to accomplish the user's task. Then use the discover tool with a query describing the capability of the tool, not what params you want to pass to the tool later. Then call a suitable tool using the call tool, passing parameters through params_to_tool. You could reference the examples given if any for each tool. You may make multiple tool calls in a single response."
|
|
82
|
+
|
|
83
|
+
Then your AI assistant can discover and call tools:
|
|
84
|
+
|
|
85
|
+
> "Find me a weather tool and get the current weather in Tokyo"
|
|
86
|
+
|
|
87
|
+
The assistant will:
|
|
88
|
+
1. Call `discover` with query "weather"
|
|
89
|
+
2. Optionally call `inspect` to review tool details
|
|
90
90
|
3. Call `call` with the tool_id and parameters
|
|
91
91
|
4. Use `usage_history` or `credits_ledger` only when the user asks about charge status or balance changes
|
|
92
|
-
|
|
93
|
-
## Available Tools
|
|
94
|
-
|
|
95
|
-
### `discover`
|
|
96
|
-
|
|
97
|
-
Discover available tools based on natural language queries.
|
|
98
|
-
|
|
99
|
-
| Parameter | Type | Required | Description |
|
|
100
|
-
|-----------|------|----------|-------------|
|
|
101
|
-
| `query` | string | ✓ | Natural language description of the capability you need |
|
|
102
|
-
| `limit` | number | | Max results to return (1-100, default: 20) |
|
|
103
|
-
| `session_id` | string | | Session identifier for tracking (auto-generated if omitted) |
|
|
104
|
-
|
|
105
|
-
**Example:**
|
|
106
|
-
|
|
107
|
-
```json
|
|
108
|
-
{
|
|
109
|
-
"query": "send email notification",
|
|
110
|
-
"limit": 10
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### `inspect`
|
|
115
|
-
|
|
92
|
+
|
|
93
|
+
## Available Tools
|
|
94
|
+
|
|
95
|
+
### `discover`
|
|
96
|
+
|
|
97
|
+
Discover available tools based on natural language queries.
|
|
98
|
+
|
|
99
|
+
| Parameter | Type | Required | Description |
|
|
100
|
+
|-----------|------|----------|-------------|
|
|
101
|
+
| `query` | string | ✓ | Natural language description of the capability you need |
|
|
102
|
+
| `limit` | number | | Max results to return (1-100, default: 20) |
|
|
103
|
+
| `session_id` | string | | Session identifier for tracking (auto-generated if omitted) |
|
|
104
|
+
|
|
105
|
+
**Example:**
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"query": "send email notification",
|
|
110
|
+
"limit": 10
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### `inspect`
|
|
115
|
+
|
|
116
116
|
Inspect tools by their IDs to get detailed information (parameters, success rate, latency, examples, and billing_rule when available).
|
|
117
|
-
|
|
118
|
-
| Parameter | Type | Required | Description |
|
|
119
|
-
|-----------|------|----------|-------------|
|
|
120
|
-
| `tool_ids` | array | ✓ | Array of tool IDs to retrieve (at least one required) |
|
|
121
|
-
| `search_id` | string | | Search ID from the discover call that returned the tool(s) |
|
|
122
|
-
| `session_id` | string | | Session identifier (auto-generated if omitted) |
|
|
123
|
-
|
|
124
|
-
**Example:**
|
|
125
|
-
|
|
126
|
-
```json
|
|
127
|
-
{
|
|
128
|
-
"tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
|
|
129
|
-
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
|
|
130
|
-
}
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
### `call`
|
|
134
|
-
|
|
117
|
+
|
|
118
|
+
| Parameter | Type | Required | Description |
|
|
119
|
+
|-----------|------|----------|-------------|
|
|
120
|
+
| `tool_ids` | array | ✓ | Array of tool IDs to retrieve (at least one required) |
|
|
121
|
+
| `search_id` | string | | Search ID from the discover call that returned the tool(s) |
|
|
122
|
+
| `session_id` | string | | Session identifier (auto-generated if omitted) |
|
|
123
|
+
|
|
124
|
+
**Example:**
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
|
|
129
|
+
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### `call`
|
|
134
|
+
|
|
135
135
|
Call a discovered tool with specific parameters.
|
|
136
|
-
|
|
137
|
-
| Parameter | Type | Required | Description |
|
|
138
|
-
|-----------|------|----------|-------------|
|
|
139
|
-
| `tool_id` | string | ✓ | Tool ID from discover results |
|
|
140
|
-
| `search_id` | string | ✓ | Search ID from the discover call that found this tool |
|
|
141
|
-
| `params_to_tool` | object | ✓ | A dictionary of parameters to pass to the tool |
|
|
142
|
-
| `session_id` | string | | Session identifier (auto-generated if omitted) |
|
|
143
|
-
| `max_response_size` | number | | Max response size in bytes (default: 20480) |
|
|
144
|
-
|
|
145
|
-
**Example:**
|
|
146
|
-
|
|
147
|
-
```json
|
|
148
|
-
{
|
|
149
|
-
"tool_id": "openweathermap.weather.execute.v1",
|
|
150
|
-
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
|
|
151
|
-
"params_to_tool": {"city": "London", "units": "metric"}
|
|
136
|
+
|
|
137
|
+
| Parameter | Type | Required | Description |
|
|
138
|
+
|-----------|------|----------|-------------|
|
|
139
|
+
| `tool_id` | string | ✓ | Tool ID from discover results |
|
|
140
|
+
| `search_id` | string | ✓ | Search ID from the discover call that found this tool |
|
|
141
|
+
| `params_to_tool` | object | ✓ | A dictionary of parameters to pass to the tool |
|
|
142
|
+
| `session_id` | string | | Session identifier (auto-generated if omitted) |
|
|
143
|
+
| `max_response_size` | number | | Max response size in bytes (default: 20480) |
|
|
144
|
+
|
|
145
|
+
**Example:**
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"tool_id": "openweathermap.weather.execute.v1",
|
|
150
|
+
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
|
|
151
|
+
"params_to_tool": {"city": "London", "units": "metric"}
|
|
152
152
|
}
|
|
153
153
|
```
|
|
154
154
|
|
|
@@ -214,126 +214,187 @@ Examples:
|
|
|
214
214
|
```
|
|
215
215
|
|
|
216
216
|
Large result sets should use `mode: "export_file"`. The server writes JSONL under `.qveris/exports/` and returns the file path instead of emitting every row into MCP context.
|
|
217
|
-
|
|
218
|
-
### Deprecated tool names
|
|
219
|
-
|
|
220
|
-
For backward compatibility, the old tool names are still supported but emit a deprecation warning:
|
|
221
|
-
|
|
222
|
-
| Old name (deprecated) | New name |
|
|
223
|
-
|----------------------|----------|
|
|
224
|
-
| `search_tools` | `discover` |
|
|
225
|
-
| `get_tools_by_ids` | `inspect` |
|
|
226
|
-
| `execute_tool` | `call` |
|
|
227
|
-
|
|
228
|
-
##
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
-
|
|
232
|
-
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
**
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
217
|
+
|
|
218
|
+
### Deprecated tool names
|
|
219
|
+
|
|
220
|
+
For backward compatibility, the old tool names are still supported but emit a deprecation warning:
|
|
221
|
+
|
|
222
|
+
| Old name (deprecated) | New name |
|
|
223
|
+
|----------------------|----------|
|
|
224
|
+
| `search_tools` | `discover` |
|
|
225
|
+
| `get_tools_by_ids` | `inspect` |
|
|
226
|
+
| `execute_tool` | `call` |
|
|
227
|
+
|
|
228
|
+
## Beyond tools: schemas, consent, resources
|
|
229
|
+
|
|
230
|
+
- Every tool declares an `outputSchema` and returns `structuredContent` alongside the JSON text (MCP 2025-06-18), so clients get typed results.
|
|
231
|
+
- With `QVERIS_MCP_CONFIRM_CALLS=true`, a charged `call` first asks the user to confirm via MCP **elicitation** (billing consent); declining cancels the call before any credits are spent. Off by default.
|
|
232
|
+
- **Resources**: read `qveris://server-card` for the server's identity card, or `qveris://capability/{tool_id}` for a capability's full metadata (parameters, examples, stats, billing) without spending a tool call.
|
|
233
|
+
|
|
234
|
+
## Session Management
|
|
235
|
+
|
|
236
|
+
Providing a consistent `session_id` in a same user session in any tool call enables:
|
|
237
|
+
- Consistent user tracking across multiple tool calls
|
|
238
|
+
- Better analytics and usage patterns
|
|
239
|
+
- Improved tool recommendations over time
|
|
240
|
+
|
|
241
|
+
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.
|
|
242
|
+
|
|
243
|
+
## Response Handling
|
|
244
|
+
|
|
245
|
+
### Successful Execution
|
|
246
|
+
|
|
247
|
+
```json
|
|
248
|
+
{
|
|
249
|
+
"execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
|
|
250
|
+
"tool_id": "openweathermap.weather.execute.v1",
|
|
251
|
+
"success": true,
|
|
252
|
+
"result": {
|
|
253
|
+
"data": {
|
|
254
|
+
"temperature": 15.5,
|
|
255
|
+
"humidity": 72,
|
|
256
|
+
"description": "partly cloudy"
|
|
257
|
+
}
|
|
258
|
+
},
|
|
259
|
+
"execution_time": 0.847
|
|
260
|
+
}
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Large Responses
|
|
264
|
+
|
|
265
|
+
When tool output exceeds `max_response_size`, you'll receive:
|
|
266
|
+
|
|
267
|
+
```json
|
|
268
|
+
{
|
|
269
|
+
"result": {
|
|
270
|
+
"message": "Result content is too long...",
|
|
271
|
+
"truncated_content": "[[1678233600000, \"22198.56...",
|
|
272
|
+
"full_content_file_url": "https://..."
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
The `full_content_file_url` is valid for 120 minutes.
|
|
278
|
+
|
|
279
|
+
## Transport modes
|
|
280
|
+
|
|
281
|
+
The server speaks two MCP transports from the same binary:
|
|
282
|
+
|
|
283
|
+
- **stdio** (default) — used by Claude Desktop, Cursor and other local clients. No change to existing configs.
|
|
284
|
+
- **Streamable HTTP** — for remote deployment (e.g. Claude Desktop Custom Connectors, hosted/edge runtimes). Each client session gets its own session id (`Mcp-Session-Id` header), managed automatically.
|
|
285
|
+
|
|
286
|
+
Enable HTTP mode with any of `--http`, `QVERIS_MCP_TRANSPORT=http`, or by setting an HTTP port/host:
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
# Local only (loopback): no inbound auth required
|
|
290
|
+
QVERIS_API_KEY=sk-... npx -y @qverisai/mcp --http --port 3000
|
|
291
|
+
|
|
292
|
+
# Exposed: bind all interfaces, require a bearer token, allow-list the public host
|
|
293
|
+
QVERIS_API_KEY=sk-... \
|
|
294
|
+
QVERIS_MCP_TRANSPORT=http \
|
|
295
|
+
QVERIS_MCP_HTTP_HOST=0.0.0.0 \
|
|
296
|
+
QVERIS_MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
|
|
297
|
+
QVERIS_MCP_ALLOWED_HOSTS=mcp.example.com \
|
|
298
|
+
npx -y @qverisai/mcp
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
- The endpoint is `POST/GET/DELETE {path}` (default `/mcp`); `GET /health` returns an unauthenticated liveness probe.
|
|
302
|
+
- **Inbound auth:** set `QVERIS_MCP_HTTP_AUTH_TOKEN` to require `Authorization: Bearer <token>` on the MCP endpoint. The server **refuses to start** when binding a non-loopback host without a token, unless you set `QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED=true` to delegate auth to an external proxy/gateway. Your `QVERIS_API_KEY` is the server's *outbound* credential to QVeris — it is **not** an inbound check, so anyone reaching an unauthenticated endpoint would spend your credits.
|
|
303
|
+
- **Embedding API:** the package root exports `startHttpServer`, `resolveTransportConfig`, `QverisClient`, and the session-auth types. An independently operated service can set `requireSessionBearer` on its resolved transport config and provide an asynchronous session factory. The transport requires a bearer, passes it only to that factory, stores only a credential fingerprint for session binding, and rejects credential changes. The embedding service owns validation, client construction, rate limits, deployment, and operations.
|
|
304
|
+
- DNS-rebinding protection is **on by default** (localhost + the bound host/port are allow-listed). When exposing the server publicly, add your public host via `QVERIS_MCP_ALLOWED_HOSTS`.
|
|
305
|
+
- Requests are capped at 4 MiB by default (`QVERIS_MCP_MAX_BODY_BYTES`), and idle sessions are evicted after 5 minutes (`QVERIS_MCP_SESSION_TIMEOUT_MS`).
|
|
306
|
+
- **Discovery:** registries and crawlers can learn about the server without connecting:
|
|
307
|
+
- **Server Card** at `GET {path}/server-card` (default `/mcp/server-card`), media type `application/mcp-server-card+json` — server identity, version, and the remote endpoint.
|
|
308
|
+
- **MCP Catalog** at `GET /.well-known/mcp/catalog.json` — a site-wide index pointing at the Server Card.
|
|
309
|
+
- Both are public (unauthenticated, CORS-enabled), even when an auth token is set. Behind a TLS proxy, set `QVERIS_MCP_PUBLIC_URL` (or send `X-Forwarded-Proto`) so the advertised URLs use your public origin.
|
|
310
|
+
- Full OAuth 2.1 authorization is tracked as a follow-up in [#107](https://github.com/QVerisAI/qveris-agent-toolkit/issues/107).
|
|
311
|
+
|
|
312
|
+
## Environment Variables
|
|
313
|
+
|
|
314
|
+
| Variable | Required | Description |
|
|
315
|
+
|----------|----------|-------------|
|
|
316
|
+
| `QVERIS_API_KEY` | ✓ | Your QVeris API key |
|
|
317
|
+
| `QVERIS_REGION` | | Force region: `global` or `cn` (auto-detected from key prefix if not set) |
|
|
318
|
+
| `QVERIS_BASE_URL` | | Override API base URL (highest priority, for custom endpoints) |
|
|
319
|
+
| `QVERIS_MAX_RETRIES` | | Retries for rate-limited (429) / transient (503) responses (default 3; `0` disables). Honors `Retry-After`, else backs off with jitter. |
|
|
320
|
+
| `QVERIS_MCP_TRANSPORT` | | `stdio` (default) or `http` |
|
|
321
|
+
| `QVERIS_MCP_HTTP_PORT` | | HTTP port (default `3000`; setting it implies HTTP mode) |
|
|
322
|
+
| `QVERIS_MCP_HTTP_HOST` | | HTTP bind host (default `127.0.0.1`) |
|
|
323
|
+
| `QVERIS_MCP_HTTP_PATH` | | MCP endpoint path (default `/mcp`) |
|
|
324
|
+
| `QVERIS_MCP_ALLOWED_HOSTS` | | Comma-separated extra `Host` values to allow (for DNS-rebinding protection) |
|
|
325
|
+
| `QVERIS_MCP_ALLOWED_ORIGINS` | | Comma-separated extra `Origin` values to allow |
|
|
326
|
+
| `QVERIS_MCP_DNS_REBINDING_PROTECTION` | | `true` (default) / `false` |
|
|
327
|
+
| `QVERIS_MCP_HTTP_JSON` | | `true` to return JSON responses instead of SSE (default `false`) |
|
|
328
|
+
| `QVERIS_MCP_HTTP_AUTH_TOKEN` | | Require `Authorization: Bearer <token>` on the MCP endpoint |
|
|
329
|
+
| `QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED` | | `true` to allow a non-loopback bind without a token (auth delegated externally) |
|
|
330
|
+
| `QVERIS_MCP_MAX_BODY_BYTES` | | Max request body size in bytes (default `4194304`) |
|
|
331
|
+
| `QVERIS_MCP_SESSION_TIMEOUT_MS` | | Idle session TTL in ms (default `300000`) |
|
|
332
|
+
| `QVERIS_MCP_CONFIRM_CALLS` | | `true` to ask the user (via MCP elicitation) before each charged `call`; clients without elicitation proceed as before |
|
|
333
|
+
| `QVERIS_MCP_PUBLIC_URL` | | Public origin advertised in discovery documents (e.g. `https://mcp.example.com`) |
|
|
334
|
+
|
|
335
|
+
## Region
|
|
336
|
+
|
|
337
|
+
Region is auto-detected from your API key prefix — no extra configuration needed.
|
|
338
|
+
|
|
339
|
+
| Key prefix | Region | API endpoint |
|
|
340
|
+
|------------|--------|--------------|
|
|
341
|
+
| `sk-xxx` | Global | `https://qveris.ai/api/v1` |
|
|
342
|
+
| `sk-cn-xxx` | China | `https://qveris.cn/api/v1` |
|
|
343
|
+
|
|
344
|
+
To override manually, set environment variables in your MCP client config:
|
|
345
|
+
|
|
346
|
+
```json
|
|
347
|
+
{
|
|
348
|
+
"mcpServers": {
|
|
349
|
+
"qveris": {
|
|
350
|
+
"command": "npx",
|
|
351
|
+
"args": ["-y", "@qverisai/mcp"],
|
|
352
|
+
"env": {
|
|
353
|
+
"QVERIS_API_KEY": "your-api-key",
|
|
354
|
+
"QVERIS_REGION": "cn"
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
**Priority:** `QVERIS_BASE_URL` > `QVERIS_REGION` > API key prefix auto-detection > default (global)
|
|
362
|
+
|
|
363
|
+
## Examples
|
|
364
|
+
|
|
365
|
+
[`examples/agent-loop.ts`](examples/agent-loop.ts) drives this server over stdio
|
|
366
|
+
the way an agent runtime does: spawn it, list the tools, then run
|
|
367
|
+
discover → inspect → call by calling those tools. It is safe to run without an
|
|
368
|
+
API key (tool listing works unconfigured), and the call step is gated behind
|
|
369
|
+
`RUN_QVERIS_CALLS=1`.
|
|
370
|
+
|
|
371
|
+
## Requirements
|
|
372
|
+
|
|
373
|
+
- Node.js 18.0.0 or higher
|
|
374
|
+
- A valid QVeris API key ([qveris.ai](https://qveris.ai) or [qveris.cn](https://qveris.cn))
|
|
375
|
+
|
|
376
|
+
## Development
|
|
377
|
+
|
|
378
|
+
```bash
|
|
379
|
+
# Clone the repository
|
|
318
380
|
git clone https://github.com/QVerisAI/qveris-agent-toolkit.git
|
|
319
381
|
cd qveris-agent-toolkit/packages/mcp
|
|
320
|
-
|
|
321
|
-
# Install dependencies
|
|
322
|
-
npm install
|
|
323
|
-
|
|
324
|
-
# Build
|
|
325
|
-
npm run build
|
|
326
|
-
|
|
327
|
-
# Run locally
|
|
328
|
-
QVERIS_API_KEY=your-key node dist/index.js
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
## License
|
|
332
|
-
|
|
333
|
-
MIT © [QVerisAI](https://github.com/QVerisAI)
|
|
334
|
-
|
|
335
|
-
## Support
|
|
336
|
-
|
|
382
|
+
|
|
383
|
+
# Install dependencies
|
|
384
|
+
npm install
|
|
385
|
+
|
|
386
|
+
# Build
|
|
387
|
+
npm run build
|
|
388
|
+
|
|
389
|
+
# Run locally
|
|
390
|
+
QVERIS_API_KEY=your-key node dist/index.js
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
## License
|
|
394
|
+
|
|
395
|
+
MIT © [QVerisAI](https://github.com/QVerisAI)
|
|
396
|
+
|
|
397
|
+
## Support
|
|
398
|
+
|
|
337
399
|
- 🐛 [Issue Tracker](https://github.com/QVerisAI/qveris-agent-toolkit/issues)
|
|
338
|
-
- 💬 Contact: contact@qveris.ai
|
|
339
|
-
|
|
400
|
+
- 💬 Contact: contact@qveris.ai
|
package/dist/api/client.d.ts
CHANGED
|
@@ -32,7 +32,16 @@ export declare class QverisClient {
|
|
|
32
32
|
private readonly apiKey;
|
|
33
33
|
private readonly baseUrl;
|
|
34
34
|
private readonly defaultTimeoutMs;
|
|
35
|
+
private readonly maxRetries;
|
|
36
|
+
private rateLimitRetries;
|
|
35
37
|
constructor(config: QverisClientConfig);
|
|
38
|
+
/**
|
|
39
|
+
* How many times the client has backed off on a rate-limited (429) /
|
|
40
|
+
* transient (503) response so far — retried pressure, not failure.
|
|
41
|
+
*/
|
|
42
|
+
get rateLimitRetryCount(): number;
|
|
43
|
+
/** Sleep for `ms` (a seam so tests can stub out the wait). */
|
|
44
|
+
private sleep;
|
|
36
45
|
/**
|
|
37
46
|
* Makes an authenticated HTTP request to the Qveris API.
|
|
38
47
|
*/
|
package/dist/api/client.d.ts.map
CHANGED
|
@@ -1 +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,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,kBAAkB,EAInB,MAAM,aAAa,CAAC;
|
|
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,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,kBAAkB,EAInB,MAAM,aAAa,CAAC;AA0CrB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,MAAM,EAAE,kBAAkB;IAatC;;;OAGG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED,8DAA8D;YAChD,KAAK;IAKnB;;OAEG;YACW,OAAO;IA2IrB;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAIlE;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAI3E;;;;OAIG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAKpF;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;IAI3E;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IAWpH;;OAEG;IACG,gBAAgB,CACpB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAAC;CAUvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,CAiBlD"}
|