@layervai/qurl-mcp 0.4.1 → 0.5.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.
Files changed (169) hide show
  1. package/README.md +742 -50
  2. package/assets/fonts/NotoSansSC-Regular.ttf +0 -0
  3. package/assets/fonts/OFL.txt +93 -0
  4. package/assets/fonts/README.md +18 -0
  5. package/dist/auth/request-context.d.ts +13 -0
  6. package/dist/auth/request-context.d.ts.map +1 -0
  7. package/dist/auth/request-context.js +21 -0
  8. package/dist/auth/request-context.js.map +1 -0
  9. package/dist/auth/static-bearer.d.ts +12 -0
  10. package/dist/auth/static-bearer.d.ts.map +1 -0
  11. package/dist/auth/static-bearer.js +47 -0
  12. package/dist/auth/static-bearer.js.map +1 -0
  13. package/dist/client.d.ts +1 -1
  14. package/dist/client.d.ts.map +1 -1
  15. package/dist/client.js +15 -4
  16. package/dist/client.js.map +1 -1
  17. package/dist/config.d.ts +98 -0
  18. package/dist/config.d.ts.map +1 -0
  19. package/dist/config.js +543 -0
  20. package/dist/config.js.map +1 -0
  21. package/dist/credential-rate-limit-store.d.ts +38 -0
  22. package/dist/credential-rate-limit-store.d.ts.map +1 -0
  23. package/dist/credential-rate-limit-store.js +135 -0
  24. package/dist/credential-rate-limit-store.js.map +1 -0
  25. package/dist/email-addresses.d.ts +7 -0
  26. package/dist/email-addresses.d.ts.map +1 -0
  27. package/dist/email-addresses.js +36 -0
  28. package/dist/email-addresses.js.map +1 -0
  29. package/dist/email-types.d.ts +33 -0
  30. package/dist/email-types.d.ts.map +1 -0
  31. package/dist/email-types.js +28 -0
  32. package/dist/email-types.js.map +1 -0
  33. package/dist/emf-metrics.d.ts +25 -0
  34. package/dist/emf-metrics.d.ts.map +1 -0
  35. package/dist/emf-metrics.js +87 -0
  36. package/dist/emf-metrics.js.map +1 -0
  37. package/dist/http-config.d.ts +38 -0
  38. package/dist/http-config.d.ts.map +1 -0
  39. package/dist/http-config.js +243 -0
  40. package/dist/http-config.js.map +1 -0
  41. package/dist/http-routes.d.ts +5 -0
  42. package/dist/http-routes.d.ts.map +1 -0
  43. package/dist/http-routes.js +12 -0
  44. package/dist/http-routes.js.map +1 -0
  45. package/dist/http.d.ts +33 -0
  46. package/dist/http.d.ts.map +1 -0
  47. package/dist/http.js +1116 -0
  48. package/dist/http.js.map +1 -0
  49. package/dist/index.d.ts +1 -1
  50. package/dist/index.d.ts.map +1 -1
  51. package/dist/index.js +42 -26
  52. package/dist/index.js.map +1 -1
  53. package/dist/logging.d.ts +7 -0
  54. package/dist/logging.d.ts.map +1 -0
  55. package/dist/logging.js +110 -0
  56. package/dist/logging.js.map +1 -0
  57. package/dist/server.d.ts +12 -4
  58. package/dist/server.d.ts.map +1 -1
  59. package/dist/server.js +33 -8
  60. package/dist/server.js.map +1 -1
  61. package/dist/services/email.d.ts +17 -0
  62. package/dist/services/email.d.ts.map +1 -0
  63. package/dist/services/email.js +351 -0
  64. package/dist/services/email.js.map +1 -0
  65. package/dist/services/html.d.ts +5 -0
  66. package/dist/services/html.d.ts.map +1 -0
  67. package/dist/services/html.js +28 -0
  68. package/dist/services/html.js.map +1 -0
  69. package/dist/services/legal-pages.d.ts +12 -0
  70. package/dist/services/legal-pages.d.ts.map +1 -0
  71. package/dist/services/legal-pages.js +588 -0
  72. package/dist/services/legal-pages.js.map +1 -0
  73. package/dist/services/text-pdf.d.ts +16 -0
  74. package/dist/services/text-pdf.d.ts.map +1 -0
  75. package/dist/services/text-pdf.js +141 -0
  76. package/dist/services/text-pdf.js.map +1 -0
  77. package/dist/services/video-page.d.ts +4 -0
  78. package/dist/services/video-page.d.ts.map +1 -0
  79. package/dist/services/video-page.js +311 -0
  80. package/dist/services/video-page.js.map +1 -0
  81. package/dist/text.d.ts +4 -0
  82. package/dist/text.d.ts.map +1 -0
  83. package/dist/text.js +16 -0
  84. package/dist/text.js.map +1 -0
  85. package/dist/tools/_shared.d.ts +9 -1
  86. package/dist/tools/_shared.d.ts.map +1 -1
  87. package/dist/tools/_shared.js +20 -8
  88. package/dist/tools/_shared.js.map +1 -1
  89. package/dist/tools/batch-create.d.ts +12 -11
  90. package/dist/tools/batch-create.d.ts.map +1 -1
  91. package/dist/tools/batch-create.js +6 -4
  92. package/dist/tools/batch-create.js.map +1 -1
  93. package/dist/tools/create-qurl.d.ts +43 -4
  94. package/dist/tools/create-qurl.d.ts.map +1 -1
  95. package/dist/tools/create-qurl.js +63 -30
  96. package/dist/tools/create-qurl.js.map +1 -1
  97. package/dist/tools/delete-qurl.d.ts +3 -2
  98. package/dist/tools/delete-qurl.d.ts.map +1 -1
  99. package/dist/tools/delete-qurl.js +3 -10
  100. package/dist/tools/delete-qurl.js.map +1 -1
  101. package/dist/tools/email-delivery.d.ts +37 -0
  102. package/dist/tools/email-delivery.d.ts.map +1 -0
  103. package/dist/tools/email-delivery.js +115 -0
  104. package/dist/tools/email-delivery.js.map +1 -0
  105. package/dist/tools/extend-qurl.d.ts +6 -5
  106. package/dist/tools/extend-qurl.d.ts.map +1 -1
  107. package/dist/tools/extend-qurl.js +3 -3
  108. package/dist/tools/extend-qurl.js.map +1 -1
  109. package/dist/tools/get-qurl.d.ts +6 -5
  110. package/dist/tools/get-qurl.d.ts.map +1 -1
  111. package/dist/tools/get-qurl.js +5 -3
  112. package/dist/tools/get-qurl.js.map +1 -1
  113. package/dist/tools/list-qurl-sessions.d.ts +5 -4
  114. package/dist/tools/list-qurl-sessions.d.ts.map +1 -1
  115. package/dist/tools/list-qurl-sessions.js +2 -2
  116. package/dist/tools/list-qurl-sessions.js.map +1 -1
  117. package/dist/tools/list-qurls.d.ts +8 -7
  118. package/dist/tools/list-qurls.d.ts.map +1 -1
  119. package/dist/tools/list-qurls.js +9 -7
  120. package/dist/tools/list-qurls.js.map +1 -1
  121. package/dist/tools/mint-link.d.ts +39 -3
  122. package/dist/tools/mint-link.d.ts.map +1 -1
  123. package/dist/tools/mint-link.js +24 -13
  124. package/dist/tools/mint-link.js.map +1 -1
  125. package/dist/tools/output-schemas.d.ts +102 -45
  126. package/dist/tools/output-schemas.d.ts.map +1 -1
  127. package/dist/tools/output-schemas.js +54 -29
  128. package/dist/tools/output-schemas.js.map +1 -1
  129. package/dist/tools/resolve-qurl.d.ts +4 -3
  130. package/dist/tools/resolve-qurl.d.ts.map +1 -1
  131. package/dist/tools/resolve-qurl.js +3 -3
  132. package/dist/tools/resolve-qurl.js.map +1 -1
  133. package/dist/tools/revoke-qurl-token.d.ts +3 -2
  134. package/dist/tools/revoke-qurl-token.d.ts.map +1 -1
  135. package/dist/tools/revoke-qurl-token.js +2 -2
  136. package/dist/tools/revoke-qurl-token.js.map +1 -1
  137. package/dist/tools/terminate-qurl-sessions.d.ts +3 -2
  138. package/dist/tools/terminate-qurl-sessions.d.ts.map +1 -1
  139. package/dist/tools/terminate-qurl-sessions.js +7 -3
  140. package/dist/tools/terminate-qurl-sessions.js.map +1 -1
  141. package/dist/tools/update-qurl-token.d.ts +5 -4
  142. package/dist/tools/update-qurl-token.d.ts.map +1 -1
  143. package/dist/tools/update-qurl-token.js +2 -2
  144. package/dist/tools/update-qurl-token.js.map +1 -1
  145. package/dist/tools/update-qurl.d.ts +6 -5
  146. package/dist/tools/update-qurl.d.ts.map +1 -1
  147. package/dist/tools/update-qurl.js +4 -4
  148. package/dist/tools/update-qurl.js.map +1 -1
  149. package/dist/tools/upload-file-data-qurl.d.ts +182 -0
  150. package/dist/tools/upload-file-data-qurl.d.ts.map +1 -0
  151. package/dist/tools/upload-file-data-qurl.js +200 -0
  152. package/dist/tools/upload-file-data-qurl.js.map +1 -0
  153. package/dist/tools/upload-file-qurl.d.ts +162 -0
  154. package/dist/tools/upload-file-qurl.d.ts.map +1 -0
  155. package/dist/tools/upload-file-qurl.js +167 -0
  156. package/dist/tools/upload-file-qurl.js.map +1 -0
  157. package/dist/tools/upload-file-shared.d.ts +36 -0
  158. package/dist/tools/upload-file-shared.d.ts.map +1 -0
  159. package/dist/tools/upload-file-shared.js +347 -0
  160. package/dist/tools/upload-file-shared.js.map +1 -0
  161. package/dist/tools/upload-mint-options.d.ts +22 -0
  162. package/dist/tools/upload-mint-options.d.ts.map +1 -0
  163. package/dist/tools/upload-mint-options.js +29 -0
  164. package/dist/tools/upload-mint-options.js.map +1 -0
  165. package/dist/tools/upload-text-qurl.d.ts +144 -0
  166. package/dist/tools/upload-text-qurl.d.ts.map +1 -0
  167. package/dist/tools/upload-text-qurl.js +102 -0
  168. package/dist/tools/upload-text-qurl.js.map +1 -0
  169. package/package.json +25 -7
