@qverisai/mcp 0.7.5 → 0.8.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 +127 -0
- package/README.md +149 -103
- package/dist/api/client.d.ts +9 -0
- package/dist/api/client.d.ts.map +1 -1
- package/dist/api/client.js +110 -68
- package/dist/api/client.js.map +1 -1
- package/dist/http.d.ts +78 -0
- package/dist/http.d.ts.map +1 -0
- package/dist/http.js +472 -0
- package/dist/http.js.map +1 -0
- package/dist/index.d.ts +14 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +62 -37
- package/dist/index.js.map +1 -1
- 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 +85 -0
- package/dist/server-card.js.map +1 -0
- package/dist/types.d.ts +6 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +59 -58
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@qverisai/mcp` are documented here.
|
|
4
|
+
|
|
5
|
+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.8.0] - 2026-07-09
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Streamable HTTP transport for remote MCP alongside the stdio default: per-session servers keyed by `Mcp-Session-Id`, optional inbound bearer auth (fail-closed on non-loopback binds), DNS-rebinding protection, request-body cap, and idle-session eviction. ([#139])
|
|
14
|
+
- Server Card (`GET {path}/server-card`) and MCP Catalog (`GET /.well-known/mcp/catalog.json`) discovery documents, so registries and crawlers can learn about the server without connecting. ([#140])
|
|
15
|
+
- Rate-limited (`429`) and transient (`503`) API responses are retried automatically: honors `Retry-After`, otherwise exponential backoff with jitter, bounded by `config.maxRetries` / `QVERIS_MAX_RETRIES` (default 3; `0` disables); `rateLimitRetryCount` exposes the backoff. ([#145])
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- Requires Node.js >= 18.2 (was >= 18.0): prompt HTTP-server shutdown uses `closeAllConnections`, added in 18.2. ([#139])
|
|
20
|
+
|
|
21
|
+
## [0.7.5] - 2026-07-07
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- The server starts without `QVERIS_API_KEY`: MCP clients and registry scanners can list tools before credentials are configured; tool calls return an actionable error until a key is set. ([#126])
|
|
26
|
+
|
|
27
|
+
## [0.7.4] - 2026-07-07
|
|
28
|
+
|
|
29
|
+
### Fixed
|
|
30
|
+
|
|
31
|
+
- `mcpName` casing (`io.github.QVerisAI/mcp`) required by the official MCP Registry ownership validation. ([#122])
|
|
32
|
+
|
|
33
|
+
## [0.7.3] - 2026-07-06
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
|
|
37
|
+
- `ToolInfo` declares `capabilities`, `expected_cost`, `why_recommended`, and `provider_id`, matching current Discover/Inspect responses. ([#102])
|
|
38
|
+
- `mcpName` and MCP registry metadata (`server.json`, Smithery, Glama) for directory listings. ([#117])
|
|
39
|
+
|
|
40
|
+
### Removed
|
|
41
|
+
|
|
42
|
+
- `provider_logo_url` from type declarations (dropped from the public spec). ([#105])
|
|
43
|
+
|
|
44
|
+
## [0.7.2] - 2026-07-06
|
|
45
|
+
|
|
46
|
+
### Fixed
|
|
47
|
+
|
|
48
|
+
- Accept object-shaped tool categories in discover/inspect results (legacy string tags still supported). ([#97])
|
|
49
|
+
- Hardened MCP probe and call params/observability paths. ([#85])
|
|
50
|
+
|
|
51
|
+
## [0.7.1] - 2026-06-13
|
|
52
|
+
|
|
53
|
+
### Fixed
|
|
54
|
+
|
|
55
|
+
- Hardened process-entrypoint detection, including npm bin symlinks.
|
|
56
|
+
|
|
57
|
+
## [0.7.0] - 2026-05-21
|
|
58
|
+
|
|
59
|
+
### Added
|
|
60
|
+
|
|
61
|
+
- Generated OpenAPI contract types with drift CI. ([#48])
|
|
62
|
+
- Canonical qveris tool names standardized across surfaces. ([#31])
|
|
63
|
+
|
|
64
|
+
## [0.6.0] - 2026-05-06
|
|
65
|
+
|
|
66
|
+
### Added
|
|
67
|
+
|
|
68
|
+
- Context-safe `usage_history` and `credits_ledger` audit tools. ([#18])
|
|
69
|
+
|
|
70
|
+
## [0.5.0] - 2026-04-09
|
|
71
|
+
|
|
72
|
+
### Changed
|
|
73
|
+
|
|
74
|
+
- Tools renamed to `discover` / `inspect` / `call`; the previous names remain as deprecated aliases. ([#14])
|
|
75
|
+
- Multi-region (global/China) support improvements. ([#13])
|
|
76
|
+
|
|
77
|
+
## [0.4.0] - 2026-04-04
|
|
78
|
+
|
|
79
|
+
### Added
|
|
80
|
+
|
|
81
|
+
- China region (`qveris.cn`) support. ([#9])
|
|
82
|
+
|
|
83
|
+
### Changed
|
|
84
|
+
|
|
85
|
+
- Monorepo restructure. ([#8])
|
|
86
|
+
|
|
87
|
+
## [0.3.0] / [0.2.0] - 2026-04-04
|
|
88
|
+
|
|
89
|
+
- Version bumps / republish; no functional changes.
|
|
90
|
+
|
|
91
|
+
## [0.1.2] - 2026-04-04
|
|
92
|
+
|
|
93
|
+
### Fixed
|
|
94
|
+
|
|
95
|
+
- Handle empty/non-JSON success responses gracefully; `params_to_tool` documented as an object.
|
|
96
|
+
|
|
97
|
+
[Unreleased]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.8.0...HEAD
|
|
98
|
+
[0.8.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.7.5...mcp-v0.8.0
|
|
99
|
+
[0.7.5]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.7.4...mcp-v0.7.5
|
|
100
|
+
[0.7.4]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.7.3...mcp-v0.7.4
|
|
101
|
+
[0.7.3]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.7.2...mcp-v0.7.3
|
|
102
|
+
[0.7.2]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.7.1...mcp-v0.7.2
|
|
103
|
+
[0.7.1]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.7.0...mcp-v0.7.1
|
|
104
|
+
[0.7.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.6.0...mcp-v0.7.0
|
|
105
|
+
[0.6.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.5.0...mcp-v0.6.0
|
|
106
|
+
[0.5.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.4.0...mcp-v0.5.0
|
|
107
|
+
[0.4.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.3.0...mcp-v0.4.0
|
|
108
|
+
[0.3.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.2.0...mcp-v0.3.0
|
|
109
|
+
[0.2.0]: https://github.com/QVerisAI/qveris-agent-toolkit/compare/mcp-v0.1.2...mcp-v0.2.0
|
|
110
|
+
[0.1.2]: https://github.com/QVerisAI/qveris-agent-toolkit/releases/tag/mcp-v0.1.2
|
|
111
|
+
[#145]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/145
|
|
112
|
+
[#140]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/140
|
|
113
|
+
[#139]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/139
|
|
114
|
+
[#126]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/126
|
|
115
|
+
[#122]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/122
|
|
116
|
+
[#117]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/117
|
|
117
|
+
[#105]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/105
|
|
118
|
+
[#102]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/102
|
|
119
|
+
[#97]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/97
|
|
120
|
+
[#85]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/85
|
|
121
|
+
[#48]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/48
|
|
122
|
+
[#31]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/31
|
|
123
|
+
[#18]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/18
|
|
124
|
+
[#14]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/14
|
|
125
|
+
[#13]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/13
|
|
126
|
+
[#9]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/9
|
|
127
|
+
[#8]: https://github.com/QVerisAI/qveris-agent-toolkit/pull/8
|
package/README.md
CHANGED
|
@@ -7,13 +7,13 @@ Official QVeris MCP Server — Dynamically search and execute tools via natural
|
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
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 a small set of tools, your AI assistant can:
|
|
11
|
-
|
|
12
|
-
- **Discover** tools using natural language queries
|
|
13
|
-
- **Inspect** detailed information about specific tools by their IDs
|
|
14
|
-
- **Call** any discovered tool with the appropriate parameters
|
|
15
|
-
- **Audit usage** with context-safe summaries or precise filtered records
|
|
16
|
-
- **Review credits ledger** without dumping full account history into context
|
|
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
|
+
|
|
12
|
+
- **Discover** tools using natural language queries
|
|
13
|
+
- **Inspect** detailed information about specific tools by their IDs
|
|
14
|
+
- **Call** any discovered tool with the appropriate parameters
|
|
15
|
+
- **Audit usage** with context-safe summaries or precise filtered records
|
|
16
|
+
- **Review credits ledger** without dumping full account history into context
|
|
17
17
|
|
|
18
18
|
## Quick Start
|
|
19
19
|
|
|
@@ -21,35 +21,35 @@ This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.
|
|
|
21
21
|
|
|
22
22
|
Visit [QVeris](https://qveris.ai) (Global) or [QVeris](https://qveris.cn) (China) to get your API key.
|
|
23
23
|
|
|
24
|
-
### 2. Configure Your MCP Client
|
|
25
|
-
|
|
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`:
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
# Print safe config with YOUR_QVERIS_API_KEY placeholder
|
|
30
|
-
qveris mcp configure --target cursor
|
|
31
|
-
|
|
32
|
-
# Write a working config using your resolved API key
|
|
33
|
-
qveris mcp configure --target cursor --write --include-key
|
|
34
|
-
qveris mcp configure --target claude-desktop --write --include-key
|
|
35
|
-
qveris mcp configure --target opencode --write --include-key
|
|
36
|
-
qveris mcp configure --target openclaw --write --include-key
|
|
37
|
-
|
|
38
|
-
# Validate config, or live-probe visible tools for stdio clients
|
|
39
|
-
qveris mcp validate --target cursor
|
|
40
|
-
qveris mcp validate --target cursor --probe
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Add the QVeris server to your MCP client configuration:
|
|
44
|
-
|
|
45
|
-
**Claude Desktop** (`claude_desktop_config.json`):
|
|
24
|
+
### 2. Configure Your MCP Client
|
|
25
|
+
|
|
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`:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# Print safe config with YOUR_QVERIS_API_KEY placeholder
|
|
30
|
+
qveris mcp configure --target cursor
|
|
31
|
+
|
|
32
|
+
# Write a working config using your resolved API key
|
|
33
|
+
qveris mcp configure --target cursor --write --include-key
|
|
34
|
+
qveris mcp configure --target claude-desktop --write --include-key
|
|
35
|
+
qveris mcp configure --target opencode --write --include-key
|
|
36
|
+
qveris mcp configure --target openclaw --write --include-key
|
|
37
|
+
|
|
38
|
+
# Validate config, or live-probe visible tools for stdio clients
|
|
39
|
+
qveris mcp validate --target cursor
|
|
40
|
+
qveris mcp validate --target cursor --probe
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Add the QVeris server to your MCP client configuration:
|
|
44
|
+
|
|
45
|
+
**Claude Desktop** (`claude_desktop_config.json`):
|
|
46
46
|
|
|
47
47
|
```json
|
|
48
48
|
{
|
|
49
49
|
"mcpServers": {
|
|
50
50
|
"qveris": {
|
|
51
51
|
"command": "npx",
|
|
52
|
-
"args": ["-y", "@qverisai/mcp"],
|
|
52
|
+
"args": ["-y", "@qverisai/mcp"],
|
|
53
53
|
"env": {
|
|
54
54
|
"QVERIS_API_KEY": "your-api-key-here"
|
|
55
55
|
}
|
|
@@ -65,7 +65,7 @@ Add the QVeris server to your MCP client configuration:
|
|
|
65
65
|
"mcpServers": {
|
|
66
66
|
"qveris": {
|
|
67
67
|
"command": "npx",
|
|
68
|
-
"args": ["-y", "@qverisai/mcp"],
|
|
68
|
+
"args": ["-y", "@qverisai/mcp"],
|
|
69
69
|
"env": {
|
|
70
70
|
"QVERIS_API_KEY": "your-api-key-here"
|
|
71
71
|
}
|
|
@@ -87,8 +87,8 @@ Then your AI assistant can discover and call tools:
|
|
|
87
87
|
The assistant will:
|
|
88
88
|
1. Call `discover` with query "weather"
|
|
89
89
|
2. Optionally call `inspect` to review tool details
|
|
90
|
-
3. Call `call` with the tool_id and parameters
|
|
91
|
-
4. Use `usage_history` or `credits_ledger` only when the user asks about charge status or balance changes
|
|
90
|
+
3. Call `call` with the tool_id and parameters
|
|
91
|
+
4. Use `usage_history` or `credits_ledger` only when the user asks about charge status or balance changes
|
|
92
92
|
|
|
93
93
|
## Available Tools
|
|
94
94
|
|
|
@@ -113,7 +113,7 @@ Discover available tools based on natural language queries.
|
|
|
113
113
|
|
|
114
114
|
### `inspect`
|
|
115
115
|
|
|
116
|
-
Inspect tools by their IDs to get detailed information (parameters, success rate, latency, examples, and billing_rule when available).
|
|
116
|
+
Inspect tools by their IDs to get detailed information (parameters, success rate, latency, examples, and billing_rule when available).
|
|
117
117
|
|
|
118
118
|
| Parameter | Type | Required | Description |
|
|
119
119
|
|-----------|------|----------|-------------|
|
|
@@ -132,7 +132,7 @@ Inspect tools by their IDs to get detailed information (parameters, success rate
|
|
|
132
132
|
|
|
133
133
|
### `call`
|
|
134
134
|
|
|
135
|
-
Call a discovered tool with specific parameters.
|
|
135
|
+
Call a discovered tool with specific parameters.
|
|
136
136
|
|
|
137
137
|
| Parameter | Type | Required | Description |
|
|
138
138
|
|-----------|------|----------|-------------|
|
|
@@ -149,71 +149,71 @@ Call a discovered tool with specific parameters.
|
|
|
149
149
|
"tool_id": "openweathermap.weather.execute.v1",
|
|
150
150
|
"search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
|
|
151
151
|
"params_to_tool": {"city": "London", "units": "metric"}
|
|
152
|
-
}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
The `call` response may include compact pre-settlement `billing`. Final charge status should be checked with `usage_history` or `credits_ledger`.
|
|
156
|
-
|
|
157
|
-
### `usage_history`
|
|
158
|
-
|
|
159
|
-
Context-safe request-level usage audit. Defaults to aggregated `summary` mode.
|
|
160
|
-
Summary mode requests service-side `summary=true` aggregates when available and falls back to bounded client-side aggregation for older deployments.
|
|
161
|
-
|
|
162
|
-
| Parameter | Type | Required | Description |
|
|
163
|
-
|-----------|------|----------|-------------|
|
|
164
|
-
| `mode` | string | | `summary`, `search`, or `export_file` (default: `summary`) |
|
|
165
|
-
| `start_date` | string | | Start date, `YYYY-MM-DD` |
|
|
166
|
-
| `end_date` | string | | End date, `YYYY-MM-DD` |
|
|
167
|
-
| `bucket` | string | | `hour`, `day`, or `week` for summary aggregation |
|
|
168
|
-
| `execution_id` | string | | Precise execution lookup |
|
|
169
|
-
| `search_id` | string | | Precise search lookup |
|
|
170
|
-
| `charge_outcome` | string | | `charged`, `included`, `failed_not_charged`, `failed_charged_review` |
|
|
171
|
-
| `min_credits` | number | | Lower credit amount bound |
|
|
172
|
-
| `max_credits` | number | | Upper credit amount bound |
|
|
173
|
-
| `limit` | number | | Search row cap, default 10, hard max 50 |
|
|
174
|
-
|
|
175
|
-
Examples:
|
|
176
|
-
|
|
177
|
-
```json
|
|
178
|
-
{ "mode": "summary", "bucket": "hour" }
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
```json
|
|
182
|
-
{ "mode": "search", "execution_id": "exec-123" }
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
```json
|
|
186
|
-
{ "mode": "search", "min_credits": 30, "max_credits": 100 }
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
### `credits_ledger`
|
|
190
|
-
|
|
191
|
-
Context-safe final credit ledger query. Defaults to aggregated `summary` mode.
|
|
192
|
-
Summary mode requests service-side `summary=true` aggregates when available and falls back to bounded client-side aggregation for older deployments.
|
|
193
|
-
|
|
194
|
-
| Parameter | Type | Required | Description |
|
|
195
|
-
|-----------|------|----------|-------------|
|
|
196
|
-
| `mode` | string | | `summary`, `search`, or `export_file` (default: `summary`) |
|
|
197
|
-
| `start_date` | string | | Start date, `YYYY-MM-DD` |
|
|
198
|
-
| `end_date` | string | | End date, `YYYY-MM-DD` |
|
|
199
|
-
| `bucket` | string | | `hour`, `day`, or `week` for summary aggregation |
|
|
200
|
-
| `entry_type` | string | | Ledger entry type, for example `consume_tool_execute` |
|
|
201
|
-
| `direction` | string | | `consume`, `grant`, or `any` |
|
|
202
|
-
| `min_credits` | number | | Lower absolute credit amount bound |
|
|
203
|
-
| `max_credits` | number | | Upper absolute credit amount bound |
|
|
204
|
-
| `limit` | number | | Search row cap, default 10, hard max 50 |
|
|
205
|
-
|
|
206
|
-
Examples:
|
|
207
|
-
|
|
208
|
-
```json
|
|
209
|
-
{ "mode": "summary", "bucket": "day" }
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
```json
|
|
213
|
-
{ "mode": "search", "direction": "consume", "min_credits": 50 }
|
|
214
|
-
```
|
|
215
|
-
|
|
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.
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The `call` response may include compact pre-settlement `billing`. Final charge status should be checked with `usage_history` or `credits_ledger`.
|
|
156
|
+
|
|
157
|
+
### `usage_history`
|
|
158
|
+
|
|
159
|
+
Context-safe request-level usage audit. Defaults to aggregated `summary` mode.
|
|
160
|
+
Summary mode requests service-side `summary=true` aggregates when available and falls back to bounded client-side aggregation for older deployments.
|
|
161
|
+
|
|
162
|
+
| Parameter | Type | Required | Description |
|
|
163
|
+
|-----------|------|----------|-------------|
|
|
164
|
+
| `mode` | string | | `summary`, `search`, or `export_file` (default: `summary`) |
|
|
165
|
+
| `start_date` | string | | Start date, `YYYY-MM-DD` |
|
|
166
|
+
| `end_date` | string | | End date, `YYYY-MM-DD` |
|
|
167
|
+
| `bucket` | string | | `hour`, `day`, or `week` for summary aggregation |
|
|
168
|
+
| `execution_id` | string | | Precise execution lookup |
|
|
169
|
+
| `search_id` | string | | Precise search lookup |
|
|
170
|
+
| `charge_outcome` | string | | `charged`, `included`, `failed_not_charged`, `failed_charged_review` |
|
|
171
|
+
| `min_credits` | number | | Lower credit amount bound |
|
|
172
|
+
| `max_credits` | number | | Upper credit amount bound |
|
|
173
|
+
| `limit` | number | | Search row cap, default 10, hard max 50 |
|
|
174
|
+
|
|
175
|
+
Examples:
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{ "mode": "summary", "bucket": "hour" }
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{ "mode": "search", "execution_id": "exec-123" }
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{ "mode": "search", "min_credits": 30, "max_credits": 100 }
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### `credits_ledger`
|
|
190
|
+
|
|
191
|
+
Context-safe final credit ledger query. Defaults to aggregated `summary` mode.
|
|
192
|
+
Summary mode requests service-side `summary=true` aggregates when available and falls back to bounded client-side aggregation for older deployments.
|
|
193
|
+
|
|
194
|
+
| Parameter | Type | Required | Description |
|
|
195
|
+
|-----------|------|----------|-------------|
|
|
196
|
+
| `mode` | string | | `summary`, `search`, or `export_file` (default: `summary`) |
|
|
197
|
+
| `start_date` | string | | Start date, `YYYY-MM-DD` |
|
|
198
|
+
| `end_date` | string | | End date, `YYYY-MM-DD` |
|
|
199
|
+
| `bucket` | string | | `hour`, `day`, or `week` for summary aggregation |
|
|
200
|
+
| `entry_type` | string | | Ledger entry type, for example `consume_tool_execute` |
|
|
201
|
+
| `direction` | string | | `consume`, `grant`, or `any` |
|
|
202
|
+
| `min_credits` | number | | Lower absolute credit amount bound |
|
|
203
|
+
| `max_credits` | number | | Upper absolute credit amount bound |
|
|
204
|
+
| `limit` | number | | Search row cap, default 10, hard max 50 |
|
|
205
|
+
|
|
206
|
+
Examples:
|
|
207
|
+
|
|
208
|
+
```json
|
|
209
|
+
{ "mode": "summary", "bucket": "day" }
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
```json
|
|
213
|
+
{ "mode": "search", "direction": "consume", "min_credits": 50 }
|
|
214
|
+
```
|
|
215
|
+
|
|
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
217
|
|
|
218
218
|
### Deprecated tool names
|
|
219
219
|
|
|
@@ -270,6 +270,38 @@ When tool output exceeds `max_response_size`, you'll receive:
|
|
|
270
270
|
|
|
271
271
|
The `full_content_file_url` is valid for 120 minutes.
|
|
272
272
|
|
|
273
|
+
## Transport modes
|
|
274
|
+
|
|
275
|
+
The server speaks two MCP transports from the same binary:
|
|
276
|
+
|
|
277
|
+
- **stdio** (default) — used by Claude Desktop, Cursor and other local clients. No change to existing configs.
|
|
278
|
+
- **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.
|
|
279
|
+
|
|
280
|
+
Enable HTTP mode with any of `--http`, `QVERIS_MCP_TRANSPORT=http`, or by setting an HTTP port/host:
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
# Local only (loopback): no inbound auth required
|
|
284
|
+
QVERIS_API_KEY=sk-... npx -y @qverisai/mcp --http --port 3000
|
|
285
|
+
|
|
286
|
+
# Exposed: bind all interfaces, require a bearer token, allow-list the public host
|
|
287
|
+
QVERIS_API_KEY=sk-... \
|
|
288
|
+
QVERIS_MCP_TRANSPORT=http \
|
|
289
|
+
QVERIS_MCP_HTTP_HOST=0.0.0.0 \
|
|
290
|
+
QVERIS_MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
|
|
291
|
+
QVERIS_MCP_ALLOWED_HOSTS=mcp.example.com \
|
|
292
|
+
npx -y @qverisai/mcp
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
- The endpoint is `POST/GET/DELETE {path}` (default `/mcp`); `GET /health` returns an unauthenticated liveness probe.
|
|
296
|
+
- **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.
|
|
297
|
+
- 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`.
|
|
298
|
+
- 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`).
|
|
299
|
+
- **Discovery:** registries and crawlers can learn about the server without connecting:
|
|
300
|
+
- **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.
|
|
301
|
+
- **MCP Catalog** at `GET /.well-known/mcp/catalog.json` — a site-wide index pointing at the Server Card.
|
|
302
|
+
- 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.
|
|
303
|
+
- Full OAuth 2.1 authorization is tracked as a follow-up in [#107](https://github.com/QVerisAI/qveris-agent-toolkit/issues/107).
|
|
304
|
+
|
|
273
305
|
## Environment Variables
|
|
274
306
|
|
|
275
307
|
| Variable | Required | Description |
|
|
@@ -277,6 +309,20 @@ The `full_content_file_url` is valid for 120 minutes.
|
|
|
277
309
|
| `QVERIS_API_KEY` | ✓ | Your QVeris API key |
|
|
278
310
|
| `QVERIS_REGION` | | Force region: `global` or `cn` (auto-detected from key prefix if not set) |
|
|
279
311
|
| `QVERIS_BASE_URL` | | Override API base URL (highest priority, for custom endpoints) |
|
|
312
|
+
| `QVERIS_MAX_RETRIES` | | Retries for rate-limited (429) / transient (503) responses (default 3; `0` disables). Honors `Retry-After`, else backs off with jitter. |
|
|
313
|
+
| `QVERIS_MCP_TRANSPORT` | | `stdio` (default) or `http` |
|
|
314
|
+
| `QVERIS_MCP_HTTP_PORT` | | HTTP port (default `3000`; setting it implies HTTP mode) |
|
|
315
|
+
| `QVERIS_MCP_HTTP_HOST` | | HTTP bind host (default `127.0.0.1`) |
|
|
316
|
+
| `QVERIS_MCP_HTTP_PATH` | | MCP endpoint path (default `/mcp`) |
|
|
317
|
+
| `QVERIS_MCP_ALLOWED_HOSTS` | | Comma-separated extra `Host` values to allow (for DNS-rebinding protection) |
|
|
318
|
+
| `QVERIS_MCP_ALLOWED_ORIGINS` | | Comma-separated extra `Origin` values to allow |
|
|
319
|
+
| `QVERIS_MCP_DNS_REBINDING_PROTECTION` | | `true` (default) / `false` |
|
|
320
|
+
| `QVERIS_MCP_HTTP_JSON` | | `true` to return JSON responses instead of SSE (default `false`) |
|
|
321
|
+
| `QVERIS_MCP_HTTP_AUTH_TOKEN` | | Require `Authorization: Bearer <token>` on the MCP endpoint |
|
|
322
|
+
| `QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED` | | `true` to allow a non-loopback bind without a token (auth delegated externally) |
|
|
323
|
+
| `QVERIS_MCP_MAX_BODY_BYTES` | | Max request body size in bytes (default `4194304`) |
|
|
324
|
+
| `QVERIS_MCP_SESSION_TIMEOUT_MS` | | Idle session TTL in ms (default `300000`) |
|
|
325
|
+
| `QVERIS_MCP_PUBLIC_URL` | | Public origin advertised in discovery documents (e.g. `https://mcp.example.com`) |
|
|
280
326
|
|
|
281
327
|
## Region
|
|
282
328
|
|
|
@@ -315,8 +361,8 @@ To override manually, set environment variables in your MCP client config:
|
|
|
315
361
|
|
|
316
362
|
```bash
|
|
317
363
|
# Clone the repository
|
|
318
|
-
git clone https://github.com/QVerisAI/qveris-agent-toolkit.git
|
|
319
|
-
cd qveris-agent-toolkit/packages/mcp
|
|
364
|
+
git clone https://github.com/QVerisAI/qveris-agent-toolkit.git
|
|
365
|
+
cd qveris-agent-toolkit/packages/mcp
|
|
320
366
|
|
|
321
367
|
# Install dependencies
|
|
322
368
|
npm install
|
|
@@ -334,6 +380,6 @@ MIT © [QVerisAI](https://github.com/QVerisAI)
|
|
|
334
380
|
|
|
335
381
|
## Support
|
|
336
382
|
|
|
337
|
-
- 🐛 [Issue Tracker](https://github.com/QVerisAI/qveris-agent-toolkit/issues)
|
|
383
|
+
- 🐛 [Issue Tracker](https://github.com/QVerisAI/qveris-agent-toolkit/issues)
|
|
338
384
|
- 💬 Contact: contact@qveris.ai
|
|
339
385
|
|
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;IA+IrB;;;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,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;IAW3B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;IAI3E;;OAEG;IACG,eAAe,CACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IAWlE;;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"}
|