@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 CHANGED
@@ -1,14 +1,132 @@
1
- # @layervai/qurl-mcp
1
+ # qURL MCP server for temporary access links
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@layervai/qurl-mcp.svg)](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
- > A qURL MCP Server that supports both local `stdio` mode and remote `HTTP` mode for creating, managing, resolving, and sharing secure access links.
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
- `qURL MCP` exposes qURL capabilities to MCP clients, GPTs, ChatGPT, and other remote integrations.
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
- ```json
203
- {
204
- "mcpServers": {
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. In HTTP mode, every
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
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAgBA,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAkC1C"}
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 { MISSING_API_KEY_MESSAGE, QURLClient } from "./client.js";
7
+ import { QURLClient } from "./client.js";
8
8
  import { getDefaultConfigPath, inspectSmtpConfig, loadRuntimeConfig } from "./config.js";
9
- import { createServer } from "./server.js";
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
- console.error(`Warning: ${MISSING_API_KEY_MESSAGE}`);
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":"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"}
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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"}