package/README.md CHANGED
@@ -4,17 +4,150 @@
4
4
 
5
5
  > **⚠️ 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
6
 
7
- MCP server for qURL™ secure link management.
7
+ > A qURL MCP Server that supports both local `stdio` mode and remote `HTTP` mode for creating, managing, resolving, and sharing secure access links.
8
8
 
9
- > **Quantum URL (qURL)** · The internet has a hidden layer. This is how you enter.
9
+ ## Overview
10
10
 
11
- ## What it does
11
+ `qURL MCP` exposes qURL capabilities to MCP clients, GPTs, ChatGPT, and other remote integrations.
12
12
 
13
- qURL MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI agents (Claude, GPT, Cursor, etc.) create, resolve, list, and manage qURL secure links natively. It connects to the qURL API over stdio transport, so any MCP-compatible client can use it without custom integration code.
13
+ It currently supports:
14
+
15
+ - creating, reading, updating, and deleting qURLs
16
+ - resolving access tokens
17
+ - managing qURL tokens and sessions
18
+ - uploading text or file content and generating qURLs
19
+ - optionally serving LayerV public legal pages
20
+ - serving a configurable MP4 video playback page
21
+
22
+ ## Runtime Modes
23
+
24
+ | Mode | Purpose | Start Command | Typical Use Case |
25
+ | ------- | ------------------------------- | -------------------- | ---------------------------------------------------------- |
26
+ | `stdio` | Local subprocess MCP server | `npm run start` | Claude Desktop, Cursor, Codex, and other local MCP clients |
27
+ | `http` | Authenticated remote MCP server | `npm run start:http` | Remote agent runtimes behind HTTPS |
28
+
29
+ ## Feature Map
30
+
31
+ ### qURL Management Tools
32
+
33
+ | Tool | Description |
34
+ | ------------------------- | --------------------------------------------------- |
35
+ | `create_qurl` | Create a new qURL |
36
+ | `resolve_qurl` | Resolve an access token into a protected target URL |
37
+ | `list_qurls` | List qURL resources |
38
+ | `get_qurl` | Fetch details for a single qURL |
39
+ | `delete_qurl` | Delete a qURL |
40
+ | `extend_qurl` | Extend qURL expiration |
41
+ | `update_qurl` | Update qURL metadata or expiration |
42
+ | `mint_link` | Mint a new access link for an existing resource |
43
+ | `batch_create_qurls` | Create multiple qURLs in one request |
44
+ | `revoke_qurl_token` | Revoke a specific token |
45
+ | `update_qurl_token` | Update a specific token |
46
+ | `list_qurl_sessions` | List active access sessions |
47
+ | `terminate_qurl_sessions` | Terminate one or all active sessions |
48
+
49
+ Resource status filters accept `active`, `revoked`, or `active,revoked`.
50
+ A resource remains active or revoked even when its `expires_at` is in the past;
51
+ individual access tokens can expire. `expired` is not accepted by `list_qurls`,
52
+ even though response parsing tolerates legacy values. The snapshot retains
53
+ upstream's stale expiration prose; its active/revoked status enum is authoritative.
54
+
55
+ The qURL SDK reuses the same `Idempotency-Key` and request body when retrying
56
+ POST/PATCH requests after a network failure or HTTP 429. Mutating HTTP 5xx
57
+ responses are not automatically retried. Each new MCP tool invocation is a new
58
+ operation with a new key, so repeating `create_qurl`, `batch_create_qurls`, or
59
+ `mint_link` can mint additional tokens. MCP does not expose a caller-supplied key.
60
+
61
+ ### Upload Tools
62
+
63
+ | Tool | Mode | Description |
64
+ | ----------------------- | ------------ | ------------------------------------------ |
65
+ | `upload_file_qurl` | `stdio` | Upload a local file and mint a qURL |
66
+ | `upload_file_data_qurl` | `stdio`/HTTP | Upload base64 file content and mint a qURL |
67
+ | `upload_text_qurl` | `stdio`/HTTP | Upload text content and mint a qURL |
68
+
69
+ `upload_file_qurl` is intentionally stdio-only. It can read any supported
70
+ PDF/image that the local MCP process user can access, so agents should invoke
71
+ it only for a path the user explicitly selected for sharing. Do not expose it
72
+ to untrusted prompts or autonomous agents: prompt injection could otherwise
73
+ select another readable PDF/image on the host. Run stdio under an OS account
74
+ whose filesystem access is limited to intended shareable content. HTTP mode
75
+ never registers this host-file tool.
76
+ The byte/text tools are also available in stdio so local clients can share
77
+ in-chat attachments without first materializing them at a known host path.
78
+ Connector upload and qURL minting are separate operations. If minting fails
79
+ after upload, the connector currently has no delete endpoint; the server logs
80
+ the orphaned `resource_id` for operator cleanup and returns the mint failure.
81
+ HTTP upload attempts remain bounded by the per-IP and per-credential MCP rate
82
+ limits; stdio operators should separately constrain autonomous retry loops.
83
+ Upload validation binds the declared media type to the filename plus format
84
+ start/end markers; it is not a malware scanner or full PDF/image decoder.
85
+ For polyglot resistance, a PDF's final `%%EOF` marker must be followed only by
86
+ ASCII whitespace; producer output with other trailing bytes is rejected even
87
+ if a permissive PDF reader would accept it. JPEG validation checks framing and
88
+ terminal markers rather than decoding image segments. The authenticated
89
+ connector must independently decode or otherwise fully validate content before
90
+ storage when semantic media validity matters. It must also preserve the
91
+ declared safe media type and serve downloads with `X-Content-Type-Options:
92
+ nosniff` rather than inferring an executable type.
93
+ There is intentionally no application-level path allowlist: symlinks and
94
+ time-of-check/time-of-use races make a lexical prefix check a misleading
95
+ security boundary. Use a dedicated OS account, container, or read-only mount
96
+ whose readable files are already limited to the intended sharing directory.
97
+ The final path component is opened with `O_NOFOLLOW`; intermediate directory
98
+ symlinks retain normal filesystem behavior under this trusted-local-user
99
+ boundary.
100
+
101
+ ### MCP Resources
102
+
103
+ | URI | Description |
104
+ | -------------- | ----------------------------------- |
105
+ | `qurl://links` | Current qURL list |
106
+ | `qurl://usage` | Current quota and usage information |
107
+
108
+ ### MCP Prompts
109
+
110
+ | Prompt | Description |
111
+ | ------------------ | --------------------------------- |
112
+ | `secure_a_service` | Secure service integration prompt |
113
+ | `audit_links` | Link audit prompt |
114
+ | `rotate_access` | Access rotation prompt |
14
115
 
