@layervai/qurl-mcp 0.6.0 → 0.7.1
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/README.md +245 -18
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -3
- package/dist/index.js.map +1 -1
- package/dist/qurl-cli.d.ts +96 -0
- package/dist/qurl-cli.d.ts.map +1 -0
- package/dist/qurl-cli.js +331 -0
- package/dist/qurl-cli.js.map +1 -0
- package/dist/server.d.ts +11 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +34 -0
- package/dist/server.js.map +1 -1
- package/dist/services/email.d.ts.map +1 -1
- package/dist/services/email.js.map +1 -1
- package/dist/tools/consumer-access.d.ts +6 -6
- package/dist/tools/local-cli.d.ts +44 -0
- package/dist/tools/local-cli.d.ts.map +1 -0
- package/dist/tools/local-cli.js +885 -0
- package/dist/tools/local-cli.js.map +1 -0
- package/dist/tools/share-by-crid.d.ts +2 -0
- package/dist/tools/share-by-crid.d.ts.map +1 -1
- package/dist/tools/share-by-crid.js +2 -2
- package/dist/tools/share-by-crid.js.map +1 -1
- package/dist/tools/upload-text-qurl.d.ts +3 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,14 +1,132 @@
|
|
|
1
|
-
#
|
|
1
|
+
# qURL MCP server for temporary access links
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@layervai/qurl-mcp)
|
|
4
4
|
|
|
5
|
+
Give an AI agent tools to share localhost web apps, private APIs, and selected
|
|
6
|
+
files through expiring [qURL™ by LayerV](https://layerv.ai/qurl/) access links.
|
|
7
|
+
This repository implements the Model Context Protocol server for that workflow.
|
|
8
|
+
The `@layervai/qurl-mcp` package runs as a local stdio server backed by the
|
|
9
|
+
qURL CLI or API, or as an authenticated remote HTTP server backed by the API.
|
|
10
|
+
|
|
11
|
+
Start with the [no-account local quickstart](#quick-start-no-account-needed)
|
|
12
|
+
or [account-backed client configuration](#mcp-client-example), then choose
|
|
13
|
+
the tools for your task. In local mode, `publish_crid` runs the installed
|
|
14
|
+
CLI to publish an app that is already running; `share_by_crid` issues its
|
|
15
|
+
access link. Creating a link alone does not publish an app or restrict an
|
|
16
|
+
existing public URL. Uploads require the account-backed tool set and use a separate connector lifecycle;
|
|
17
|
+
see [upload tools](#upload-tools) for their supported options and limits.
|
|
18
|
+
|
|
19
|
+
[Local app sharing](#let-an-ai-agent-share-a-localhost-preview) ·
|
|
20
|
+
[File sharing](#let-an-ai-agent-share-a-pdf-or-image) ·
|
|
21
|
+
[Sharing questions](#mcp-sharing-questions) · [Private links](https://qurl.link/)
|
|
22
|
+
|
|
5
23
|
> **⚠️ Renamed from `@layerv/qurl-mcp` in v0.4.0.** The old package is deprecated and will not receive further updates. If you're using `@layerv/qurl-mcp@0.3.x`, swap the scope in your MCP client config — same binary, same API key, no other changes.
|
|
6
24
|
|
|
7
|
-
|
|
25
|
+
## Let an AI agent share a localhost preview
|
|
26
|
+
|
|
27
|
+
Use this workflow when an agent needs to give a reviewer access to a development
|
|
28
|
+
preview or internal API. A tool that creates a link does not start the app on
|
|
29
|
+
your laptop.
|
|
30
|
+
|
|
31
|
+
1. Keep the local app running. Configure a local stdio MCP client using the
|
|
32
|
+
[no-account quickstart](#quick-start-no-account-needed), with the qURL CLI
|
|
33
|
+
installed on the same host and no `QURL_API_KEY` set.
|
|
34
|
+
2. Ask the agent to call `publish_crid` with `app_name` (a short public name, without secrets or recipient details) and the app's root loopback URL, such
|
|
35
|
+
as `http://127.0.0.1:3000`, and save the returned CRID. Alternatively, publish
|
|
36
|
+
it directly with the [CLI](https://github.com/layervai/qurl-integrations#share-a-localhost-web-app).
|
|
37
|
+
Local tools use that machine's device identity; a CRID does not grant another
|
|
38
|
+
device authority over the resource.
|
|
39
|
+
3. Ask the agent to call `share_by_crid` with the published CRID and a requested
|
|
40
|
+
lifetime. The following is a tool argument object, not a complete MCP message:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"crid": "REPLACE_WITH_PUBLISHED_CRID",
|
|
45
|
+
"ttl": "5m"
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
4. Share the full returned link through your intended private channel and
|
|
50
|
+
report the expiry returned by the service. Do not assume the requested TTL
|
|
51
|
+
was granted unchanged. Keep the publishing host and app available.
|
|
52
|
+
|
|
53
|
+
Check that your installed release exposes these tools. In account-backed mode,
|
|
54
|
+
`share_by_crid` instead uses the API credential and requires `qurl:resolve` and
|
|
55
|
+
resource authorization. For resources already managed through the API, see `mint_link` and the other
|
|
56
|
+
[link-management tools](#qurl-management-tools). Tool availability and resource
|
|
57
|
+
identifiers matter; an uploaded-file identifier cannot be substituted into
|
|
58
|
+
the same workflow.
|
|
59
|
+
|
|
60
|
+
## Let an AI agent share a PDF or image
|
|
61
|
+
|
|
62
|
+
For example, give a reviewer a short-lived link to a selected PDF report.
|
|
63
|
+
Use account-backed stdio mode (`QURL_API_KEY` set) or authenticated HTTP mode,
|
|
64
|
+
then configure the upload Connector under [configuration files](#configuration-files).
|
|
65
|
+
Upload tools are not listed in no-account local mode. Choose the tool for the transport:
|
|
66
|
+
|
|
67
|
+
| File location | Tool | Important requirement |
|
|
68
|
+
| --- | --- | --- |
|
|
69
|
+
| A PDF or supported raster image on the local MCP server host | `upload_file_qurl` | Available in stdio mode; the host process must be allowed to read the selected file. |
|
|
70
|
+
| PDF or image bytes supplied to an HTTP or stdio MCP client | `upload_file_data_qurl` | Supply the supported file as base64 data with the correct filename and media type. |
|
|
71
|
+
| Text to share as a generated PDF | `upload_text_qurl` | Uses the configured upload service, rather than publishing a local app. |
|
|
72
|
+
|
|
73
|
+
A stdio tool argument example:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"file_path": "/absolute/path/to/review.pdf",
|
|
78
|
+
"expires_in": "5m",
|
|
79
|
+
"one_time_use": true
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Pass these arguments to `upload_file_qurl` only for a file the user selected.
|
|
84
|
+
The tool uploads to the configured file service and returns a new access link.
|
|
85
|
+
Use the confirmed expiry in its response. Opening a single-use link to test it
|
|
86
|
+
can consume it before the recipient opens it.
|
|
87
|
+
|
|
88
|
+
Upload links cannot currently be revoked through this MCP server, and `mint_link`
|
|
89
|
+
cannot create another link for an uploaded file. See [upload tools](#upload-tools)
|
|
90
|
+
for the supported formats, size limits, response fields, and cleanup limitations.
|
|
91
|
+
|
|
92
|
+
## Choosing what an agent should share
|
|
93
|
+
|
|
94
|
+
### Should the agent share an app or a deployed preview?
|
|
95
|
+
|
|
96
|
+
If the reviewer needs the current localhost app, keep it running and use the [local CLI-backed tools](#quick-start-no-account-needed) to publish the resource and issue its link. An existing ngrok endpoint, Cloudflare application, or Vercel preview is another possible handoff, but its access controls and availability come from that separately configured service. This server exposes qURL operations; it does not create those other deployments. See the [app-sharing comparison](https://github.com/layervai/qurl-integrations#should-i-share-the-running-app-or-deploy-a-preview) when choosing the workflow. Share the confirmed expiry and preserve the app's login requirements.
|
|
97
|
+
|
|
98
|
+
### Should the agent upload the result or link to a running file service?
|
|
99
|
+
|
|
100
|
+
A selected PDF or image can use this server's [account-backed upload tools](#upload-tools). A hosted Google Drive document instead uses Drive's [sharing permissions](https://support.google.com/drive/answer/2494822?hl=en); an S3 object can use a [presigned download URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html). Those storage workflows are distinct from publishing a local file server, which must remain available. Choose based on where the result should live and which service the agent is authorized to use. This server's upload identifiers and revocation limits still apply; a file path, uploaded-file identifier, and local-service CRID are not interchangeable.
|
|
101
|
+
|
|
102
|
+
## MCP sharing questions
|
|
103
|
+
|
|
104
|
+
### Is this a public tunnel to my localhost app?
|
|
105
|
+
|
|
106
|
+
In no-account stdio mode, this server invokes the local CLI to publish and
|
|
107
|
+
manage an already running app. API-backed and remote HTTP modes use their
|
|
108
|
+
configured resources; a remote server cannot publish an app on your laptop
|
|
109
|
+
through its own localhost address. Use the
|
|
110
|
+
[localhost-sharing comparison](https://github.com/layervai/qurl-integrations#choose-how-to-share-an-app-or-file)
|
|
111
|
+
when choosing between resource access links and a public endpoint workflow.
|
|
112
|
+
|
|
113
|
+
### Does every AI client support the same tools?
|
|
114
|
+
|
|
115
|
+
No. Configure the client's supported transport and check the installed server's
|
|
116
|
+
tool list. A remote HTTP server cannot use `upload_file_qurl` to read a file
|
|
117
|
+
from the client's laptop; use the file-data tool for a supported attachment.
|
|
118
|
+
|
|
119
|
+
### Can I use an app link and an uploaded-file link interchangeably?
|
|
120
|
+
|
|
121
|
+
No. App resource management and uploaded-file link minting use different
|
|
122
|
+
lifecycles. Follow the tool that issued the link, including its revocation limits.
|
|
123
|
+
Your local app's own login continues to apply when the link opens it.
|
|
8
124
|
|
|
9
125
|
## Overview
|
|
10
126
|
|
|
11
|
-
|
|
127
|
+
The server exposes qURL operations as MCP tools for clients that support the
|
|
128
|
+
configured transport. See the [LayerV MCP guide](https://layerv.ai/mcp/) for
|
|
129
|
+
product setup and the tables below for the capabilities in this source version.
|
|
12
130
|
|
|
13
131
|
It currently supports:
|
|
14
132
|
|
|
@@ -19,6 +137,117 @@ It currently supports:
|
|
|
19
137
|
- optionally serving LayerV public legal pages
|
|
20
138
|
- serving a configurable MP4 video playback page
|
|
21
139
|
|
|
140
|
+
## Quick start: no account needed
|
|
141
|
+
|
|
142
|
+
Share an app running on your machine, or a URL, privately from Claude
|
|
143
|
+
Desktop, Claude Code, Cursor, Codex, or any local MCP client. You need no
|
|
144
|
+
account and no API key: with no `QURL_API_KEY` set, the server drives the
|
|
145
|
+
[qURL CLI](https://github.com/layervai/qurl-integrations/tree/main/apps/cli)
|
|
146
|
+
installed on your machine, and the first publish creates this machine's
|
|
147
|
+
identity by itself.
|
|
148
|
+
|
|
149
|
+
**1. Install the qURL CLI** (macOS and Linux; Node.js 22.12 or later is
|
|
150
|
+
needed for the MCP server):
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
(umask 022 && mkdir -p "$HOME/.local/bin" "$HOME/.local/state") && chmod go-w "$HOME/.local" "$HOME/.local/bin" "$HOME/.local/state" && curl -fsSL --proto '=https' https://raw.githubusercontent.com/layervai/qurl-integrations/main/scripts/install.sh | INSTALL_DIR="$HOME/.local/bin" sh
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
On Windows, download `qurl.exe` from the
|
|
157
|
+
[latest release](https://github.com/layervai/qurl-integrations/releases/latest)
|
|
158
|
+
and put its folder on `PATH`. The server finds `qurl` on `PATH`, and also in
|
|
159
|
+
`~/.local/bin`, `/opt/homebrew/bin`, and `/usr/local/bin`, which many MCP
|
|
160
|
+
clients leave off the `PATH` they give servers. If the CLI is missing, every
|
|
161
|
+
tool answers with this install command instead of failing.
|
|
162
|
+
|
|
163
|
+
**2. Add the server to your MCP client**, with no `env` block.
|
|
164
|
+
|
|
165
|
+
Claude Desktop (`claude_desktop_config.json`) and Cursor (`~/.cursor/mcp.json`):
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"mcpServers": {
|
|
170
|
+
"qurl": {
|
|
171
|
+
"command": "npx",
|
|
172
|
+
"args": ["-y", "@layervai/qurl-mcp"]
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Codex (`~/.codex/config.toml`):
|
|
179
|
+
|
|
180
|
+
```toml
|
|
181
|
+
[mcp_servers.qurl]
|
|
182
|
+
command = "npx"
|
|
183
|
+
args = ["-y", "@layervai/qurl-mcp"]
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Claude Code:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
claude mcp add qurl -- npx -y @layervai/qurl-mcp
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
**3. Ask for what you want**, for example "share the app on localhost:3000
|
|
193
|
+
with my client". The agent publishes the app (it stays on your machine; the
|
|
194
|
+
CLI's background service keeps the share running), and gives you a
|
|
195
|
+
short-lived link for one person, or turns on access requests so people can
|
|
196
|
+
ask for access.
|
|
197
|
+
|
|
198
|
+
### Tools without an account
|
|
199
|
+
|
|
200
|
+
| Tool | What it does | CLI command |
|
|
201
|
+
| ---------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------- |
|
|
202
|
+
| `publish_crid` | Publish a local app or URL privately and return its CRID | `qurl publish <url> [--allow-requests] [--access <mode>]` |
|
|
203
|
+
| `share_by_crid` | Make a short-lived access link for a CRID this machine published | `qurl share <CRID> [--ttl] [--session-duration]` |
|
|
204
|
+
| `list_crids` | List this machine's published resources (read-only) | `qurl list --status active` |
|
|
205
|
+
| `manage_crid_requests` | List, approve by code, or deny access requests; list or remove approved people; turn requests on or off | `qurl requests`, `qurl approve`, `qurl deny`, `qurl grants` |
|
|
206
|
+
| `manage_crid_access` | Private access policy, invitations, and consumer grants | `qurl access <action> <CRID>` |
|
|
207
|
+
| `set_crid_sharing` | Stop, start, or restart sharing a local app | `qurl stop`, `qurl start`, `qurl restart` |
|
|
208
|
+
| `delete_crid` | Delete a resource permanently | `qurl delete <CRID> --yes` |
|
|
209
|
+
|
|
210
|
+
The tools follow the same rules as the qURL agent skill
|
|
211
|
+
(<https://layerv.ai/skills/qurl/SKILL.md>):
|
|
212
|
+
|
|
213
|
+
- Everything is published private. These tools have no option to publish
|
|
214
|
+
publicly.
|
|
215
|
+
- A pending access request is approved only with the six-digit code the
|
|
216
|
+
person gives you. No listing shows a code, and no tool approves by name:
|
|
217
|
+
anyone can type any name, and names come back as unverified data.
|
|
218
|
+
- An access link is a bearer secret for one recipient. A CRID grants nothing
|
|
219
|
+
by itself and is safe to share.
|
|
220
|
+
|
|
221
|
+
The server runs the CLI with an argument array (never a shell), with
|
|
222
|
+
JSON output, closed stdin, a timeout, and bounded output, and it does not
|
|
223
|
+
log what the CLI prints. The tools that need an account key (the qURL link,
|
|
224
|
+
token, session, and upload tools, and the `qurl://` resources and prompts)
|
|
225
|
+
are not listed in this mode.
|
|
226
|
+
|
|
227
|
+
### With an account key
|
|
228
|
+
|
|
229
|
+
Set `QURL_API_KEY` to a LayerV API key and the server uses the qURL API
|
|
230
|
+
directly, with the full tool set described in the [feature map](#feature-map):
|
|
231
|
+
|
|
232
|
+
```json
|
|
233
|
+
{
|
|
234
|
+
"mcpServers": {
|
|
235
|
+
"qurl": {
|
|
236
|
+
"command": "npx",
|
|
237
|
+
"args": ["-y", "@layervai/qurl-mcp"],
|
|
238
|
+
"env": { "QURL_API_KEY": "lv_live_xxx" }
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Remote HTTP server
|
|
245
|
+
|
|
246
|
+
The HTTP transport (`qurl-mcp-http`) serves remote agent runtimes. It is
|
|
247
|
+
account-based: every request carries the caller's qURL API key as a bearer
|
|
248
|
+
token, and it never runs a local CLI. See [HTTP Authentication](#http-authentication)
|
|
249
|
+
and the [LayerV MCP guide](https://layerv.ai/mcp/).
|
|
250
|
+
|
|
22
251
|
## Private consumer access
|
|
23
252
|
|
|
24
253
|
Node.js 22.12 or later is required by the shared qURL SDK.
|
|
@@ -28,7 +257,11 @@ email_capture, review, or contract access. `manage_crid_access` changes the
|
|
|
28
257
|
policy with its current version, sends invitations, lists grants, approves
|
|
29
258
|
or denies requests, and removes access. The tools return resource-scoped
|
|
30
259
|
receipts and omit invitation secrets and bearer links. Local apps use the
|
|
31
|
-
qURL CLI on the publisher machine.
|
|
260
|
+
qURL CLI on the publisher machine. In local mode, `app_name` sets and confirms
|
|
261
|
+
the public preview name through `qurl preview set` (requires a CLI with that command).
|
|
262
|
+
If naming fails, the tool returns an error with the published CRID and recovery
|
|
263
|
+
instructions. It does not delete or republish the resource. Older callers may
|
|
264
|
+
omit `app_name`; agents should always provide it for a complete preview.
|
|
32
265
|
|
|
33
266
|
For example, an assistant can turn “share this with ana@example.com, and
|
|
34
267
|
allow no requests” into an invite_only resource and an authorized invitation.
|
|
@@ -197,19 +430,11 @@ npm run start:http
|
|
|
197
430
|
|
|
198
431
|
## MCP Client Example
|
|
199
432
|
|
|
200
|
-
If you want to use this server in `stdio` mode with a local MCP client
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
{
|
|
204
|
-
|
|
205
|
-
"qurl": {
|
|
206
|
-
"command": "npx",
|
|
207
|
-
"args": ["@layervai/qurl-mcp"],
|
|
208
|
-
"env": { "QURL_API_KEY": "lv_live_xxx" }
|
|
209
|
-
}
|
|
210
|
-
}
|
|
211
|
-
}
|
|
212
|
-
```
|
|
433
|
+
If you want to use this server in `stdio` mode with a local MCP client, use
|
|
434
|
+
the configuration from [Quick start](#quick-start-no-account-needed). Leave
|
|
435
|
+
out `env` to work without an account through the local qURL CLI, or add
|
|
436
|
+
`"env": { "QURL_API_KEY": "lv_live_xxx" }` to use the qURL API with an
|
|
437
|
+
account key.
|
|
213
438
|
|
|
214
439
|
## Configuration Files
|
|
215
440
|
|
|
@@ -285,7 +510,9 @@ setting; clients configured for a larger first upload must validate the session
|
|
|
285
510
|
with a small qURL API call or a smaller upload first.
|
|
286
511
|
Size the configured maximum and reverse-proxy concurrency limit together.
|
|
287
512
|
|
|
288
|
-
Set `QURL_API_KEY` in the environment for `stdio` mode
|
|
513
|
+
Set `QURL_API_KEY` in the environment for `stdio` mode to use the qURL API.
|
|
514
|
+
Without it, `stdio` mode runs through the local qURL CLI and needs no account
|
|
515
|
+
(see [Quick start](#quick-start-no-account-needed)). In HTTP mode, every
|
|
289
516
|
client request supplies its own qURL API key as a bearer token.
|
|
290
517
|
|
|
291
518
|
`defaultQurlApiUrl` and `QURL_API_URL` require HTTPS for non-loopback hosts
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAiBA,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0C1C"}
|
package/dist/index.js
CHANGED
|
@@ -4,9 +4,10 @@ import { createRequire } from "node:module";
|
|
|
4
4
|
import { fileURLToPath } from "node:url";
|
|
5
5
|
import { formatErrorForLog, installTimestampedConsole, logInfo } from "./logging.js";
|
|
6
6
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
7
|
-
import {
|
|
7
|
+
import { QURLClient } from "./client.js";
|
|
8
8
|
import { getDefaultConfigPath, inspectSmtpConfig, loadRuntimeConfig } from "./config.js";
|
|
9
|
-
import {
|
|
9
|
+
import { QurlCli } from "./qurl-cli.js";
|
|
10
|
+
import { createLocalCliServer, createServer } from "./server.js";
|
|
10
11
|
installTimestampedConsole();
|
|
11
12
|
const require = createRequire(import.meta.url);
|
|
12
13
|
const { version } = require("../package.json");
|
|
@@ -16,7 +17,13 @@ export async function main() {
|
|
|
16
17
|
const runtimeConfig = loadRuntimeConfig(runtimeConfigPath);
|
|
17
18
|
const apiKey = runtimeConfig.qurlApiKey ?? "";
|
|
18
19
|
if (!apiKey) {
|
|
19
|
-
|
|
20
|
+
// No account key: drive the locally installed qURL CLI, which publishes
|
|
21
|
+
// without an account. The CLI is looked up per tool call, so a missing
|
|
22
|
+
// CLI becomes an install instruction in the tool result, not a startup
|
|
23
|
+
// failure.
|
|
24
|
+
logInfo("QURL_API_KEY is not set: tools run through the local qURL CLI (qurl), which needs no account.");
|
|
25
|
+
await createLocalCliServer(new QurlCli(), version).connect(new StdioServerTransport());
|
|
26
|
+
return;
|
|
20
27
|
}
|
|
21
28
|
const smtpInspection = inspectSmtpConfig(runtimeConfigPath);
|
|
22
29
|
logInfo("Runtime config loaded.");
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
|
+
type CliEnv = Record<string, string | undefined>;
|
|
3
|
+
type CliPlatform = typeof process.platform;
|
|
4
|
+
/**
|
|
5
|
+
* Runs the locally installed qURL CLI (`qurl`) for the no-account stdio mode.
|
|
6
|
+
*
|
|
7
|
+
* Safety rules, all enforced here rather than by callers:
|
|
8
|
+
* - The binary is started directly with an argument array (`shell: false`),
|
|
9
|
+
* so no argument is ever interpreted by a shell.
|
|
10
|
+
* - stdin is closed, so a command that would prompt cannot wait for input.
|
|
11
|
+
* - Every run has a timeout (SIGTERM, then SIGKILL) and bounded stdout and
|
|
12
|
+
* stderr. Output beyond the bound stops the process.
|
|
13
|
+
* - Only machine-readable output (`--output=json`) is parsed. Nothing the CLI
|
|
14
|
+
* prints is logged by this module.
|
|
15
|
+
*/
|
|
16
|
+
/** One-line install command for macOS and Linux, from the qURL agent skill. */
|
|
17
|
+
export declare const QURL_CLI_INSTALL_COMMAND = "(umask 022 && mkdir -p \"$HOME/.local/bin\" \"$HOME/.local/state\") && chmod go-w \"$HOME/.local\" \"$HOME/.local/bin\" \"$HOME/.local/state\" && curl -fsSL --proto '=https' https://raw.githubusercontent.com/layervai/qurl-integrations/main/scripts/install.sh | INSTALL_DIR=\"$HOME/.local/bin\" sh";
|
|
18
|
+
export declare const QURL_CLI_MISSING_MESSAGE: string;
|
|
19
|
+
export type QurlCliErrorCode = "cli_missing" | "cli_failed" | "cli_timeout" | "cli_cancelled" | "cli_output_too_large" | "cli_bad_output";
|
|
20
|
+
/**
|
|
21
|
+
* The tool call a CLI run belongs to. The server runs every tool handler in
|
|
22
|
+
* this context with the MCP request's abort signal, so a call that the client
|
|
23
|
+
* cancels (or gives up on at its own timeout) stops the qurl process instead
|
|
24
|
+
* of leaving it running behind a failed call.
|
|
25
|
+
*/
|
|
26
|
+
export declare const cliCallContext: AsyncLocalStorage<{
|
|
27
|
+
signal?: CancelSignal;
|
|
28
|
+
}>;
|
|
29
|
+
/** The part of an abort signal a run uses (the MCP request's signal fits it). */
|
|
30
|
+
export type CancelSignal = {
|
|
31
|
+
readonly aborted: boolean;
|
|
32
|
+
addEventListener(type: "abort", listener: () => void, options?: {
|
|
33
|
+
once?: boolean;
|
|
34
|
+
}): void;
|
|
35
|
+
removeEventListener(type: "abort", listener: () => void): void;
|
|
36
|
+
};
|
|
37
|
+
export declare class QurlCliError extends Error {
|
|
38
|
+
readonly code: QurlCliErrorCode;
|
|
39
|
+
readonly exitCode?: number | undefined;
|
|
40
|
+
constructor(code: QurlCliErrorCode, message: string, exitCode?: number | undefined);
|
|
41
|
+
}
|
|
42
|
+
export type QurlCliOptions = {
|
|
43
|
+
/** Environment for the lookup and the child process (default: process.env). */
|
|
44
|
+
env?: CliEnv;
|
|
45
|
+
platform?: CliPlatform;
|
|
46
|
+
homeDir?: string;
|
|
47
|
+
/**
|
|
48
|
+
* Directories searched after PATH. MCP clients often start servers with a
|
|
49
|
+
* minimal PATH that lacks the installer's directories, so the default list
|
|
50
|
+
* holds the places the official installer and Homebrew use.
|
|
51
|
+
*/
|
|
52
|
+
fallbackDirs?: string[];
|
|
53
|
+
timeoutMs?: number;
|
|
54
|
+
maxStdoutBytes?: number;
|
|
55
|
+
maxStderrBytes?: number;
|
|
56
|
+
killGraceMs?: number;
|
|
57
|
+
};
|
|
58
|
+
export type QurlCliRunOptions = {
|
|
59
|
+
timeoutMs?: number;
|
|
60
|
+
signal?: CancelSignal;
|
|
61
|
+
};
|
|
62
|
+
/** The surface the CLI-backed tools use; tests may substitute it. */
|
|
63
|
+
export interface IQurlCli {
|
|
64
|
+
runJson(args: string[], options?: QurlCliRunOptions): Promise<unknown>;
|
|
65
|
+
}
|
|
66
|
+
export declare function sanitizeCliText(text: string): string;
|
|
67
|
+
export declare class QurlCli implements IQurlCli {
|
|
68
|
+
private readonly env;
|
|
69
|
+
private readonly platform;
|
|
70
|
+
private readonly fallbackDirs;
|
|
71
|
+
private readonly timeoutMs;
|
|
72
|
+
private readonly maxStdoutBytes;
|
|
73
|
+
private readonly maxStderrBytes;
|
|
74
|
+
private readonly killGraceMs;
|
|
75
|
+
constructor(options?: QurlCliOptions);
|
|
76
|
+
/**
|
|
77
|
+
* Find `qurl` on PATH, then in the fallback directories. Relative PATH
|
|
78
|
+
* entries are skipped: they would resolve against whatever directory the
|
|
79
|
+
* MCP client started this server in. The lookup runs on every call, so a
|
|
80
|
+
* CLI installed while the server runs is found without a restart.
|
|
81
|
+
*/
|
|
82
|
+
findBinary(): string | undefined;
|
|
83
|
+
/**
|
|
84
|
+
* Run `qurl <args> --output=json` and return the parsed JSON document.
|
|
85
|
+
* Throws QurlCliError for every failure; its message is safe to show.
|
|
86
|
+
*/
|
|
87
|
+
runJson(args: string[], options?: QurlCliRunOptions): Promise<unknown>;
|
|
88
|
+
private running;
|
|
89
|
+
private readonly waiting;
|
|
90
|
+
private acquire;
|
|
91
|
+
private release;
|
|
92
|
+
private childEnv;
|
|
93
|
+
private run;
|
|
94
|
+
}
|
|
95
|
+
export {};
|
|
96
|
+
//# sourceMappingURL=qurl-cli.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"qurl-cli.d.ts","sourceRoot":"","sources":["../src/qurl-cli.ts"],"names":[],"mappings":"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"}
|