15
116
  ## Quick Start
16
117
 
17
- Add the server to your MCP client configuration (Claude Desktop, Claude Code, etc.):
118
+ ### 1. Install Dependencies
119
+
120
+ ```bash
121
+ npm install
122
+ ```
123
+
124
+ For a local stdio-only source install, use `npm install --omit=optional`; this
125
+ omits the AWS SDK. HTTP deployments using the DynamoDB credential quota must use
126
+ the ordinary install so the optional SDK is packaged.
127
+
128
+ ### 2. Build
129
+
130
+ ```bash
131
+ npm run build
132
+ ```
133
+
134
+ ### 3. Start
135
+
136
+ Local `stdio` mode:
137
+
138
+ ```bash
139
+ npm run start
140
+ ```
141
+
142
+ Remote `HTTP` mode:
143
+
144
+ ```bash
145
+ npm run start:http
146
+ ```
147
+
148
+ ## MCP Client Example
149
+
150
+ If you want to use this server in `stdio` mode with a local MCP client:
18
151
 
19
152
  ```json
20
153
  {
@@ -28,74 +161,633 @@ Add the server to your MCP client configuration (Claude Desktop, Claude Code, et
28
161
  }
29
162
  ```
30
163
 
31
- Replace `lv_live_xxx` with your actual API key. The key must have the appropriate scopes for the tools you intend to use (see below).
164
+ ## Configuration Files
165
+
166
+ Copy the tracked examples to create local configuration files:
167
+
168
+ ```bash
169
+ cp qurl-mcp.config.example.json qurl-mcp.config.json
170
+ cp qurl-mcp.http.example.json qurl-mcp.http.json
171
+ ```
172
+
173
+ The local files are gitignored so credentials and machine-specific paths are
174
+ not committed.
175
+
176
+ Their responsibilities are:
177
+
178
+ | File | Purpose |
179
+ | ---------------------- | ----------------------------------------------------------- |
180
+ | `qurl-mcp.config.json` | Shared runtime config used by both `stdio` and `http` modes |
181
+ | `qurl-mcp.http.json` | HTTP-only server listener and public access config |
182
+
183
+ ## qurl-mcp.config.json Reference
184
+
185
+ ### Shared Core Settings
186
+
187
+ | Field | Purpose |
188
+ | ------------------------- | ------------------------------------------------------ |
189
+ | `maxUploadFileDataBytes` | Limits decoded and local file uploads (default `10mb`) |
190
+ | `defaultQurlApiUrl` | Base URL of the qURL backend API |
191
+ | `defaultQurlConnectorUrl` | Base URL of the upload connector |
192
+
193
+ Shared settings have these environment overrides. Environment values take
194
+ precedence over the shared config file.
195
+ The process caches resolved shared settings but automatically invalidates that
196
+ cache when the file metadata or any relevant environment value changes.
197
+
198
+ | Environment variable | Config field |
199
+ | -------------------------------------- | ------------------------------ |
200
+ | `MCP_MAX_UPLOAD_FILE_DATA_BYTES` | `maxUploadFileDataBytes` |
201
+ | `QURL_API_URL` | `defaultQurlApiUrl` |
202
+ | `QURL_CONNECTOR_URL` | `defaultQurlConnectorUrl` |
203
+ | `QURL_SMTP_HOST` | `smtp.host` |
204
+ | `QURL_SMTP_PORT` | `smtp.port` |
205
+ | `QURL_SMTP_SECURE` | `smtp.secure` |
206
+ | `QURL_SMTP_USERNAME` | `smtp.username` |
207
+ | `QURL_SMTP_PASSWORD` | `smtp.password` |
208
+ | `QURL_SMTP_FROM_EMAIL` | `smtp.fromEmail` |
209
+ | `QURL_SMTP_FROM_NAME` | `smtp.fromName` |
210
+ | `QURL_SMTP_ALLOWED_RECIPIENTS` | `smtp.allowedRecipients` |
211
+ | `QURL_SMTP_ALLOWED_RECIPIENT_DOMAINS` | `smtp.allowedRecipientDomains` |
212
+ | `QURL_SMTP_MAX_RECIPIENTS_PER_MESSAGE` | `smtp.maxRecipientsPerMessage` |
213
+ | `QURL_SMTP_MAX_RECIPIENTS_PER_HOUR` | `smtp.maxRecipientsPerHour` |
214
+ | `QURL_PUBLIC_VIDEO_FILE_PATH` | `publicVideo.filePath` |
215
+ | `QURL_PUBLIC_VIDEO_TITLE` | `publicVideo.title` |
216
+ | `QURL_PUBLIC_VIDEO_PAGE_PATH` | `publicVideo.pagePath` |
217
+
218
+ `QURL_API_KEY` is intentionally environment-only and has no config-file field.
219
+ Prefer `QURL_SMTP_PASSWORD` for the SMTP secret as well. If `smtp.password` is
220
+ stored in the config file on a POSIX host, restrict that file to owner-only
221
+ permissions (for example, `chmod 600`); startup warns when group/other read bits
222
+ are present. This check is intentionally advisory so existing deployments do
223
+ not fail after an upgrade, and it is skipped on Windows because POSIX mode bits
224
+ are not available there.
225
+ Email delivery itself is fail-closed unless at least one exact
226
+ `smtp.allowedRecipients` entry or `smtp.allowedRecipientDomains` entry is
227
+ configured; startup warns when complete SMTP credentials lack that policy.
228
+
229
+ Raising `maxUploadFileDataBytes` also raises the HTTP JSON parser's per-request
230
+ memory ceiling to roughly 1.5 times that value (up to about 150 MB at the
231
+ 100 MB maximum), before base64 decoding applies the exact byte cap. Until a
232
+ session has completed a successful downstream qURL API call, its parser ceiling
233
+ remains at the smaller 10 MB default upload setting; clients configured for a
234
+ larger first upload must validate the session with a small qURL API call first.
235
+ Size the configured maximum and reverse-proxy concurrency limit together.
236
+
237
+ Set `QURL_API_KEY` in the environment for `stdio` mode. In HTTP mode, every
238
+ client request supplies its own qURL API key as a bearer token.
239
+
240
+ `defaultQurlApiUrl` and `QURL_API_URL` require HTTPS for non-loopback hosts
241
+ because qURL API keys and data are bearer-sent to that destination. Plain HTTP
242
+ is accepted only for literal loopback development endpoints. Upload connector
243
+ URLs follow the same HTTPS-except-loopback rule.
244
+ Loopback means `127.0.0.0/8` or `::1`; wildcard bind addresses such as
245
+ `0.0.0.0` and `::` are intentionally not accepted as outbound HTTP targets.
246
+ Connector destinations are trusted operator configuration rather than caller
247
+ input; private addresses and DNS resolution are therefore permitted. Pin the
248
+ connector hostname in deployment DNS and do not point it at metadata services.
249
+ The caller's qURL bearer credential is forwarded to this host, so treat connector
250
+ URL and DNS control as part of the credential trust boundary.
251
+ Configure the connector service base URL, not an upload route: qurl-mcp appends
252
+ `/api/upload` to ordinary base paths, accepts that exact endpoint suffix, and
253
+ rejects ambiguous upload-like paths such as `/upload` or `/api/upload/v2`.
254
+ The MCP server performs bounded file-framing checks, not full media parsing;
255
+ the connector must independently revalidate uploaded content before storage or
256
+ serving, and delivery must retain `nosniff` behavior as the authoritative type
257
+ boundary.
258
+
259
+ API and connector base URLs that contain embedded credentials, a query string,
260
+ or a fragment are now rejected during startup. Deployments that previously used
261
+ one of those unusual URL forms must move credentials to `QURL_API_KEY` and keep
262
+ the configured service URL to its origin and optional path prefix.
263
+
264
+ ### SMTP Settings
265
+
266
+ | Field | Purpose |
267
+ | ------------------------------ | ---------------------------------------------------------------------------- |
268
+ | `smtp.host` | SMTP server hostname |
269
+ | `smtp.port` | SMTP server port |
270
+ | `smtp.secure` | `true` for implicit TLS; `false` for required STARTTLS |
271
+ | `smtp.username` | SMTP login username |
272
+ | `smtp.password` | SMTP login password or app-specific code |
273
+ | `smtp.fromEmail` | Sender email address |
274
+ | `smtp.fromName` | Sender display name |
275
+ | `smtp.allowedRecipients` | Optional exact-address allowlist |
276
+ | `smtp.allowedRecipientDomains` | Optional exact-domain allowlist (subdomains are not included) |
277
+ | `smtp.maxRecipientsPerMessage` | Per-message recipient cap (default `10`) |
278
+ | `smtp.maxRecipientsPerHour` | Per-qURL-key attempted-recipient cap per fixed hourly window (default `100`) |
279
+
280
+ These settings are used when email delivery is requested by tools such as:
281
+
282
+ - `create_qurl`
283
+ - `mint_link`
284
+ - `upload_text_qurl`
285
+ - `upload_file_qurl`
286
+ - `upload_file_data_qurl`
32
287
 
33
- ## Available Tools
288
+ If either recipient allowlist is configured, only an exact address or domain
289
+ match is delivered. If both are empty, the message and hourly caps still apply.
290
+ Domain entries are exact: `example.com` does not implicitly allow
291
+ `mail.example.com`; list each permitted subdomain explicitly.
292
+ Addresses and domains are normalized to lowercase NFC/IDNA ASCII form and a
293
+ trailing DNS root dot is removed before comparison and delivery.
294
+ Each recipient allowlist is limited to 1,000 configured entries. The
295
+ per-message recipient cap applies to the complete unique requested fan-out
296
+ before allowlist filtering, so blocked addresses cannot be used to submit an
297
+ oversized batch.
298
+ In HTTP mode, any caller with a valid qURL API key can request a server-side
299
+ SMTP delivery. Configure `allowedRecipients` or `allowedRecipientDomains`
300
+ before enabling SMTP on an Internet-facing HTTP deployment; empty allowlists
301
+ permit delivery to any syntactically valid address subject to the quotas.
302
+ The SMTP transport uses bounded connection/socket timeouts and is closed after
303
+ each delivery batch. Failed SMTP attempts still consume quota—including when a
304
+ transient outage results in zero delivered messages—so repeated failures cannot
305
+ bypass the abuse limit.
306
+ Each delivery request also has a 60-second aggregate deadline. Recipients not
307
+ started before that deadline are reported as skipped; provider-side queues are
308
+ the supported path for larger or slower fan-out.
309
+ Transport encryption is mandatory: `smtp.secure: true` uses implicit TLS,
310
+ while `smtp.secure: false` requires a successful STARTTLS upgrade. Port 465 is
311
+ reserved for implicit TLS and therefore requires `smtp.secure: true`.
312
+ Hourly quota state is maintained per server process: it resets on restart and
313
+ is not shared across replicas. Operators running multiple instances should
314
+ enforce a corresponding aggregate limit at the SMTP provider or gateway.
315
+ The in-process quota is therefore an abuse backstop, not a durable global
316
+ safety boundary; restart/scale-out fail-open behavior must be covered by that
317
+ provider-side limit.
318
+ Tracking fails closed for new principals after 10,000 principals are retained
319
+ in one process; existing principals continue to use their current buckets until
320
+ expired entries are pruned.
321
+ Restrict qURL API-key issuance and monitor new-principal quota-cap rejections:
322
+ cycling many valid keys can deliberately hold that shared table at capacity for
323
+ up to one quota window.
324
+ The quota uses a fixed one-hour window that starts with the first attempted
325
+ delivery after the prior window expires.
326
+ As with any fixed window, traffic immediately before and after a boundary can
327
+ total nearly twice the configured hourly value; use a provider-side sliding or
328
+ rolling limit when that boundary burst must be prevented across replicas.
34
329
 
35
- | Tool | Description | Required Scope |
36
- |------|-------------|----------------|
37
- | `create_qurl` | Create a secure, policy-bound link to a protected resource | `qurl:write` |
38
- | `resolve_qurl` | Resolve an access token to get the target URL and grant network access | `qurl:resolve` |
39
- | `list_qurls` | List active qURLs with optional pagination | `qurl:read` |
40
- | `get_qurl` | Get details of a specific qURL by resource ID | `qurl:read` |
41
- | `delete_qurl` | Revoke a qURL, immediately invalidating the link | `qurl:write` |
42
- | `extend_qurl` | Extend the expiration of an active qURL (alias for `update_qurl`) | `qurl:write` |
43
- | `update_qurl` | Update expiration, tags, or description on an active qURL | `qurl:write` |
44
- | `mint_link` | Mint a new access link for an existing protected resource | `qurl:write` |
45
- | `batch_create_qurls` | Create multiple qURLs in a single call | `qurl:write` |
46
- | `revoke_qurl_token` | Revoke one qURL token without revoking sibling tokens on the resource | `qurl:write` |
47
- | `update_qurl_token` | Update expiry, label, policy, or session limits on one qURL token | `qurl:write` |
48
- | `list_qurl_sessions` | List active access sessions for a qURL resource | `qurl:read` |
49
- | `terminate_qurl_sessions` | Terminate one or all active sessions for a qURL resource | `qurl:write` |
330
+ HTTP SMTP delivery is restricted to the operator credential configured in
331
+ `QURL_API_KEY`. A different customer's
332
+ valid qURL key does not authorize use of the operator's SMTP account. Without
333
+ that explicit operator key, HTTP email delivery is disabled. Stdio retains its
334
+ local operator trust model. Recipient allowlists and quotas apply in both modes.
50
335
 
51
- ## Available Resources
336
+ Generated qURL links are included in the plain-text email body. Restrict
337
+ recipients with the SMTP allowlists and configure transport encryption at the
338
+ SMTP server/provider when link confidentiality matters.
52
339
 
53
- | URI | Name | Description |
54
- |-----|------|-------------|
55
- | `qurl://links` | Active qURL Links | List of all active qURL links |
56
- | `qurl://usage` | qURL Usage & Quota | Current quota and usage information |
340
+ Prefer environment variables for SMTP credentials and policy:
341
+ `QURL_SMTP_USERNAME`, `QURL_SMTP_PASSWORD`, `QURL_SMTP_FROM_EMAIL`,
342
+ `QURL_SMTP_ALLOWED_RECIPIENTS`, `QURL_SMTP_ALLOWED_RECIPIENT_DOMAINS`,
343
+ `QURL_SMTP_MAX_RECIPIENTS_PER_MESSAGE`, and
344
+ `QURL_SMTP_MAX_RECIPIENTS_PER_HOUR`.
57
345
 
58
- ## Configuration
346
+ ### Public Video Page Settings
59
347
 
60
- | Environment Variable | Required | Description | Default |
61
- |---------------------|----------|-------------|---------|
62
- | `QURL_API_KEY` | Conditional (see description) | API key with appropriate scopes (`qurl:read`, `qurl:write`, `qurl:resolve`). The server boots without it so MCP introspection (`tools/list`, `resources/list`, `prompts/list`) works for directory probes — required only on the first tool call or resource read, where invocations surface a typed `missing_api_key` error until the key is set. | -- |
63
- | `QURL_API_URL` | No | qURL API base URL | `https://api.layerv.ai` |
348
+ | Field | Purpose |
349
+ | ---------------------- | -------------------------------------- |
350
+ | `publicVideo.title` | Title shown on the public video page |
351
+ | `publicVideo.pagePath` | Public path of the video playback page |
352
+ | `publicVideo.filePath` | Absolute server path of the MP4 file |
353
+
354
+ When configured, the HTTP server additionally exposes:
355
+
356
+ - a public video playback page
357
+ - a streaming endpoint for the MP4 file
358
+
359
+ `publicVideo.filePath` is trusted operator configuration. The final component
360
+ must be a non-symlink regular `.mp4` file; intermediate directory symlinks keep
361
+ normal filesystem resolution and must therefore remain under operator control.
362
+ Startup probes this optional asset and warns when it is missing, empty, or not
363
+ regular, but intentionally keeps the MCP service and `/healthz` available. The
364
+ video-file route still fails closed with `404` until the asset is corrected.
365
+
366
+ ## qurl-mcp.http.json Reference
367
+
368
+ Use [`qurl-mcp.http.example.json`](qurl-mcp.http.example.json) for local,
369
+ stateful development. [`qurl-mcp.http.stateless.example.json`](qurl-mcp.http.stateless.example.json)
370
+ shows every store and metric field required by a deployed stateless service.
371
+
372
+ | Field | Purpose |
373
+ | ------------------------------ | ----------------------------------------------------------------------------------- |
374
+ | `port` | HTTP MCP listener port |
375
+ | `host` | HTTP MCP bind address |
376
+ | `baseUrl` | Public base URL of the service |
377
+ | `allowedHosts` | Host allowlist for Host header validation |
378
+ | `trustProxyHops` | Exact trusted reverse-proxy hop count (default `0`) |
379
+ | `stateless` | Request-scoped HTTP transport with no session affinity (default `false`) |
380
+ | `maxConcurrentRequests` | Stateless-only POST/parser concurrency cap per process (default `20`) |
381
+ | `credentialRateLimitStore` | Credential counter backend: `memory` or `dynamodb` (default `memory`) |
382
+ | `rateLimitDynamoDbTable` | DynamoDB table used by the shared credential counter |
383
+ | `metricsNamespace` | CloudWatch EMF namespace for stateless saturation metrics |
384
+ | `metricsService` | Stable CloudWatch EMF Service dimension |
385
+ | `metricsEnvironment` | Stable CloudWatch EMF Environment dimension |
386
+ | `maxSessions` | Hard cap on live MCP sessions (default `1000`) |
387
+ | `maxSessionsPerCredential` | Per-bearer live and initializing session cap (default `20`) |
388
+ | `maxUnvalidatedSessions` | Cap on sessions that have not completed a downstream qURL API call (default `100`) |
389
+ | `sessionIdleTtlMs` | Connected-session idle eviction window (default 15 minutes) |
390
+ | `sessionAbsoluteTtlMs` | Absolute session lifetime, including active SSE/tool requests (default 24 hours) |
391
+ | `unvalidatedSessionTtlMs` | Absolute validation deadline for never-validated bearer sessions (default 1 minute) |
392
+ | `mcpRateLimitPerMinute` | Per-client `/mcp` request limit (default `120`) |
393
+ | `publicFileRateLimitPerMinute` | Per-client public-route request limit (default `300`) |
394
+
395
+ HTTP fields have matching environment overrides:
396
+
397
+ | Environment variable | Config field |
398
+ | --------------------------------------- | --------------------------------- |
399
+ | `MCP_PORT` | `port` |
400
+ | `MCP_HOST` | `host` |
401
+ | `MCP_BASE_URL` | `baseUrl` |
402
+ | `MCP_ALLOWED_HOSTS` | `allowedHosts` |
403
+ | `MCP_TRUST_PROXY_HOPS` | `trustProxyHops` |
404
+ | `MCP_HTTP_STATELESS` | `stateless` |
405
+ | `MCP_MAX_CONCURRENT_REQUESTS` | `maxConcurrentRequests` |
406
+ | `MCP_CREDENTIAL_RATE_LIMIT_STORE` | `credentialRateLimitStore` |
407
+ | `MCP_SERVE_LAYERV_LEGAL_PAGES` | `serveLayerVLegalPages` (default `false`) |
408
+ | `MCP_RATE_LIMIT_DYNAMODB_TABLE` | `rateLimitDynamoDbTable` |
409
+ | `MCP_METRICS_NAMESPACE` | `metricsNamespace` |
410
+ | `MCP_METRICS_SERVICE` | `metricsService` |
411
+ | `MCP_METRICS_ENVIRONMENT` | `metricsEnvironment` |
412
+ | `MCP_MAX_SESSIONS` | `maxSessions` |
413
+ | `MCP_MAX_SESSIONS_PER_CREDENTIAL` | `maxSessionsPerCredential` |
414
+ | `MCP_MAX_UNVALIDATED_SESSIONS` | `maxUnvalidatedSessions` |
415
+ | `MCP_SESSION_IDLE_TTL_MS` | `sessionIdleTtlMs` |
416
+ | `MCP_SESSION_ABSOLUTE_TTL_MS` | `sessionAbsoluteTtlMs` |
417
+ | `MCP_UNVALIDATED_SESSION_TTL_MS` | `unvalidatedSessionTtlMs` |
418
+ | `MCP_RATE_LIMIT_PER_MINUTE` | `mcpRateLimitPerMinute` |
419
+ | `MCP_PUBLIC_FILE_RATE_LIMIT_PER_MINUTE` | `publicFileRateLimitPerMinute` |
420
+ | `MCP_MAX_UPLOAD_FILE_DATA_BYTES` | `maxUploadFileDataBytes` (shared) |
421
+
422
+ The listener defaults to `127.0.0.1`. A non-loopback `host` is rejected unless
423
+ `allowedHosts` is explicitly configured. Set `trustProxyHops` (or
424
+ `MCP_TRUST_PROXY_HOPS`) to the exact number of trusted proxy hops; leave it at
425
+ `0` for direct connections so forwarded IP headers cannot spoof rate-limit keys.
426
+ The Host allowlist is limited to 1,000 entries so request-time validation stays
427
+ bounded even under pathological operator configuration.
428
+ `/mcp` applies the configured request allowance independently to both the
429
+ client IP and the SHA-256 digest of the authenticated bearer. The memory store
430
+ is process-local; the DynamoDB store uses an atomic fixed-window counter keyed
431
+ by credential digest and UTC minute. It never stores the bearer. As with any
432
+ fixed window, requests around a minute boundary can total nearly twice the
433
+ configured allowance. The table contract is a string partition key named
434
+ `rate_key`; the atomic update writes a numeric `request_count` counter and a
435
+ numeric `expires_at` TTL timestamp. Enable DynamoDB TTL on `expires_at` so
436
+ expired rows do not accumulate; TTL only schedules asynchronous cleanup, and
437
+ the minute in the key—not physical deletion—resets the active window. The task
438
+ role requires `dynamodb:DescribeTable` for startup and `dynamodb:UpdateItem` on
439
+ the request path. Use on-demand capacity or provision enough write capacity for
440
+ the expected fleet rate; throttling fails closed with `503` and never falls
441
+ back to memory. The client uses standard retry mode with at most two attempts,
442
+ a one-second connection timeout, and a two-second request timeout that throws;
443
+ these explicit bounds limit how long a request holds a concurrency permit
444
+ during a partial store failure. The optional AWS SDK dependency is top-level
445
+ exact-version pinned, while the committed package lock fixes its transitive
446
+ `@aws-sdk/*` and `@smithy/*` graph. Any SDK bump must update the lockfile and
447
+ keep the real-`NodeHttpHandler` timeout-materialization regression test green.
448
+ The dependency is loaded only when the DynamoDB store is selected, so
449
+ stdio-only consumers may install with `--omit=optional`. Deployed HTTP images
450
+ must include optional dependencies; startup fails before listening if the SDK
451
+ is absent or exposes an incompatible runtime surface. The client uses the
452
+ standard `AWS_REGION` and credential provider chain; ECS deployments
453
+ normally obtain both from the task environment and task role. Reverse-proxy
454
+ deployments must set the correct hop count or all callers behind the proxy will
455
+ share the proxy's single IP bucket. Only the DynamoDB credential quota is
456
+ fleet-wide: the IP limiter is process-local, so its effective fleet allowance
457
+ multiplies with task count and must be backed by a shared edge limit. The
458
+ managed deployment in qurl-integrations-infra PR #1305 enforces both a
459
+ per-source-IP WAF limit and a lower aggregate `/mcp` fleet cap, with live
460
+ headroom proof tracked in issue #1306. The credential bucket also prevents one
461
+ key from bypassing the request allowance by rotating source IPs, while
462
+ `maxSessionsPerCredential` prevents it from occupying the full session pool.
463
+ Each distinct bearer value retains one credential-bucket entry for the current
464
+ one-minute window. The IP limiter runs first, so token rotation from one source
465
+ cannot create entries faster than `mcpRateLimitPerMinute`; hostile distributed
466
+ traffic still requires the documented shared edge limit. The IP bucket is the
467
+ primary in-process control against arbitrary bearer rotation because distinct
468
+ unvalidated bearer strings necessarily occupy distinct credential buckets.
469
+ In stateful mode, budget pending-session parser memory as
470
+ `maxUnvalidatedSessions` times roughly
471
+ 1.5 times the smaller of `maxUploadFileDataBytes` and 10 MB (plus about 64 KiB
472
+ per request). At the defaults, the theoretical concurrent ceiling is about
473
+ 1.5 GiB. Lower `maxUnvalidatedSessions` and the shared edge concurrency limit
474
+ together when the deployment has a smaller memory budget.
475
+ Bearer credentials are conclusively validated by the first successful
476
+ downstream qURL API call. Until then, sessions use the smaller pending-session
477
+ cap and one-minute validation deadline, so arbitrary non-empty bearer strings
478
+ cannot occupy the full session pool for the normal 15-minute TTL. A client that
479
+ performs only MCP introspection remains pending by design; after deadline
480
+ eviction it must re-initialize before its next request. The session caps and
481
+ validation deadline are configurable for clients with longer
482
+ introspection-to-tool-call gaps. The deadline is absolute and applies regardless
483
+ of activity, including an open SSE stream or a long-running first tool call.
484
+ Validated clients that disconnect without sending `DELETE /mcp` retain their
485
+ bounded session slot for a 30-second reconnect grace period. A reconnect clears
486
+ that deadline; otherwise the session is reaped without waiting for the longer
487
+ idle TTL. Size `maxSessions` and the idle TTL for clients that remain connected
488
+ but do not perform explicit session teardown.
489
+ Validated sessions also expire at `sessionAbsoluteTtlMs` (24 hours by default),
490
+ even during an active SSE stream or tool request. This prevents keepalives from
491
+ pinning a global or per-credential session slot indefinitely.
492
+ The first downstream qURL operation must therefore complete before that
493
+ deadline; an unusually slow first API call may be interrupted and the client
494
+ must re-initialize. This fail-closed behavior prevents an invalid credential
495
+ from extending its pending slot with a deliberately long-running request.
496
+
497
+ At the unvalidated-session cap, a new initialization replaces the oldest idle
498
+ unvalidated session, so junk handshakes cannot reserve every slot for the full
499
+ validation TTL. Validated sessions and active requests are never evicted;
500
+ pending initializations and asynchronous teardown remain bounded. Sustained
501
+ traffic can still churn unvalidated sessions, so public deployments should use
502
+ stateless mode and edge admission controls.
503
+
504
+ Accepting a non-empty bearer during MCP initialization is intentional: it keeps
505
+ protocol introspection available before the first qURL operation, while the
506
+ global session cap, per-credential session cap, pending-session cap, absolute
507
+ deadline, and request rate limit bound invalid-key slot usage. The MCP
508
+ middleware does not validate the key itself; only a successful downstream qURL
509
+ API response promotes the session.
510
+ Downstream errors, including non-2xx responses that appear authenticated, do
511
+ not promote it because an intermediary may have generated them before the qURL
512
+ API authenticated the bearer.
513
+ Promotion therefore assumes the configured HTTPS qURL API endpoint and every
514
+ trusted intermediary neither cache nor synthesize authenticated success
515
+ responses. Reverse proxies in that path must forward authorization and disable
516
+ response caching for qURL API traffic.
517
+ Consequently, any caller with a non-empty bearer can enumerate the public
518
+ tool/resource/prompt catalog and briefly hold bounded pending-session state. On
519
+ hostile networks, place non-loopback deployments behind an identity-aware proxy
520
+ that preserves the caller's qURL bearer credential for `/mcp` authorization.
521
+ Initialization and catalog listing return server-owned static metadata only;
522
+ they do not invoke tool/resource/prompt handlers, read host files, contact the
523
+ qURL API or connector, or send email. Handler calls rely on the configured qURL
524
+ API to authenticate the forwarded bearer before returning data or applying an
525
+ operation. The configured connector is a second credential authority: it must
526
+ authenticate the forwarded qURL bearer before accepting or storing upload bytes.
527
+ Deploying an unauthenticated connector is unsupported because it would allow an
528
+ unvalidated MCP caller to create connector-side state.
529
+
530
+ Stateful mode is the compatibility default and retains the existing MCP session
531
+ registry, GET SSE, explicit DELETE behavior, and process-local credential quota
532
+ charging for all three MCP methods. Stateless mode creates and closes a server
533
+ and transport for each POST, ignores `mcp-session-id`, and
534
+ returns JSON-RPC-shaped `405` responses for GET and DELETE. It is the required
535
+ mode behind a load balancer or autoscaling service because no request depends
536
+ on process-local affinity. The concurrency permit is acquired before JSON
537
+ parsing and released on every response/error/disconnect path. Stateless mode
538
+ uses the configured `maxUploadFileDataBytes` parser ceiling directly because
539
+ the pre-parse concurrency permit provides its memory-amplification bound.
540
+ Budget roughly `maxConcurrentRequests` times (1.5 times
541
+ `maxUploadFileDataBytes` plus 64 KiB) per process; the default concurrency at
542
+ the 100 MB upload ceiling is approximately 3 GiB before downstream work.
543
+ Stateless startup rejects configurations whose conservative parser budget
544
+ exceeds 4 GiB. Lower either setting further when the ECS task has a smaller
545
+ memory limit. In contrast, stateful sessions above the default ceiling must
546
+ first complete a successful downstream qURL API call.
547
+ On hostile networks, an authenticated edge request-size limit no larger than
548
+ the configured parser ceiling is a deployment requirement: the permit bounds
549
+ aggregate memory, but a non-empty bearer is not authoritatively validated until
550
+ the parsed operation reaches the downstream qURL API.
551
+
552
+ The stateless listener bounds header receipt at 15 seconds and both complete
553
+ request receipt and idle socket lifetime at 120 seconds. A concurrency permit
554
+ spans parsing through response completion, so stalled clients cannot retain the
555
+ entire permit pool indefinitely. A tool call that produces no socket traffic
556
+ for 120 seconds is intentionally aborted; integrations needing longer silent
557
+ operations must move that work behind an asynchronous API rather than raising
558
+ this fleet-wide retention bound.
559
+
560
+ Deployed (non-loopback) stateless mode requires the DynamoDB credential store
561
+ and all three stable metric identity fields. It emits a 30-second EMF heartbeat:
562
+ `McpConcurrencyUtilization` is the peak permit utilization observed during the
563
+ interval at request admission and heartbeat (including requests that start and
564
+ finish between heartbeats), while
565
+ `McpConcurrencyRejected` and `McpRateLimitStoreErrors` are snapshot-and-zero
566
+ interval deltas that include explicit zeros. Session caps and email recipient
567
+ quotas remain in-memory; the DynamoDB credential quota is fleet-wide and counts
568
+ every authenticated HTTP POST, including initialization, discovery, and tool
569
+ calls. Size that quota for the expected complete request pattern rather than
570
+ tool calls alone. The permit also spans the bounded DynamoDB increment: during
571
+ a store brownout, each admitted request may retain one permit for roughly four
572
+ seconds (two two-second attempts) before failing closed, while excess requests
573
+ receive a fast concurrency `503`. The fixed-window counter increments every
574
+ attempt, including
575
+ attempts already above the credential limit; edge rate limits and DynamoDB
576
+ write/throttle alarms must therefore bound abusive write amplification.
577
+ Deployment owners must make both alarms and an over-limit write-amplification
578
+ probe hard promotion gates rather than treating them as optional observability.
579
+ The managed deployment in
580
+ [qurl-integrations-infra#1305](https://github.com/layervai/qurl-integrations-infra/pull/1305)
581
+ provisions those alarms, with live proof tracked in its rollout ledger and
582
+ issue #1306 before promotion.
583
+ Direct `createHttpRuntime` embedders that inject a credential-store
584
+ implementation must still declare `credentialRateLimitStore: "dynamodb"` for
585
+ non-loopback stateless mode. The generic injection interface cannot prove a
586
+ custom backend is shared across replicas, so injection is deliberately not an
587
+ escape hatch from the deployed contract.
588
+ Metric identity fields are rejected in stateful mode so the concurrency gauge
589
+ cannot silently report a misleading zero.
590
+ Each stateless POST owns a fresh MCP server and transport so no request can
591
+ inherit another credential's handler state. Completed-response teardown is
592
+ tracked asynchronously. Admission stops when that backlog reaches
593
+ `maxConcurrentRequests`; requests already in flight may then finish, so the
594
+ backlog can transiently approach twice that count but remains bounded. While
595
+ the admission guard is closed, new requests fail with `503` and increment
596
+ `McpConcurrencyRejected` instead of growing teardown memory without bound.
597
+ That counter intentionally represents admission failure from either active
598
+ request saturation or teardown backpressure. Autoscaling must use
599
+ `McpConcurrencyUtilization` alone; the rejection counter remains page-worthy,
600
+ and low utilization alongside rejections identifies teardown lag.
601
+ Pooling these objects would weaken request isolation and is deliberately not a
602
+ performance optimization without measured registration pressure.
603
+ `/healthz` and the public video-file endpoint each use their own
604
+ `publicFileRateLimitPerMinute` bucket, isolated from legal/video-page traffic
605
+ and from each other. Keep load-balancer, liveness-probe, and expected video
606
+ range-request frequency below that per-source-IP allowance (300
607
+ requests/minute by default), or raise it for unusually aggressive clients.
608
+
609
+ ## Configuration Priority
610
+
611
+ By default, configuration is loaded from the two local JSON files above. If a
612
+ file is absent, built-in defaults and environment variables are used.
613
+ Relative config paths—including the defaults—are resolved from the process
614
+ working directory. Set the explicit path variables below when a supervisor,
615
+ `npx`, or an MCP host launches the server from a different directory.
616
+
617
+ The following environment variables independently override the config file paths:
618
+
619
+ - `QURL_MCP_CONFIG`
620
+ - `QURL_MCP_HTTP_CONFIG`
621
+
622
+ `QURL_MCP_HTTP_CONFIG` never replaces the shared runtime config path. This keeps
623
+ listener settings from silently shadowing SMTP, connector, or API settings.
624
+
625
+ `server.json` and `smithery.yaml` describe the published stdio transport, so
626
+ they include shared upload/SMTP settings but intentionally omit HTTP-only
627
+ listener variables such as `QURL_MCP_HTTP_CONFIG` and `MCP_MAX_SESSIONS`.
628
+
629
+ Do not commit API keys, SMTP credentials, or private file-system paths.
630
+
631
+ ## HTTP Routes
632
+
633
+ After starting in `http` mode, the common routes are:
634
+
635
+ | Route | Purpose |
636
+ | ------------------------------ | ---------------------------- |
637
+ | `/mcp` | Main remote MCP endpoint |
638
+ | `/healthz` | Health check endpoint |
639
+ | `/legal/privacy` | Public privacy policy page |
640
+ | `/legal/terms` | Public terms of service page |
641
+ | `publicVideo.pagePath` | Public video playback page |
642
+ | `publicVideo.pagePath + /file` | MP4 streaming endpoint |
643
+
644
+ `/healthz` is intentionally unauthenticated and Host-unvalidated for every
645
+ caller, exposes only `{ "ok": true }`, and uses the configured public-route
646
+ request limit in a separate bucket so health probes cannot consume the
647
+ legal/video route allowance. A `429` from this route
648
+ means the probe source exceeded `publicFileRateLimitPerMinute`, not that the
649
+ application failed its liveness check; keep probe frequency below that limit.
650
+ It is registered before Host validation because ALB target probes use the task
651
+ IP and port as Host; public MCP and browser routes remain Host-validated.
652
+
653
+ ## HTTP Authentication
654
+
655
+ The `/mcp` endpoint requires `Authorization: Bearer <qURL API key>` on every
656
+ request. In stateful mode the bearer token is bound to the resulting MCP
657
+ session, so a session ID cannot be reused with a different credential. In
658
+ stateless mode the bearer remains request-scoped and is discarded when the
659
+ response closes.
660
+
661
+ **Operator authentication boundary:** initialization accepts any non-empty
662
+ bearer token and allows the public tools/resources/prompts catalog to be read
663
+ before authoritative validation by the first downstream qURL API call.
664
+ That catalog is assembled from static schemas and descriptions and does not
665
+ include bearer tokens, SMTP credentials, or other operator configuration.
666
+ Unvalidated-session caps, a short validation deadline, and request rate limits
667
+ bound that pre-validation state; the supplied token is forwarded only to the
668
+ configured qURL API.
669
+ Introspection-only sessions therefore remain unvalidated and are closed at
670
+ `unvalidatedSessionTtlMs`; clients can re-initialize if they need a longer-lived
671
+ session. A session is promoted only after a successful qURL API call—rejected
672
+ or rate-limited calls do not prove the credential valid. Disconnected sessions
673
+ remain registered for a 30-second SSE reconnect grace period, while
674
+ `maxSessions` and `maxSessionsPerCredential` bound that allowance under churn.
675
+
676
+ Requests without an `Origin` header are accepted for non-browser MCP clients.
677
+ When `Origin` is present, it must match the origin of `baseUrl`; malformed or
678
+ cross-origin values are rejected on `/mcp`. Public health, legal, and configured
679
+ video routes do not use browser-origin state and are not gated by this check.
680
+
681
+ Configure remote MCP clients with:
682
+
683
+ | Setting | Value |
684
+ | -------------- | --------------------------------- |
685
+ | MCP Server URL | Your public HTTPS URL plus `/mcp` |
686
+ | Authentication | Bearer token |
687
+ | Token | The caller's qURL API key |
688
+
689
+ If a client only supports OAuth discovery, place an OAuth-compatible gateway
690
+ in front of this server rather than exposing `/mcp` without authentication.
691
+
692
+ ## How to Verify Deployment
693
+
694
+ ### Service-Level Checks
695
+
696
+ Start with:
697
+
698
+ - `/healthz`
699
+ - `/mcp`
700
+
701
+ LayerV legal documents are disabled by default. Only LayerV-operated services
702
+ should set `MCP_SERVE_LAYERV_LEGAL_PAGES=true` (or `serveLayerVLegalPages: true`
703
+ in the HTTP config). Self-hosted operators must publish their own policies.
704
+
705
+ ### Public Page Checks
706
+
707
+ When enabled, verify the legal pages and configured video page:
708
+
709
+ - `/legal/privacy`
710
+ - `/legal/terms`
711
+ - the configured public video page path
712
+
713
+ ### Domain Verification
714
+
715
+ If you plan to use OpenAI Platform, make sure the following root-level path exists:
716
+
717
+ ```text
718
+ /.well-known/openai-apps-challenge
719
+ ```
720
+
721
+ > This verification file must live under the domain root `.well-known` path, not under `/mcp`.
64
722
 
65
723
  ## Docker
66
724
 
67
- A multi-stage Dockerfile is included for container-based deployment:
725
+ The repository includes a Dockerfile for containerized deployment.
726
+
727
+ Example:
68
728
 
69
729
  ```bash
70
730
  docker build -t qurl-mcp .
71
731
  docker run -i -e QURL_API_KEY=lv_live_xxx qurl-mcp
72
732
  ```
73
733
 
74
- The image runs as the non-root `node` user, ships only production dependencies, and uses `tini` as PID 1 for clean signal handling.
734
+ If you deploy with Docker, make sure the container can still access the correct config files, or override the config file paths with environment variables.
75
735
 
76
- If a tool call returns `missing_api_key` despite `QURL_API_KEY` looking set, check stderr for the boot-time warning — some MCP hosts hide stderr, and the warning is the fastest way to spot a whitespace-only or unset value:
736
+ Run the HTTP listener locally in Docker:
737
+
738
+ The image defaults to the stdio entry point and the HTTP server defaults to
739
+ container-local loopback. HTTP deployments must override the command and bind
740
+ to `0.0.0.0` with an explicit Host allowlist and HTTPS public origin. This
741
+ example publishes only to host loopback; put a TLS reverse proxy in front of
742
+ it for the configured `https://mcp.example.com` origin:
77
743
 
78
744
  ```bash
79
- docker logs <container> # if running detached
80
- docker run -i -e QURL_API_KEY=lv_live_xxx qurl-mcp 2>&1 # interactive
745
+ docker run --rm -p 127.0.0.1:3000:3000 \
746
+ -e MCP_HOST=0.0.0.0 \
747
+ -e MCP_BASE_URL=https://mcp.example.com \
748
+ -e MCP_ALLOWED_HOSTS=mcp.example.com,127.0.0.1,localhost \
749
+ qurl-mcp node dist/http.js
81
750
  ```
82
751
 
83
- ## Development
752
+ For a single trusted production reverse proxy, set
753
+ `MCP_TRUST_PROXY_HOPS=1`, use the public HTTPS origin in `MCP_BASE_URL`, and
754
+ set `MCP_ALLOWED_HOSTS` to the public hostname. Do not expose the container's
755
+ listener directly when proxy trust is enabled.
84
756
 
85
- ```bash
86
- npm install
87
- npm run build
88
- npm test
89
- npm run lint
90
- ```
757
+ ## Common Commands
91
758
 
92
- Additional commands:
759
+ | Command | Purpose |
760
+ | ----------------------- | --------------------- |
761
+ | `npm run build` | Compile TypeScript |
762
+ | `npm test` | Run tests |
763
+ | `npm run test:coverage` | Run enforced coverage |
764
+ | `npm run lint` | Run ESLint |
765
+ | `npm run dev` | TypeScript watch mode |
766
+ | `npm run format` | Format source code |
767
+ | `npm run format:check` | Check formatting |
768
+ | `npm run start` | Start stdio mode |
769
+ | `npm run start:http` | Start HTTP mode |
93
770
 
94
- ```bash
95
- npm run dev # Watch mode (rebuild on changes)
96
- npm run format # Format source with Prettier
97
- npm run format:check # Check formatting without modifying files
98
- ```
771
+ ## Recommended Deployment Order
772
+
773
+ 1. Copy and update the two example config files
774
+ 2. Set credentials through environment variables
775
+ 3. Run `npm install`
776
+ 4. Run `npm run build`
777
+ 5. Run `npm run start:http`
778
+ 6. Verify `/healthz`
779
+ 7. Verify unauthenticated `/mcp` requests receive `401`
780
+ 8. Configure the HTTPS reverse proxy
781
+ 9. Verify an authenticated MCP initialization and the optional public pages
782
+
783
+ ## Third-Party Assets
784
+
785
+ Text-to-PDF generation bundles the regular-weight Noto Sans SC font as TrueType
786
+ (about 10 MB) for offline multilingual glyph coverage. The static font retains
787
+ all characters from the original variable font; PDFKit embeds only the glyphs
788
+ used by each document. No download or additional runtime dependency is needed.
789
+ Its SIL Open Font License and copyright notice are included in
790
+ `assets/fonts/OFL.txt`; conversion details are in `assets/fonts/README.md`.
99
791
 
100
792
  ## License
101
793